Manual:Installation

From DikuMUD Wiki
Revision as of 06:14, 15 November 2026 by Agent-mud (talk | contribs) (checked against the current code (wiki review 2026-11-15))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This page explains how to build DikuMUD III from source, configure it and run it. For a shorter walk-through from nothing to a game in your browser, see Getting started - Step by Step. For how the parts fit together, see Understanding the Architecture of DikuMUD at runtime.

DikuMUD III is three programs, which all end up in vme/bin/:

  • vme, the game server.
  • mplex, the network front end that players connect to, by telnet or by websocket from the web client.
  • vmc, the zone compiler. It turns the zone sources in vme/zone/*.zon into the files vme loads.

There is also a web client in vme/www/client/, which needs no building.

Requirements

A Linux machine. The project is built and tested on Ubuntu; other distributions work as long as they have the packages below. You need:

  • a C++17 compiler (g++) and make,
  • CMake 3.16.3 or newer,
  • bison and flex (for vmc),
  • perl (the build converts the .def files in vme/etc/ with a perl script),
  • the Boost libraries unit_test_framework, filesystem and regex,
  • OpenSSL, RapidJSON and libcrypt development files.

On Ubuntu or Debian:

sudo apt install build-essential cmake git bison flex perl \
    libboost-dev libboost-filesystem-dev libboost-regex-dev libboost-test-dev \
    libssl-dev rapidjson-dev libcrypt-dev

libboost-all-dev in place of the four Boost packages works too; it is just bigger.

On Fedora:

sudo dnf install gcc-c++ make cmake git bison flex perl boost-devel openssl-devel rapidjson-devel libxcrypt-devel

Optional:

  • doxygen and graphviz: if CMake finds Doxygen, the build also writes code documentation to docs/.
  • ninja-build, if you prefer Ninja to make. See README_cmake.md.
  • Python 3 with python3-venv, only for the Discord link.

Getting the source

Run the game as an ordinary user, not as root. Clone the repository into that user's home directory:

git clone https://github.com/Seifert69/DikuMUD3.git
cd DikuMUD3

Building

From the top of the repository:

cmake .
make all -j$(nproc)
ctest

make all does all of this:

  • builds vme, mplex, vmc and the helpers pp and defcomp into vme/bin/,
  • turns the .def files in vme/etc/ into the .dat files the server reads,
  • compiles every zone in vme/zone/,
  • runs the unit tests.

ctest runs the five unit test suites again on their own; they must all pass.

Build types:

Command Result
cmake . Debug build: no optimisation, extra checks (MUD_DEBUG), full warnings. Good for development, slow for a real game.
cmake -DCMAKE_BUILD_TYPE=Release . Optimised (-O2).
cmake -DO2=1 . The Debug build with its checks and symbols, but at -O2.
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo . Optimised, with symbols for the debugger.
add -DWERROR=1 Warnings stop the build. The code builds without warnings.

You can also build outside the source tree (cmake -B build && cmake --build build). The programs still go to vme/bin/, and the zones are still compiled in vme/zone/.

Configuring

The server's settings are in vme/etc/server.cfg. The file has comments for each setting. Lines starting with # are comments, and the server reads the settings in the order they come in the file, so change values but don't move lines around.

The settings you are most likely to change:

Setting Meaning
mudname The name of your game, shown when players connect.
immortal_name A character with this name gets the highest level (255) every time it enters the game. It is Papi in the file that ships. Change it to a name of your own before others can reach your game, and create that character yourself, or anybody can log in as your god.
libdir, etcdir, logdir, zondir, plydir, dil_file_dir Where the server's directories are. The defaults are relative to vme/bin/, the directory the server is started in.
Port The mother port that mplex connects to (4999). It must be between 2000 and 8000. Players never connect to it.
mplex hosts The addresses mplex may connect from. ~127.0.0.1~ is enough when mplex runs on the same machine. Up to 10.
auto_reboot_hour Hour of the day (1-24) for an automatic reboot; 0 turns it off.
rent How much rent is charged: 0 is none, 100 is the full rent set in the zones.
promptstr The default prompt.

The server stops reading at the line "Startup script variables only past here". The settings after it, such as the mplexer lines, are read by the start script startvme.sh. The vmehome, zonedir and nextzon lines near the top are for old zone compile scripts; the server does not use them.

Which zones are loaded

vme/etc/zonelist lists the zones the server loads, one per line. The comments at the top of vme/etc/zonelist.minimal explain the columns. The zonelist in the repository names more zones than the repository contains. For each one that is missing, the server logs Could not open data file: ... and boots without it. zonelist.minimal is a short list of zones that are all in the repository.

Compiling zones

make all has already compiled the zones. After you change a zone:

cd vme/zone
../bin/vmc -m -d ../etc/ -I../include/ *.zon

-m compiles only the zones that have changed. The server reads zones only at boot, so restart it afterwards. make zone_files from the top directory does the same. See Manual:Zone Manual/General Compiler Information for vmc's options and messages.

Running the game

By hand

Start everything from vme/bin/, each program in its own terminal:

cd vme/bin
./vme                  # the game server
./mplex -p 4242        # telnet: telnet localhost 4242
./mplex -w -p 4280     # web client, plain ws://

Then watch the logs with tail -f vme.log and tail -f mplex.log. vme empties vme.log every time it starts. To run two mplexers from the same directory, give each its own log with -l, for example ./mplex -w -p 4280 -l mplex-4280.log.

Ctrl-C (or kill) stops vme cleanly: it saves the players and exits. The in-game reboot and shutdown commands also just stop vme when you run it by hand, because nothing starts it again.

With the start scripts

For a game that stays up, use the scripts in vme/bin/:

cd vme/bin
./startvme.sh          # starts vme, the mplexers and the Discord programs
./stopvme.sh           # stops them all
  • runvme.sh runs vme with ../etc/server.cfg and the log vme/log/vme.log. It keeps the last ten logs compressed (vme.log.1.gz and on), and starts vme again whenever it exits. That is what makes the in-game reboot command work.
  • runmplex.sh is started once for each mplexer line in server.cfg. The line gives the port, then any mplex options. Each mplex logs to vme/log/mplex-<port>.log. The file that ships has mplexer = 4280 -w -t, which needs a certificate (see below). Change it to mplexer = 4280 -w if you don't use TLS.
  • The scripts find the installation through $VME_ROOT (the vme/ directory). If it isn't set, they assume you started them in vme/bin/.

Docker

The repository also has a Dockerfile and a docker-compose.yaml. They build the game and serve a web client on port 80, with a websocket mplex on 4280. See the Docker section of README.md.

Connecting and creating your god

  • Telnet: telnet localhost 4242.
  • Web: open vme/www/client/index.html in a browser. In the connect form choose This computer (protocol ws, host localhost, port 4280), or fill in your own server.

Create a new character with the name set in immortal_name. When it enters the game, it is made level 255, the highest. See Wizarding 101 and Manual:Wizhelp Files for what an administrator can do in the game.

Opening the game to players

  • Ports. Players need the mplex ports, for example 4242 for telnet and 4280 for the web client. Keep the mother port (4999) closed in your firewall: vme listens on all network interfaces and only checks the mplex hosts list.
  • mplex on another machine. Start it with -a <address of the vme machine> (and -s <port> if the mother port isn't 4999), and add its address to mplex hosts.
  • The web client over https needs wss. A page served over https may not open a plain ws:// connection. Run the websocket mplex as ./mplex -w -t -p 4280, with server.pem (the private key and the certificate chain in one file) in the directory mplex is started in. A certificate from Let's Encrypt or another authority is best, since browsers silently refuse a self-signed certificate on a websocket. vme/src/mplex/mplex.md has the details.
  • Telnet with TLS. ./mplex -z -p 4243 runs a telnets port beside the plain one. It reads the same server.pem.
  • Hosting the web client. Copy vme/www/client/ and vme/www/img/ side by side to your web server; the client looks for images in ../img/ and img/. Served from your own host name, the client suggests that host, port 4280, and wss when the page came over https. You can link to a ready-filled form, for example index.html?host=mud.example.com&port=4280.

Program options

vme option Meaning
-s <file> The server.cfg to use. The default is ../etc/server.cfg, or the file named in the environment variable VME_SERVER_CFG.
-l <file> The log file (default ./vme.log).
-w Time-warped: the game never sleeps between passes, so game time passes as fast as the machine allows. For tests.
-L List the player files, then exit.
-c Load and save every player file again, in the current format, then exit.
-C Clean up the player files: deletes corrupt and old characters. Back up vme/lib/ first.
-d Print the profession tables, then exit.
-h Help.
mplex option Meaning
-p <port> The port players connect to (default 4242).
-w Websocket, for the web client.
-t With -w: TLS, so wss://. Reads ./server.pem and ./dh.pem.
-z TLS on a telnet port (telnets). Reads ./server.pem. Not with -w.
-a <address> Where vme runs (default localhost).
-s <port> vme's mother port (default 4999).
-l <file> The log file (default ./mplex.log).
-x Telnet: send the raw HTML, for debugging.
-y Websocket: strip the HTML.
-e, -r Telnet: echo characters locally, and redraw the prompt locally.
-h Help.

When the server won't start

Look at the end of the server log: vme/bin/vme.log when you started vme by hand, vme/log/vme.log when runvme.sh did. Common messages:

Message Cause
Can't bind Mother Connection port 4999 Another vme is still running. Stop it, for example with pkill -x vme.
Could not find server configuration file. vme wasn't started in vme/bin/. Start it there, or give the file with -s.
The ... directory ... does not exist. A directory in server.cfg is wrong, or vme was started in the wrong directory.
Mplex not from trusted host, terminating. An mplex connected from an address that isn't in mplex hosts.
Could not open data file: ... A zone in zonelist has no compiled .data file. Compile it, or remove it from the list.

If vme crashes, the core dump usually goes to systemd-coredump on a modern Linux: coredumpctl list, then coredumpctl gdb opens the most recent one in the debugger.

Upgrading

See Upgrading Tips.