Game SDK

Welcome to the documentation for the Discord Game SDK! We're glad you made it. The Game SDK helps you develop your 3rd party game or app, and integrate it with Discord.

This section will walk you through the first few steps you need to take to get up-and-running with the Game SDK. After you download the SDK and configure your app, you can find more details in the Using the SDK section.

Now, let's get started. First, get the SDK. Here it is:

• Discord Game SDK v3.2.1 - Latest version, includes Apple silicon (aarch64) support
• Discord Game SDK v2.5.6 - Try this version if you encounter bugs on the latest version

There's a few things in there, but let's quickly talk about what the SDK actually is. Inside the lib/ folder, you'll see x86/ and x86_64/ that have some .lib, .bundle, and .dll files. These are the things you want to distribute with your game.

These files are comprised of two parts: a "stub", and fallback modules. What that means is that when everything is running smoothly, the DLLs will just call back to the local running Discord client to do the heavy lifting. If, however, something is wrong, like a breaking change, the files also include "fallback" modules that reflect the native SDK modules in Discord at the time that version of the SDK was published. TLDR - you don't need to worry about breaking changes.

Next, we need to set up the application for your game. An app is the base "entity" in Discord for your game.

Head over to our developer site and create an account/log in if you haven't yet. The first thing we're going to do is create a Team. Teams are groups of developers working together on applications; you should create a team for your organization at https://discord.com/developers/teams. You can invite other users to join your team and work on applications together with you.

Now that your team is created, you'll want to make an application. To do so, click on "Applications" at the top of the page and create an application. Make sure you pick your newly-created team in the Team dropdown. You want your team to own the application! Now that your app is made, let's dive into some more setup.

First, we'll need to set an OAuth2 redirect URL. You can add http://127.0.0.1 in there for now; this powers some behind-the-scenes stuff you don't need to worry about.

Next, copy the Client ID at the top of the page. This id, also referred to as an "application id", is your game's unique identifier across Discord. Keep it handy!

While you're here, head to the "OAuth2" section of your application and add http://127.0.0.1 as a redirect URI for your application. This will allow us to do the OAuth2 token exchange within the Discord client.

Before you start developing, there are a couple of notes to keep in mind about the SDK:

• All strings in the SDK are UTF8 strings. Make sure you've converted properly if necessary!
• The SDK is NOT threadsafe!

With that out of the way, let's start coding. Didn't think we'd get there so fast, did ya? Think again! The dropdowns are code primers for the main languages of the SDK: C#, C, and C++. They'll get you up and running with the most basic examples, and then you're off to the races.

/*
    Grab that Client ID from earlier
    Discord.CreateFlags.Default will require Discord to be running for the game to work
    If Discord is not running, it will:
    1. Close your game
    2. Open Discord
    3. Attempt to re-open your game
    Step 3 will fail when running directly from the Unity editor
    Therefore, always keep Discord running during tests, or use Discord.CreateFlags.NoRequireDiscord
*/
var discord = new Discord.Discord(CLIENT_ID, (UInt64)Discord.CreateFlags.Default);

/*
    Grab that Client ID from earlier
    Discord.CreateFlags.Default will require Discord to be running for the game to work
    If Discord is not running, it will:
    1. Close your game
    2. Open Discord
    3. Attempt to re-open your game
    Step 3 may fail when running directly from your editor
    Therefore, always keep Discord running during tests, or use Discord.CreateFlags.NoRequireDiscord
*/
var discord = new Discord.Discord(CLIENT_ID, (UInt64)Discord.CreateFlags.Default);

#pragma pack(push, 8)
#include "discord_game_sdk.h"
#pragma pack(pop)

struct Application {
    struct IDiscordCore* core;
    struct IDiscordUsers* users;
};

struct Application app;
// Don't forget to memset or otherwise initialize your classes!
memset(&app, 0, sizeof(app));

