Difference between revisions of "Manual:Installation"
(checked against the current code (wiki review 2026-11-15)) |
|||
| Line 1: | Line 1: | ||
| − | + | 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 <code>vme/bin/</code>: | |
| − | + | * '''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 <code>vme/zone/*.zon</code> into the files vme loads. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | There is also a web client in <code>vme/www/client/</code>, 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 <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. | ||
| − | + | 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. | ||
| − | + | On Fedora: | |
| − | + | <pre> | |
| − | + | 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> | ||
| − | + | == Building == | |
| − | + | From the top of the repository: | |
| − | + | <pre> | |
| + | cmake . | ||
| + | make all -j$(nproc) | ||
| + | ctest | ||
| + | </pre> | ||
| − | + | <code>make all</code> does all of this: | |
| − | + | * builds vme, mplex, vmc and the helpers pp and defcomp into <code>vme/bin/</code>, | |
| − | + | * 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>. | |
| − | |||
| − | |||
| + | == 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. | ||
| − | + | === Which zones are loaded === | |
| − | + | <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. | |
| − | + | == Compiling zones == | |
| − | + | <code>make all</code> has already compiled the zones. After you change a zone: | |
| − | + | <pre> | |
| − | + | 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. | ||
| − | + | == 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 === | |
| − | + | For a game that stays up, use the scripts in <code>vme/bin/</code>: | |
| − | + | <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-<port>.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. | ||
| − | + | == 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 <code>mplex hosts</code> list. | |
| + | * '''mplex on another machine.''' Start it with <code>-a <address of the vme machine></code> (and <code>-s <port></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 <file></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 <file></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" | |
| − | + | ! mplex option !! Meaning | |
| − | + | |- | |
| + | | <code>-p <port></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 <address></code> || Where vme runs (default localhost). | ||
| + | |- | ||
| + | | <code>-s <port></code> || vme's mother port (default 4999). | ||
| + | |- | ||
| + | | <code>-l <file></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]]. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
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/*.zoninto the files vme loads.
There is also a web client in vme/www/client/, which needs no building.
Contents
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
.deffiles invme/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:
doxygenandgraphviz: if CMake finds Doxygen, the build also writes code documentation todocs/.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
.deffiles invme/etc/into the.datfiles 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.shruns vme with../etc/server.cfgand the logvme/log/vme.log. It keeps the last ten logs compressed (vme.log.1.gzand on), and starts vme again whenever it exits. That is what makes the in-gamerebootcommand work.runmplex.shis started once for eachmplexerline inserver.cfg. The line gives the port, then any mplex options. Each mplex logs tovme/log/mplex-<port>.log. The file that ships hasmplexer = 4280 -w -t, which needs a certificate (see below). Change it tomplexer = 4280 -wif you don't use TLS.- The scripts find the installation through
$VME_ROOT(thevme/directory). If it isn't set, they assume you started them invme/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.htmlin a browser. In the connect form choose This computer (protocolws, hostlocalhost, port4280), 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 hostslist. - 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 tomplex 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, withserver.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 4243runs a telnets port beside the plain one. It reads the sameserver.pem. - Hosting the web client. Copy
vme/www/client/andvme/www/img/side by side to your web server; the client looks for images in../img/andimg/. Served from your own host name, the client suggests that host, port 4280, andwsswhen the page came over https. You can link to a ready-filled form, for exampleindex.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.