Server Configuration

Configure a hosted server, including the global server config and per-session server profiles.

This guide covers how to configure a hosted server, including the global server config file and per-session server profiles.

Global Server Config

File: server_config/server_config.yaml

This file sets the default behaviour for every server session. Any value here can be overridden on a per-profile basis (see Server Profiles below).

Authentication Mode

auth-mode: steam

Controls how the server verifies player identity at login.

Note: In steam mode, operator permissions (see below) must use the player’s Steam ID, not their display name. Steam IDs appear in the server log when a player connects.

Operators

operators:
  - 76561198000000000
  - 76561198000000001

A list of player IDs that have operator-level permission. Operators can use privileged chat commands such as /kick, /ban, /mute, and /teleport.

• In steam mode: use the player’s Steam ID (a 17-digit number shown in the server log on login).
• In offline mode: use the player’s login ID (the save ID sent at login, shown in the server log) — not the display name, which can be changed freely and is never used for permission checks.

Operator lists from profiles are added to this list — they never replace it. A player in either list has operator access.

Security: operator commands are disabled by default under offline auth, because offline mode does not verify identity — any connecting player could claim a configured operator’s login ID and gain operator powers. On a public server, use steam auth so operator identity is verified. See Offline Operators below to re-enable them on a trusted private server.

Automatic Operators

You do not have to list yourself here to be an operator on a server you run:

• The player who hosts the server is automatically granted operator for that session. This is resolved from your own identity when you start hosting and is not stored in the save or the profile — so it applies whichever profile you host under, and hosting a world you downloaded from someone else grants operator to nobody but you. It is subject to the same rules above: under offline auth it still requires allow-offline-operators (see below), and under steam auth it just works.
• In singleplayer, the local player is always an operator; no configuration is needed.

To grant operator to other people persistently (co-admins), add them to the operators: list here or in a profile, as described above.

Offline Operators

allow-offline-operators: false

When operators are configured but disabled by this default, the server logs a warning at startup explaining how to enable them or switch to Steam auth.

Chat

chat:
  log-messages: true
  slowdown-ms: 500
  announce-player-connections: true
  history-size: 20
  max-message-chars: 256

Rate Limiting

rate-limiting:
  packets-per-second: 150
  burst-size: 50
  chunk-packets-per-second: 1000
  chunk-burst-size: 1024
  violation-limit: 1000

Controls how aggressively the server throttles clients that send packets too quickly. These defaults are suitable for normal play and generally do not need to be changed.

Chunk requests get their own, looser token bucket (chunk-*) because a client legitimately requests one chunk per position in its render distance all at once while a world loads — a burst the general limit would reject. The server also validates that each requested chunk is near the player’s actual position, so a looser chunk bucket does not expose the server to far-away chunk-flooding.

Connection Limits

connection-limits:
  max-connections: 256
  max-connections-per-ip: 8
  handshake-timeout-seconds: 30
  idle-timeout-seconds: 120

Bounds how many clients may connect and how long a silent connection is tolerated, so a flood of connections or stalled peers can’t exhaust server resources. These defaults suit normal play and rarely need changing. Unlike the chat and rate-limiting blocks, connection-limits is a global-only setting — it is not a profile override.

Mob Limits

mob-limits:
  - spawn-group: Neutral
    limit: 50

Sets a cap on how many mobs of each group can exist in the world at once, and doubles as the allow-list for natural spawning: a mob whose spawn-group has no entry here is never chosen by the natural spawner, so it will not spawn on its own (it can still be summoned or spawned by scripts/structures). The spawn-group value is matched against a mob’s own spawn-group case-insensitively — Hostile, hostile, and HOSTILE are the same group. Neutral and Npc always exist as groups even with no entry here, but still need an entry to spawn naturally. You can add as many entries as needed — one per spawn group.

An entry takes exactly spawn-group and limit; any other key fails that entry at load with a named error. A bad entry skips only itself, so the rest of your limits still apply — but a skipped entry means that group never spawns naturally, so read the log if a mob stops appearing.

Renamed in this version. This key was type: in earlier versions. An un-migrated server_config.yaml logs an error naming the old key and skips that entry (which silently disables natural spawning for that group), so rename it when you upgrade.

Required Client Mods

required-client-mods:
  - SomeTexturePack
  - AnotherClientMod

A list of client-only mod names (e.g. a texture pack marked side: client) that a connecting client must have installed, even though the server itself never loads them. They are advertised to the client during the connection handshake and reuse the same mod-compatibility warning dialog as the instance check. Defaults to empty (no extra client mods required).

Server Profiles

Server profiles let you save different server configurations and switch between them when hosting a session. This is useful if you host the same world for different audiences — for example, a private session for friends and a public session — without editing the global config each time.

Each profile is a folder inside server_profiles/:

server_profiles/
  my_profile/
    config.yaml   ← settings that override server_config.yaml
    data.yaml     ← auto-managed: muted and banned players

Profiles are created automatically when you select a new profile name in the host menu.

Profile Config (config.yaml)

A profile’s config.yaml overrides specific values from server_config/server_config.yaml. Any field you omit is inherited from the global config — you only need to specify what you want to change.

All available overrides:

# Override authentication mode for this profile.
# "steam" or "offline". Inherits global value if omitted.
auth-mode: steam

# Additional operators for this profile. These are added to (not replacing)
# the global operators list in server_config.yaml.
operators:
  - 76561198000000000

chat:
  log-messages: true
  slowdown-ms: 500
  announce-player-connections: true
  history-size: 20
  max-message-chars: 256

rate-limiting:
  packets-per-second: 150
  burst-size: 50
  chunk-packets-per-second: 1000
  chunk-burst-size: 1024
  violation-limit: 1000

All fields are optional. A completely empty config.yaml is valid — it simply inherits everything from the global config.

Profile Data (data.yaml)

This file is managed automatically by the server. It stores the list of muted and banned players for this profile. You should not edit it by hand unless you need to manually remove a ban or clear a muted player list when the server is offline.

muted-players:
  - 76561198000000000

banned-players:
  76561198000000001: 'Reason for ban'

Bans and mutes are profile-scoped — banning a player under one profile does not ban them under a different profile.

Example: Public vs. Private Profiles

server_profiles/public/config.yaml

auth-mode: steam

chat:
  slowdown-ms: 2000
  max-message-chars: 128

server_profiles/private/config.yaml

auth-mode: offline

chat:
  announce-player-connections: false

Both profiles share the global operator list. The public profile adds chat rate limiting and Steam auth. The private profile uses offline mode and skips join/leave announcements. Note that allow-offline-operators is a global server_config.yaml setting, not a profile override — set it there (see above), not in a profile’s config.yaml, where it would be ignored.

Operator Commands Reference

Operators can run the following commands in chat:

Operator status is granted through the operators: list and the automatic host grant described above — there is no in-chat /op or /deop command. /list and /help are available to everyone, not just operators.

Player arguments can be the player’s display name or their player ID. In steam auth mode, the player’s display name is their Steam persona name.