+ +
+

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.

+
+
+
+ + +