Difference between revisions of "Manual:Discord"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
 
Line 1: Line 1:
−
= Connecting the MUD server to Discord =
+
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.
  
−
== Creating a Discord Robot ==
+
== 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>.
  
−
First you need to create a "robot" on Discord that will relay messages between your Discord server and the MUD.
+
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.
  
−
... Maybe a link to Discord or some help article ...
+
=== 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.
  
−
The end-result is token that looks something like '''Mzk3NjA4QTAyNjU0NDLzNTYw.X_jH5w.aQVUDfJvugh3HTOQzfcPnp6_36E'''
+
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.
  
−
== Configuration ==
+
== 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'''.
  
−
In the folder vme/bin/ create a text file called '''discord.token''' and put the Discord token value in this file.
+
=== 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.
  
−
== Running the VME Discord programs ==
+
=== 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>
  
−
The two Python 3 scripts "dispatcher.py" and "muddiscord.py" must be running on your server.
+
=== 4. Store the token ===
−
If you just edited the token you will have to restart the scripts.
+
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.
  
−
If you start the VME using the "startvme.sh" script then it will take care of also launching
+
=== 5. Make the who-is-online message ===
−
these two programs.
+
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
  
−
Check their respective log files to check for any connection problems. If you used the scripts
+
class Once(discord.Client):
−
to run it, then look in '''$VME_ROOT/log/muddiscord.log''' and '''$VME_ROOT/log/dispatcher.log'''
+
    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.
  
−
=== Example of Dispatcher Log File ===
+
=== 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.
  
−
  *** dispatcher.py started by val at Mon May 20 10:41:39 UTC 2024. ***
+
== Running it ==
−
  10:41:39 up 0 min, 0 users, load average: 1.04, 0.22, 0.07
+
<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>:
−
  Opening connection to named pipe: pipeDiscord
+
<pre>
−
  Reusing pipe pipeDiscord
+
cd vme/bin
−
  Pipe has been accessed pipeDiscord
+
./rundispatcher.sh &
−
  Nobody is listening to pipeDiscord. Pausing and retrying
+
./runmuddiscord.sh &
−
  Nobody is listening to pipeDiscord. Pausing and retrying
+
</pre>
−
  Pipe has been opened as write-only non-blocking: pipeDiscord
+
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.
−
  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
 
−
  MUD said: [discord who Finndo &&
 
−
  ]
 
−
  Relaying message to Discord: <discord> who Finndo &&
 
−
 
 
−
  Message of 24  bytes sent, wrote  24  bytes
 
−
  Ready for next line in fifopipe
 
−
  MUD said: [discord who Osric &&Finndo &&
 
−
  ]
 
  
−
=== Example of muddiscord log file ===
+
=== 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.
  
−
  *** muddiscord.py started by val at Mon May 20 10:41:39 UTC 2024. ***
+
When all is well, <code>dispatcher.log</code> shows the pipes opening and then every line from the game:
−
  10:41:39 up 0 min, 0 users, load average: 1.04, 0.22, 0.07
+
<pre>
−
  Discord Bot Token loaded, logging in
+
Opening connection to named pipe: pipeDiscord
−
  Opening named pipe WR ONLY: pipeMUD
+
Reusing pipe pipeDiscord
−
  Reusing pipe pipeMUD
+
Pipe has been accessed pipeDiscord
−
  Pipe has been accessed pipeMUD
+
Pipe has been opened as write-only non-blocking: pipeDiscord
−
  Nobody is listening to pipeMUD. Pausing and retrying
+
Opening blocking read connection to MUD : pipeDispatcher
−
  Pipe has been opened: pipeMUD
+
Reusing pipe pipeDispatcher
−
  Opening RO connection to named pipe: pipeDiscord
+
Pipe has been accessed pipeDispatcher
−
  Reusing pipe pipeDiscord
+
MUD said: [discord msg #build **BOOTING** Valhalla MUD.
−
  Pipe has been accessed pipeDiscord
+
]
−
  Pipe has been opened: pipeDiscord
+
Relaying message to Discord: <discord> msg #build **BOOTING** Valhalla MUD.
−
  pipeListener running
+
 
−
  Resolving channel name =  mud
+
Message of  47  bytes sent, wrote  47  bytes
−
  Resolved new channel  mud
+
Ready for next line in fifopipe
−
  Resolving channel name =  mudstatus
+
</pre>
−
  Resolved new channel  mudstatus
+
and <code>muddiscord.log</code> shows the bot logging in and finding its channels and the who message (here the bot is called MUDDiscord):
−
  Resolving channel name =  builder
+
<pre>
−
  Resolved new channel  builder
+
Discord Bot Token loaded, logging in
−
  Getting my whomsg to pin and alter
+
Opening named pipe WR ONLY: pipeMUD
−
  Resolving channel name =  mudstatus
+
Reusing pipe pipeMUD
−
  Logged in to Discord as:  MUDDiscord 797208102654443560
+
Pipe has been accessed pipeMUD
−
  ------
+
Pipe has been opened: pipeMUD
−
  Got whomsg and ready to begin
+
Opening RO connection to named pipe: pipeDiscord
−
  Debug: Got line: [ <discord> msg #build **BOOTING** Valhalla MUD.
+
Reusing pipe pipeDiscord
−
    ]
+
Pipe has been accessed pipeDiscord
−
  Line =  [<discord> msg #build **BOOTING** Valhalla MUD.]
+
Pipe has been opened: pipeDiscord
−
  words[2][1:] =  build
+
pipeListener running
−
  Resolving channel name =  build
+
Resolving channel name =  mud
−
  Msg Line =  [<discord> msg #build **BOOTING** Valhalla MUD.]
+
Resolved new channel  mud
−
  Partition =  **BOOTING** Valhalla MUD.
+
Resolving channel name =  mudstatus
−
  Send as message id =  1242064821994786857
+
Resolved new channel  mudstatus
−
  Debug: Got line: [ <discord> who Finndo &&
+
Resolving channel name =  builder
−
    ]
+
Resolved new channel  builder
−
  Line =  [<discord> who Finndo &&]
+
Getting my whomsg to pin and alter
−
  Resolving channel name =  mud
+
Resolving channel name =  mudstatus
−
  WHO update:
+
Logged in to Discord as:  MUDDiscord 797208102654443560
−
    [Finndo
+
------
−
  ]
+
Got whomsg and ready to begin
−
  editWho: Sending
+
</pre>
−
  editWho: Done
+
"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.
−
  Who update done.
 
−
  Debug: Got line: [ <discord> who Osric &&Finndo &&
 
−
    ]
 
−
  Line =  [<discord> who Osric &&Finndo &&]
 
−
  Resolving channel name =  mud
 
−
  WHO update:
 
−
    [Osric
 
−
  Finndo
 
−
  ]
 

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.

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 to pipeDispatcher. vme also reads pipeMUD and hands every line from it to the DIL program dispatcher@comm (in vme/zone/comm.zon).
  • dispatcher.py reads pipeDispatcher and passes lines that start with discord on to pipeDiscord. 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 to pipeMUD.

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.