struct IDiscordCoreEvents events;
memset(&events, 0, sizeof(events));

struct DiscordCreateParams params;
params.client_id = CLIENT_ID;
params.flags = DiscordCreateFlags_Default;
params.events = &events;
params.event_data = &app;

DiscordCreate(DISCORD_VERSION, &params, &app.core);

/*
    ABSOLUTE_PATH_TO_DISCORD_FILES_DIRECTORY will look something like:

    "H:\\Unreal Projects\\Game SDKtest\\Source\\Game SDKtest\\discord-files\\"

    You should get this value programmatically
*/
PublicIncludePaths.Add(ABSOLUTE_PATH_TO_DISCORD_FILES_DIRECTORY)

/*
    ABSOLUTE_PATH_TO_LIB_FILE will look something like:

    "H:\\Unreal Projects\\Game SDKtest\\Binaries\\Win64\\discord_game_sdk.dll.lib"

    You should get this value programmatically
*/
PublicAdditionalLibraries.Add(ABSOLUTE_PATH_TO_LIB_FILE)

#include "MyPawn.h"
#include "discord-files/discord.h"

discord::Core* core{};

AMyPawn::AMyPawn()
{
  // Set this pawn to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
  PrimaryActorTick.bCanEverTick = true;
}

// Called when the game starts or when spawned
void AMyPawn::BeginPlay()
{
  Super::BeginPlay();
  /*
      Grab that Client ID from earlier
      Discord.CreateFlags.Default will require Discord to be running for the game to work
      If Discord is not running, it will:
      1. Close your game
      2. Open Discord
      3. Attempt to re-open your game
      Step 3 will fail when running directly from the Unreal Engine editor
      Therefore, always keep Discord running during tests, or use Discord.CreateFlags.NoRequireDiscord
  */
  auto result = discord::Core::Create(461618159171141643, DiscordCreateFlags_Default, &core);
  discord::Activity activity{};
  activity.SetState("Testing");
  activity.SetDetails("Fruit Loops");
  core->ActivityManager().UpdateActivity(activity, [](discord::Result result) {

  });
}

// Called every frame
void AMyPawn::Tick(float DeltaTime)
{
  Super::Tick(DeltaTime);
  ::core->RunCallbacks();
}

// Called to bind functionality to input
void AMyPawn::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
  Super::SetupPlayerInputComponent(PlayerInputComponent);
}

At a high level, the Discord Game SDK has a parent class, Discord.

This class is in charge of the creation of a few "manager" sub-classes to interact with Discord.

Each manager class contains its own functions and events used to interact with Discord in the context of the manager:

Most functions in the Discord Game SDK, uh, function in a similar way. They take whatever parameters are required for the function to do its job—a user id, the requested size for an image, etc.—and a callback by means of a function pointer. That callback is fired when the function completes its work, letting you handle events without worrying about piping asynchronously-returned data to the right context.

Some functions behave with a normal return behavior; e.g. RelationshipManager.Count() just returns the number directly. Don't worry, it's outlined in the docs.

var userManager = discord.GetUserManager();

// Return via callback
userManager.GetUser(290926444748734465, (Discord.Result result, ref Discord.User otherUser) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine(otherUser.Username);
    Console.WriteLine(otherUser.Id);
  }
});


// Return normally
userManager.OnCurrentUserUpdate += () =>
{
    var currentUser = userManager.GetCurrentUser();
        Console.WriteLine(currentUser.Username);
        Console.WriteLine(currentUser.Discriminator);
        Console.WriteLine(currentUser.Id);
};

Discord passes a number of environment variables down to the SDK. These are accessed by various functions in the SDK and can be changed for local testing by changing the value in your local environment.

Debugging is a pain, so before we get into the meat of the SDK, we want to make sure you're prepared for when things go awry. Within the Discord core is a function called SetLogHook(). It takes a level, which is minimum level of log message you want to listen to, and a callback function:

