Discordia 2.11.0 and Discord API v8

[SinisterRectus]

Changelog: https://github.com/SinisterRectus/Discordia/blob/master/CHANGELOG.md
Diff: https://github.com/SinisterRectus/Discordia/compare/2.10.0..2.11.0

---

In early 2022, Discord released API v10 and announced plans to decomission v6 and v7. These plans were said to be carried out in "early 2023". Based on their details, I expect v6 and v7 to be fully decomissioned around April 2023, though no exact date has been announced.

To meet this deadline, Discordia 2.11.0 has been released to support Discord API v8. Although v8 is old and deprecated, it is still functional and will act as a stepping stone for us to incrementally update to more modern versions of the API (v9, v10, and beyond).

Every attempt has been made to keep Discordia behavior from changing, but please be aware that some changes may be unavoidable.

Because of the potential impact of these changes, this discussion will serve as a guide and forum for users to update their bots.

If you run into any issues or bugs, please let me know, and I will address them as soon as possible!

Gateway Intents

The biggest behavioral change comes with the addition of gateway intents. If you are not already aware of what these are, you'll probably want to read Discord's official docs about this. Gateway intents are supported in v7 and required in v8 and above.

To support intents in Discordia, the gatewayIntent client option has been added. The default value for this is 3243773 which includes all currently known gateway intents except for privileged intents.

Privileged intents include: guildMembers, guildPresences, and messageContent. If you do not want to use privileged intents, no user code changes are required. If you want to use any privileged intents, your bot must be in fewer than 100 guilds or verified by Discord. Once this condition has been met, you must manually enable the desired intent(s) on your bot's application page. Then, to use privileged intents in your bot, you must programmatically enable them in your bot code. To do this, you may use the enableIntents, enableAllIntents, or setIntents client methods after initilizing your Client instance, but before calling run.

Here are several ways to enable all intents:

local client = discordia.Client {
	gatewayIntents = 3276799,
}

local client = discorida.Client()
local e = discordia.enums.gatewayIntent
client:enableIntents(e.guildMembers, e.guildPresences, e.messageContent)

local client = discorida.Client()
local e = discordia.enums.gatewayIntent
client:enableIntents(e.guildMembers)
client:enableIntents(e.guildPresences)
client:enableIntents(e.messageContent)

local client = discorida.Client()
client:enableAllIntents()

local client = discordia.Client()
client:setIntents(3276799)

If you'd like to use different static values, you can use an intents calculator.

Since intents are now required and privileged intents are disabled by default, some side-effects may be seen.

• If you do not enable certain intents, your bot will simply never receive the events that are governed by those intents.
• The cacheAllMembers client option cannot be set to true while the guildMembers intent is disabled. To account for this, Discordia clients will automatically disable cacheAllMembers if it detects the intent is disabled and will log a warning to the console.
• Without the messageContent intent, your bot will receive empty strings for most message content, excluding some cases such as your bot's own messages, DMs, and messages where your bot is mentioned.

Permissions

Due to technical limitations in bit operation behavior, old Discord API and Discordia versions supported permissions values up to 1 << 31. New API versions now support larger values and Discordia has been updated to support these. Values up to 1 << 64 are supported internally with the use of LuaJIT 64-bit integers, though Discordia's numerical enumerations are limited to 1 << 53. The largest permission value currently known is 1 << 36. No user code changes should be required unless you want to use new permissions.

Enumerations

A ton of missing enumeration fields have been added. See the official changelog for the list. No user code changes should be required unless you want to use new enumerations.

Embeds

Message sending now supports multiple embeds with the embeds field. This is simply a sequential table of embed objects. The singular embed field is still supported and represents embeds[1]. Editing multiple embeds and/or attachments may come in a later update. No user code changes should be required unless you want to use this new field.

Deprecations

The client method setGame has been deprecated and is replaced by the new method setActivity with the same behavior. No user code changes should be required, but changing all of your setGame calls to setActivity calls is recommended.

Internal Changes

The REST/HTTP constant VERSION used in API.lua and the Gateway/WebSocket constant GATEWAY_VERSION used in Shard.lua have been merged as the API_VERSION constant in constants.lua. The default and currently supported value is 8; however, I have made attempts to keep Discordia code backwards compatible with v7. Thus, if you run into trouble, you may manually set API_VERSION to 7, but please be aware that v7 may not always be supported and Discord may disable access to this API version at any time.

Because roles, nick, and premium_since values are not provided in PRESENCE_UPDATE in v8 and above, Discordia will no longer attempt to create member objects for offline members during presence updates. This is not strictly a breaking change since Discordia provides no guarantees about member object caching unless cacheAllMembers is true. A likely side-effect of this change is seeing more HTTP requests for the getMember method. Enable cacheAllMembers if this concerns you.

I've added a bunch of events to the ignore list so you should see fewer unhandled event warnings in the console.

I've recently switched from using Atom to VSCode and luacheck to Sumneko's Lua Language Server. Thus, I made a handful of minor edits to suppress new code warnings.

All mentions of "game" have been changed to "activity". RIP gaming.

[SinisterRectus]

I overlooked an issue with API v8.

Long ago, Discord removed private channels from bot READY payloads. To compensate, your bot would receive a CHANNEL_CREATE event before any related direct message events. This feature was removed in v8. To maintain compatibility in Discordia, I made an internal change explained below and have released this with 2.11.1.

Discordia now will make an HTTP request to fetch a private or group channel when your bot receives a direct message event and the channel is not previously known.

I do not expect this to be a problem as this should only have to occur once per channel per client. After that, the channel will be cached indefinitely and your bot will receive direct messages normally.

If you are concerned about the penalties that these HTTP requests may incur to your bot, I recommend disabling direct message events using gateway intents.