All Guides·Downloads

Reference · v1.0.1

The Server Handbook

The complete manual for devilutionx-server — every flag, every deployment path, and the reasoning behind the machine. The same text ships inside every server package and lives in the repository as HANDBOOK.md.

Reference Linux · WSL · Docker v1.0.1

What it is

A port of DevilutionX that runs the game engine as a headless dedicated server — no window, no display server, no window manager, no audio device. It hosts a public multiplayer game (TCP/IP or ZeroTier), keeps an idle player seated in the game so the world stays up, and runs forever until stopped — ideal for a systemd service, a container, or any machine without a desktop.

The normal devilutionx client is unaffected and joins the server's game exactly like any other multiplayer game.

Requirements (release binary)

The release binary is built for x86-64 Linux, glibc ≥ 2.35 — in practice Ubuntu 22.04 LTS or newer (22.04, 24.04, 26.04, and current Debian releases all qualify). Only three shared libraries are not bundled:

sudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 zlib1g

Everything else — libfmt, libsodium, bzip2, and the C++ runtime — is statically linked into the binary, so there are no version-specific dependencies like libfmt.so.9 to chase across distro releases. MPQ game assets are always supplied by you; they are never included.

Building from source (Linux / WSL)

For a dev build:

cd DevilutionX-1.5.5
cmake -B build-server -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
cmake --build build-server -j$(nproc) --target devilutionx devilutionx-server

For a release binary — what ships in the GitHub tarball — use the release flag set, so the result runs on any Ubuntu 22.04+ distro regardless of build host:

cmake -B build-server -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
    -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 \
    -DDEVILUTIONX_SYSTEM_LIBFMT=OFF \
    -DDEVILUTIONX_SYSTEM_LIBSODIUM=OFF \
    -DDEVILUTIONX_SYSTEM_BZIP2=OFF \
    -DDEVILUTIONX_STATIC_CXX_STDLIB=ON
cmake --build build-server -j$(nproc) --target devilutionx-server

Quick start

With the game MPQs (hellfire.mpq, hfmonk.mpq, …) in a directory:

cd build-server
./devilutionx-server --data-dir /path/to/mpqs \
    --save-dir ~/.local/share/devilutionx-server \
    --config-dir ~/.config/devilutionx-server

The server prints Hosting game … on TCP/IP, binds TCP port 6112 on all interfaces, and idles until killed. Stop it with Ctrl+C (SIGINT), kill (SIGTERM), or systemctl stop — it shuts down cleanly and saves.

Then, on a client machine, run stock DevilutionX → Multiplayer → TCP/IP → enter the server's IP → join server-XXXX (or your --name).

Options

--server-tcp [ADDRESS]   Host a TCP/IP game (default). Binds to all interfaces
                         by default; give an address to bind to, e.g. a
                         ZeroTier interface address.
--server-zerotier        Host a ZeroTier game on the configured network.
--server-zt-network ID   Join the ZeroTier network with the given 16-hex-digit
                         ID before hosting (default: Diasurgical public Earth).
--join ADDRESS           Do not host: join the game at ADDRESS as an idle
                         player instead (TCP/IP host name or IP, or the
                         advertised game name for ZeroTier).
--name NAME              Game name shown in the game list (default: server-<pid>).
--password PASSWORD      Password of the game (hosted or joined; default: public).
--port PORT              TCP port to listen on (default: 6112).
--hero-class CLASS       Idle player class: warrior rogue sorcerer monk bard
                         barbarian (default: warrior).
--hero-name NAME         Idle player name (default: Server).
--game GAME              hellfire or diablo (default: hellfire).
--difficulty N           0 = normal, 1 = nightmare, 2 = hell (default: 0).
--full-quests            Enable the full quest set for the game.
--data-dir PATH          Asset (MPQ) search directory.
--save-dir PATH          Directory for the server hero save.
--config-dir PATH        Directory for configuration files.
-f                       Display frame count in the log.
--verbose                More verbose logging.
-h, --help               Show this help.