public void LogProblemsFunction(Discord.LogLevel level, string message)
{
  Console.WriteLine("Discord:{0} - {1}", level, message);
}

discord.SetLogHook(Discord.LogLevel.Debug, LogProblemsFunction);

While integrating the Discord Game SDK, you will probably find yourself wanting to test functionality between two game clients locally, be it for networking, Rich Presence, etc.

We know that getting a test build of a game on two separate machines can be both difficult and cumbersome. So, we've got a solution for you!

// This machine opened Discord Canary first, and Discord PTB second

// This makes the SDK connect to Canary
System.Environment.SetEnvironmentVariable("DISCORD_INSTANCE_ID", "0");
var discord = new Discord(applicationId, Discord.CreateFlags.Default);

// This makes the SDK connect to PTB
System.Environment.SetEnvironmentVariable("DISCORD_INSTANCE_ID", "1");
var discord = new Discord(applicationId, Discord.CreateFlags.Default);

Creates an instance of Discord to initialize the SDK. This is the overlord of all things Discord. We like to call her Nelly.

Returns a new Discord.

// c++ land
discord::Core* core{};
discord::Core::Create(53908232506183680, DiscordCreateFlags_Default, &core);

// c# land
var discord = new Discord(53908232506183680, (UInt64)Discord.CreateFlags.Default);

Destroys the instance. Wave goodbye, Nelly! You monster. In C# land, this is Dispose().

Returns void.

discord.Dispose();

Registers a logging callback function with the minimum level of message to receive. The callback function should have a signature of:

MyCallbackFunction(LogLevel level, string message);

Returns void.

public void LogProblemsFunction(Discord.LogLevel level, string message)
{
  Console.WriteLine("Discord:{0} - {1}", level, message);
}

discord.SetLogHook(Discord.LogLevel.Debug, LogProblemFunctions);

Runs all pending SDK callbacks. Put this in your game's main event loop, like Update() in Unity. That way, the first thing your game does is check for any new info from Discord.

This function also serves as a way to know that the local Discord client is still connected. If the user closes Discord while playing your game, RunCallbacks() will return/throw Discord.Result.NotRunning.

In C and C++, this function returns Discord.Result. In C#, it returns void and will throw Discord.Result error if something went wrong.

void Update()
{
  discord.RunCallbacks();
}

Fetches an instance of the manager for interfacing with activities in the SDK.

Returns an ActivityManager.

var activityManager = discord.GetActivityManager();

Fetches an instance of the manager for interfacing with users in the SDK.

Returns an UserManager.

var userManager = discord.GetUserManager();

Fetches an instance of the manager for interfacing with the overlay in the SDK.

Returns an OverlayManager.

var overlayManager = discord.GetOverlayManager();

Looking to integrate Rich Presence into your game? No need to manage multiple SDKs—this one does all that awesome stuff, too! Delight your players with the ability to post game invites in chat and party up directly from Discord. Surface interesting live game data in their profile for their friends, encouraging them to group up and play together.

For more detailed information and documentation around the Rich Presence feature set and integration tips, check out our Rich Presence Documentation.

For more details about the activity types, see Gateway documentation.

ActivityType is strictly for the purpose of handling events that you receive from Discord; though the SDK will not reject a payload with an ActivityType sent, it will be discarded and will not change anything in the client.

If you want to hook up joining and spectating for your games, there are certain fields in the activity payload that need to be sent. Refer to the following handy table for what needs to be set for certain actions.

Registers a command by which Discord can launch your game. This might be a custom protocol, like my-awesome-game://, or a path to an executable. It also supports any launch parameters that may be needed, like game.exe --full-screen --no-hax.

On macOS, due to the way Discord registers executables, your game needs to be bundled for this command to work. That means it should be a .app.

Returns void.

activityManager.RegisterCommand("my-awesome-game://run --full-screen");

