Difference between revisions of "Getting started - Step by Step"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
 
Line 1: Line 1:
−
To get started with DikuMUD, you're going to need a few things.
+
This page takes you from nothing to playing your own DikuMUD III game in a browser. It uses Ubuntu; other Linux distributions work the same way with their own package names. [[Manual:Installation]] has the details behind each step.
  
−
First of all, you're going to need a host machine to run it on. It's easiest if this is one you own, but it's also ok as long as you have permission. Running a MUD means that there will be network connections to the machine and the to do that it's going to have to listen for network traffic.  Those owning the machine might not take kindly to allowing these network connections.  There's security risk involved, and there may be a cost involved for the traffic itself.
+
== 1. A machine to run it on ==
 +
You need a Linux machine you may run a server on. It is easiest if it is your own. A MUD listens for network connections, and whoever owns the machine may not want that: it is a security risk, and the traffic may cost money. For trying things out, your own computer is fine; nothing has to be reachable from the internet.
  
−
The MUD will run on a wide variety of platforms, but is written using '''(distribution)''', a LINUX host.
+
== 2. Install the tools ==
 +
<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>
  
−
==== Pre-requisites ==== - stuff that has to already be installed on the platform include
+
== 3. Get the source ==
 +
<pre>
 +
git clone https://github.com/Seifert69/DikuMUD3.git
 +
cd DikuMUD3
 +
</pre>
 +
This makes a <code>DikuMUD3</code> directory that is also a git repository linked to the one on GitHub, so <code>git pull</code> fetches later changes.
  
−
    gcc/g++
+
The quick way, used on this page, is to run the game straight from this directory. That is fine for trying it out. For a game that others play, think early about keeping your own changes (configuration, zones) on a branch of your own, so that updates from GitHub can be merged in; see [[Upgrading Tips]].
−
    flex/bison (sudo apt-get install bison flex)
 
−
    boost devel (sudo apt-get install libboost-all-dev)
 
  
−
For CentOS:
+
== 4. Build ==
−
    sudo yum group install "Development Tools"
+
<pre>
 +
cmake .
 +
make all -j$(nproc)
 +
</pre>
 +
This builds the server (<code>vme</code>), the network front end (<code>mplex</code>) and the zone compiler (<code>vmc</code>) into <code>vme/bin/</code>, compiles all the zones, and runs the unit tests at the end. It takes a few minutes. If the machine runs out of memory, use a smaller number than <code>$(nproc)</code>, for example <code>-j2</code>.
  
−
should do it, but you may need:
+
<code>cmake .</code> makes a debug build, which is right while you are learning. For a game with players, see the build types in [[Manual:Installation]].
−
    sudo yum install boost-devel flex-devel
 
  
−
To download a copy, you can pull down a current copy of the software from GitHub with:
+
== 5. Start the game ==
−
+
Open three terminals (or use <code>screen</code> or <code>tmux</code> if the machine has no desktop). In each one, go to <code>vme/bin</code> first.
−
    git clone https://github.com/Seifert69/DikuMUD3.git
 
  
−
While a lesson in using git is beyond the scope of this document, you're probably going to want a version control system at some point, and git is probably the most widely in use at this point. You could just download it in a package from GitHub and make a directory to unpack it to, but this will download the current version into a 'DikuMUD3' directory, create the local git repository, link it to the master on GitHub and give you an unpacked directory of files.
+
Terminal 1, the game server:
 +
<pre>
 +
cd DikuMUD3/vme/bin
 +
./vme
 +
</pre>
 +
Its messages go to <code>vme.log</code> in the same directory, not to the terminal.
  
−
Now, what I'm about to say is dirty, and you shouldn't do it...but this document isn't meant to go into the nitty gritty of separating your development environment from your test and production environments, setting up a pipeline to configure development code and keeping pristine environments...this is the wild, wild west, and we're just going to run the MUD from your local repository....Just remember that I told you not to do this, so later when you're cursing me out for making your setup all messy as you're making copies of config files and figuring out what you should replicate and what you shouldn't, you can hear me saying 'I told you not to' in the background.
+
Terminal 2, the websocket front end for the browser:
 +
<pre>
 +
cd DikuMUD3/vme/bin
 +
./mplex -w -p 4280
 +
</pre>
  
−
What SHOULD you do?  Set up a production directory to copy this clone to that you'll run the MUD from, and figure out a good work pattern for pushing out production code.  Make changes under source control, and decide if you're going to be a contributor to the main project.  Separate the config data from the dev environment to the production one and protect any secrets from being accidentally pushed up to the main.  In the end, you'll save some heartache.  But if you just want to get started today....
+
Terminal 3, the logs:
 +
<pre>
 +
cd DikuMUD3/vme/bin
 +
tail -f vme.log mplex.log
 +
</pre>
  
