Discover
Learn
Get
Create
Community
Login
Navigation

Learn

Learn

Published on 27th March 2024

This tutorial was written to go with the official Phaser Discord Template, which is a great starting point for creating games on Discord with Phaser, utilising their new Embedded App SDK. It helps you seamlessly integrate custom games and activities into your Discord server, fostering community engagement, interaction, and fun.

Our template closely follows the structure set out in the official Discord Building An Activity Developer Documentation. Follow along with the official documentation when you need more detailed information.

You can get a full overview of the Discord Embedded App SDK on the Discord Developer Portal.

Requirements

Node.js is required to install dependencies and run scripts via npm.

Creating A Discord App

First you need to create a Discord app via the Discord Developer Portal:

createdcapp

This app will house your game and allow you to create activities for your server.

Installation

To get started, clone the Phaser Discord Project Template:

git clone git@github.com:phaserjs/discord-template.git

Or download it using GitHub Desktop, or a similar GUI, from the main repository

Set OAuth2 Credentials

Once cloned you need to set your OAuth2 credentials in the .env file.

To do this, rename example.env to .env. Be careful to not include a double extension, this is a dot-file.

On Linux/MacOS you can do this via the terminal with the following command:

mv example.env .env

On Windows you can do this via the command prompt with the following command:

move example.env .env

Once you have renamed the file, open it in your text editor of choice and replace the placeholders with your OAuth2 credentials, as given on the Discord App -> OAuth2 page:

VITE_DISCORD_CLIENT_ID=YOUR_OAUTH2_CLIENT_ID_HERE
DISCORD_CLIENT_SECRET=YOUR_OAUTH2_CLIENT_SECRET_HERE

oauth2

Prefixing the DISCORD_CLIENT_ID environment variable with VITE_ makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. Read more in the Vite docs

Also, don't forget to set Redirect URI as https://127.0.0.1

redirects

Client Installation

With the environment set, you can now run the client in the browser:

cd client
npm install
npm run dev

This will start the Vite development server and open your default browser to the game. It will be served from http://localhost:5173

If everything is set up correctly, you should see a Phaser game running in the browser. Feel free to play with it however you like!

Initialize the Embedded App SDK

If you look in the client/package.json file you will see that the Embedded App SDK is already installed.

To use it, we need to instantiate the Embedded App SDK for the client. To do that, you need to uncomment the SDK code in the client/main.js file:

const discordSdk = new DiscordSDK(import.meta.env.VITE_DISCORD_CLIENT_ID);

setupDiscordSdk().then(() => {
  console.log("Discord SDK is ready");
});

async function setupDiscordSdk() {
  await discordSdk.ready();
}

Doing this will initialize the SDK and make it ready for use in your game. However, as a side effect, you will no longer be able to view your game directly from your web browser but will need to test it from within the Discord app itself.

Running the game locally in Discord

To run the game locally in Discord, you need to tunnel your local server to a public URL.

We recommend using cloudflared or ngrok for this purpose. In this example, we will use cloudflared.

If you haven't, you can install cloudflared locally or globally by using: 

npm i -g cloudflared

Then, you can run the following command to tunnel your local server:

cloudflared tunnel --url http://localhost:5173

If all goes well, you should see a message like this:

cloudflared

Note the part we have highlighted in the screenshot above. This is the public URL that your local server is available from. Take a copy of it.

Let's add this public URL to your Discord Activities -> URL Mappings admin page, as in the screenshot below:

urlmapping

This completes the loop between your local server and the Discord app, allowing you to test your game in Discord.

OAuth2 Server

In order to have OAuth2 working for authorization with Discord, let's install and run our local server. Open a new terminal and run the following commands:

cd server
npm install
npm run dev

This will start the OAuth2 server, which will handle the OAuth2 authorization flow with Discord.

Activate Developer Mode in Discord

For the final step, we need to activate Developer Mode inside of Discord, so we can view our game in the Activities section.

To do this, go to Discord Settings -> Advanced -> Developer Mode and ensure to toggle the control on.

activatedevelopermode

Launch your Activity!

Now for the fun part! Go into Discord, select a Voice Channel, and click the green 'Activity' icon to launch your game. Make sure you have allowed the channel to create Activities.

runactivity

You will see your game pop-up in the Activities section if everything has been set up correctly.

screenshot

Test With Other People

If you want your friends on Discord to try your game, you'll need to invite them to test the app. Do this by going to this part of the Discord Developer portal site:

Developer Portal -> Applications -> Your App -> App Testers -> Invite

Once they accept the invitation, they can join your Activity:

addtester

Have Fun!

This completes the process of getting started creating games on Discord with Phaser. We hope you have fun creating your game and engaging with your community.

At the time of writing, this Discord feature is still in Developer Preview, which means there are some limitations in place with regard to how large the server can be and so on. Please refer to the official Discord documentation for the most up-to-date information.

Please see our Discord Project Template for further instructions on configuring and using the project template.