The Ares Discord app is an extension for AresMUSH that lets you connect your in-game chat channels to a Discord server.
Table of Contents generated with DocToc
- What It Does
- How It Works
- Limitations
- Setup
- Troubleshooting
- Upgrades
- Pre-v0.108 Channel Configuration
In the game, chat from Discord is indicated by a prefix ([D] by default, which you can configure).
In Discord, chat from the game will show up with a little [Bot] tag next to it.
There are two completely independent paths for traffic, Game to Discord and Discord to Game. Understanding how they differ will aid you in understanding the setup, and also in troubleshooting any issues.
Discord allows external apps to post to channels using a webhook, a special URL that you can send data to. You can set up one discord webhook for each channel you want to link with the game. Whenever someone talks on an in-game channel, Ares will see if you've configured a discord webhook for that channel. If so, the game will post a message to the webhook, and the message will appear in the associated discord channel.
Note: There is no additional security on this path. Anyone with the webhook URL can post to your discord, so treat your webhook URLs like you would a key or password.
You can't use Discord webhooks for outgoing traffic. The only way to get chat from discord to the game is to use a Discord Bot.
The Bot has two sides. The first is a Bot User, which you set up in your Discord account. This sits in your Discord server just like another user--you'll even see it on the user list like it's online. It listens for chat messages.
The second side of the Bot is the Bot Script. This runs on your game server, and is basically the brains of the bot. Whenever the Bot User sees a chat message, the Bot Script relays that to your game using an internal webhook URL.
Before installing the Discord integration, you should understand its limitations.
The bot relies on the discord.js library to talk to the Discord API. Additionally, the Discord API itself may change at any time. Any changes or problems with either the Discord API or discord.js library may break the integration, and are largely out of our control.
Bottom line...
There are no guarantees of stability with the Discord integration.
Setting up the Discord app is unfortunately an involved process, requiring multiple steps. Fortunately the setup only needs to be done once.
First you need to create an "application" in discord that will enable your bot.
- Go to Discord Developer Portal and log in with your Discord account.
- Click "New Application".
- Give it a name, like "My Ares Connection".
- Select the "Bot" menu.
- Click "Add Bot".
- Give your bot a username and optionally an icon.
- Activate the slider for the "Message Content Intent" so your bot can receive raw message data.
- Under the bot's username is a thing that says "Click to Reveal Token." Click that and save the token somewhere safe. You'll need it in a minute.
- Select the "OAuth2" menu.
- Copy the "Client ID". You'll need that in a minute too.
NOTE: Never give your bot token to anyone, as it will allow them to control your bot in potentially malicious ways.
Next you need to add the Bot you just defined to your game's Discord server. This will create a bot 'user' in your game's Discord.
- Substitute your client ID (that you got in step 10 above) into this URL and go there in your browser: https://discordapp.com/oauth2/authorize?&client_id=YOUR_CLIENT_ID_HERE&scope=bot&permissions=2048
- You'll see a prompt asking you to connect your bot. Select your game's discord server and click Authorize.
NOTE: You'll need administrator permissions on the discord server to authorize a bot.
Now you can install the code that makes the bot run. This is a tiny app that runs alongside the MUSH on your game server.
- Log into your game's server shell.
- Clone this repository using
git clone https://github.com/AresMUSH/ares-discord.git. - Run the installer:
cd ares-discord
chmod +x install.sh
./install.sh
- Edit
config.jsonusing your favorite text editor (nano config.jsonis a good choice if you don't have a favorite).
Here are the config options:
- url: This is your game's API endpoint. For typical installs with https enabled it would be
https://YOUR_WEB_PORTAL/api. - bot_token: This is the bot token that you got from "Click to Reveal Token" when you created the bot.
- api_token: Make up a long password for your game. This prevents random people from adding junk to your channels. The website Guid Generator is good for making up a password. Avoid symbols (other than
-in your token password, as some of them can mess up the file parsing when used for the discord bot.)
Note: Make sure your config options are in quotes.
Once the bot code is installed, you need to start it up.
- Log into your game's server shell.
- Start the bot:
cd ares-discord
./restart.sh
You only need to do this the first time. The installer sets it up so it'll start automatically when the server restarts.
You'll need to set up a web hook in your Discord server for each MUSH channel you want to hook up to discord.
- Go to the "Server Settings" panel of your Discord server.
- Select "Webhooks".
- Select "Create Webhook".
- Give the hook a name (like "Ares Link"), and select the channel you want to hook it up to.
- Copy the "Webhook URL". You'll need this in the next step.
NOTE: These webhooks will allow anyone to post to your discord server. Treat them like you would an API key or password.
Finally you can update your game's configuration with the discord info.
- Log into your web portal with an admin character.
- Go to Admin -> Setup.
- Edit
secrets.yml. - Look for a config option named 'discord'. If it doesn't exist, use the 'add key' option to create it.
- Set the discord config to:
api_token: 'YOUR_API_TOKEN'This must exactly match theapi_tokenoption that you put in the config.json file when installing the bot. (Be sure to use the api token, not the bot token.)
In channels.yml you can set up two additional config options:
discord_prefix- This is the prefix that shows up on the in-game chat to indicate that the message came from Discord.discord_gravatar_style- If the player doesn't have an icon, Discord will use a randomly-assigned one from Gravatar. Gravatar supports various styles such as 'robohash' (robots), 'retro' (blocky video game things), 'identicon' (geometric patterns) and more.discord_debug- Enables additional debugging to troubleshoot Discord issues.
You can add and edit the game channel configuration in the Web Portal under Admin -> Setup -> Setup Channels. Pick the channel you wish to manage, and edit the following settings:
Discord Channel- The name of the Discord channel you want this to link to. This must match exactly the name in Discord.Discord Webhook URL- The secret webhook URL associated with the Discord channel.
Note: In versions before v0.108, channel configuration was done in secrets.yml. See Pre-v0.018 Configuration below for details.
If game chat is not showing up in Discord:
- Make sure the webhook URL matches the one you configured in Discord.
If Discord chat is not showing up in game, there are a few common issues:
If your bot was working fine and suddenly stopped and nothing else changed, it could be that Discord reset your bot's token. It does this occasionally for reasons unknown.
- Go to your Discord Developer Portal and log in with your Discord account.
- Select your Ares bot.
- Click the "Bot" tab.
- Click "Show Token" under your bot's username.
- Make sure it's the same token you have in your ares-discord/config.json file. If not, update the config file and restart the bot.
We've also seen Discord reset the bot's permissions occasionally, so make sure it has the "Send Messages" permission checked.
Make sure the bot is running on your game server.
Type ps -aux | grep bot.js in the server shell and you should see an entry like this:
ares 1234 0.0 1.8 1089216 37520 ? Sl Jul24 2:40 node bot.js
If the bot is not running, restart it:
cd ares-discord
./restart.sh
Make sure the Ares Link bot is visible in the "Online" list of your Discord channel.
If it isn't, walk through the "Add the Bot User" steps again to check that your bot is set up correctly.
Also make sure your bot has the necessary Discord roles for the channels you want it to work on.
If the bot is running and online, double-check the settings in your bot configuration file (config.json) and game configuration. Pay particular attention to:
- Making sure the API key and game URL match.
- Making sure the channel names match exactly.
If everything else is working, check the game log and the bot log (ares-discord/bot##.log - look for the highest numbered log) for any weird errors.
If you ever need to upgrade your bot, here are the steps:
To upgrade the bot, log into your server shell and run ps -aux | grep bot.js. You should see a line like this with "node bot.js" at the end:
ares 1234 0.0 1.2 811652 25792 ? Sl 01:01 0:02 node bot.js
The number in the second column is the process id. Stop the bot by typing:
kill -9 <process ID>
Then do this to upgrade the bot code:
cd ares-discord
git pull
./restart.sh
In versions before v0.108, channel configuration was done in secrets.yml under secrets / discord / webhooks.
For each hook, you must list the name of the MUSH channel, the name of the corresponding Discord channel, and the webhook URL from the previous step. Remember that each channel needs a different webhook URL.
Here's an example:
secrets:
discord:
api_token: '123'
webhooks:
-
mush_channel: chat
discord_channel: lobby
webhook_url: 'https://discordapp.com/api/webhooks/WEBHOOK1'
-
mush_channel: sports
discord_channel: sports
webhook_url: 'https://discordapp.com/api/webhooks/WEBHOOK2'
See License