Difference between revisions of "Manual:Installation"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
 
Line 1: Line 1:
−
  Installing the VME 2.0
+
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]].
−
  Ken Perry whistler@valhalla.com
 
−
  v2.0, 1 April 2001
 
  
−
  When installing for the first time or upgrading from a previous ver-
+
DikuMUD III is three programs, which all end up in <code>vme/bin/</code>:
−
  sion of the VME you should still install first and then upgrade sec-
+
* '''vme''', the game server.
−
  ond. Following the install section should get you up in running with
+
* '''mplex''', the network front end that players connect to, by telnet or by websocket from the web client.
−
  in minutes.  If you have problems with the installation write
+
* '''vmc''', the zone compiler. It turns the zone sources in <code>vme/zone/*.zon</code> into the files vme loads.
−
  whistler@valhalla.com.
 
−
 
 
−
----
 
−
Table of Contents
 
−
# Installing the VME 2.0
 
−
# Upgrading from a previous VME
 
−
## Back up old VME first
 
−
## Moving Player base
 
−
## Converting Zones
 
−
## Combining your skils.def with the new commands.def
 
−
## Converting Socials
 
−
## Converting Help files
 
−
# Debugging if the Server won't run
 
−
----
 
  
−
  1. Installing the VME 2.0
+
There is also a web client in <code>vme/www/client/</code>, which needs no building.
  
−
  Installing the VME 2.0 is quick and painless. Follow the steps bellow
+
== Requirements ==
−
  and you will be up and running in minutes..
+
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 <code>.def</code> files in <code>vme/etc/</code> with a perl script),
 +
* the Boost libraries unit_test_framework, filesystem and regex,
 +
* OpenSSL, RapidJSON and libcrypt development files.
  
−
  NOTE
+
On Ubuntu or Debian:
 +
<pre>
 +
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
 +
</pre>
 +
<code>libboost-all-dev</code> in place of the four Boost packages works too; it is just bigger.
  
−
      All the following steps assume that you are running the Bash or Ksh
+
On Fedora:
−
      shells if you use another shell and want to add a list of how to
+
<pre>
−
      please send me your steps and I will add it.
+
sudo dnf install gcc-c++ make cmake git bison flex perl boost-devel openssl-devel rapidjson-devel libxcrypt-devel
 +
</pre>
  
 +
Optional:
 +
* <code>doxygen</code> and <code>graphviz</code>: if CMake finds Doxygen, the build also writes code documentation to <code>docs/</code>.
 +
* <code>ninja-build</code>, if you prefer Ninja to make. See [https://github.com/Seifert69/DikuMUD3/blob/master/README_cmake.md README_cmake.md].
 +
* Python 3 with <code>python3-venv</code>, only for the [[Manual:Discord|Discord link]].
  
 +
== Getting the source ==
 +
Run the game as an ordinary user, not as root. Clone the repository into that user's home directory:
 +
<pre>
 +
git clone https://github.com/Seifert69/DikuMUD3.git
 +
cd DikuMUD3
 +
</pre>
  
−
  1. Download the VME2.0.tgz file and place it in the home directory
+
== Building ==
−
    that you will be running the mud as. We suggest you use a user
+
From the top of the repository:
−
    like 'mud'.
+
<pre>
 +
cmake .
 +
make all -j$(nproc)
 +
ctest
 +
</pre>
  
−
  2. As the user that you will be running the mud as untar the VME file.
+
<code>make all</code> does all of this:
−
    Do not untar the file as 'root'. The following is the command you
+
* builds vme, mplex, vmc and the helpers pp and defcomp into <code>vme/bin/</code>,
−
    use to untar the file.
+
* turns the <code>.def</code> files in <code>vme/etc/</code> into the <code>.dat</code> files the server reads,
 +
* compiles every zone in <code>vme/zone/</code>,
 +
* runs the unit tests.
 +
<code>ctest</code> runs the five unit test suites again on their own; they must all pass.
  
 +
Build types:
 +
{| class="wikitable"
 +
! Command !! Result
 +
|-
 +
| <code>cmake .</code> || Debug build: no optimisation, extra checks (<code>MUD_DEBUG</code>), full warnings. Good for development, slow for a real game.
 +
|-
 +
| <code>cmake -DCMAKE_BUILD_TYPE=Release .</code> || Optimised (-O2).
 +
|-
 +
| <code>cmake -DO2=1 .</code> || The Debug build with its checks and symbols, but at -O2.
 +
|-
 +
| <code>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .</code> || Optimised, with symbols for the debugger.
 +
|-
 +
| add <code>-DWERROR=1</code> || Warnings stop the build. The code builds without warnings.
 +
|}
  
−
      ______________________________________________________________________
+
You can also build outside the source tree (<code>cmake -B build && cmake --build build</code>). The programs still go to <code>vme/bin/</code>, and the zones are still compiled in <code>vme/zone/</code>.
−
      tar zxvf vme-2.0-1.tgz
 
−
      ______________________________________________________________________
 
  
 +
== Configuring ==
 +
The server's settings are in <code>vme/etc/server.cfg</code>. The file has comments for each setting. Lines starting with <code>#</code> 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:
 +
{| class="wikitable"
 +
! Setting !! Meaning
 +
|-
 +
| <code>mudname</code> || The name of your game, shown when players connect.
 +
|-
 +
| <code>immortal_name</code> || A character with this name gets the highest level (255) every time it enters the game. It is <code>Papi</code> 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.
 +
|-
 +
| <code>libdir</code>, <code>etcdir</code>, <code>logdir</code>, <code>zondir</code>, <code>plydir</code>, <code>dil_file_dir</code> || Where the server's directories are. The defaults are relative to <code>vme/bin/</code>, the directory the server is started in.
 +
|-
 +
| <code>Port</code> || The '''mother port''' that mplex connects to (4999). It must be between 2000 and 8000. Players never connect to it.
 +
|-
 +
| <code>mplex hosts</code> || The addresses mplex may connect from. <code>~127.0.0.1~</code> is enough when mplex runs on the same machine. Up to 10.
 +
|-
 +
| <code>auto_reboot_hour</code> || Hour of the day (1-24) for an automatic reboot; 0 turns it off.
 +
|-
 +
| <code>rent</code> || How much rent is charged: 0 is none, 100 is the full rent set in the zones.
 +
|-
 +
| <code>promptstr</code> || The default prompt.
 +
|}
  
 +
The server stops reading at the line "Startup script variables only past here". The settings after it, such as the <code>mplexer</code> lines, are read by the start script <code>startvme.sh</code>. The <code>vmehome</code>, <code>zonedir</code> and <code>nextzon</code> lines near the top are for old zone compile scripts; the server does not use them.
  
−
  3. Edit the server.cfg in the 'vme2.0/etc/' directory and fill it out.
+
=== Which zones are loaded ===
−
    The server.cfg has comments that explain what each option does.
+
<code>vme/etc/zonelist</code> lists the zones the server loads, one per line. The comments at the top of <code>vme/etc/zonelist.minimal</code> explain the columns. The <code>zonelist</code> in the repository names more zones than the repository contains. For each one that is missing, the server logs <code>Could not open data file: ...</code> and boots without it. <code>zonelist.minimal</code> is a short list of zones that are all in the repository.
  
−
  4. Add the profile.txt to your .profile or .bash_profile file
+
== Compiling zones ==
−
    depending on which one you use when you log on. You must do this
+
<code>make all</code> has already compiled the zones. After you change a zone:
−
    even if upgrading from the older VME because the server.cfg
+
<pre>
−
    variable has changed in the profile.
+
cd vme/zone
 +
../bin/vmc -m -d ../etc/ -I../include/ *.zon
 +
</pre>
 +
<code>-m</code> compiles only the zones that have changed. The server reads zones only at boot, so restart it afterwards. <code>make zone_files</code> from the top directory does the same. See [[Manual:Zone Manual/General Compiler Information]] for vmc's options and messages.
  
−
  5. Run the profile again by either logging back on or typing:
+
== Running the game ==
 +
=== By hand ===
 +
Start everything from <code>vme/bin/</code>, each program in its own terminal:
 +
<pre>
 +
cd vme/bin
 +
./vme                  # the game server
 +
./mplex -p 4242        # telnet: telnet localhost 4242
 +
./mplex -w -p 4280    # web client, plain ws://
 +
</pre>
 +
Then watch the logs with <code>tail -f vme.log</code> and <code>tail -f mplex.log</code>. vme empties <code>vme.log</code> every time it starts. To run two mplexers from the same directory, give each its own log with <code>-l</code>, for example <code>./mplex -w -p 4280 -l mplex-4280.log</code>.
  
 +
Ctrl-C (or <code>kill</code>) stops vme cleanly: it saves the players and exits. The in-game <code>reboot</code> and <code>shutdown</code> commands also just stop vme when you run it by hand, because nothing starts it again.
  
−
      ______________________________________________________________________
+
=== With the start scripts ===
−
      . .profile
+
For a game that stays up, use the scripts in <code>vme/bin/</code>:
−
      . .bash_profile
+
<pre>
−
      ______________________________________________________________________
+
cd vme/bin
 +
./startvme.sh          # starts vme, the mplexers and the Discord programs
 +
./stopvme.sh          # stops them all
 +
</pre>
 +
* <code>runvme.sh</code> runs vme with <code>../etc/server.cfg</code> and the log <code>vme/log/vme.log</code>. It keeps the last ten logs compressed (<code>vme.log.1.gz</code> and on), and starts vme again whenever it exits. That is what makes the in-game <code>reboot</code> command work.
 +
* <code>runmplex.sh</code> is started once for each <code>mplexer</code> line in <code>server.cfg</code>. The line gives the port, then any mplex options. Each mplex logs to <code>vme/log/mplex-&lt;port&gt;.log</code>. The file that ships has <code>mplexer = 4280 -w -t</code>, which needs a certificate (see below). Change it to <code>mplexer = 4280 -w</code> if you don't use TLS.
 +
* The scripts find the installation through <code>$VME_ROOT</code> (the <code>vme/</code> directory). If it isn't set, they assume you started them in <code>vme/bin/</code>.
  
 +
=== Docker ===
 +
The repository also has a <code>Dockerfile</code> and a <code>docker-compose.yaml</code>. They build the game and serve a web client on port 80, with a websocket mplex on 4280. See the Docker section of [https://github.com/Seifert69/DikuMUD3/blob/master/README.md README.md].
  
 +
== Connecting and creating your god ==
 +
* Telnet: <code>telnet localhost 4242</code>.
 +
* Web: open <code>vme/www/client/index.html</code> in a browser. In the connect form choose '''This computer''' (protocol <code>ws</code>, host <code>localhost</code>, port <code>4280</code>), or fill in your own server.
  
 +
Create a new character with the name set in <code>immortal_name</code>. 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.
  
−
  6. Change directories into the 'vme2.0/zone' directory and then
+
== Opening the game to players ==
−
    compile all the zones by.
+
* '''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 <code>mplex hosts</code> list.
 +
* '''mplex on another machine.''' Start it with <code>-a &lt;address of the vme machine&gt;</code> (and <code>-s &lt;port&gt;</code> if the mother port isn't 4999), and add its address to <code>mplex hosts</code>.
 +
* '''The web client over https needs wss.''' A page served over https may not open a plain <code>ws://</code> connection. Run the websocket mplex as <code>./mplex -w -t -p 4280</code>, with <code>server.pem</code> (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. [https://github.com/Seifert69/DikuMUD3/blob/master/vme/src/mplex/mplex.md vme/src/mplex/mplex.md] has the details.
 +
* '''Telnet with TLS.''' <code>./mplex -z -p 4243</code> runs a telnets port beside the plain one. It reads the same <code>server.pem</code>.
 +
* '''Hosting the web client.''' Copy <code>vme/www/client/</code> and <code>vme/www/img/</code> side by side to your web server; the client looks for images in <code>../img/</code> and <code>img/</code>. Served from your own host name, the client suggests that host, port 4280, and <code>wss</code> when the page came over https. You can link to a ready-filled form, for example <code>index.html?host=mud.example.com&port=4280</code>.
  
 +
== Program options ==
 +
{| class="wikitable"
 +
! vme option !! Meaning
 +
|-
 +
| <code>-s &lt;file&gt;</code> || The <code>server.cfg</code> to use. The default is <code>../etc/server.cfg</code>, or the file named in the environment variable <code>VME_SERVER_CFG</code>.
 +
|-
 +
| <code>-l &lt;file&gt;</code> || The log file (default <code>./vme.log</code>).
 +
|-
 +
| <code>-w</code> || Time-warped: the game never sleeps between passes, so game time passes as fast as the machine allows. For tests.
 +
|-
 +
| <code>-L</code> || List the player files, then exit.
 +
|-
 +
| <code>-c</code> || Load and save every player file again, in the current format, then exit.
 +
|-
 +
| <code>-C</code> || Clean up the player files: '''deletes''' corrupt and old characters. Back up <code>vme/lib/</code> first.
 +
|-
 +
| <code>-d</code> || Print the profession tables, then exit.
 +
|-
 +
| <code>-h</code> || Help.
 +
|}
  
−
      ______________________________________________________________________
+
{| class="wikitable"
−
      vmc *.zon
+
! mplex option !! Meaning
−
      ______________________________________________________________________
+
|-
 +
| <code>-p &lt;port&gt;</code> || The port players connect to (default 4242).
 +
|-
 +
| <code>-w</code> || Websocket, for the web client.
 +
|-
 +
| <code>-t</code> || With <code>-w</code>: TLS, so <code>wss://</code>. Reads <code>./server.pem</code> and <code>./dh.pem</code>.
 +
|-
 +
| <code>-z</code> || TLS on a telnet port (telnets). Reads <code>./server.pem</code>. Not with <code>-w</code>.
 +
|-
 +
| <code>-a &lt;address&gt;</code> || Where vme runs (default localhost).
 +
|-
 +
| <code>-s &lt;port&gt;</code> || vme's mother port (default 4999).
 +
|-
 +
| <code>-l &lt;file&gt;</code> || The log file (default <code>./mplex.log</code>).
 +
|-
 +
| <code>-x</code> || Telnet: send the raw HTML, for debugging.
 +
|-
 +
| <code>-y</code> || Websocket: strip the HTML.
 +
|-
 +
| <code>-e</code>, <code>-r</code> || Telnet: echo characters locally, and redraw the prompt locally.
 +
|-
 +
| <code>-h</code> || Help.
 +
|}
  
 +
== When the server won't start ==
 +
Look at the end of the server log: <code>vme/bin/vme.log</code> when you started vme by hand, <code>vme/log/vme.log</code> when <code>runvme.sh</code> did. Common messages:
 +
{| class="wikitable"
 +
! Message !! Cause
 +
|-
 +
| <code>Can't bind Mother Connection port 4999</code> || Another vme is still running. Stop it, for example with <code>pkill -x vme</code>.
 +
|-
 +
| <code>Could not find server configuration file.</code> || vme wasn't started in <code>vme/bin/</code>. Start it there, or give the file with <code>-s</code>.
 +
|-
 +
| <code>The ... directory ... does not exist.</code> || A directory in <code>server.cfg</code> is wrong, or vme was started in the wrong directory.
 +
|-
 +
| <code>Mplex not from trusted host, terminating.</code> || An mplex connected from an address that isn't in <code>mplex hosts</code>.
 +
|-
 +
| <code>Could not open data file: ...</code> || A zone in <code>zonelist</code> has no compiled <code>.data</code> file. Compile it, or remove it from the list.
 +
|}
 +
If vme crashes, the core dump usually goes to systemd-coredump on a modern Linux: <code>coredumpctl list</code>, then <code>coredumpctl gdb</code> opens the most recent one in the debugger.
  
−
 
+
== Upgrading ==
−
 
+
See [[Upgrading Tips]].
−
  7. Change directory into the 'vme2.0/bin/' directory and type
 
−
    startvme.
 
−
 
 
−
  8. Now telnet into your mud using your domain name and port address
 
−
    that you set up in the server.cfg and log on the first immortal
 
−
    that you set in the server.cfg.
 
−
 
 
−
  Congratulations that is all there is to it.
 
−
 
 
−
  Make sure you read the IMPORTANT file in the doc directory.
 
−
 
 
−
 
 
−
  2.  Upgrading from a previous VME
 
−
 
 
−
  When upgrading your VME to the new 2.0 version we have tried to make
 
−
  the upgrade as painless as possible. It is of corse easier to start
 
−
  over again but we all know if you already have a mud running that is
 
−
  not always possible.  The following is an explanation of what needs to
 
−
  be done to get everything up and running.
 
−
 
 
−
  IN order to make this as easy as possible we have created a few
 
−
  convert scripts that will convert your zones socials and your help
 
−
  file to the new format.  We have replaced many of the SFUN_* functions
 
−
  with Dil so it is necessary to convert the zones to be able to get
 
−
  them to compile The zone convert script has proven to be around 90 to
 
−
  95% accurate so if you run into a few errors when compiling don't be
 
−
  sup prised but they should be easy enough to fix.
 
−
 
 
−
  2.1.  Back up old VME first
 
−
 
 
−
  We suggest you back up your old VME before you begin moving stuff
 
−
  around just incase some how you wipe something out.  First cd into the
 
−
  home directory where you VME is located and type the following
 
−
  command.
 
−
 
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      tar zcvf backupvme.tgz vme1.1
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
  2.2.  Moving Player base
 
−
 
 
−
  To move the player base from your old vme to the new server you can
 
−
  use either the cp command or the mv command we suggest however that
 
−
  you use cp so that you don't accidentally move your players into never
 
−
  never land.  This following command will move the player base only if
 
−
  both muds are installed as the same user.
 
−
 
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
 
 
−
      //first change directories into lib
 
−
      cd vme2.0/lib
 
−
 
 
−
      /Next remove the current player directories so they can be replaced
 
−
      rm -rf ply
 
−
 
 
−
      //Copy the files
 
−
      cp - R /home/mud/vme1.1/lib/ply .
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  2.3.  Converting Zones
 
−
 
 
−
  The zone convert script is written in Gawk and can be edited with a
 
−
  regular editor if your nervous and want to know what it is doing.  The
 
−
  script only works on one zone file at a time.  To convert one zone do
 
−
  the following.
 
−
 
 
−
 
 
−
  1. Copy the script from the 'vme2.0/scripts' directory into the
 
−
    directory you will be converting the zones in.
 
−
 
 
−
  2. Convert each zone by typing
 
−
 
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      convert.zone filename.zon newfilename.zon
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  NOTE
 
−
 
 
−
      If it says no such executable check the permissions and make sure the
 
−
      script is executable.
 
−
 
 
−
 
 
−
  If you want to convert more than one zone at a time the following is
 
−
  what I type at the command line to convert the entire zone directory.
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      for u in $(ls *.zon)
 
−
      do
 
−
      convert.zone $u $u.new
 
−
      done
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
  NOTE
 
−
 
 
−
      You must have Gawk installed and the examples are for Bsh and Ksh
 
−
      shells only if you are using another shell you may have to change how
 
−
      you do this.
 
−
 
 
−
 
 
−
  After converting them I then check to make sure the convert went fine
 
−
  and then copy the zones back to their original filename with the fol-
 
−
  lowing command.
 
−
 
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
 
 
−
      for u in $(ls *.zon)
 
−
      do
 
−
      mv $u.new $u
 
−
      done
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  2.4.  Combining your skils.def with the new commands.def
 
−
 
 
−
  In the new VME there is no skills.def.  The commands.def now allows
 
−
  you to alter any commands in the VME and how they are parsed.  The
 
−
  commands.def is order sensitive so you must put the commands in the
 
−
  order in which you need them to activate for example if you want 'n'
 
−
  to parse as north then 'north' needs to be the first command in
 
−
  commands.def starting with 'n'.
 
−
 
 
−
  The commands.def that comes with the vme is totally usable but if you
 
−
  have added any skills or commands to the skills.def you will need to
 
−
  move them to the new commands.def.
 
−
 
 
−
  Unfortunately there is no quick script to complete this task.  If you
 
−
  write one please submit it so it will be easier for other users of the
 
−
  VME.
 
−
 
 
−
 
 
−
  2.5.  Converting Socials
 
−
 
 
−
  The new socials are nothing but Dil commands so you can make your
 
−
  socials do anything you want them to.  We have included have the two
 
−
  files you will have to manually add your 'socials.def' into the
 
−
  'commands.def'.  Remember you can not have duplicates it may cause the
 
−
  VME to crash if you do we are working with removing this problem but I
 
−
  am not sure if this has been fixed by the release.  Just make sure you
 
−
  don't have duplicates and this will not happen.  To convert your
 
−
  socials to the new socials just do the following.
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  ______________________________________________________________________
 
−
 
 
−
  //make a work directory
 
−
  mkdir work
 
−
 
 
−
  //change into your work directory
 
−
  cd work
 
−
 
 
−
  //copy file from your old vme
 
−
  cp /home/mud/vme1.1/etc/actions .
 
−
 
 
−
  //copy script from new mud
 
−
  cp /home/mud/vme2.0/scripts/convert.socials
 
−
 
 
−
  //convert the socials
 
−
  convert.socials actions
 
−
  ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  NOTE
 
−
 
 
−
      You must have Gawk installed and the examples are for Bsh and Ksh
 
−
      shells only if you are using another shell you may have to change how
 
−
      you do this.  If it says no such executable check the permissions and
 
−
      make sure the script is executable.
 
−
 
 
−
 
 
−
 
 
−
  2.6.  Converting Help files
 
−
 
 
−
  The new VME's help system is coded entirely in Dil.  This allows you
 
−
  to make the help system do what ever you want.  This also means you
 
−
  must convert the old files to the new format.  You could leave the
 
−
  help files that come with the new VME but that would mean you would be
 
−
  missing any of the help files you ahve added.  With this in mind we
 
−
  have created two convert scripts one for wizard help and one for
 
−
  general help and local help.
 
−
 
 
−
  We have attempted to make this as easy as possible but it does require
 
−
  some work removing and moving files to get it all to convert.  Don't
 
−
  stress follow the next steps carefully and you will find the
 
−
  conversion process is not as bad as it seems.
 
−
 
 
−
 
 
−
  1. Change directories into the new help file.
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      cd /home/mud/vme2.0/etc/help/strings
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  2. Remove all the help files and index files that come with the
 
−
    release
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      rm *
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
  WARNING
 
−
 
 
−
  When doing 'rm *' make sure your in the right directory everything in
 
−
  that directory will be lost and there is no getting it back.
 
−
 
 
−
  3. Copy the help files from the old VME to the new one.
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      cp /home/mud/vme1.1/etc/help* /home/mud/vme2.0/etc/help/strings
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  4. Copy the convert scripts to the new directory
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      cp /home/mud/vme2.0/scripts/convert.help /home/mud/vme2.0/etc/help/strings
 
−
      cp /home/mud/vme2.0/scripts/convert.wizhelp /home/mud/vme2.0/etc/help/strings
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  5. Make both the 'help' and 'help.local' into one file.
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      cat help help.local >help.new
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  6. Convert the 'help.new' and 'help.wiz' using the scripts.
 
−
 
 
−
 
 
−
      ______________________________________________________________________
 
−
      convert.help help.new
 
−
      convert.wizhelp help.wiz
 
−
      ______________________________________________________________________
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  7. Now just log on and the helps are fixed. No reboot is necessary.
 
−
 
 
−
  NOTE
 
−
 
 
−
      You must have Gawk installed and the examples are for Bsh and Ksh
 
−
      shells only if you are using another shell you may have to change how
 
−
      you do this.
 
−
 
 
−
 
 
−
 
 
−
 
 
−
  3.  Debugging if theServer won't run
 
−
 
 
−
  If the server doesn't run right up you can look in the log directory
 
−
  and edit the following file.
 
−
 
 
−
 
 
−
 
 
−
  vme2.0/log/vme.log
 
−
 
 
−
 
 
−
  If you don't understand the log don't worry just block the last 50
 
−
  lines of your log and send it to:
 
−
 
 
−
 
 
−
      whistler@vlahalla.com
 

Latest revision as of 06:14, 15 November 2026

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.