Difference between revisions of "Manual:Discord"
(checked against the current code (wiki review 2026-11-15)) |
|||
| Line 1: | Line 1: | ||
| − | + | DikuMUD III can link some of its chat channels to a Discord server. What players say on such a channel in the game is posted in the Discord channel of the same name, and what people write in that Discord channel appears in the game. The link also keeps a "who is online" message on Discord, and posts bug and typo reports there. | |
| − | == | + | == How it works == |
| + | Three programs take part, and they talk through named pipes (special files) in <code>vme/bin/</code>: | ||
| + | <pre> | ||
| + | vme --pipeDispatcher--> dispatcher.py --pipeDiscord--> muddiscord.py --> Discord | ||
| + | vme <--pipeMUD------------------------------------------- muddiscord.py <-- Discord | ||
| + | </pre> | ||
| + | * '''vme''', the game server. DIL code sends a line to Discord with [[Manual:DIL Manual/dispatch()|dispatch()]], for example <code>dispatch("discord msg #builder Hello")</code>. vme writes it to <code>pipeDispatcher</code>. vme also reads <code>pipeMUD</code> and hands every line from it to the DIL program <code>dispatcher@comm</code> (in <code>vme/zone/comm.zon</code>). | ||
| + | * '''dispatcher.py''' reads <code>pipeDispatcher</code> and passes lines that start with <code>discord</code> on to <code>pipeDiscord</code>. It is there so that other links can be added beside Discord later. | ||
| + | * '''muddiscord.py''' is the Discord bot. It posts what arrives on <code>pipeDiscord</code>, and writes what people say on Discord to <code>pipeMUD</code>. | ||
| − | + | The pipes are made by whichever program opens them first, in the directory it runs in. That is why vme and both scripts must run in <code>vme/bin/</code>, as the start scripts do. | |
| − | ... | + | === What is sent === |
| + | From the game to Discord (all in the public zones, so you can change them): | ||
| + | {| class="wikitable" | ||
| + | ! What !! Where in the zones !! Discord channel | ||
| + | |- | ||
| + | | Talk on the channels <code>newbie</code>, <code>builder</code>, <code>mud</code>, <code>accessibility</code>, <code>bugs</code>, <code>diku3</code> and <code>chat</code> || <code>DISCORD_CHANNELS</code> and <code>channel</code> in <code>function.zon</code> || the one with the channel's name | ||
| + | |- | ||
| + | | Bug and typo reports from the <code>bug</code> and <code>typo</code> commands || <code>commands.zon</code> || <code>bugs</code> | ||
| + | |- | ||
| + | | A welcome when a level 1 player enters the game (once per player until the next boot) || <code>basis.zon</code> || <code>newbie</code> | ||
| + | |- | ||
| + | | A message when the game boots || <code>wiz.zon</code> || <code>build</code> | ||
| + | |- | ||
| + | | The list of players online, when a player enters the game (gods who are invisible don't trigger it), and when someone writes <code>#</code> on Discord || <code>basis.zon</code>, <code>comm.zon</code> || one message in <code>mudstatus</code>, edited in place (at most every 15 seconds) | ||
| + | |} | ||
| + | If a channel doesn't exist on your Discord server, the bot posts in <code>mud</code> instead. | ||
| − | + | From Discord to the game: every message the bot can read, in any channel, is sent to the game as talk on the game channel with the same name as the Discord channel, from "@" and the writer's Discord display name. Players who have that channel switched on see it. A message that is just <code>#</code> makes the game update the who-is-online message. So give the bot access only to the channels you want linked. | |
| − | == | + | == Setting it up == |
| + | === 1. Make a Discord bot === | ||
| + | In the [https://discord.com/developers/applications Discord Developer Portal], create an application and add a bot to it. Then: | ||
| + | * Copy the bot's '''token'''. Treat it like a password: anyone who has it can act as your bot. | ||
| + | * Under the bot's privileged intents, switch on '''Message Content Intent'''. Without it the bot can't read what people write. | ||
| + | * Invite the bot to your Discord server (OAuth2, scope <code>bot</code>) with the permissions '''View Channels''', '''Send Messages''' and '''Read Message History'''. | ||
| − | + | === 2. Make the channels === | |
| + | On your Discord server, create at least the text channels <code>mud</code> and <code>mudstatus</code>; muddiscord.py stops if it can't find them. Add channels for the game channels you want linked (<code>newbie</code>, <code>builder</code>, <code>chat</code> and so on), and <code>bugs</code> and <code>build</code> if you want the reports and boot messages in their own place. | ||
| − | == | + | === 3. Install the Python library === |
| + | The scripts need Python 3 and the <code>discord.py</code> library, in a virtual environment called <code>pythonEnv</code> in <code>vme/bin/</code> (the start scripts activate it): | ||
| + | <pre> | ||
| + | sudo apt install python3-venv | ||
| + | cd vme/bin | ||
| + | python3 -m venv pythonEnv | ||
| + | source pythonEnv/bin/activate | ||
| + | python3 -m pip install -U discord.py | ||
| + | deactivate | ||
| + | </pre> | ||
| − | + | === 4. Store the token === | |
| − | + | Put the token in the file <code>vme/bin/discord.token</code> and nothing else, and make it readable only by the user that runs the game: | |
| + | <pre> | ||
| + | cd vme/bin | ||
| + | printf '%s' 'YOUR-TOKEN-HERE' > discord.token | ||
| + | chmod 600 discord.token | ||
| + | </pre> | ||
| + | Git ignores this file, so it is not committed by accident. | ||
| − | + | === 5. Make the who-is-online message === | |
| − | + | The bot keeps the list of players in one message in <code>mudstatus</code>, which it edits. Discord lets a bot edit only its own messages, so the bot must post it first. Save this as <code>whomsg.py</code> in <code>vme/bin/</code> and run it once: | |
| + | <pre> | ||
| + | import discord | ||
| − | + | class Once(discord.Client): | |
| − | + | async def on_ready(self): | |
| + | channel = discord.utils.get(self.get_all_channels(), name="mudstatus") | ||
| + | message = await channel.send("Who is online") | ||
| + | print("Message ID:", message.id) | ||
| + | await self.close() | ||
| + | Once(intents=discord.Intents.default()).run(open("discord.token").read().strip()) | ||
| + | </pre> | ||
| + | <pre> | ||
| + | source pythonEnv/bin/activate | ||
| + | python3 whomsg.py | ||
| + | deactivate | ||
| + | </pre> | ||
| + | It prints the new message's ID. In <code>muddiscord.py</code>, the ID of the message is written into the code, as the number in <code>fetch_message(...)</code>. Replace that number with yours. Until you do, muddiscord.py logs <code>Cant find the mudstatus channel message with ID ...</code> and stops. | ||
| − | === | + | === 6. Change the texts === |
| + | The messages in the zones name Valhalla, the game DikuMUD III was written for: the welcome in <code>basis.zon</code> ("Welcome ... to Valhalla MUD.") and the boot message in <code>wiz.zon</code>. The newbie guide in <code>newbie.zon</code> also invites players to Valhalla's Discord server. Change these to your own game and Discord server, and recompile the zones. | ||
| − | + | == Running it == | |
| − | + | <code>vme/bin/startvme.sh</code> starts <code>rundispatcher.sh</code> always, and <code>runmuddiscord.sh</code> when <code>vme/bin/discord.token</code> exists. Both scripts start their program again when it stops. If you start the game another way, start them yourself from <code>vme/bin/</code>: | |
| − | + | <pre> | |
| − | + | cd vme/bin | |
| − | + | ./rundispatcher.sh & | |
| − | + | ./runmuddiscord.sh & | |
| − | + | </pre> | |
| − | + | After changing the token or <code>muddiscord.py</code>, stop <code>muddiscord.py</code> (<code>pkill -f muddiscord.py</code>) and the script starts it again with the new settings. <code>stopvme.sh</code> stops all of it. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | === | + | === Logs === |
| + | The scripts log to <code>vme/log/dispatcher.log</code> and <code>vme/log/muddiscord.log</code>. vme logs each line it sends (<code>Wrote message [...] to dispatcher.</code>) and receives (<code>Received line [...]</code>) in its own log. | ||
| − | + | When all is well, <code>dispatcher.log</code> shows the pipes opening and then every line from the game: | |
| − | + | <pre> | |
| − | + | Opening connection to named pipe: pipeDiscord | |
| − | + | Reusing pipe pipeDiscord | |
| − | + | Pipe has been accessed pipeDiscord | |
| − | + | Pipe has been opened as write-only non-blocking: pipeDiscord | |
| − | + | Opening blocking read connection to MUD : pipeDispatcher | |
| − | + | Reusing pipe pipeDispatcher | |
| − | + | Pipe has been accessed pipeDispatcher | |
| − | + | MUD said: [discord msg #build **BOOTING** Valhalla MUD. | |
| − | + | ] | |
| − | + | Relaying message to Discord: <discord> msg #build **BOOTING** Valhalla MUD. | |
| − | + | ||
| − | + | Message of 47 bytes sent, wrote 47 bytes | |
| − | + | Ready for next line in fifopipe | |
| − | + | </pre> | |
| − | + | and <code>muddiscord.log</code> shows the bot logging in and finding its channels and the who message (here the bot is called MUDDiscord): | |
| − | + | <pre> | |
| − | + | Discord Bot Token loaded, logging in | |
| − | + | Opening named pipe WR ONLY: pipeMUD | |
| − | + | Reusing pipe pipeMUD | |
| − | + | Pipe has been accessed pipeMUD | |
| − | + | Pipe has been opened: pipeMUD | |
| − | + | Opening RO connection to named pipe: pipeDiscord | |
| − | + | Reusing pipe pipeDiscord | |
| − | + | Pipe has been accessed pipeDiscord | |
| − | + | Pipe has been opened: pipeDiscord | |
| − | + | pipeListener running | |
| − | + | Resolving channel name = mud | |
| − | + | Resolved new channel mud | |
| − | + | Resolving channel name = mudstatus | |
| − | + | Resolved new channel mudstatus | |
| − | + | Resolving channel name = builder | |
| − | + | Resolved new channel builder | |
| − | + | Getting my whomsg to pin and alter | |
| − | + | Resolving channel name = mudstatus | |
| − | + | Logged in to Discord as: MUDDiscord 797208102654443560 | |
| − | + | ------ | |
| − | + | Got whomsg and ready to begin | |
| − | + | </pre> | |
| − | + | "Nobody is listening to ... Pausing and retrying" means the program at the other end of that pipe isn't running yet; it goes away once it is. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
Latest revision as of 06:14, 15 November 2026
DikuMUD III can link some of its chat channels to a Discord server. What players say on such a channel in the game is posted in the Discord channel of the same name, and what people write in that Discord channel appears in the game. The link also keeps a "who is online" message on Discord, and posts bug and typo reports there.
Contents
How it works
Three programs take part, and they talk through named pipes (special files) in vme/bin/:
vme --pipeDispatcher--> dispatcher.py --pipeDiscord--> muddiscord.py --> Discord vme <--pipeMUD------------------------------------------- muddiscord.py <-- Discord
- vme, the game server. DIL code sends a line to Discord with dispatch(), for example
dispatch("discord msg #builder Hello"). vme writes it topipeDispatcher. vme also readspipeMUDand hands every line from it to the DIL programdispatcher@comm(invme/zone/comm.zon). - dispatcher.py reads
pipeDispatcherand passes lines that start withdiscordon topipeDiscord. It is there so that other links can be added beside Discord later. - muddiscord.py is the Discord bot. It posts what arrives on
pipeDiscord, and writes what people say on Discord topipeMUD.
The pipes are made by whichever program opens them first, in the directory it runs in. That is why vme and both scripts must run in vme/bin/, as the start scripts do.
What is sent
From the game to Discord (all in the public zones, so you can change them):
| What | Where in the zones | Discord channel |
|---|---|---|
Talk on the channels newbie, builder, mud, accessibility, bugs, diku3 and chat |
DISCORD_CHANNELS and channel in function.zon |
the one with the channel's name |
Bug and typo reports from the bug and typo commands |
commands.zon |
bugs
|
| A welcome when a level 1 player enters the game (once per player until the next boot) | basis.zon |
newbie
|
| A message when the game boots | wiz.zon |
build
|
The list of players online, when a player enters the game (gods who are invisible don't trigger it), and when someone writes # on Discord |
basis.zon, comm.zon |
one message in mudstatus, edited in place (at most every 15 seconds)
|
If a channel doesn't exist on your Discord server, the bot posts in mud instead.
From Discord to the game: every message the bot can read, in any channel, is sent to the game as talk on the game channel with the same name as the Discord channel, from "@" and the writer's Discord display name. Players who have that channel switched on see it. A message that is just # makes the game update the who-is-online message. So give the bot access only to the channels you want linked.
Setting it up
1. Make a Discord bot
In the Discord Developer Portal, create an application and add a bot to it. Then:
- Copy the bot's token. Treat it like a password: anyone who has it can act as your bot.
- Under the bot's privileged intents, switch on Message Content Intent. Without it the bot can't read what people write.
- Invite the bot to your Discord server (OAuth2, scope
bot) with the permissions View Channels, Send Messages and Read Message History.
2. Make the channels
On your Discord server, create at least the text channels mud and mudstatus; muddiscord.py stops if it can't find them. Add channels for the game channels you want linked (newbie, builder, chat and so on), and bugs and build if you want the reports and boot messages in their own place.
3. Install the Python library
The scripts need Python 3 and the discord.py library, in a virtual environment called pythonEnv in vme/bin/ (the start scripts activate it):
sudo apt install python3-venv cd vme/bin python3 -m venv pythonEnv source pythonEnv/bin/activate python3 -m pip install -U discord.py deactivate
4. Store the token
Put the token in the file vme/bin/discord.token and nothing else, and make it readable only by the user that runs the game:
cd vme/bin printf '%s' 'YOUR-TOKEN-HERE' > discord.token chmod 600 discord.token
Git ignores this file, so it is not committed by accident.
5. Make the who-is-online message
The bot keeps the list of players in one message in mudstatus, which it edits. Discord lets a bot edit only its own messages, so the bot must post it first. Save this as whomsg.py in vme/bin/ and run it once:
import discord
class Once(discord.Client):
async def on_ready(self):
channel = discord.utils.get(self.get_all_channels(), name="mudstatus")
message = await channel.send("Who is online")
print("Message ID:", message.id)
await self.close()
Once(intents=discord.Intents.default()).run(open("discord.token").read().strip())
source pythonEnv/bin/activate python3 whomsg.py deactivate
It prints the new message's ID. In muddiscord.py, the ID of the message is written into the code, as the number in fetch_message(...). Replace that number with yours. Until you do, muddiscord.py logs Cant find the mudstatus channel message with ID ... and stops.
6. Change the texts
The messages in the zones name Valhalla, the game DikuMUD III was written for: the welcome in basis.zon ("Welcome ... to Valhalla MUD.") and the boot message in wiz.zon. The newbie guide in newbie.zon also invites players to Valhalla's Discord server. Change these to your own game and Discord server, and recompile the zones.
Running it
vme/bin/startvme.sh starts rundispatcher.sh always, and runmuddiscord.sh when vme/bin/discord.token exists. Both scripts start their program again when it stops. If you start the game another way, start them yourself from vme/bin/:
cd vme/bin ./rundispatcher.sh & ./runmuddiscord.sh &
After changing the token or muddiscord.py, stop muddiscord.py (pkill -f muddiscord.py) and the script starts it again with the new settings. stopvme.sh stops all of it.
Logs
The scripts log to vme/log/dispatcher.log and vme/log/muddiscord.log. vme logs each line it sends (Wrote message [...] to dispatcher.) and receives (Received line [...]) in its own log.
When all is well, dispatcher.log shows the pipes opening and then every line from the game:
Opening connection to named pipe: pipeDiscord Reusing pipe pipeDiscord Pipe has been accessed pipeDiscord Pipe has been opened as write-only non-blocking: pipeDiscord Opening blocking read connection to MUD : pipeDispatcher Reusing pipe pipeDispatcher Pipe has been accessed pipeDispatcher MUD said: [discord msg #build **BOOTING** Valhalla MUD. ] Relaying message to Discord: <discord> msg #build **BOOTING** Valhalla MUD. Message of 47 bytes sent, wrote 47 bytes Ready for next line in fifopipe
and muddiscord.log shows the bot logging in and finding its channels and the who message (here the bot is called MUDDiscord):
Discord Bot Token loaded, logging in Opening named pipe WR ONLY: pipeMUD Reusing pipe pipeMUD Pipe has been accessed pipeMUD Pipe has been opened: pipeMUD Opening RO connection to named pipe: pipeDiscord Reusing pipe pipeDiscord Pipe has been accessed pipeDiscord Pipe has been opened: pipeDiscord pipeListener running Resolving channel name = mud Resolved new channel mud Resolving channel name = mudstatus Resolved new channel mudstatus Resolving channel name = builder Resolved new channel builder Getting my whomsg to pin and alter Resolving channel name = mudstatus Logged in to Discord as: MUDDiscord 797208102654443560 ------ Got whomsg and ready to begin
"Nobody is listening to ... Pausing and retrying" means the program at the other end of that pipe isn't running yet; it goes away once it is.