dst-server 0.1.0

Start and control a Don't Starve Together server process.

Don't Starve Together Dedicated Server Image

English | 简体中文

Container image: quay.io/wh2099/dst-server

The image runs every shard in one DST cluster and keeps the familiar console FIFO. It can also export validated game events through OpenTelemetry.

Quick Start

1. Install a container runtime such as Podman.

2. Create and download a dedicated-server configuration from Klei's server management page.

3. Extract the archive on the host.

   The directory mounted at /cluster must directly contain cluster.ini, cluster_token.txt, and the shard directories:

   Cluster_1/
   ├── cluster.ini
   ├── cluster_token.txt
   ├── Master/
   │   └── server.ini
   └── Caves/
       └── server.ini
   

4. Start the container, replacing the host path with the extracted cluster directory:

   sudo podman run \
     --name dst \
     --detach \
     --network host \
     --volume "${HOME}/Cluster_1:/cluster" \
     quay.io/wh2099/dst-server:latest
   

Operations

podman logs dst
podman stop dst
podman start dst
podman restart dst

Stopping the container terminates every shard gracefully, and DST saves during shutdown.

The entrypoint creates a named console pipe for the master shard at the cluster root. Each secondary shard receives one in its own directory:

echo 'c_announce("Server maintenance is coming.")' > "${HOME}/Cluster_1/console"
echo 'c_save()' > "${HOME}/Cluster_1/Caves/console"

Common lifecycle commands include c_reset(), c_regenerateworld(), c_save(), and c_shutdown(false). Use c_announce("...") to send a message and c_listallplayers() to inspect players.

What the Entrypoint Does

On startup, entrypoint.py validates the cluster and prepares permission and Mod files. It updates Workshop content once, discovers every shard, and starts one Server per shard in -cloudserver mode.

DST_SKIP_MOD_UPDATE=1 skips the one-shot Workshop update.

DST_INSTALL_PATH and DST_CLUSTER_PATH override /install and /cluster for development and tests.

An OTEL_EXPORTER_OTLP_*_ENDPOINT variable enables the official OpenTelemetry pipeline. The entrypoint then exports validated game events.

Python SDK

The dst-server package starts and controls one Linux DST shard process.

import asyncio

from dst_server import Server, ServerArgs


async def main() -> None:
    async with Server(ServerArgs(shard="Master")) as server:
        world = await server.game.world.state()
        players = await server.game.players.list()
        await server.game.world.announce(
            f"Day {world.day}: {len(players)} player(s) online"
        )
        await server.save()


asyncio.run(main())

The typed API covers world and player queries, inventory, administration, confirmed saves, and raw Lua. It also exposes lifecycle and game events.

Install dst-server[otel] for OTLP export or dst-server[klei] for Klei build and lobby services.

Lua Annotations

The dst-annotations command generates LSP-compatible Lua definitions from DST components or modutil.lua.

dst-annotations dst-scripts/scripts/components --output components_def.lua
dst-annotations dst-scripts/scripts/modutil.lua --output modutil_def.lua

Documentation

Game server reference:

• Cluster architecture and configuration files
• Dedicated server command-line options

Technical design:

• -cloudserver bidirectional IPC
• Game events and OpenTelemetry

Source reference:

• DST Lua source index

The detailed documentation is maintained in Simplified Chinese.