Understanding the Architecture of DikuMUD at runtime

From DikuMUD Wiki
Jump to navigation Jump to search

A running DikuMUD III game is a few separate programs. This page explains what each one does, how they connect, and what they keep on disk. For building and starting them, see Manual:Installation.

The picture

  Browser                       Telnet / MUD client
  (vme/www/client)              (telnet, TinTin++, Mudlet ...)
      |                               |                |
      | ws:// or wss://               | telnet         | telnets (TLS)
      | port 4280                     | port 4242      | e.g. port 4243
      v                               v                v
  +-------------+              +-------------+   +-------------+
  | mplex -w    |              | mplex       |   | mplex -z    |
  | (websocket) |              | (telnet)    |   | (telnet+TLS)|
  +-------------+              +-------------+   +-------------+
         \                            |                 /
          \_____ one TCP connection per mplex _________/
                 to the mother port (4999)
                              |
                              v
                 +--------------------------+       named pipes
                 |  vme  (the game server)  | <-----------------> dispatcher.py <-> muddiscord.py <-> Discord
                 +--------------------------+       (optional)
                   |      |       |       |
                 etc/   zone/    lib/    log/

The web client

vme/www/client/ is a plain HTML and JavaScript client; there is nothing to build. index.html is the normal client and client-a.html is a simpler one made for screen readers. You can open the files straight from disk or put them on any web server.

The client opens one websocket per player to a websocket mplex. The connect form asks for protocol (ws or wss), host, port and path (/echo by default; mplex ignores the path). When the client is served from a web server, it suggests that server's host name and port 4280. The same settings can be given in the address, for example index.html?protocol=ws&host=localhost&port=4280.

The server sends HTML, and the client shows it. It also understands a few extra containers (who is online, aliases, combat status). The format is described in vme/www/client/PROTOCOL.md.

mplex, the network front end

mplex (source in vme/src/mplex/) is what players connect to. Each mplex listens on one port and handles one kind of connection:

Started as Players connect with
mplex -p 4242 telnet or a MUD client. mplex handles the telnet negotiation and turns the server's HTML into ANSI colour text.
mplex -z -p 4243 telnet inside TLS ("telnets"), for clients that support it. Needs server.pem.
mplex -w -p 4280 the web client over plain ws://.
mplex -w -t -p 4280 the web client over wss:// (TLS). Needs server.pem; dh.pem is optional.

You can run as many mplexers as you like against one game, for example one for telnet and one for the web client. Each one opens a single TCP connection to vme and sends all its players' traffic over it, using a small protocol of its own (vme/src/protocol.h): new connection, text, prompt, close, the player's address, and so on.

mplex does not need to restart when the game does. When vme goes away, mplex tells its players "The connection to ... was broken. Please be patient...", keeps their connections open, and connects to vme again as soon as it is back. The players then log in again.

The certificate files are read from the directory mplex is started in. The details are in vme/src/mplex/mplex.md.

vme, the game server

vme (source in vme/src/) is the game. It runs the whole game in one loop that makes four passes a second: commands, combat, NPCs, zone resets and all DIL programs (DIL is the scripting language of the zones, run by the interpreter in vme/src/dil*.cpp).

vme does not talk to players directly. It listens on the mother port (Port in vme/etc/server.cfg, 4999 by default) for mplexers. It accepts a connection there only from an address listed under mplex hosts in server.cfg; any other is logged as "Mplex not from trusted host" and closed. vme listens on all network interfaces, so keep the mother port closed to the outside in your firewall. Only the mplex ports need to be open to players.

The name "mother connection" is used on both sides: in vme it is the port the mplexers connect to, and in mplex it is the port the players connect to.

What is on disk

vme finds its directories through server.cfg. The paths there are relative to the directory vme is started in, which is why it is started from vme/bin/.

Directory What vme does with it
vme/etc/ Read at boot: server.cfg, zonelist (which zones to load), the compiled definition files (commands.dat, spells.dat, races.dat and others, built from the .def files), color.dat, the money definitions, login texts in etc/strings/ and the help files in etc/help/.
vme/zone/ The compiled zones: one .data and one .reset file per zone, made by vmc from the .zon source. They are read only at boot, so a recompiled zone takes effect after a restart.
vme/lib/ Everything the game saves while it runs. lib/ply/<first letter>/<name> is a player, and <name>.inv next to it is what the player carries. lib/players.id holds the next player id. Boards, banned sites, slimed objects and the data that DIL programs save (under lib/dilfiles/ and the paths given in zonelist) are kept here too. Back this directory up; it is the state of your game.
vme/log/ Statistics and account logs. When vme is started by runvme.sh, its log is here too.

The server log is vme.log in the directory vme was started in, unless -l names another file. vme empties it at every start, so copy it first if you need it. mplex writes mplex.log in its own start directory, or the file given with -l.

The zone compiler, vmc, is not part of the running game. It turns .zon files into .data and .reset files; see Manual:Zone Manual/General Compiler Information.

Discord (optional)

vme can talk to a Discord server through two small Python programs in vme/bin/. vme writes lines for Discord to the named pipe pipeDispatcher. dispatcher.py passes them on to muddiscord.py, which posts them on Discord. Messages from Discord go the other way, through the pipe pipeMUD, and reach the players as channel messages. The pipes are files in vme/bin/. See Manual:Discord.

Keeping it running

vme/bin/startvme.sh starts everything: vme through runvme.sh, one runmplex.sh for each mplexer line in server.cfg, and the Discord programs. Each run*.sh script starts its program again when it exits. That is how the in-game reboot command works: vme saves the players and exits, and runvme.sh starts it again. stopvme.sh stops it all.