−
== Compiling the MUD ==
+
The server log names a number of zones it could not open (<code>Could not open data file</code>). That is expected: the list of zones in <code>vme/etc/zonelist</code> is longer than the set of zones in the repository.
  
−
Now on to getting it up and running.  What you have is a bunch of files, but what you want is an up and running world. That means it needs to be compiled to run on your chosen platform and linked in with all of the local support libraries.  There's a method to this madness.
+
If you prefer telnet, start a telnet front end too, in another terminal, with its own log so it does not share <code>mplex.log</code>:
 +
<pre>
 +
./mplex -p 4242 -l mplex-telnet.log
 +
</pre>
 +
and connect with <code>telnet localhost 4242</code>.
  
−
How to build & launch
+
== 6. Connect with the web client ==
 +
Open <code>DikuMUD3/vme/www/client/index.html</code> in a browser (for example <code>firefox vme/www/client/index.html</code>). In the connect form, choose '''This computer''' (protocol <code>ws</code>, host <code>localhost</code>, port <code>4280</code>) and connect. You should see the game's welcome screen.
  
−
First build the binaries:
+
== 7. Create your god ==
 +
Create a new character called '''Papi'''. This name is set by <code>immortal_name</code> in <code>vme/etc/server.cfg</code>, and a character with that name is made the highest level (255) when it enters the game. Before anyone else can reach your game, change <code>immortal_name</code> to a name of your own and create that character.
  
−
    cd vme/src/
+
Now look around. [[Wizarding 101]] and [[Manual:Wizhelp Files]] describe the administrator commands.
−
    make all #
 
  
−
There is a flag (-j8) in the Makefile to compile on 8 threads in parallel. If you run into errors with the compile and you're on a machine with limited resources, this may cause a race condition during the compilation. Edit Makefile and remove this flag if the compile starts complaining about errors that should be reported to the compiler developers.
+
== 8. Stop it, change something, start it again ==
 +
Press Ctrl-C in the terminal running <code>vme</code>. The server saves the players and stops. mplex tells the players that the connection was broken. It keeps running and reconnects by itself when the server is back.
  
−
Make sure .def files are pre-processed:
+
Try a change: set <code>mudname</code> in <code>vme/etc/server.cfg</code> to the name of your game and start <code>./vme</code> again.
  
−
    cd ../etc/
+
When you change a zone in <code>vme/zone/</code>, compile it and restart the server, since zones are read only at boot:
−
    make all
+
<pre>
 +
cd DikuMUD3/vme/zone
 +
../bin/vmc -m -d ../etc/ -I../include/ *.zon
 +
</pre>
 +
The [[Manual:Zone Manual]] explains how zones are written.
  
−
Then compile the zones:
+
== 9. Keeping it running ==
 +
