Connect Evennia channels to Discord

Discord is a popular chat service, especially for game communities. If you have a discord server for your game, you can connect it to your in-game channels to communicate between in-game and out.

Configuring Discord

The first thing you’ll need is to set up a Discord bot to connect to your game. Go to the bot applications page and make a new application. You’ll need the “MESSAGE CONTENT” toggle flipped On, and to add your bot token to your settings.

# mygame/server/conf/secret_settings.py
DISCORD_BOT_TOKEN = '<your Discord bot token>'

You will also need the pyopenssl module, if it isn’t already installed. Install it into your Evennia python environment with

pip install pyopenssl

Lastly, enable Discord in your settings

DISCORD_ENABLED = True

Start/reload Evennia and log in as a privileged user. You should now have a new command available: discord2chan. Enter help discord2chan for an explanation of its options.

Adding a new channel link is done with the following command:

 discord2chan <evennia_channel> = <discord_channel_id>

The evennia_channel argument must be the name of an existing Evennia channel, and discord_channel_id is the full numeric ID of the Discord channel.

Your bot needs to be added to the correct Discord server with access to the channel in order to send or receive messages. This command does NOT verify that your bot has Discord permissions!

Step-By-Step Discord Setup

This section will walk through the entire process of setting up a Discord connection to your Evennia game, step by step. If you’ve completed any of the steps already, feel free to skip to the next.

Creating a Discord Bot Application

You will need an active Discord account and admin access to a Discord server in order to connect Evennia to it. This assumes you already do.

Make sure you’re logged in on the Discord website, then visit https://discord.com/developers/applications. Click the “New Application” button in the upper right corner, then enter the name for your new app - the name of your Evennia game is a good option.

You’ll next be brought to the settings page for the new application. Click “Bot” on the sidebar menu, then “Build-a-Bot” to create your bot account.

Save the displayed token! This will be the ONLY time that Discord will allow you to see that token - if you lose it, you will have to reset it. This token is how your bot confirms its identity, so it’s very important.

Next, add this token to your secret settings.

# file: mygame/server/conf/secret_settings.py

DISCORD_BOT_TOKEN = '<token>'

Once that is saved, scroll down the Bot page a little more and find the toggle for “Message Content Intent”. You’ll need this to be toggled to ON, or you bot won’t be able to read anyone’s messages.

Finally, you can add any additional settings to your new bot account: a display image, display nickname, bio, etc. You can come back and change these at any time, so don’t worry about it too much now.

Adding your bot to your server

While still in your new application, click “OAuth2” on the side menu, then “URL Generator”. On this page, you’ll generate an invite URL for your app, then visit that URL to add it to your server.

In the top box, find the checkbox for bot and check it: this will make a second permissions box appear. In that box, you’ll want to check off at least the following boxes:

  • Read Messages/View Channels (in “General Permissions”)

  • Send Messages (in “Text Permissions”)

Lastly, scroll down to the bottom of the page and copy the resulting URL. It should look something like this:

https://discord.com/api/oauth2/authorize?client_id=55555555555555555&permissions=3072&scope=bot

Visit that link, select the server for your Evennia connection, and confirm.

After the bot is added to your server, you can fine-tune the permissions further through the usual Discord server administration.

Activating Discord in Evennia

You’ll need to do two additional things with your Evennia game before it can connect to Discord.

First, install pyopenssl to your virtual environment, if you haven’t already.

pip install pyopenssl

Second, enable the Discord integration in your settings file.

# file: server/conf/settings.py
DISCORD_ENABLED = True

Start or reload your game to apply the changed settings, then log in as an account with at least Developer permissions and initialize the bot account on Evennia with the discord2chan command. You should receive a message that the bot was created, and that there are no active connections to Discord.

Connecting an Evennia channel to a Discord channel

You will need the name of your Evennia channel, and the channel ID for your Discord channel. The channel ID is the last part of the URL when you visit a channel.

e.g. if the url is https://discord.com/channels/55555555555555555/12345678901234567890 then your channel ID is 12345678901234567890

Link the two channels with the following command:

discord2chan <evennia channel> = <discord channel id>

The two channels should now relay to each other. Confirm this works by posting a message on the evennia channel, and another on the Discord channel - they should both show up on the other end.

If you don’t see any messages coming to or from Discord, make sure that your bot has permission to read and send messages and that your application has the “Message Content Intents” flag set.

Further Customization

The help file for discord2chan has more information on how to use the command to customize your relayed messages.

For anything more complex, however, you can create your own child class of DiscordBot and add it to your settings.

# file: mygame/server/conf/settings.py
# EXAMPLE
DISCORD_BOT_CLASS = 'accounts.bots.DiscordBot'

If you had already set up a Discord relay and are changing this, make sure you either delete the old bot account in Evennia or change its typeclass or it won’t take effect.

The core DiscordBot account class has several useful hooks already set up for processing and relaying channel messages between Discord and Evennia channels, along with the (unused by default) direct_msg hook for processing DMs sent to the bot on Discord.

Only messages and server updates are processed by default, but the Discord custom protocol passes all other unprocessed dispatch data on to the Evennia bot account so you can add additional handling yourself. However, this integration is not a full library and does not document the full range of possible Discord events.