Welcome to the Discord extension wiki!
On this wiki you can find the reference for the Discord extension for GameMaker and a guide to get started with it.
This guide describes the required steps to set up a GameMaker project for use with the Discord extension.
"../discord_game_sdk/". Note that this path is relative to the project's .yyp file.In order to run a game with the Discord extension, Discord must already be running. If Discord isn't running yet, the current run of your game will fail and will attempt to start Discord. The following error message is shown in The Output Window in that case:
FAILED: Run Program Complete
For the details of why this build failed, please review the whole log above and also see your Compile Errors window.
The game will not restart automatically after doing this, however, and you will need to manually run the game again, after Discord has properly started. So the most convenient way to test your game with the Discord extension is to keep Discord open the entire time.
The first thing to do is setting up the Discord extension using Discord_Core_Create:
var _applicationId = int64(extension_get_option_value("Discord", "appId"));
Discord_Core_Create(_applicationId);
The function requires the Application ID set earlier, which you can retrieve from the extension using the built-in function extension_get_option_value.
The next thing is to run the callbacks Discord_Core_RunCallbacks every step. This can go in e.g. an object's Step event:
/// @desc Step Event
Discord_Core_RunCallbacks();
Whenever the current connected user changes something in Discord (i.e. their avatar, username, or something else), the data in the User struct should also be changed to reflect these changes in your game.
To be notified about these changes, you should listen for an Async Social Event of type Discord_Users_OnCurrentUserUpdate and update the user data by making a new call to Discord_Users_GetCurrentUser when this type of event occurs.
Initializes the Discord extension. If Discord is not running, it will:
Discord_Core_Create(appId)
| Argument | Type | Description |
|---|---|---|
| appId | int64 | Application identifier |
Discord_Core_Create(appId);
Requests the extension instances to do work.
⚠️ IMPORTANT It is imperative that this function is called at regular intervals to ensure that all the services offered by the SDK function optimally.
Discord_Core_RunCallbacks()
N/A
/// Step Event
Discord_Core_RunCallbacks();
| Constant | Value | Description |
|---|---|---|
| Discord_OK | 0 | A constant that indicates that the result is OK. |
Discord_Overlay_OpenActivityInviteDiscord_Overlay_IsEnabledDiscord_Overlay_IsLockedDiscord_Overlay_OpenGuildInviteDiscord_Overlay_OpenVoiceSettingsDiscord_Overlay_SetLockedOpens the overlay modal for sending game invitations to users, channels, and servers. If you do not have a valid activity with all the required fields, this call will error. See Activity Action Field Requirements for the fields required to have join and spectate invites function properly.
Discord_Overlay_OpenActivityInvite(activityActionType)
| Argument | Type | Description |
|---|---|---|
| value | Discord_ActivityActionType | What type of invite to send |
N/A
Discord_Overlay_OpenActivityInvite(Discord_ActivityActionType_Spectate);
The code sample above triggers an activity invite overlay that can be listened for inside an Async Social Event.
if (async_load[? "type"] == "Discord_Overlay_OpenActivityInvite")
{
if (async_load[? "result"] == Discord_OK)
{
show_debug_message("succeeded!");
}
else
{
show_debug_message("failed!");
}
}
The code above matches the response against the correct event type and logs the success of the task.
Check whether the user has the overlay enabled or disabled. If the overlay is disabled, all the functionality in this manager will still work. The calls will instead focus the Discord client and show the modal there instead.
Discord_Overlay_IsEnabled()
var _overlay_is_enabled = Discord_Overlay_IsEnabled();
Check if the overlay is currently locked or unlocked.
Discord_Overlay_IsLocked()
var _overlay_is_locked = Discord_Overlay_IsLocked();
Opens the overlay modal for joining a Discord guild, given its invite code.
Discord_Overlay_OpenGuildInvite(code)
| Argument | Type | Description |
|---|---|---|
| code | string | The server invitation code. |
N/A
identifier = Discord_Overlay_OpenGuildInvite();
The code sample above save the identifier that can be used inside an Async Social Event.
if (async_load[? "type"] == "Discord_Overlay_OpenGuildInvite")
if(async_load[? "identifier"] == identifier)
{
if (async_load[? "status"] == Discord_OK)
{
show_debug_message(async_load[? "type"] + " succeeded!");
}
else
{
show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
}
}
The code above matches the response against the correct event type and logs the success of the task.
Opens the overlay widget for voice settings for the currently connected application. These settings are unique to each user within the context of your application. That means that a user can have different favorite voice settings for each of their games!
Discord_Overlay_OpenVoiceSettings()
N/A
Async Social Event of type
Discord_Overlay_OpenVoiceSettings
identifier = Discord_Overlay_OpenVoiceSettings();
The code sample above saves the identifier that can be used inside an Async Social Event.
if (async_load[? "type"] == "Discord_Overlay_OpenVoiceSettings")
if (async_load[? "identifier"] == identifier)
{
if (async_load[? "status"] == Discord_OK)
{
show_debug_message(async_load[? "type"] + " succeeded!");
}
else
{
show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
}
}
The code above matches the response against the correct event type and logs the success of the task.
Locks or unlocks input in the overlay. Calling Discord_Overlay_SetLocked(true) will also close any modals in the overlay or in-app from things like IAP purchase flows and disallow input.
Discord_Overlay_SetLocked(value)
| Argument | Type | Description |
|---|---|---|
| value | bool | true: locked or false: unlocked |
identifier = Discord_Overlay_SetLocked();
The code sample above save the identifier that can be used inside an Async Social Event.
if (async_load[? "type"] == "Discord_Overlay_SetLocked")
if (async_load[? "identifier"] == identifier)
{
if (async_load[? "status"] == Discord_OK)
{
show_debug_message(async_load[? "type"] + " succeeded!");
}
else
{
show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
}
}
The code above matches the response against the correct event type and logs the success of the task.
| Key | Type | Description |
|---|---|---|
| result | real | Result code of the async request |
| type | string | "Discord_Overlay_OpenGuildInvite" |
| Key | Type | Description |
|---|---|---|
| id | real | The asynchronous request ID |
| type | string | "Discord_Overlay_SetLocked" |
| Key | Type | Description |
|---|---|---|
| result | real | Result code of the async request |
| success | boolean | Whether the request was successful |
| type | string | "Discord_Overlay_OpenVoiceSettings" |
Discord_Users_GetCurrentUserDiscord_Users_GetCurrentUserPremiumTypeDiscord_Users_GetUserDiscord_Users_SetCurrentUsernameFetch information about the currently connected user account.
Discord_Users_GetCurrentUser()
struct = Discord_User_GetCurrentUser();
username = struct.username;
bot = struct.bot;
userId = struct.userId;
discriminator = struct.discriminator;
Get the PremiumType for the currently connected user.
Discord_Users_GetCurrentUserPremiumType()
switch(Discord_User_GetCurrentUserPremiumType())
{
case Discord_PremiumType_None:
show_debug_message("User is not a Nitro subscriber");
break;
case Discord_PremiumType_Tier1:
show_debug_message("User has Nitro Classic");
break;
case Discord_PremiumType_Tier2:
show_debug_message("User has Nitro");
break;
}
Get user information for a given id.
This is an asynchronous function that will trigger the Async Social Event when the task is finished, after which you can use the following functions.
Discord_Users_GetUser(userId)
| Argument | Type | Description |
|---|---|---|
| userId | int64 | Identifier of the user |
N/A
Discord_Users_GetUser(userId);
The code sample above save the identifier that can be used inside an Async Social Event.
if (async_load[? "type"] == "Discord_User_GetUser")
{
if (async_load[? "result"] == Discord_OK)
{
show_debug_message(async_load[? "type"] + " succeeded!");
show_debug_message(async_load[? "user"]);
}
else
{
show_debug_message(async_load[? "type"] + " failed!");
}
}
The code above matches the response against the correct event type and logs the success of the task.
Set the current user's username information.
Discord_Users_SetCurrentUsername(name)
| Argument | Type | Description |
|---|---|---|
| username | string | The new username to be applied to the current user. |
Discord_User_SetCurrentUsername("SuperUser");
The code sample above will update the current user's username.
This extension has functions that return a data structure containing information about a Discord user.
Discord_User_GetCurrentUserDiscord_User_GetUserDiscord_Relationship_GetAtDiscord_Relationship_Get| Field | Type | Description |
|---|---|---|
| userId | int64 | The unique ID assigned to the user by Discord. |
| username | string | The username of the user, which is the name displayed on their profile and in chat messages. |
| discriminator | string | The four-digit number that appears after the username, used to distinguish between users with the same username. |
| avatar | string | The hash of the user's avatar image. |
| bot | bool | A boolean value indicating whether the user is a bot account or a human user. |
The Presence struct contains information about a user's current online status and activity.
| Field | Type | Description |
|---|---|---|
| Status | UserStatus | The user's current online status. |
| Activity | Activity | The user's current activity, if any. |
| Key | Datatype | Description |
|---|---|---|
| result | real | Result code of the async request |
| type | string | "Discord_User_GetUser" |
| user | User | The user data |
This async event is triggered whenever the user struct of the currently connected user changes.
They may have changed their avatar, username, or something else.
| Key | Datatype | Description |
|---|---|---|
| result | real | Result code of the async request |
| type | string | "Discord_Users_OnCurrentUserUpdate" |
The Status enum represents the online status of a user on Discord, including Online, Offline, Idle, and DoNotDisturb.
| Constant | Value | Description |
|---|---|---|
| Discord_UserStatus_Offline | 0 | The user is offline. |
| Discord_UserStatus_Online | 1 | The user is online. |
| Discord_UserStatus_Idle | 2 | The user is idle (i.e., away from keyboard or has been inactive for a certain amount of time). |
| Discord_UserStatus_DoNotDisturb | 3 | The user is in "do not disturb" mode, indicating that they do not want to be disturbed or receive notifications. |
The PremiumType enum describes the type of Nitro subscription a user has. It has the following values and descriptions:
| Constant | Value | Description |
|---|---|---|
| Discord_PremiumType_None | 0 | Not a Nitro subscriber |
| Discord_PremiumType_Tier1 | 1 | Nitro Classic subscriber |
| Discord_PremiumType_Tier2 | 2 | Nitro subscriber |
| Discord_PremiumType_Tier3 | 3 | Nitro Basic subscriber (formerly Nitro) |
Discord_Activities_UpdateActivityDiscord_Activities_AcceptInviteDiscord_Activities_ClearActivityDiscord_Activities_SendInviteDiscord_Activities_SendRequestReplyDiscord_Activities_UpdateActivityDiscord_Activities_AcceptInviteDiscord_Activities_ClearActivityDiscord_Activities_SendInviteDiscord_Activities_SendRequestReply
Sets a user's presence in Discord to a new activity.
This is an asynchronous function that will trigger the Async Social Event when the task is finished, after which you can use the following functions.
ℹ️ INFO It is possible for users to hide their presence on Discord (User Settings -> Game Activity). Presence set through this SDK may not be visible when this setting is toggled off.
⚠️ IMPORTANT This has a rate limit of 5 updates per 20 seconds.
Discord_Activities_UpdateActivity(activityData)
| Argument | Type | Description |
|---|---|---|
| activityData | ActivityData struct | The data to be applied to the user's activity |
N/A
Async Social Event of type
Discord_Activities_UpdateActivity
Discord_Activity_UpdateActivity({
state: "Creating Games",
type: Discord_Activity_Type_Playing,
details: "Details...",
smallImage: "mySmallImageName",
smallText: "mySmallText",
largeImage: "myLargeImageName",
largeText: "myLargeText"
});
The code sample above saves the identifier that can be used inside an Async Social Event.
if (async_load[? "type"] == "Discord_Activity_UpdateActivity")
{
if (async_load[? "result"] == Discord_OK)
{
show_debug_message(async_load[? "type"] + " succeeded!");
}
else
{
show_debug_message(async_load[? "type"] + " failed!");
}
}
The code above matches the response against the correct event type and logs the success of the task.
Accepts a game invitation from a given userId.
This is an asynchronous function that will trigger the Async Social Event when the task is finished, after which you can use the following functions.
Discord_Activities_AcceptInvite(userId)
| Argument | Type | Description |
|---|---|---|
| userId | int64 | The id of the user who invited you |
N/A
Discord_Activities_AcceptInvite(userId);
Clears a user's presence in Discord to make it show nothing.
This is an asynchronous function that will trigger the Async Social Event when the task is finished, after which you can use the following functions.
Discord_Activities_ClearActivity()
N/A
Discord_Activities_ClearActivity();
Sends a game invite to a given user. If you do not have a valid activity with all the required fields, this call will error. See Activity Action Field Requirements for the fields required to have join and spectate invites function properly.
Discord_Activities_SendInvite(userId, type, content)
| Argument | Type | Description |
|---|---|---|
| userId | int64 | the id of the user to invite |
| type | ActivityActionType | marks the invite as an invitation to join or spectate |
| content | string | a message to send along with the invite |
N/A
Discord_Activities_SendInvite(otherUserId, Discord_ActivityActionType_Join, "Come join my awesome game!")
Sends a reply to an Ask to Join request.
This is an asynchronous function that will trigger the Async Social Event when the task is finished, after which you can use the following functions.
Discord_Activities_SendRequestReply(userId, requestReply)
| Key | Datatype | Description |
|---|---|---|
| userId | int64 | The user id of the person who asked to join |
| reply | ActivityJoinRequestReply |
No, Yes or Ignore |
N/A
Async Social Event of type
Discord_Activities_SendRequestReply
Discord_Activities_SendRequestReply(otherUserId, Discord_ActivityJoinRequestReply_Yes);
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Activities_UpdateActivity" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Activities_AcceptInvite" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Activities_ClearActivity" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Activities_SendInvite" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Activities_SendRequestReply" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| Field | Type | Description |
|---|---|---|
| state | string | The state of the user activity. |
| type | ActivityType | The type of the user activity. |
| details | string | The details of the user activity. |
| smallImage | string | The user's small image asset value (see Activity Asset Image). |
| smallText | string | The user's small image tooltip. |
| largeImage | string | The user's larger image asset value (see Activity Asset Image). |
| largeText | string | The user's larger image tooltip. |
The Activity struct contains information about a user's current activity, including the application ID, name of the application, current party status, what the player is currently doing, timestamps, assets to display on the player's profile, party information, and secret passwords for joining and spectating the player's game.
| Key | Datatype | Description |
|---|---|---|
| applicationId | int64 | Your application ID. This is a read-only field. |
| name | string | Name of the application. This is a read-only field. |
| state | string | The player's current party status. |
| details | string | What the player is currently doing. |
| timestamps | ActivityTimestamps | Helps create elapsed/remaining timestamps on a player's profile. |
| assets | ActivityAssets | Assets to display on the player's profile. |
| party | ActivityParty | Information about the player's party. |
| secrets | ActivitySecrets |
Secret passwords for joining and spectating the player's game. |
| instance | bool | Whether this activity is an instanced context, like a match. |
The ActivityTimestamps struct is used to create elapsed/remaining timestamps on a player's profile. It contains two fields: Start and End, both of which are Unix timestamps.
| Key | Datatype | Description |
|---|---|---|
| startTimestamp | int64 | Unix timestamp - send this to have an "elapsed" timer |
| endTimestamp | int64 | Unix timestamp - send this to have a "remaining" timer |
The ActivityAssets struct contains assets to display on a player's profile, including both large and small images and corresponding hover text.
| Key | Datatype | Description |
|---|---|---|
| largeImage | string | The key for the large image asset |
| largeText | string | The text to display when hovering over the asset |
| smallImage | string | The key for the small image asset |
| smallText | string | The text to display when hovering over the asset |
The ActivityParty struct contains information about the player's party, including a unique identifier and party size.
| Key | Datatype | Description |
|---|---|---|
| partyId | string | A unique identifier for this party |
| size | Struct.PartySize | Info about the size of the party |
The PartySize struct contains information about the size of a party, including both the current size and maximum possible size.
| Key | Datatype | Description |
|---|---|---|
| currentSize | int32 | The current size of the party. |
| maxSize | int32 | The max possible size of the party. |
The ActivitySecrets struct contains secret passwords for joining and spectating the player's game, as well as a unique hash for the given match context.
| Key | Datatype | Description |
|---|---|---|
| match | string | unique hash for the given match context |
| join | string | unique hash for chat invites and Ask to Join |
| spectate | string | unique hash for Spectate button |
This represents the type of a user activity and is to be used with Discord_Activities_UpdateActivity.
| Constant | Value | Description |
|---|---|---|
| Discord_ActivityType_Playing | 0 | Represents the playing activity type; useful when user is playing games. |
| Discord_ActivityType_Streaming | 1 | Represents the streaming activity type; useful when user is streaming on discord, twitch or other platforms. |
| Discord_ActivityType_Listening | 2 | Represents the listening activity type; useful when user is listening to music on spotify or other platforms. |
| Discord_ActivityType_Watching | 3 | Represents the watching activity type; useful when user is watching their favorite shows. |
| Discord_ActivityType_Custom | 4 | Represents any custom activity type |
| Discord_ActivityType_Competing | 5 | Represents the competing activity type |
This represents the type of activity action and is to be used with Discord_Overlay_OpenActivityInvite.
| Constant | Value | Description |
|---|---|---|
| Discord_ActivityActionType_Join | 1 | Represents the action of joining an activity. |
| Discord_ActivityActionType_Spectate | 2 | Represents the action of spectating an activity. |
The ActivityJoinRequestReply enum provides options for how to respond to a user's request to join an activity.
| Constant | Value | Description |
|---|---|---|
| Discord_ActivityJoinRequestReply_No | 0 | Do not join |
| Discord_ActivityJoinRequestReply_Yes | 1 | Join |
| Discord_ActivityJoinRequestReply_Ignore | 2 | Ignore the join request |
Discord_Relationships_FilterDiscord_Relationships_CountDiscord_Relationships_GetDiscord_Relationships_GetAtThis function performs a query over the relationships of the current user selection only the ones that match the given type.
Discord_Relationships_Filter(type)
| Argument | Type | Description |
|---|---|---|
| type | Discord_RelationshipType |
The type of relationship to filter when performing the query |
N/A
Discord_Relationship_Filter(Discord_RelationshipType_Friend);
count = Discord_Relationships_Count();
for(var a = 0 ; a < count ; a++)
{
var struct = Discord_Relationships_GetAt(a);
type = struct.type;
username = struct.username;
avatar = struct.avatar;
id = struct.id;
bot = struct.bot;
discriminator = struct.discriminator;
//Do something each loop with this information..
}
Get the number of relationships that match your previous query.
Discord_Relationships_Count()
Discord_Relationships_Filter(Discord_Relationship_Filter_Friend);
count = Discord_Relationships_Count();
for(var a = 0 ; a < count ; a++)
{
var struct = Discord_Relationships_GetAt(a);
type = struct.type;
username = struct.username;
avatar = struct.avatar;
id = struct.id;
bot = struct.bot;
discriminator = struct.discriminator;
//Do something each loop with this information..
}
Get the relationship between the current user and a given user by id.
Discord_Relationships_Get(userId)
| Argument | Type | Description |
|---|---|---|
| userId | int64 | User identifier |
Relationship struct
var struct = Discord_Relationships_getAt(userId);
type = struct.type;
username = struct.username;
avatar = struct.avatar;
userId = struct.userId;
bot = struct.bot;
discriminator = struct.discriminator;
Get the relationship at a given index when iterating over a list of relationships.
⚠️ REQUIRES This function requires a previous call to the function Discord_Relationships_Filter.
Discord_Relationships_GetAt(index)
| Argument | Type | Description |
|---|---|---|
| indx | int | Index of the relationship |
Relationshipstruct
Discord_Relationships_Filter(Discord_RelationshipType_Friend);
count = Discord_Relationship_Count()
for(var a = 0 ; a < count ; a++)
{
var struct = Discord_Relationship_GetAt(a)
type = struct.type
username = struct.username
avatar = struct.avatar
userId = struct.id
bot = struct.bot
discriminator = struct.discriminator
//Do something each loop with this information..
}
The Relationship structure returned by the following functions:
contains information about the user with whom the connected user has a relationship. The structure includes the user's username, avatar, user ID, whether they are a bot or not, and their discriminator.
The "username" field contains the username of the user, which is the name displayed on their profile and in chat messages. The "avatar" field contains the URL of the user's avatar image. The "userId" field contains the unique user ID assigned by Discord. The "bot" field is a boolean value indicating whether the user is a bot account or a human user. The "discriminator" field contains the four-digit number that appears after the username, used to distinguish between users with the same username.
Here is a table summarizing the fields in the "relationship" structure and their meanings:
| Field | Type | Description |
|---|---|---|
| type | Discord_RelationshipType | The username of the user, which is the name displayed on their profile and in chat messages. |
| user | User |
The user the relationship is for. |
| presence | Presence |
That user's current presence |
| Constant | Value | Description |
|---|---|---|
| Discord_RelationshipType_None | 0 | User has no intrinsic relationship on Discord. |
| Discord_RelationshipType_Friend | 1 | User is a friend of the connected user, and they can see each other's online status, send direct messages, etc. |
| Discord_RelationshipType_Blocked | 2 | User is blocked by the connected user and cannot interact with them on Discord. |
| Discord_RelationshipType_PendingIncoming | 3 | User has sent a friend request to the connected user, but it has not yet been accepted. |
| Discord_RelationshipType_PendingOutgoing | 4 | Connected user has sent a friend request to the other user, but it has not yet been accepted. |
| Discord_RelationshipType_Implicit | 5 | Users are not friends but interact with each other often, based on frequency and recency of interactions. |
Prepares an image to later retrieve data about it.
Discord_Images_Fetch(userId, size)
| Argument | Type | Description |
|---|---|---|
| userId | int64 | The ID of the user whose avatar you want to get. |
| size | real | The resolution at which you want the image (needs to be a power of 2) |
N/A
// Create Event /////////////////////////////////////////////
Discord_Images_Fetch(userId, 64);
// Async Event /////////////////////////////////////////////
if(async_load[?"result"] == Discord_OK)
switch(async_load[?"type"])
{
case "Discord_Images_Fetch":
// If user ids don't match bail
if (userId != async_load[?"userId"]) exit;
var buffer = async_load[?"buffer"];
surf = surface_create(async_load[?"width"], async_load[?"height"]);
buffer_set_surface(buffer, surf, 0);
buffer_delete(buffer);
break;
}
| Key | Datatype | Description |
|---|---|---|
| type | string | "Discord_Images_Fetch" |
| result | real | Result code of the async request. |
| success | bool | Whether the current request was successful or not. |
| userId | int64 | The ID of the user whose avatar you requested. |
| width | real | The width of the avatar image |
| height | real | The height of the avatar image |
| buffer | Buffer ID | A buffer containing the avatar image data. |