Used if you are distributing this SDK on Steam. Registers your game's Steam app id for the protocol steam://run-game-id/<id>.

Returns void.

activityManager.RegisterSteam(1938123);

Sets a user's presence in Discord to a new activity. This has a rate limit of 5 updates per 20 seconds.

Returns a Discord.Result via callback.

var activity = new Discord.Activity
{
  State = "In Play Mode",
  Details = "Playing the Trumpet!",
  Timestamps =
  {
      Start = 5,
  },
  Assets =
  {
      LargeImage = "foo largeImageKey", // Larger Image Asset Value
      LargeText = "foo largeImageText", // Large Image Tooltip
      SmallImage = "foo smallImageKey", // Small Image Asset Value
      SmallText = "foo smallImageText", // Small Image Tooltip
  },
  Party =
  {
      Id = "foo partyID",
      Size = {
          CurrentSize = 1,
          MaxSize = 4,
      },
  },
  Secrets =
  {
      Match = "foo matchSecret",
      Join = "foo joinSecret",
      Spectate = "foo spectateSecret",
  },
  Instance = true,
};

activityManager.UpdateActivity(activity, (result) =>
{
    if (result == Discord.Result.Ok)
    {
        Console.WriteLine("Success!");
    }
    else
    {
        Console.WriteLine("Failed");
    }
});

Clear's a user's presence in Discord to make it show nothing.

Results a Discord.Result via callback.

activityManager.ClearActivity((result) =>
{
    if (result == Discord.Result.Ok)
    {
        Console.WriteLine("Success!");
    }
    else
    {
        Console.WriteLine("Failed");
    }
});

Sends a reply to an Ask to Join request.

Returns a Discord.Result via callback.

activityManager.OnActivityJoinRequest += user =>
{
    Console.WriteLine("Join request from: {0}", user.Id);
    activityManager.SendRequestReply(user.Id, Discord.ActivityJoinRequestReply.Yes, (res) =>
    {
      if (res == Discord.Result.Ok)
      {
        Console.WriteLine("Responded successfully");
      }
    });
}

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.

Returns a Discord.Result via callback.

var userId = 53908232506183680;
activityManager.SendInvite(userId, Discord.ActivityActionType.Join, "Come play!", (result) =>
{
    if (result == Discord.Result.Ok)
    {
        Console.WriteLine("Success!");
    }
    else
    {
        Console.WriteLine("Failed");
    }
});

Accepts a game invitation from a given userId.

Returns a Discord.Result via callback.

activityManager.AcceptInvite(290926444748734466, (result) =>
{
    if (result == Discord.Result.Ok)
    {
        Console.WriteLine("Success!");
    }
    else
    {
        Console.WriteLine("Failed");
    }
});

Fires when a user accepts a game chat invite or receives confirmation from Asking to Join.

// Received when someone accepts a request to join or invite.
// Use secrets to receive back the information needed to add the user to the group/party/match
activityManager.OnActivityJoin += secret => {
    Console.WriteLine("OnJoin {0}", secret);
    // Now update your internal systems to reflect the user as joined

		// Sends this off to a Activity callback named here as 'UpdateActivity' passing in the discord instance details
    UpdateActivity(discord);
};

void UpdateActivity(Discord.Discord discord)
    {
    	//Creates a Static String for Spectate Secret.
        string discordSpectateSecret = "wdn3kvj320r8vk3";
        spectateActivitySecret = discordSpectateSecret;
        var activity = new Discord.Activity
        {
            State = "Playing Co-Op",
            Details = "In a Multiplayer Match!",
            Timestamps =
            {
                Start = startTimeStamp,
            },
            Assets =
            {
                LargeImage = "matchimage1",
                LargeText = "Inside the Arena!",
            },
            Party = {
                Id = <Party/match/group id here>,
                Size = {
                    CurrentSize = ...,
                    MaxSize = ...,
                },
            },
            Secrets = {
                Spectate = spectateActivitySecret,
                Join = joinActivitySecret,
            },
            Instance = true,
        };

        activityManager.UpdateActivity(activity, result =>
        {
            Debug.LogFormat("Updated to Multiplayer Activity: {0}", result);

            // Send an invite to another user for this activity.
            // Receiver should see an invite in their DM.
            // Use a relationship user's ID for this.
            // activityManager
            //   .SendInvite(
            //       364843917537050624,
            //       Discord.ActivityActionType.Join,
            //       "",
            //       inviteResult =>
            //       {
            //           Console.WriteLine("Invite {0}", inviteResult);
            //       }
            //   );
        });
    }