Programs started in a terminal stop when you log out. For a game that stays up, use <code>vme/bin/startvme.sh</code> and <code>stopvme.sh</code>. They run vme and the mplexers in the background and start them again when they stop, which is also what makes the in-game <code>reboot</code> command work. See [[Manual:Installation]], which also covers opening the game to the internet (firewall, <code>wss://</code> certificates, putting the web client on a web server).
  
−
    cd ../zone/
+
== Where next ==
−
    ../bin/vmc -m -I../include/ *.zon
+
* [[Understanding the File System]]: what is in each directory.
−
 
+
* [[Understanding the Architecture of DikuMUD at runtime]]: how the programs work together.
−
== Running the MUD ==
+
* [[Manual:Discord]]: linking the game to a Discord server.
−
 
 
−
Now you're ready to launch, the dev likes to four tabs in shell:
 
−
 
 
−
    cd ../log/                # Do this before you start the tabs.  Git docs say to run from bin, but if you do, that's where it will log to.
 
−
    ../bin/vme                # tab1
 
−
    tail -f vme.log            # tab2
 
−
    ../bin/mplex -w -p 4280    # tab3
 
−
    tail -f mplex.log          # tab4
 
−
 
 
−
There's a number of ways to get multiple tabs - from multiple Terminal windows, to using screen if your host environment isn't running a graphical windowing system.
 
−
 
 
−
Tailing the logs are optional steps - you'll definitely need tab1 and tab3 for your MUD to run.
 
−
 
 
−
You can also run these commands in the background using
 
−
 
 
−
    cd ../log                                              # So running the MUD logs to DikuMUD3/vme/log
 
−
    nohup ../bin/vme > vmenohup.log &                      # This starts the MUD engine
 
−
    nohup ../bin/mplex -w -p 4280 > mplexnohup.log &      # This starts a Websockets listener on port 4280 that will connect to your MUD
 
−
 
 
−
This will keep the MUD up and running in a background process even if you terminate your login on your host. Note that if you DO log out with the MUD running on nohup, your process will no longer be retrievable to the foreground (The & sends the process to the background, retrieved with the 'fg' command) on subsequent logins, since your next login shell will not be the parent.  You may have to KILL the MUD to stop it if you can't log in and shut it down.
 
−
 
 
−
If you run it from tabs, terminal windows, or just get it back with fg you can terminate the running programs with Ctrl-C in the appropriate shell.
 
−
 
 
−
You can also launch a telnet mplex using e.g. mplex -p 4242 And then telnet localhost 4242. But telnet is best for debugging
 
−
 
 
−
== Connecting to the MUD ==
 
−
 
 
−
DikuMUD3 comes with a web front-end client. To open the client directly if you're on a windowed distro:
 
−
 
 
−
    cd ../www/
 
−
    firefox index.html
 
−
 
 
−
If you're going to be hosting the MUD, you should copy the files in ../www to your web hosted files directory so they are available to your users at your web address.  (If you own the box, probably /var/www/html or something similar).
 
−
 
 
−
If you're using the web client, the distributed version doesn't point to your MUD, it points to the author's.  Edit the index.html file and find all of the host references (including the ones in the urls like www.valhalla.com) and replace them with your fully qualified domain name, IP address or localhost and set the port to match mplex (4280 if you used that).
 
−
 
 
−
Once you load index.html in Firefox (or browser of choice), you'll have the quick link to connect or can manually input a websocket host to connect to. Press connect and you're connected to a game from the 20th century with 21st century technology!
 

Latest revision as of 06:14, 15 November 2026

This page takes you from nothing to playing your own DikuMUD III game in a browser. It uses Ubuntu; other Linux distributions work the same way with their own package names. Manual:Installation has the details behind each step.

1. A machine to run it on

You need a Linux machine you may run a server on. It is easiest if it is your own. A MUD listens for network connections, and whoever owns the machine may not want that: it is a security risk, and the traffic may cost money. For trying things out, your own computer is fine; nothing has to be reachable from the internet.

2. Install the tools

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

3. Get the source

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

This makes a DikuMUD3 directory that is also a git repository linked to the one on GitHub, so git pull fetches later changes.

The quick way, used on this page, is to run the game straight from this directory. That is fine for trying it out. For a game that others play, think early about keeping your own changes (configuration, zones) on a branch of your own, so that updates from GitHub can be merged in; see Upgrading Tips.

4. Build

cmake .
make all -j$(nproc)

This builds the server (vme), the network front end (mplex) and the zone compiler (vmc) into vme/bin/, compiles all the zones, and runs the unit tests at the end. It takes a few minutes. If the machine runs out of memory, use a smaller number than $(nproc), for example -j2.

cmake . makes a debug build, which is right while you are learning. For a game with players, see the build types in Manual:Installation.

5. Start the game

Open three terminals (or use screen or tmux if the machine has no desktop). In each one, go to vme/bin first.

Terminal 1, the game server:

cd DikuMUD3/vme/bin
./vme

Its messages go to vme.log in the same directory, not to the terminal.

Terminal 2, the websocket front end for the browser:

cd DikuMUD3/vme/bin
./mplex -w -p 4280

Terminal 3, the logs:

cd DikuMUD3/vme/bin
tail -f vme.log mplex.log

The server log names a number of zones it could not open (Could not open data file). That is expected: the list of zones in vme/etc/zonelist is longer than the set of zones in the repository.

If you prefer telnet, start a telnet front end too, in another terminal, with its own log so it does not share mplex.log:

./mplex -p 4242 -l mplex-telnet.log

and connect with telnet localhost 4242.

6. Connect with the web client

Open DikuMUD3/vme/www/client/index.html in a browser (for example firefox vme/www/client/index.html). In the connect form, choose This computer (protocol ws, host localhost, port 4280) and connect. You should see the game's welcome screen.

7. Create your god

Create a new character called Papi. This name is set by immortal_name in vme/etc/server.cfg, and a character with that name is made the highest level (255) when it enters the game. Before anyone else can reach your game, change immortal_name to a name of your own and create that character.

Now look around. Wizarding 101 and Manual:Wizhelp Files describe the administrator commands.

8. Stop it, change something, start it again

Press Ctrl-C in the terminal running vme. The server saves the players and stops. mplex tells the players that the connection was broken. It keeps running and reconnects by itself when the server is back.

Try a change: set mudname in vme/etc/server.cfg to the name of your game and start ./vme again.

When you change a zone in vme/zone/, compile it and restart the server, since zones are read only at boot:

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

The Manual:Zone Manual explains how zones are written.

9. Keeping it running

Programs started in a terminal stop when you log out. For a game that stays up, use vme/bin/startvme.sh and stopvme.sh. They run vme and the mplexers in the background and start them again when they stop, which is also what makes the in-game reboot command work. See Manual:Installation, which also covers opening the game to the internet (firewall, wss:// certificates, putting the web client on a web server).

Where next