Public games over TCP/IP

Public games over ZeroTier

  1. Create (or pick) a ZeroTier network and have every player plus the server join it.
  2. On the server: join the network with the ZeroTier CLI (zerotier-cli join <network>), authorize the node, then run:
    ./devilutionx-server --server-zerotier \
        --server-zt-network 0123456789abcdef \
        --name "My ZT Server" --data-dir ... --save-dir ... --config-dir ...

    (If the network is joined externally as above, --server-zt-network can be omitted; the server will use the network configured in its ini file — by default the Diasurgical public Earth network.)

  3. Clients join the same ZeroTier network, run stock DevilutionX → Multiplayer → ZeroTier, and pick the game from the list.

You can also bind a TCP game to the ZeroTier interface only: --server-tcp <zt-ip-address>.

The idle player

The server seats a real player (Server by default) so the simulation stays alive. On first start it creates a save for the configured --hero-class; later runs reuse that save (level, equipment, etc. persist). The idle player just stands in town — it takes no actions.

Bot mode (--join) behaves the same, but joins someone else's game instead of hosting — e.g. --join 192.168.1.10 --hero-name Bot.

Running as a service (systemd)

[Unit]
Description=DevilutionX headless dedicated server
After=network-online.target
Wants=network-online.target

[Service]
User=games
ExecStart=/opt/devilutionx/devilutionx-server \
    --data-dir /opt/devilutionx \
    --save-dir /var/lib/devilutionx-server \
    --config-dir /etc/devilutionx-server \
    --name "My Public Server" --server-tcp
Restart=on-failure
# The server needs no display, audio, or input devices.

[Install]
WantedBy=multi-user.target

The binary itself requires no window manager and works in containers (docker run -d -p 6112:6112 …) without extra device passthroughs.

Hosting multiple gates on one machine

Each gate is one systemd template instance plus one env file. The server package ships devxh@.service, devxh-beat@.service, and devxh-instance.env.example. Per gate (example instance name east):

sudo cp devxh-instance.env.example /etc/devxh/east.env
sudo chmod 600 /etc/devxh/east.env && sudo nano /etc/devxh/east.env
# set DEVXH_NAME, a unique DEVXH_PORT (6112, 6113, ...), DEVXH_GAME,
# DEVXH_DIFFICULTY, and this gate's DEVXH_SERVER_ID + DEVXH_API_KEY
# (register each gate separately on the website: My Gates -> Create Gate)

sudo cp devxh@.service devxh-beat@.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now devxh@east devxh-beat@east
sudo ufw allow 6113/tcp    # each additional gate's own port

Every instance gets its own save dir (/var/lib/devxh/east), config dir, port, and listing registration. Each gate's heartbeat agent scopes its process checks to that exact instance via systemd (DEVXH_UNIT), so player counts and uptime never bleed across gates — a down gate is reported as down even when its neighbors run fine. Test one beat from the shell anytime with DEVXH_BEAT_ONCE=1 /opt/devxh/devxh-beat.sh.

Troubleshooting multi-gate boxes

These four bit the first real multi-gate deployment (three gates on one Ubuntu 24.04 VPS). All are silent — units look started, ports never appear:

Verifying the player count

The heartbeat agent counts non-loopback established connections on the game port, so the idle host player (which connects to the listener over 127.0.0.1) never inflates the public listing. To audit any gate by hand:

sudo ss -Htnp 'sport = :6112'

Every ESTAB whose peer address is not 127.0.0.1/::1 is a real player. Exactly one loopback self-connection owned by devilutionx-server is normal and healthy — that's the idle host.

Logging and diagnostics

The server logs to stderr (journald picks it up under systemd):

Use --verbose for packet-level debug logging.

Tests

Bash smoke/soak tests ship in the source tree (test/):

Implementation notes