Fires when a user accepts a spectate chat invite or clicks the Spectate button on a user's profile.

// Received when someone accepts a request to spectate
activityManager.OnActivitySpectate += secret =>
{
    Console.WriteLine("OnSpectate {0}", secret);
};

Fires when a user asks to join the current user's game.

// A join request has been received. Render the request on the UI.
activityManager.OnActivityJoinRequest += (ref Discord.User user) =>
{
    Console.WriteLine("OnJoinRequest {0} {1}", user.Username, user.Id);
};

Fires when the user receives a join or spectate invite.

// An invite has been received. Consider rendering the user / activity on the UI.
activityManager.OnActivityInvite += (Discord.ActivityActionType Type, ref Discord.User user, ref Discord.Activity activity2) =>
{
      Console.WriteLine("Received Invite Type: {0}, from User: {1}, with Activity Name: {2}", Type, user.Username, activity2.Name);
      // activityManager.AcceptInvite(user.Id, result =>
      // {
      //     Console.WriteLine("AcceptInvite {0}", result);
      // });
};

var discord = new Discord.Discord(clientId, Discord.CreateFlags.Default);

// Update user's activity for your game.
// Party and secrets are vital.
var activity = new Discord.Activity
{
  State = "olleh",
  Details = "foo details",
  Timestamps =
  {
      Start = 5,
      End = 6,
  },
  Assets =
  {
      LargeImage = "foo largeImageKey",
      LargeText = "foo largeImageText",
      SmallImage = "foo smallImageKey",
      SmallText = "foo smallImageText",
  },
  Party =
  {
      Id = "foo partyID",
      Size = {
          CurrentSize = 1,
          MaxSize = 4,
      },
  },
  Secrets =
  {
      Match = "foo matchSecret",
      Join = "foo joinSecret",
      Spectate = "foo spectateSecret",
  },
  Instance = true,
};

activityManager.UpdateActivity(activity, (result) =>
{
    Console.WriteLine("Update Activity {0}", result);

    // Send an invite to another user for this activity.
    // Receiver should see an invite in their DM.
    // Use a relationship user's ID for this.
    activityManager.SendInvite(364843917537050999, Discord.ActivityActionType.Join, "", (inviteUserResult) =>
    {
        Console.WriteLine("Invite User {0}", inviteUserResult);
    });
});

Discord comes with an awesome built-in overlay, and you may want to make use of it for your game. This manager will help you do just that! It gives you the current state of the overlay for the user, and allows you to update that state.

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.

Returns a bool.

if (!overlaymanager.IsEnabled())
{
  Console.WriteLine("Overlay is not enabled. Modals will be shown in the Discord client instead");
}

Check if the overlay is currently locked or unlocked

if (overlayManager.IsLocked())
{
  overlayManager.SetLocked(true, (res) =>
  {
    Console.WriteLine("Input in the overlay is now accessible again");
  });
}

Locks or unlocks input in the overlay. Calling SetLocked(true); will also close any modals in the overlay or in-app from things like IAP purchase flows and disallow input.

Returns Discord.Result via callback.

overlayManager.SetLocked(true, (res) =>
{
  Console.WriteLine("Overlay has been locked and modals have been closed");
});

Opens 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.

