Local Setup

TL;DR: Build the server on Ubuntu 18.04 or 20.04 with gcc 9 or newer, install it into a runtime directory, clone dreamland_world and dreamland_fenia_public into it and start bin/dreamland etc/dreamland.xml. You get ports 9000, 9001 and 1234 and two administrator characters. This page covers environments, the runtime layout, ports, logging in and what to rebuild or reload after a change. The build commands themselves are in the README. Use when: you set up a local server, you cannot log in, or you changed something and do not know whether to rebuild, reload or restart. Source of truth: dreamland_code/README.md, dreamland_code/configure.ac, dreamland_code/etc/dreamland.xml.template, dreamland_code/admin/acinclude.m4.in, dreamland_code/admin/drone-build.sh, dreamland_code/src/dreamland.cpp, dreamland_code/src/plugin/pluginmanager.cpp, dreamland_code/plug-ins/iomanager/backdoorhandler.cpp, dreamland_world/ports/ Verified: 2026-11-02 against dreamland_code a7c4fd10, dreamland_world a35c62ce, dreamland_fenia_public c28874b

Build and install commands: README.md. This page does not repeat them. It adds what the README leaves out.

Pick an environment

Environment	Notes
Ubuntu 18.04 or 20.04, real machine or VM	The reference setup. gcc 9 or newer (the build uses gcc-only flags)
Docker	Dockerfile.localbuild (Ubuntu 20.04 build container with ccache) and Dockerfile.localrun (runtime container) in dreamland_code
Windows	Ubuntu under WSL 2, edited from VS Code. See below
Gitpod	.gitpod.yml and Dockerfile.gitpod in dreamland_code. Opens ports 9000, 9001 and 1234
macOS	Not supported. The server does not build natively, use Docker or a Linux VM

Ubuntu 18.04 ships gcc 7. The README shows the PPA route to gcc 9.

dreamland_docker is a separate repository with prebuilt-image Dockerfiles. It was last changed in 2020 (unverified that its images still match the code). Prefer the Dockerfiles inside dreamland_code.

Build notes the README does not spell out

• The build is out of tree. Sources, build directory (objs) and runtime directory (--prefix) are three different folders.
• make -f Makefile.git generates the configure script. It needs perl besides automake, libtool and autoconf. Run it again, and then configure, when configure.ac, any Makefile.am, Makefile.inc or a .m4 file changes.
• Default flags are -g -Og -std=c++17, a debug build. configure --enable-optimization exists but adds old 32-bit x86 flags. Do not rely on it.
• The locale-gen uk_UA step matters. The engine asks for the uk_UA.koi8u locale for Cyrillic sorting. If it is missing the server still starts but falls back to the default locale and sorts Russian text wrongly.
• Some C++ sources are generated by a tool called moc from XML_VARIABLE and XML_OBJECT lines in headers. If you add or remove such a line in a header, a stale generated file can survive. Delete *_moc_xml.cpp under the build directory and run make again. The server's own build script does the same.
• The first full build compiles about 90 directories and is slow on a small machine. Later builds touch one or two plugins.

What configure and make install create

configure builds the runtime tree under --prefix and fills it:

• bin/, lib/, libexec/ with the program, the core library and the plugins. libexec/plugin.xml is the plugin load list, copied from a template.
• etc/dreamland.xml, copied from etc/dreamland.xml.template if it does not exist yet.
• share/, empty. You clone dreamland_world into share/DL.
• var/log, var/run, var/misc, var/db/... for logs, player files, notes, saved mobiles and objects, and the Fenia database.
• Two administrator characters copied into var/db/player and var/db/oldstyle/player, unless files with those names exist.
• The Fenia database var/db/fenia, loaded from admin/fenia/fenia.dump by db_load, plus two saved nanny mobiles unpacked from admin/fenia/nanny-mobs.tar. This runs only if var/db/fenia/fenia does not exist.

After the install, clone the two repositories into the tree:

git clone https://github.com/dreamland-mud/dreamland_world.git share/DL
git clone https://github.com/dreamland-mud/dreamland_fenia_public.git share/DL/fenia/public

Run these from the runtime directory. See Repositories for what each one provides.

The server config

etc/dreamland.xml is read at start and also written back. The server increments bootVersion on every start and saves the file again about once a minute, on every game tick, to store worldTime. Keep your own edits small and do not be surprised by a changed file in a diff.

Field	Stock value	Meaning
tablePath	share/DL	Root of dreamland_world
areaDir, areaListFile	share/DL/areas.local, area.lst	Zones to load. The loader adds .xml, so the list is area.lst.xml
feniaScriptDir	share/DL/fenia	Base for cs load and cs save all
feniaPublicScriptDir	share/DL/fenia/public	Declared, but nothing reads it
feniaDbDir	var/db/fenia	Fenia database
apiPort	1235	HTTP API for the site and the bots
options	pk save_objs save_mobs buildplot	Server options, see below
pulsePerSecond, pulseViolence, pulseMobile, pulseTick	4, 12, 16, 240	Timing, see Engine-Time-and-Pulses
logPattern	absent	Log file name pattern

Only zones listed in area.lst.xml are loaded. They are read once at start, so a new or edited zone needs a restart.

The buildplot option

The stock template turns on buildplot. It is meant for builders and testers, and it changes behaviour:

• Mobs do not start fights with players.
• Hunger and thirst do not tick.
• Clan skills skip the clan membership check.
• The "vnum not found on world startup" log lines are not written.
• Fenia eval also works for a character with a feniasecurity attribute of 110 or more.
• The Fenia API dump and the help keyword index are not written to disk.
• Fenia sees the option as the root field buildplot.

Remove the word from options to test the game as players see it.

Logging

Without logPattern the server writes its log to standard output. To log to files, stop the server and add a line to etc/dreamland.xml (the server writes its in-memory config back every tick and at shutdown, so edits made while it runs are lost):

<logPattern>var/log/%Y%m%d-%H%M%S.log</logPattern>

The pattern takes date and time codes and is expanded once, when the log opens, so the file is named after the start time. To stop the server send SIGINT or SIGTERM (Ctrl-C in the foreground). Both start a normal shutdown.

Ports

Ports are defined by files in share/DL/ports/, one file per port. After you add or change one, restart the server.

Port	Kind	Use
9000	telnet	Normal entry with character creation
9001	telnet, backdoor	Login on one line, skips the creation dialog
1234	WebSocket	The browser client
1236	WebSocket	Same as 1234 on a stock install (its file sets newnanny false, which is also the default)
9127	telnet, backdoor	Local connections only (127.0.0.1)
1235	HTTP	Game API, from apiPort

A port that cannot be opened is logged as an error, for example bind::port:9000::listen:5::Address already in use, and the server keeps running without it.

Logging in

Telnet to 9000 for the normal dialog:

telnet localhost 9000

Backdoor ports ask for one line in the form <codepage> <name> <password>. The first character is the codepage number:

Number	Encoding
1	KOI8-R
2	CP866
3	CP1251
4	ISO-8859-5
5	Mac
6	transliteration
7	UTF-8

For example, 7 Cadmus KadmKadm logs in over UTF-8. A zero or a missing number gives Wrong codepage. Replace localhost with the VM's address if the server runs in a VM or container.

The two default characters

Both are level 107 with the coder attribute, which gives maximal trust and the right to use eval and cs. Both use the same password, KadmKadm (documented in the README, the stored hash is not re-checked here). These exist only for local development. Never keep them on a server that other people can reach.

Character	Class	Interface	Starts in
Kadm	universal, which is not a shipped profession, see Local-Testing	Russian commands and output (rucommands is set, which seeds config lang to Russian)	room 3001
Cadmus	warlock	English	room 31000, in a sample zone

The profile file for Cadmus has no rucommands, so its language is seeded as English. Change it later with config lang. See L10n.

What to do after a change

You changed	Do
A .cpp file in one plugin	In objs/plug-ins/<dir>: make -j 4 && make install. In the game: plugin reload <name>
Several plugins	Build each, then plugin reload changed
A .cpp file in src/ only	In objs/src: make -j 4 && make install, then restart the server
A header in src/, or any header plugins share	Full build in objs, then restart
A file in dreamland_world	Usually plugin reload most re-reads it. Zones and port files need a restart
A public Fenia file	Load it in the game, see Fenia-Scripts

Reload rules:

• plugin list shows loaded plugins with the load time. Use the name shown there.
• plugin reload all unloads every plugin including descriptor, which holds the connections, so everybody is disconnected.
• plugin reload most reloads everything except descriptor.
• plugin reload changed reloads plugins whose library changed on disk, also skipping descriptor.
• Never reload after a change to a core header while the old core is still running. The new plugins expect the new core layout and the reload fails or crashes. Restart instead. The same applies when a plugin starts calling a new function from a plugin that most skips.
• After any reload, read the log for Exception loading or undefined symbol, and for a load [<name>] so line per plugin.

cs load <name> reads a script from feniaScriptDir (read at boot, so stop the server before you change it), and a name starting with public/ is looked up in a public folder inside that directory. The stock template puts feniaScriptDir at share/DL/fenia, and the README clones the public repository to share/DL/fenia/public, so cs load public/utils/chance finds it. configure does not overwrite an existing etc/dreamland.xml: a config made from an older template says share/DL/fenia.local, and there cs load public/... fails until you change it. The seeded Fenia database holds only the system, Russian and nanny scripts, so the public helpers (.tmp.chance and others) are absent until you load them. See Fenia-Scripts.

Windows with WSL 2

The server builds only on Linux, but Windows works well through WSL 2:

1. Install WSL 2 with an Ubuntu 20.04 distribution by following Microsoft's guide at https://learn.microsoft.com/windows/wsl/install.
2. In Ubuntu, follow the README: install packages, build, install, clone the two repositories.
3. Install Visual Studio Code and the Remote - WSL extension. dreamland_code/.vscode/extensions.json recommends it together with the C/C++ extension.
4. Open the source folder from inside WSL (the "Open a remote window" button, then "New WSL window"). The workspace file src/dreamland_code.code-workspace opens dreamland_code and a sibling dreamland_world together.

The old Windows page described a first-start crash in WSL 1 that was fixed in WSL 2 (unverified here). Use WSL 2.

Containers

Dockerfile.localbuild makes a build container. Mount a folder that holds the sources, the build directory and the runtime directory, attach a shell and run the Ubuntu steps from the README. Dockerfile.localrun makes a small runtime container for an already built runtime directory. It exposes ports 9000, 9001 and 1234. Its header comment also maps 1235. The container starts the server with ulimit -c unlimited, so a crash leaves a core file for gdb.

If it does not start

See Troubleshooting. To test what you built, see Local-Testing.

See also

• Local-Testing
• Troubleshooting
• Repositories
• Contributing-Workflow
• Engine-Architecture