Returns a Discord.Result via callback.

overlayManager.OpenActivityInvite(Discord.ActivityActionType.Join, (result) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine("User is now inviting others to play!");
  }
});

Opens the overlay modal for joining a Discord guild, given its invite code. An invite code for a server may look something like fortnite for a verified server—the full invite being discord.gg/fortnite—or something like rjEeUJq for a non-verified server, the full invite being discord.gg/rjEeUJq.

Returns a Discord.Result via callback. Note that a successful Discord.Result response does not necessarily mean that the user has joined the guild. If you want more granular control over and knowledge about users joining your guild, you may want to look into implementing the guilds.join OAuth2 scope in an authorization code grant in conjunction with the Add Guild Members endpoint.

overlayManager.OpenGuildInvite("rjEeUJq", (result) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine("Invite was valid.");
  }
});

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!

Returns a Discord.Result via callback.

overlayManager.OpenVoiceSettings((result) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine("Overlay is open to the voice settings for your application/")
  }
})

Fires when the overlay is locked or unlocked (a.k.a. opened or closed)

overlayManager.OnToggle += overlayLock =>
{
    Console.WriteLine("Overlay Locked: {0}", overlayLock);
};

var discord = new Discord.Discord(clientId, Discord.CreateFlags.Default);
var overlayManager = discord.GetOverlayManager();

// Invite users to join your game
overlayManager.OpenActivityInvite(ActivityActionType.Join, (result) =>
{
  Console.WriteLine("Overlay is now open!");
})

This manager helps retrieve basic user information for any user on Discord.

Fetch information about the currently connected user account. If you're interested in getting more detailed information about a user—for example, their email—check out our GetCurrentUser API endpoint. You'll want to call this with an authorization header of Bearer <token>, where <token> is the token retrieved from a standard OAuth2 Authorization Code Grant flow.

Returns a Discord.User.

var user = userManager.GetCurrentUser();
Console.WriteLine("Connected to user {0}", user.Id);

Get user information for a given id.

Returns a Discord.Result and ref Discord.User via callback.

userManager.GetUser(userId, (Discord.Result result, ref Discord.User user) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine("User {0} is {1}", user.Id, user.Username);
  }
});

Get the PremiumType for the currently connected user.

Returns Discord.PremiumType.

var userManager = discord.GetUserManager();
var premiumType = userManager.GetCurrentUserPremiumType();
switch (premiumType)
{
  case PremiumType.None:
    Console.WriteLine("User is not a Nitro subscriber");

  case PremiumType.Tier1:
    Console.WriteLine("User has Nitro Classic");

  case PremiumType.Tier2:
    Console.WriteLine("User has Nitro");

  default:
    return;
}

See whether or not the current user has a certain UserFlag on their account.

Returns bool.

var userManager = discord.GetUserManager();
if (userManager.CurrentUserHasFlag(Discord.UserFlag.HypeSquadHouse1))
{
  Console.WriteLine("User is a member of House Bravery!");
}

Fires when the User struct of the currently connected user changes. They may have changed their avatar, username, or something else.

var userManager = discord.GetUserManager();
// GetCurrentUser will error until this fires once.
userManager.OnCurrentUserUpdate += () => {
  var currentUser = userManager.GetCurrentUser();

  Console.WriteLine(currentUser.Username);
  Console.WriteLine(currentUser.Id);
  Console.WriteLine(currentUser.Discriminator);
  Console.WriteLine(currentUser.Avatar);
};

var discord = new Discord.Discord(clientId, Discord.CreateFlags.Default);

var userManager = discord.GetUserManager();
userManager.GetUser(450795363658366976, (Discord.Result result, ref Discord.User user) =>
{
  if (result == Discord.Result.Ok)
  {
    Console.WriteLine("user fetched: {0}", user.Username);
  }
  else
  {
    Console.WriteLine("user fetch error: {0}", result);
  }
});