Guide

Host a dedicated server

Run one or more always-on servers from a single folder and a single configuration file, natively on Windows, Linux or macOS, or in Docker. Each holds up to 127 players on enhanced networking, plays your own playlist on every supported game's maps, any game's campaign or Firefight in co-op, shares the mods its games use, and answers to your admins and your own tools.

Work in progressEarly development build. What this page describes may still change.

How it works

The dedicated command reads dedicated.toml and starts every server listed in it. Each server is a process of its own: a headless copy of the Reclaimer Engine with no window, graphics card or sound device, and with its own name, port and games. A crash in one never touches the others, and a server that stops is started again by itself. Players stay connected from one map to the next.

Every listed server reports to the three default master servers, which every player's Server Browser reads, and to the master this machine runs. A master lists a server once the server has answered it from the address it reports from. The browser then asks each server on its game port what it's playing, so players see the live game, players and ping. Or they join by address with Direct Connect. Servers behind routers register with the masters so players can be introduced to them; see hosts behind routers.

Server folder
reclaimer/
├─ dedicated.toml          every server and setting, commented
├─ game/                   files copied from your own game install
├─ content/                maps, game types and mods every server shares
│  ├─ Maps/
│  ├─ Game Modes/
│  ├─ Images/
│  └─ Mods/
├─ playlists/              playlist files (one example is provided)
├─ bans.json               bans and VPN allowances shared by every server
├─ vpn-local.txt           optional: networks you refuse yourself
└─ data/
   ├─ <server>/            each server's log, live status, keys, chat log and films
   ├─ master/              this machine's master: its log and key
   ├─ vpn/                 the VPN lists
   └─ stats-key.json       the key its stats reports are signed with

No game files or game code come with Project Reclaimer. Every host copies the few files a server needs from their own installation of the game, and the server prepares the engine from that copy on its first start, on your machine.

This guide writes commands as project-reclaimer dedicated …, run in the server folder. Type the program the way your system does:

WhereThe program
Windows.\project-reclaimer.exe dedicated … in PowerShell
Linux./project-reclaimer dedicated …
macOS./project-reclaimer dedicated …, or from the game's app, "/Applications/Project Reclaimer.app/Contents/MacOS/project-reclaimer" dedicated …
Dockerdocker compose exec server-1 dedicated …

Run it in another folder with --config path/to/dedicated.toml, as in project-reclaimer dedicated --config /srv/reclaimer/dedicated.toml check, or with project-reclaimer --server /srv/reclaimer/dedicated.toml check.

Requirements

WhatDetails
SoftwareThe server-only package from the newest release: project-reclaimer-dedicated-version.exe on Windows, project-reclaimer-dedicated-version-macos-aarch64.zip on macOS, or project-reclaimer-dedicated-version-linux-x86_64.tar.gz or -linux-aarch64.tar.gz on Linux. It has no menus, sound or graphics. The game client from the download page runs servers too. Docker brings its own image.
Game filesYour own Steam copy of Halo: The Master Chief Collection with Halo 3 installed, campaign included, on the PC where you create the server folder. The machine that hosts can be another one: nothing but the folder goes there. A server that plays Halo 3: ODST, Halo: Reach, Halo: CE or Halo 2, or their campaigns, also needs that game installed there.
WindowsWindows 10, 11 or Server 2019 or newer (x64), on a processor with SSE4.2: any Intel Core i3, i5 or i7 and newer, AMD FX and newer, and every Ryzen. No runtime to install.
Linuxx86-64, with the same processors as Windows, or ARM64, built on Debian 12, so any system with glibc 2.36 or newer. The server-only package needs no display, graphics card, sound or Wine.
macOSmacOS 11 or newer, Apple Silicon.
Dockerx86-64 Linux with Docker Engine and Compose 2.24 or newer. The image runs natively, with no Wine. It holds no game files.
DiskAbout 1.5 GB for one map; about 5.5 GB for every multiplayer map, which character mods need. Both include the two campaign maps Forge's campaign vehicles and AI come from (about 520 MB). A campaign server also needs the campaign missions, about 4 GB for all of Halo 3's, and a Halo 3: ODST server about 3.5 GB of ODST's files and two of Halo 3's missions. Add a few hundred MB for the caches: the prepared engine and the Forge library.
Memory, CPUPer server: about 110 MB and next to no CPU while it waits for players, about 0.6–0.9 GB and up to a core of its own during a game. See servers per machine.
NetworkOne UDP port per server (49176, 49177, …), which players join and the Server Browser asks what the server is playing, and port 49175 on both TCP and UDP for this machine's master. The optional remote console uses TCP at each game port number, for your own tools. Servers also answer the Server Browser's search of its own network on UDP 44329, whatever their game port: allow it in the machine's firewall when players on your network should find them without the masters. A public address, a forwarded port, UPnP or PCP is the surest way in; see hosts behind routers.

What has run so far. Servers are tested natively on macOS, and in Docker on ARM64 Linux and x86-64 through Rosetta. The Windows and x86-64 Linux builds compile but haven't been run on real hardware yet. UPnP, PCP and hole punching have run against simulated routers only. Please report what you find, with the server's log.

Up to 127 players

A game holds 128 machines, and a dedicated server is one of them with no player of its own, so a server takes 127 PCs: a 127-player free-for-all, or 64 against 63 in a team game. Servers admit 16 unless you raise max_players, under [defaults] for every server or in one [[server]]:

dedicated.toml
[[server]]
name = "Sandtrap Free-for-All"
port = 49178
map = "Sandtrap"
game = "Slayer"
max_players = 127
  • Split-screen players count toward max_players. The next player is refused, told the server is full, and the Server Browser shows the limit.
  • Campaign co-op and Firefight hold at most 16 players: a campaign server, an ODST server or a Reach co-op server with a higher max_players doesn't start.
  • Fighting bots take places within max_players too, so a server of 128 with 120 bots has room for 8 people.
  • To keep a big server in its lobby until enough players are in, set min_players; see minimum players.
  • Every machine in a game needs the same version of Project Reclaimer: see one version for everyone.
  • A game of 126 players has run at 60 frames a second on one fast machine, with bots on Guardian. Infection, King of the Hill, Territories and VIP haven't been played past 16 players yet.

Servers per machine

How many servers one machine holds depends on how many players they have at once. Roughly, per server:

ServerMemoryProcessor
Waiting for playersabout 110 MBnext to none
In a small gameabout 0.6 GB, more on a Forge mapabout 0.6 of a core on Apple Silicon
In a full gameabout 0.6–0.9 GB, more for a moment while a map loadsabout a core of its own
  • A server simulates 60 ticks a second, or 30 with tick_rate, which saves processor time on a machine running many servers. An empty lobby runs at 20 a second, a lobby with players at 60.
  • A server draws nothing, so it needs no graphics card and uses no memory for textures.
  • Upload depends on the game. A player downloads about 30 KB/s in a 16-player game and about 84 KB/s in a 126-player game. For a full server, plan on 50 Mbit/s or more of upload.
  • Each server's log shows its upload every 5 minutes while players are on: Network upload over the last 5 minutes: … MB/s to N players (… KB/s each): the game …, messages …; … on the wire.
  • A server holds 60 frames a second only with enough processor. Several full servers on one machine need a core each; in Docker, each server's container can get its own share.
  • While players are on, a server that often drops below 54 frames a second during a game (27 at a tick_rate of 30) says so in its log once a minute, such as Server falling behind: under 54 frames a second for 41 of the last 60 seconds (48 on average, longest frame 95 ms) with 6 players. Its players get fewer updates and see lag: give it more processor time, or fewer players. The lobby and loading don't count.

Quick start: Windows

  1. Download the programMake a folder for your servers, such as C:\reclaimer. Get project-reclaimer-dedicated-version.exe from the newest release, put it in that folder, rename it project-reclaimer.exe, the name the commands below use, and open a terminal there. The game client from the download page works the same way.
  2. Create the server folder from your game install This writes a commented dedicated.toml and an example playlist, and copies the game files a server needs into game, including the campaign's campaign.map and 040_voi.map for Forge's campaign vehicles and AI. Give it your own game's folder:
    PowerShell
    .\project-reclaimer.exe dedicated init . --from "C:\Program Files (x86)\Steam\steamapps\common\Halo The Master Chief Collection"
    --from on its own uses the folder the game saved on this PC, so it works once the game has run here. Without --maps it copies every multiplayer map. Add --maps "Guardian,Valhalla" to copy only the maps you host, campaign for the campaign's missions, odst for ODST's files, or reach, halo1 and halo2 for the other games, alone or among the maps. On the same drive, files are hard-linked instead of copied.
  3. Edit dedicated.tomlSet your server names, ports, admins and what each server plays. .\project-reclaimer.exe dedicated content lists the maps and game types you can name, and dedicated playlist new makes a playlist of them; see names and playlists from the command line. The example's playlist needs Guardian, Valhalla, The Pit and Narrows: with fewer maps, change it. See also the configuration file and custom playlists.
  4. Check, then start
    PowerShell
    .\project-reclaimer.exe dedicated check
    .\project-reclaimer.exe dedicated
    check goes through the game files, the configuration, every playlist, map and game type, and the ports, and lists everything that's wrong at once, with the name you probably meant when one is close (Did you mean 'Valhalla'?). Once all is well, it prints what each server plays and the ports to open. If your servers name Workshop mods by ID, it downloads the missing ones first. The first start prepares the engine from game\halo3\halo3.dll, which takes seconds and happens once per release.
  5. Open the ports In a terminal opened as administrator, with your own game ports:
    PowerShell (administrator)
    New-NetFirewallRule -DisplayName "Reclaimer games" -Direction Inbound -Protocol UDP -LocalPort 49176-49177 -Action Allow
    New-NetFirewallRule -DisplayName "Reclaimer master" -Direction Inbound -Protocol TCP -LocalPort 49175 -Action Allow
    New-NetFirewallRule -DisplayName "Reclaimer master UDP" -Direction Inbound -Protocol UDP -LocalPort 49175 -Action Allow
    Behind a home router, forward the same ports to this PC, or set upnp = true in dedicated.toml. Players can often reach the servers without it, but not through every router: see hosts behind routers.

Ctrl+C stops every server. Double-clicking the server-only program in a folder with a dedicated.toml runs its servers in a console too; in a folder without one, it says what it is and how to set a server up. To start them with Windows, create a Task Scheduler task that runs C:\reclaimer\project-reclaimer.exe with the argument dedicated, starting in C:\reclaimer, at startup, whether or not a user is logged on.

Quick start: Linux

Servers run natively on Linux, x86-64 and ARM64, with nothing else to install: no Wine, no display, no graphics card, no sound. Prefer containers? See Quick start: Docker.

  1. Unpack the server-only package Get project-reclaimer-dedicated-version-linux-x86_64.tar.gz, or -linux-aarch64.tar.gz for ARM64, from the newest release. It holds the program and its texts:
    Shell
    mkdir -p ~/reclaimer
    tar -xzf project-reclaimer-dedicated-v0.10.7-linux-x86_64.tar.gz -C ~/reclaimer --strip-components=1
    cd ~/reclaimer
  2. Create the server folder from your game install With the game installed on this machine, give it the game's folder:
    Shell
    ./project-reclaimer dedicated init . --from "$HOME/.local/share/Steam/steamapps/common/Halo The Master Chief Collection"
    With the game on another PC, run dedicated init there, as in the Windows quick start, and copy the folder over, keeping the program you unpacked here:
    PowerShell, on the Windows PC
    scp -r C:\reclaimer\game C:\reclaimer\dedicated.toml C:\reclaimer\playlists you@host:reclaimer/
    Or leave the files where they are and set game in dedicated.toml to the game's own folder: ./project-reclaimer dedicated init . writes the file without copying anything.
  3. Check and start Edit dedicated.toml, then:
    Shell
    ./project-reclaimer dedicated check
    ./project-reclaimer dedicated
  4. Open the ports
    Shell
    sudo ufw allow 49175:49177/udp && sudo ufw allow 49175/tcp
    Open the same in your provider's firewall or security group. Servers don't need root.
  5. Run it as a service (optional)
    /etc/systemd/system/reclaimer.service
    [Unit]
    Description=Project Reclaimer dedicated servers
    After=network-online.target
    Wants=network-online.target
    
    [Service]
    User=reclaimer
    WorkingDirectory=/home/reclaimer/reclaimer
    ExecStart=/home/reclaimer/reclaimer/project-reclaimer dedicated
    KillSignal=SIGINT
    TimeoutStopSec=30
    Restart=always
    RestartSec=5
    
    [Install]
    WantedBy=multi-user.target
    Then sudo systemctl enable --now reclaimer, and follow it with journalctl -u reclaimer -f. The account needs a home folder: its caches go in ~/.local/share/ProjectReclaimer/Cache, or wherever RECLAIMER_CACHE_DIR says.

Quick start: macOS

Servers run natively on Apple silicon Macs and open no window. With the game already installed, its own program runs servers too: skip the first step, work in an empty folder, and use "/Applications/Project Reclaimer.app/Contents/MacOS/project-reclaimer" in place of ./project-reclaimer.

  1. Unpack the server-only package Get project-reclaimer-dedicated-version-macos-aarch64.zip from the newest release. It holds the program and its texts. Apple hasn't checked it, so macOS blocks a browser's download until you clear it, once, with xattr:
    Terminal
    cd ~/Downloads
    ditto -x -k project-reclaimer-dedicated-v0.10.7-macos-aarch64.zip .
    mv project-reclaimer-dedicated-v0.10.7-macos-aarch64 ~/reclaimer
    xattr -dr com.apple.quarantine ~/reclaimer
    cd ~/reclaimer
  2. Create the server folder Give it your copy of the game. --from alone uses the folder the game found; name it if the game hasn't run here:
    Terminal
    ./project-reclaimer dedicated init . --from "/path/to/Halo The Master Chief Collection"
  3. Check and start Edit dedicated.toml, then:
    Terminal
    ./project-reclaimer dedicated check
    ./project-reclaimer dedicated
  4. Open the portsAllow incoming connections if macOS asks. Behind a router, forward the servers' UDP ports and TCP and UDP 49175 to this Mac, or set upnp = true in dedicated.toml.

Quick start: Docker

The Docker image runs the same servers natively, so the rest of this guide applies as it is: the same dedicated.toml, commands, bans, votes, playlists and mods. Docker adds one command to start, stop and update, and settings through environment variables.

Each server runs in a container of its own, on the machine's own network: compose.yaml has a service per server, server-1 for the first [[server]] in dedicated.toml, server-2 for the second, and so on. Each server then has its own share of the processor, and one that restarts never touches the others. The containers share one server folder, one ban list and one master. Where host networking isn't available, one container for every server works too.

One file to host. Each release publishes the image as ghcr.io/projectreclaimer/project-reclaimer-dedicated, for x86-64 Linux, so all you need is compose.yaml and your own game files: nothing to build and nothing else to download. The image holds the server, never game files or game code: it prepares the engine from your game folder when it starts, and keeps the result in its cache volume.

Folder
reclaimer/
├─ compose.yaml             a service per server: image, folders
├─ .env                     optional settings
└─ server/                  the server folder
   ├─ dedicated.toml        written on the first start, commented
   ├─ game/                 files copied from your own game install
   ├─ content/  playlists/  bans.json
   └─ data/<server>/        each server's log and live status
  1. Install Docker Docker Engine with the Compose plugin, 2.24 or newer, on any x86-64 Linux:
    Ubuntu
    sudo apt install docker.io docker-compose-v2
  2. Make the folder and add compose.yaml
    Shell
    mkdir reclaimer
    cd reclaimer
    Save compose.yaml in reclaimer, or copy it from the file below.
  3. Put the game files in server/game On a PC with the game, run dedicated init C:\reclaimer --from "your game's folder" as in the Windows quick start and upload that folder as server with the scp Windows includes; that brings a dedicated.toml too:
    PowerShell, on the Windows PC
    scp -r C:\reclaimer you@host:reclaimer/server
    reclaimer/server mustn't exist yet, or the upload lands inside it as server/reclaimer. Or make the folders with mkdir -p server/game and copy the files in by hand, keeping their folders, such as server/game/halo3/halo3.dll. With the game installed on this machine through Steam, copy nothing: make the same folders and set GAME_DIR in .env to the game's folder. Make the folders yourself before the first start: a folder Docker has to create for you belongs to root.
  4. Choose settings (optional)Save env.example as .env next to compose.yaml and uncomment what you change, such as RECLAIMER_DEDICATED_HOST_NAME or RECLAIMER_DEDICATED_ADMINS. See environment variables.
  5. Start
    Shell
    docker compose up -d
    docker compose logs -f
    The first start downloads the image, writes server/dedicated.toml with two servers (a Slayer playlist on UDP 49176, which needs Guardian, Valhalla, The Pit and Narrows, and Slayer on Guardian on UDP 49177), checks everything and starts them: container server-1 runs the first, server-2 the second. With fewer maps, change the servers in that file. The servers report to the project's public masters, so players find them in the Server Browser without adding anything.
  6. Open the ports Open the servers' UDP ports and TCP and UDP 49175 in your provider's firewall or security group, and in the machine's own firewall: on the host's network, the servers' ports are the machine's, so ufw applies.
    Shell
    sudo ufw allow 49175:49177/udp && sudo ufw allow 49175/tcp

If something is missing, the log says what and the containers wait: fix it in the server folder, and the servers start by themselves within 15 seconds.

compose.yaml

The whole file. Its settings come from .env, so you edit it only to add a service for each server past the first two (see more servers).

compose.yaml
# Project Reclaimer dedicated servers in Docker (Linux containers, the game
# running natively), one container per server. Guide: docs/servers.md.
#
# This file is all a host needs: it runs the published image, so no copy
# of the repository and no build. It is Project Reclaimer 0.9's file with
# the same services, folders and volume: a host of 0.9 updates with
#   docker compose pull && docker compose up -d
# and keeps its server folder, its settings and its servers' keys.
#
# Put it in a folder of its own, then:
#
#   1. Copy Halo 3's files from your own MCC installation into
#      server/game/ next to this file (halo3/halo3.dll, halo3/maps/shared.map,
#      the maps you host, and campaign.map with 040_voi.map for Forge's
#      campaign vehicles and AI). `project-reclaimer dedicated init server
#      --from` on a PC with MCC copies them. The image contains no game files.
#   2. Optional: a .env file next to this one with your settings
#      (see .env.example).
#   3. docker compose up -d
#      docker compose logs -f
#
# On first start the containers write a commented dedicated.toml into the
# server folder; edit it for names, maps, playlists and admins (edits apply
# while the servers run). Each service below runs one [[server]] of that
# file: server-1 the first, server-2 the second. For another server, add a
# [[server]] block there and a service here like server-2, with the next
# number. Commands for running servers:
#   docker compose exec server-1 dedicated status
#   docker compose exec server-1 dedicated ban <player ID | IP | CIDR> --reason "..."
# (bans.json is shared: a ban applies to every server.)
# Update to a new release: docker compose pull && docker compose up -d
#
# The containers use the host's network: each server's own UDP port and the
# machine's master (TCP and UDP 49175) need no list of ports here, and the
# servers share one master. Open them in the firewall. Where host
# networking is not available, compose.single.yaml runs every server in
# one container on published ports instead.
#
# To build the image from a checkout of the repository instead, add
# compose.build.yaml; for a master, stats service or social service of
# your own, compose.services.yaml (see there).

name: reclaimer

# What every server's container shares.
x-server: &server
  # The newest release; set IMAGE in .env to stay on one version.
  image: ${IMAGE:-ghcr.io/projectreclaimer/project-reclaimer-dedicated:latest}
  restart: unless-stopped
  # The supervisor stops its servers cleanly on Ctrl+C (SIGINT).
  stop_signal: SIGINT
  stop_grace_period: 30s
  # Every RECLAIMER_DEDICATED_* setting in .env overrides dedicated.toml,
  # as do PUID and PGID (see .env.example).
  env_file:
    - path: .env
      required: false
  volumes:
    - ${SERVER_DIR:-./server}:/server
    # Read-only: the servers never change the game files.
    - ${GAME_DIR:-./server/game}:/server/game:ro
    # The Forge library and other caches, kept across updates.
    - cache:/cache
  network_mode: host
  security_opt:
    - no-new-privileges:true
  # Roughly per server: under 0.1 core and 100 MB waiting, a core and
  # 0.6-0.9 GB in a full game (more briefly while loading a map). Uncomment
  # to cap or pin a server, e.g. per service: cpus: "1.5" or cpuset: "2,3".
  # cpus: "2"
  # mem_limit: 3g
  logging:
    driver: json-file
    options:
      max-size: 10m
      max-file: "3"

services:
  server-1:
    <<: *server
    environment:
      # The [[server]] this container runs: its position in dedicated.toml,
      # its name or its game port.
      RECLAIMER_DEDICATED_ONLY: "1"
  server-2:
    <<: *server
    environment:
      RECLAIMER_DEDICATED_ONLY: "2"

volumes:
  cache:

Versions and updates

compose.yaml runs latest, the newest release, and docker compose pull && docker compose up -d updates to the next one. To stay on one version, name it in .env and run docker compose up -d:

.env
IMAGE=ghcr.io/projectreclaimer/project-reclaimer-dedicated:0.10.0

Every release has its own tag, such as 0.10.0, and 0.10 follows the newest 0.10.x. Pre-releases are only published under their own tag, never as latest.

Automatic updates don't apply in Docker: the image is the update. A container ignores auto_update and RECLAIMER_DEDICATED_AUTO_UPDATE, and says so in its log.

Everyday use

Run these in the folder with compose.yaml. A command run in one server's container, such as server-1, sees that server; the shared ban list makes a ban apply to every server.

TaskCommand
Follow the logdocker compose logs -f, or one server's: docker compose logs -f server-2
Every server's players and addresses, the masterdocker compose exec -e RECLAIMER_DEDICATED_ONLY= server-1 dedicated status
One server'sdocker compose exec server-2 dedicated status
Ban, lift a bandocker compose exec server-1 dedicated ban <target> --reason "…", … dedicated unban <target>
Let a player through the VPN blockdocker compose exec server-1 dedicated vpn allow <player ID> (see VPN blocking)
Remote console commandsdocker compose exec server-2 dedicated rcon players, for the server that container runs (see RCON)
Check files and settingsdocker compose run --rm server-1 dedicated check
The maps and game types dedicated.toml and playlists can namedocker compose run --rm server-1 dedicated content <words> (see names and playlists)
List and check the playlists; one in detaildocker compose run --rm server-1 dedicated playlist, … dedicated playlist show <file>
Make a playlistdocker compose run --rm server-1 dedicated playlist new "Team Slayer" --maps "Guardian,Valhalla,The Pit" --games Slayer
Apply dedicated.toml, playlist or content editsThey apply by themselves once saved; see changing settings while servers run. With auto_reload = false: docker compose exec -e RECLAIMER_DEDICATED_ONLY= server-1 dedicated reload. docker compose restart applies everything at once, ending the games under way.
Apply .env or compose.yaml editsdocker compose up -d
Stop, startdocker compose stop, docker compose start
Updatedocker compose pull && docker compose up -d
  • Each container restarts by itself after a crash or reboot, and Docker reports it healthy while its servers keep their live status fresh and the machine's master answers. Each server also logs to server/data/<server>/server.log.
  • File owner: the servers run as the owner of the server folder, so the files they write are yours. PUID and PGID in .env choose another user and group; use those rather than Compose's user:.
  • Mods and playlists: put shared maps, game types and mods in server/content, and playlists in server/playlists. The image has no Steam, so copy Workshop mods into server/content/Mods yourself; see Workshop downloads in Docker.
  • Remote console: set RECLAIMER_DEDICATED_RCON_PASSWORD in .env. On the host's network, each server's console then listens on the machine's own 127.0.0.1, at its game port number, where tools on the machine reach it. RECLAIMER_DEDICATED_RCON_ADDRESS=0.0.0.0 opens the consoles on every network the machine is on: do that only behind a firewall that lets just your tools in. See RCON.
  • Docker Desktop (Windows, or macOS on Intel) runs the same containers once host networking is turned on in its settings (4.34 or newer), or every server in one container with compose.single.yaml.

More servers

Add a [[server]] block to dedicated.toml with the next port, and a service for it to compose.yaml, under services:, with the next number:

compose.yaml
  server-3:
    <<: *server
    environment:
      RECLAIMER_DEDICATED_ONLY: "3"

Then run docker compose up -d, and open the new server's UDP port in the firewall.

  • RECLAIMER_DEDICATED_ONLY picks the server a container runs: its position in dedicated.toml, counting from 1, its name ("Big Team Battle") or its game port ("49178"). A list, such as "3,4", runs several in one container. Set it per service in compose.yaml, never in .env. A choice that matches no server stops the start.
  • Every container mounts the same server folder: the bans, playlists, content and caches are shared, and the first container to start writes the folder on the first start.
  • The containers share one master: one serves port 49175, the others' servers report to it, and another takes it over within half a minute if its container stops. When two start at once, both may try: the second's master ends and it uses the first's.
  • To give a server its own share of the machine, add cpus: (such as cpus: "1.5"), cpuset: (such as cpuset: "2,3") or mem_limit: to its service. A full server wants about a core of its own; see servers per machine.
  • Outside Docker, RECLAIMER_DEDICATED_ONLY works the same: each dedicated started with it runs only the servers it names, from one shared folder.

One container for every server

Where host networking isn't available, such as Docker Desktop without it, compose.single.yaml runs every server in one container on published ports. Save it next to compose.yaml, and either name it in each command or set it once in .env:

Shell
docker compose -f compose.single.yaml up -d
.env
COMPOSE_FILE=compose.single.yaml
  • Its one service is reclaimer: docker compose exec reclaimer dedicated status lists every server, and the other commands above take reclaimer in place of server-1.
  • More servers: add a [[server]] block with the next port, widen GAME_PORTS in .env to cover it (GAME_PORTS=49176-49180) and run docker compose up -d. A configuration runs up to 32 servers.
  • Ports: Docker publishes the master's TCP and UDP ports and the GAME_PORTS range itself, past ufw; open them in your provider's firewall.
  • Remote console: inside this container it must listen on every interface to be published at all. Set RECLAIMER_DEDICATED_RCON_PASSWORD and RECLAIMER_DEDICATED_RCON_ADDRESS=0.0.0.0 in .env, and uncomment the TCP line under ports: in compose.single.yaml, which publishes the consoles on the host's own 127.0.0.1 only.

Moving between the two layouts

To move a running setup from compose.single.yaml to one container per server, add a service for each [[server]] past the second to compose.yaml, open the ports on the machine (on the host's network, its own firewall applies), and start with:

Shell
docker compose pull
docker compose up -d --remove-orphans

--remove-orphans is needed once, so the old reclaimer container stops and frees the ports. The server folder, bans and caches stay as they are. Moving back the other way also takes --remove-orphans once.

Updating a 0.9 server

0.10 is the update of 0.9: a server folder carries over as it is, on Windows and in Docker alike. What players see on it is new, so update your servers when your players update: the network protocol is new, and 0.9 and 0.10 can't play together.

  • On Windows, a server with auto_update = true updates itself. Otherwise stop the servers, replace project-reclaimer.exe with project-reclaimer-dedicated-v0.10.7.exe, renamed the same, and start them again. See automatic updates.
  • In Docker, docker compose pull && docker compose up -d with your own compose file, .env and server folder. The new image runs natively. It takes 0.9's mounts, commands and settings, and removes 0.9's Windows copies from server/.reclaimer on its first start. RECLAIMER_XVFB and RECLAIMER_EXE mean nothing any more, and RECLAIMER_DEDICATED_AUTO_UPDATE is ignored.
  • On Linux under Wine, move to the native package: keep your server folder, and start the Linux program in it.
  • Open UDP 49175. The master now takes UDP on its port too. In a firewall that opened only TCP 49175, add it. With 0.9's compose.single.yaml, get the new file, which publishes it.
  • dedicated.toml loads as it is. Your bans, admins, VPN allowances, playlists and content carry over. Admins and bans named by 0.9 player IDs still match. Each server makes a new network key on its first start: its listing's identity, which nothing else depends on. data/stats-key.json stays, so a whitelisted server stays whitelisted.
  • Masters must be http://. A peers entry with https:// stops the server: see [master]. A master you run yourself needs updating too: see masters from 0.9.
  • Bots and panels: player IDs in status.json and in RCON's events are players' network keys now, not 0.9's community IDs, and a player's ip in status.json is address, with its port. Tools keyed on 0.9's player IDs need to change. In admins, vote_kick_immune and bans.json, either ID still names a player.
  • The public services moved: the project's masters to port 44340, beside 0.9's, and its stats service to its name, stats.ibigs.us, on port 8792. A [master] peers list or MASTER_PEERS naming 0.9's public masters, and a stats_server naming the stats service's earlier address, read as the new ones, so there's nothing to change. Your machine's own master and servers keep 49175 and up, so firewall rules and compose files stay as they were.
  • Commands that changed: server-status and local-server are gone. project-reclaimer --list-servers http://148.251.153.44:44340 shows what a master lists, with live status and ping.

Hosts behind routers

Players can often reach a server whose router doesn't forward its game port. Every listed server registers its game port with up to four master servers, every 20 seconds. When a player's game gets no quick answer from a server, it asks a master to introduce it, again every second for up to 12 seconds. The master tells each side where the other is, and both send a few small packets at once, which opens each router to the other. This is hole punching. The Server Browser's status check, joining and mod downloads all work this way.

The masters only answer STUN and make introductions: the game, voice and mods always go straight between the player and the server. There's nothing to set up for it and no port to open: servers that are listed publicly do it by themselves.

Each side learns what its router does from the answers of two or more masters (STUN), so it knows which ports to try. Which pairs connect:

The server's sideThe player's sideJoins
Public address, forwarded port, UPnP or PCPAnyYes, directly
An ordinary home router (cone NAT)An ordinary home routerYes
Behind the same router as the playerBehind the same routerYes, on local addresses
A new port per destination (symmetric NAT)Cone NAT, full or address-restrictedYes
Symmetric NAT with ports handed out in orderPort-restricted cone NATYes, usually: the player tries the likely ports
Port-restricted cone NATSymmetric NAT with ports in orderYes, usually: the server tries the likely ports
Cone NAT that filters by address aloneSymmetric NATYes
Symmetric NAT with random portsPort-restricted cone or symmetric NATNo
Port-restricted cone NATSymmetric NAT with random portsNo
Symmetric NATSymmetric NATNo, at most by chance
UDP blocked on either sideNo

Not every pair can connect. Two symmetric NATs, common on mobile connections and some providers' shared addresses, can't reach each other, and a pair that can't connect is told so after 12 seconds: no answer from the host: its router and yours let no direct connection through (forwarding the game's port, UPnP or IPv6 on either side would). A server anyone can reach is still the surest way to host: a public address, a forwarded port, upnp = true, or IPv6. Behind a provider's shared address, you may need to ask your provider for a public IPv4 address. Hole punching has been tested through simulated routers so far, not real ones.

  • upnp = true asks the router to forward the servers' UDP ports and the master's TCP and UDP port, through UPnP, or PCP when no router answers UPnP. The mapping is renewed every 45 seconds and removed when dedicated stops. The router's public IPv4 address then becomes the address listed, unless public_address names one. If it fails, the log says Manual setup may be needed.
  • Hidden servers aren't listed and don't register, so players reach them only by Direct Connect, and only directly.
  • Servers that share one public address need different game ports, as they do for forwarding.
  • Masters limit requests to protect themselves and hosts.

Check from another network

If players can't find or join a server, look from a PC with the game on another network, such as a friend's or a phone's hotspot. This asks a master for its list, then asks each server the way the Server Browser does, introductions included, and prints every server that answers with its ping:

Shell
project-reclaimer --list-servers http://148.251.153.44:44340

The Server Browser shows only servers that answer this, and the list names what each server's players need, such as needs Halo 3: ODST or needs the mod "title". project-reclaimer --find-lan lists the servers on your own network the same way. A server that dedicated status shows as running, or that the masters list, can still be out of players' reach. Each server's log says how it fares with the masters:

server.log
[online] listing on http://127.0.0.1:49175, http://148.251.153.44:44340, http://75.98.127.228:44340, http://23.159.176.140:44340
[online] registering with the rendezvous at 148.251.153.44:44340
[online] registered with the server list at 148.251.153.44:44340 as 203.0.113.4:49176
[online] NAT: one address for every destination

The last line is what your router does: one address for every destination is a cone, and a new port for every destination is symmetric, with 2 apart or the like when its ports come in order and in no order when they don't.

Networking

A multiplayer server plays enhanced networking unless you say otherwise: built for big games, it sends each player object updates by the error that player would see, sends far players' controls less often, and blends corrections on players' PCs. Classic networking is Halo 3's own. Co-op has models of its own, and the choice is per server, in [defaults] or a [[server]]:

SettingValuesMeaning
network_model"enhanced" (default), "classic"How multiplayer games replicate. Changing it restarts the server once it has no players. "large", an earlier name, still reads as "enhanced".
coop_network"lockstep" (default), "lockstep30", "host"How co-op games play: campaign, ODST, Firefight and a playlist's co-op entries. "lockstep" is Halo 3's own, at MCC's 60 ticks a second: every machine runs the game together. "lockstep30" is the same at the Xbox 360's 30 ticks a second. With "host", experimental, the server simulates and its players predict their own moves, so aiming and moving don't wait for the round trip. Restart the server to change it.
dedicated.toml
[defaults]
network_model = "enhanced"   # or "classic", Halo 3's own
coop_network = "lockstep"    # Halo 3's own; "lockstep30" at 30 ticks; or "host", experimental
  • Every player's game takes the server's model as it joins: there's nothing for them to set. The Server Browser shows it. Listen hosts have the same choice under Host Settings → Classic networking, and co-op hosts choose Lockstep 60, Lockstep 30 or host-authoritative co-op in their lobby.
  • A server that names no network_model plays enhanced networking. To host Halo 3's own, set network_model = "classic".
  • Neither setting has an environment variable: set them in dedicated.toml.
  • Tick rate: servers simulate 60 ticks a second unless you set tick_rate to 30.
  • Per-player upload: there's no cap to set. Under overload, an enhanced server gives way by itself, in order: objects behind a player tolerate more error first, then the AI's far controls, then every other update, and only while its network work takes a fifth of its time or more. share_rate caps mod downloads only.
  • Every player records their own films, on both models, and a server can record its games too: see server films.
  • A server with many places spreads its network work over more threads: see big servers.

Playing at 30 ticks

tick_rate = 30, in [defaults] or a [[server]] block, plays a server's multiplayer games at 30 ticks a second instead of 60. It halves the server's simulation, for a machine that runs many servers: with 13 players on Guardian, a server used about 47% less processor time. Only the server changes. Every player's game stays at 60, and any player on your version can join.

  • What players get: 30 updates a second instead of 60, and a round trip about 8 ms longer on average, which max_ping sees too. What the server simulates moves in steps of 33 ms: grenades, unmanned vehicles and a projectile's instant hit, whose range doubles. A player's own movement and shots still start on their own machine.
  • Multiplayer only: co-op, ODST and Firefight keep the rate their coop_network sets, in a playlist too.
  • The value is 30 or 60, and a change counts from the next game. RECLAIMER_DEDICATED_TICK_RATE sets it too.
  • Server falling behind goes by the server's own rate: under 27 frames a second at 30, not 54.
  • A vehicle driven at speed hasn't been tried at 30 yet.

A player's own host has the same choice in Host Settings.

Big servers

A server with more than 32 places (max_players) spreads its network work by itself; a smaller one keeps Halo 3's single game thread. Three settings, in [defaults] or a [[server]], say otherwise. What each player receives is the same either way, and a change restarts the server once it has no players.

SettingDefaultMeaning
encode_onceon above 32 placesEach object's update is encoded once a tick and shared by every player owed the same fields, instead of once per player. false turns it off.
channel_threadsautomatic above 32 places, else 1The threads that update the players' network channels each frame, the game's own included. 1 is the game's thread alone. 0 is automatic: one thread for every 8 players, up to a quarter of the machine's threads and 8. At most 64.
node_threads1The threads that pose players' bodies each tick, the game's own included. 0 is automatic: in games of 48 to 96 bodies, one thread for every 16, up to a quarter of the machine's threads and 4. At most 64.

Give a big server the cores to go with it: these threads help only where the machine has spare ones. See servers per machine.

The configuration file

dedicated init writes a commented dedicated.toml. Relative paths are relative to the file's folder. A small setup with two servers looks like this:

dedicated.toml
game = "game"
public_address = ""          # empty: the address the masters see
upnp = false
auto_update = false          # true: install each new release and restart
auto_reload = true           # apply saved edits while the servers run
host_name = "My Community"
admins = [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
]

[master]
enabled = true
port = 49175

[rcon]
password = ""             # set one to turn on the remote console
address = "127.0.0.1"

[defaults]
voice = true
voice_global = true        # V: everyone
voice_team = true          # B: teammates
voice_proximity = true     # N: players nearby
text_chat = true
votes = true
max_players = 16
min_players = 1            # wait in the lobby until this many players join
anti_cheat = "enforce"     # the default; see Anti-cheat
block_vpn = true           # the default; see VPN blocking
welcome = "Welcome to {server}, {name}!"

[[server]]
name = "Community Rotation"
port = 49176
playlist = "playlists/community.playlist.json"

[[server]]
name = "Snipers Only"
port = 49177
map = "Valhalla"
game = "Game Modes/snipers.bin"
max_players = 8

General settings

These go at the top of the file, before the first [section].

SettingDefaultMeaning
gamegame beside the file, else the folder the game savedFolder with the game files: a copy, or the game's own folder.
content"content"The Maps, Game Modes, Images and Mods every server shares.
data"data"One folder per server: its log, live status, keys and profile.
bans"bans.json"The ban list every server shares.
public_address""The IP address or DNS name players connect to. Empty uses the router's with upnp, else the address the masters see.
bind_address"::"The local address the game ports and this machine's master listen on: "::" for every network, "127.0.0.1" for this machine only, or one of its addresses. dedicated check shows it as Listening.
upnpfalseAsk the router to forward the ports, through UPnP or else PCP. Leave it off on a VPS.
auto_updatefalseInstall new stable releases by themselves and restart the servers, which interrupts their games. Ignored in Docker. See automatic updates.
auto_reloadtrueApply edits to this file, the playlists and variants it names and the content folder's maps and game types while the servers run, once they pass the same checks as a start. false waits for dedicated reload. See changing settings while servers run.
host_name"" (dedicated init writes "Dedicated server")Shown under each server's name in the browser, on its card and in its lobby.
admins[]Player IDs who may kick and ban on every server, and can't be vote-kicked.
vote_kick_immune[]Player IDs no vote can kick, without admin rights.
moderators[]Player IDs who hold the Mod role on every server. See roles.
stats_server""The stats service finished games are reported to. Empty uses the project's public service, "off" reports nowhere, or give your own as http://host:port. See stats.
stats_copies[]Up to 8 more stats services that get a copy of each game's signed report, such as a mirror of your own. See copies of the reports.
film_receivers, film_upload_kbps[], 0Where the servers' finished films are uploaded, and the most KB/s that may take. See film uploads.

Discovery ([master])

SettingDefaultMeaning
enabledtrueRun this machine's master. Only one runs per port: another configuration on the machine shares it, and takes over within half a minute if it stops. Servers report to the three default masters either way. A master that can't start is logged and the servers run without it.
port49175Its port, on TCP and UDP. Players' browsers look for a master on this PC at 49175.
peers[]More masters, as http://host:port: every server reports to them and registers with them too, and this machine's master swaps listings with them. https:// isn't taken: a server given one doesn't start.
origin""Where others reach this master, as http://host:port, named when it writes to its peers. Without it, other masters don't learn it.

Players find your servers without adding anything: every server that isn't hidden reports to the three default masters, to this machine's master and to your peers, and masters pass on the other masters they know. While one default master is down, the others keep your servers listed. A hidden server reports nowhere; players reach it by Direct Connect.

The masters check what they list:

  • A server is listed once it answers. A master asks each server it's told of, the way a browser does, and lists it a couple of seconds after its first report, once the server itself has answered. A server the master can't reach, directly or through an introduction, isn't listed there. One that doesn't answer is looked at again after two minutes.
  • From its own address. A master takes a server's report only from the address the server lists. A public_address set by hand to another address than the one the machine's connections leave from, or a report that leaves over IPv6 for a game listed by IPv4, isn't listed. Leave public_address empty unless you need it.
  • Four servers per address. A master lists at most four servers at one IP address, the four that answered first, and hosts behind one public address share its four. To list more, ask the master's operator to allow your address; see Master servers. This machine's own master lists every server it runs.
  • Players are counted by the masters. Each player's game tells the masters which server it plays on, and the Server Browser shows no more players than the masters counted, whatever a server says.

Masters only hand out addresses players can reach. A public_address of 127.0.0.1 lists your servers to this machine only. A local-network one (192.168.x.x) lists them to that network, and to everyone else under the internet address a master on the internet saw. Leave public_address empty to be listed at the address the masters see.

How masters share listings and fall back when one is down, how the master here can introduce itself to others, and how to run a master on its own, on a machine without the game: see Master servers.

Remote console ([rcon])

SettingDefaultMeaning
password""Turns the console on: 8 to 128 characters on one line. Empty leaves it off.
address"127.0.0.1"Where each server's console listens. "0.0.0.0" is every network. See security.

VPN block ([vpn])

SettingDefaultMeaning
lists[] (the default lists)http(s):// addresses or files of ranges and networks. "default" among them keeps the default lists. See the lists.
asns[]Networks refused whole, as 64500 or "AS64500".
asn_tableiptoasn.com's tableThe table that says which network announces each address: an http(s):// address or a file in its format, plain or gzip. "" turns network matching off.
fail_closedfalseWhile no list has ever arrived, refuse everyone but admins and allowed players, instead of admitting everyone.

[workshop] is under Workshop downloads.

Each server ([defaults] and [[server]])

Up to 32 servers, each a [[server]] block. name and port are required. Everything in the second table can also go under [defaults], for every server that doesn't set its own.

Only in [[server]]Meaning
nameRequired, up to 48 characters. Its folder in data is made from it: lower case, Latin letters and digits, at most 40 characters.
portRequired. The UDP game port, different for each server. Use 1024 or higher.
enabledfalse keeps the entry without running it. true by default.
base_mapWith map and game, when map names a Forge variant: the map it was made on, when a mod shares that map's number. See Forge variants on mod maps.
campaignCampaign co-op instead, of any of the five games or a mod: the campaign, the mission by its name or number, where it starts, the difficulty, the characters and modifiers. See campaign co-op and Campaign servers.
odstHalo 3: ODST's campaign or Firefight instead. See Halo 3: ODST.
reachA Halo: Reach mission or Firefight instead. See Reach co-op and Firefight.
host_nameThis server's own host name.
admins, vote_kick_immuneMore player IDs, for this server only, added to the ones at the top of the file.
rcon_portThis server's remote console TCP port, 1024 or higher. Its game port number unless set.
rcon_passwordIts own console password, in place of [rcon] password.
metrics_httpA loopback address, such as "127.0.0.1:9310", where this server answers GET /health and GET /metrics. Off unless set. See live status for panels.
In eitherDefaultMeaning
playlistnoneA playlist file: a rotation players vote on from three games up.
playlistsnoneSeveral playlist files, each for its own lobby sizes, instead of playlist. See playlists by lobby size.
weightsnoneHow often the server picks each map, game type or game by itself, over every playlist. See server weights.
map + game"guardian", "slayer"One map and game type for every game, named as in a playlist entry. game = "Forge" hosts Forge.
variantnoneA saved custom game or shareable game type (.json). A saved co-op game makes it a campaign server.
max_players16Players admitted at once, split-screen players included. Up to 127 PCs can join, as the server holds one of a game's 128 places; the file takes up to 128. A campaign server or an ODST server takes at most 16. See up to 127 players.
min_players1Players the server waits for in its lobby before a playlist vote or the automatic start begins, 1 to max_players, split-screen players included. See minimum players.
post_game_seconds15Seconds the post-game screen stays before the next game.
start_countdown_seconds3Seconds the lobby counts down once min_players are in it and its ballot chose the game.
hiddenfalseOnline but never listed; players join by address.
password""A password players need to join. See private servers.
welcomenoneA chat message every player reads as they join; a list gives up to five lines. See welcome messages.
network_model"enhanced""enhanced" or "classic". See networking.
coop_network"lockstep""lockstep", "lockstep30" or "host", experimental. See networking.
encode_once, channel_threads, node_threadsby the server's sizeHow a big server spreads its network and animation work. See big servers.
campaign_skip_vote_percent33Co-op games: the share of players, 1 to 100, who must press skip before a cinematic is skipped. See skipping cinematics.
failover, failover_in_gamenone, falseA standby server that takes the lobby over if this one goes down, and whether it stays through each game. See handoff and failover.
film_recording, film_keep, film_max_mbfalse, 25, 2048Record each game's film, and how many films and MB to keep. See server films.
joins, join_gates, queue_max, vip_queue_max, vip_priority, queue_starve_after, queue_max_waitsee the sectionWhether new players get in, and the line a full server keeps. See join queue and gates.
moderator_ban_minutes, devs_as_vip60, falseA Mod's longest ban, and whether Project Reclaimer's developers hold VIP. See roles.
allow_botsfalseLet bots join.
combat_bots, bot_pilots0, 0Fighting players the server hosts in its multiplayer games, and how many of them fly or drive vehicles. See fighting bots.
voice, text_chat, votestrueVoice chat, text chat and player votes.
voice_global, voice_team, voice_proximitytrueTurn global voice (V), team voice (B) and proximity voice (N) on or off. See voice scopes.
voice_team_only, voice_proximity_onlyfalseOlder shorthands: team voice alone, or proximity voice alone.
chat_logtrueKeep the server's text chat in a file per day; see chat logs.
anti_cheat"enforce""enforce" refuses and kicks, "detect" refuses and reports, "off" doesn't check. See anti-cheat.
block_vpntrueRefuse players who connect through a VPN, proxy or hosting provider. See VPN blocking.
max_ping0The highest ping, in milliseconds, a player may have as they join, up to 1000; 0 takes everyone. See ping limit.
load_timeout30Co-op games in a playlist only: seconds one player's game may hold up the next game before that player is removed, up to 600; 0 waits as long as it takes. Multiplayer games wait for no slow player. See players still loading.
team_changing"balanced""balanced", "game_type" or "off". See team changes.
camera"first_person""first_person", "player_choice" or "third_person". See camera.
friendly_firetruefalse stops players from hurting their teammates and co-op partners. See friendly fire.
round_outlasts_leaversfalsetrue keeps a round going when a player leaving, or removed, leaves too few contenders, such as one team emptied: the others play on until the time limit, the score limit or the console ends it. false ends the round at once, as Halo 3 does. From the next game.
force_modelnone"spartan" or "elite": every player plays that character in multiplayer games on Halo 3's maps. Unset, each player's own pick.
map_hudfalsetrue: every player sees the HUD of the map's own character, whatever character they play. false: each character brings its own HUD.
stock_map_defaultstrueHalo 3's maps played without a saved map get the extra respawn points of Bungie's default variants. false leaves them out.
trust_player_gamestrueFor co-op servers: when every player's game goes out of step with the server's at once, the server checks one player's game and takes it, instead of every player loading the server's.
draw_framesfalseA server draws no frames. true has it draw them all the same, against no graphics card: a way back if a server misbehaves.
tick_rate60Ticks a second in this server's multiplayer games: 60, or 30 to save processor time. Players' games stay at 60, and co-op games keep their own rate. See playing at 30 ticks.
share_modsfalseLet players who lack a mod this server's games use download it from the server itself, and fall back to the server when a Steam Workshop download fails. See Mods.
share_rate20Upload limit for downloads from the server together, in Mbit/s. 0 is no limit.
customization, require_customization, no_vanilla_charactersnone, false, falseThe character mods the server's multiplayer games add, by name, at most 122; whether players must take them to join; and whether nobody plays Halo 3's own characters.
odst_objectsfalseForge games: Halo 3: ODST's objects in the palette on Halo 3's maps. The server's games then need ODST: its listing says so, and players without it are told. See Forge palettes.
reach_objects, halo1_objects, halo2_objectsfalseForge games: Halo: Reach's, Combat Evolved's or Halo 2's objects in the palette on Halo 3's maps. The server's games then need that game. See Reach, CE and Halo 2.
halo3_objectstrueForge games: Halo 3's objects stay in the palette on ODST's canvases.
forge_mods[]Forge games: mods whose objects join the palette, by title, package folder or workshop:item. Each becomes a mod the games require, which players download as they join.
forge_primitivestrueForge games: Project Reclaimer's primitives in the palette.
forge_edit"game_type"Who edits in Forge games: "game_type" follows the game type's Allow editing, and "roles" lets only players whose role may. See who edits in Forge.
restore_state, forge_autosave_minutes, forge_autosave_keepfalse, 0, 3Start from the state saved last, and save it by itself during Forge games. See saving on the server.

Choose one of playlist, playlists, map + game, variant, campaign, odst or reach per server. A server that sets none of them plays the [defaults] choice, and with none there, Slayer on Guardian. A map without a game plays Slayer, and a game without a map plays Guardian.

A setting the file doesn't know stops dedicated check and the start, with its name and the settings that section takes: max_player gives unknown field `max_player`, expected one of `hidden`, `password`, `max_players`, … in `defaults`. The same goes for a setting in the wrong section, such as auto_update written after [defaults]: the general settings come before the first [section] header, since every line after a header belongs to that section. Misspelt maps and game types get the name you probably meant, in dedicated check, in the playlists and at the start.

Welcome messages

A server can greet every player in chat as they join: your rules, your Discord, what the server plays. Set welcome under [defaults] for every server, or in one [[server]] block. {name} stands for the player's name and {server} for the server's, and a list gives up to five lines:

dedicated.toml
[defaults]
welcome = "Welcome to {server}, {name}! Be nice, and vote for the next game in the lobby."

[[server]]
name = "Big Team Battle"
port = 49178
playlist = "playlists/btb.playlist.json"
welcome = ["Welcome, {name}!", "Big Team Battle: CTF, Slayer and Heavies rotate.", "Discord: discord.gg/example"]
  • The message arrives once the player's name is known, in the lobby or on the loading screen, and again each time they rejoin.
  • welcome = "" in a [[server]] block turns the [defaults] welcome off for that server.
  • It's sent in text chat, so a server with text_chat = false can't have one: dedicated check and the start say so.
  • RECLAIMER_DEDICATED_WELCOME sets a one-line [defaults] welcome, for example in Docker's .env. For several lines, use a list in dedicated.toml.

Private servers

Set password in a [[server]] block to make players enter it to join, or under [defaults] for every server. A server with password = "" is open even when [defaults] has one.

dedicated.toml
[[server]]
name = "Clan Practice"
port = 49178
map = "The Pit"
game = "Slayer"
password = "a password you give your players"
  • The Server Browser marks the server PRIVATE, and joining asks for the password, from the list, by Direct Connect or with a join link. A wrong one can be tried again.
  • Capitals and spaces count. The password never appears in listings or join links, and players prove they know it over the encrypted connection instead of sending it.
  • It's separate from the remote console's password, and doesn't hide the server: use hidden for that.
  • RECLAIMER_DEDICATED_PASSWORD sets the [defaults] password, for example in Docker's .env.

Minimum players

A server can wait in its lobby until enough players have joined, so a big game doesn't start with two people in it. Set min_players in a [[server]] block, or under [defaults] for every server, from 1 to that server's max_players. The default, 1, starts as soon as someone is there. A player counts once their game has joined the server, not when they first connect or while it's still joining.

dedicated.toml
[[server]]
name = "Big Team Battle"
port = 49178
playlist = "playlists/btb.playlist.json"
max_players = 32
min_players = 8   # no vote or start until 8 players are in
  • Until then, players wait in the lobby: no playlist vote opens and no game starts by itself.
  • If players leave and the count drops below min_players, a vote or countdown under way stops, and starts again once enough players are back.
  • Split-screen players count, as they do toward max_players.
  • A game already under way carries on when players leave it, until every player has left: then it ends after 5 seconds. A round that a leaving player leaves without enough contenders ends at once, unless round_outlasts_leavers = true.
  • RECLAIMER_DEDICATED_MIN_PLAYERS sets the [defaults] value, for example in Docker's .env. A value above a server's max_players stops dedicated check and the start, naming the server.

Ping limit

max_ping turns away players whose ping to the server is too high as they join. Set it in a [[server]] block, or under [defaults] for every server; max_ping = 0 opens one server to every ping when [defaults] has a limit.

dedicated.toml
[defaults]
max_ping = 150   # milliseconds; 0 takes everyone
  • It's checked only as a player joins: once in, a player stays whatever their ping does, so a lag spike never removes anyone. A joiner over the limit leaves within 5 seconds of joining.
  • A refused player is told their ping and the limit. The Server Browser shows a server's limit on its card and marks it PING LIMIT when a player's ping is over it; they can still try, since the server measures again.
  • The remote console's maxping shows the limit, and maxping 120 or maxping off changes it until the server restarts or a configuration reload changes max_ping.
  • RECLAIMER_DEDICATED_MAX_PING sets the [defaults] value, for example in Docker's .env.
  • Games hosted from the game have the same limit under Host Settings → Max ping; see how to play.

Players still loading

A multiplayer game waits for nobody. It begins as soon as its first player's game has loaded it. Players whose PCs are still getting the map ready or loading it finish and come straight into the running game, on the same connection, and nobody is removed for loading slowly.

Co-op games in a playlist, a mission or Firefight, still start with every player, so there everyone waits for the slowest. A player whose game holds the others up for load_timeout seconds, 30 by default, is removed and the others play:

  • The removed player reads why and can join again at once: it isn't a kick, so there's no wait.
  • The time counts from the player's last step forward, so a big map's slow first load isn't cut off while it still makes progress.
  • If players are often removed who would have finished, such as on slow disks, raise it, up to 600. load_timeout = 0 waits as long as it takes. RECLAIMER_DEDICATED_LOAD_TIMEOUT sets the [defaults] value.
  • A campaign server or an ODST server removes nobody while a mission loads, whatever the setting.
  • Games hosted from the game start multiplayer the same way. Their co-op lobbies have Host Settings → Wait for slow players: how long a mission change waits for a player whose game isn't ready before that game joins again by itself.

Environment variables

Most settings outside [[server]] can also come from an environment variable: RECLAIMER_DEDICATED_ and the setting's name in capitals, with MASTER_ before the [master] ones, RCON_ before the [rcon] ones, WORKSHOP_ before the [workshop] ones and VPN_ before the [vpn] ones. That suits Docker, systemd and other service managers, and works the same on every system.

VariablesSettings
RECLAIMER_DEDICATED_PUBLIC_ADDRESS, _BIND_ADDRESS, _HOST_NAME, _ADMINS, _VOTE_KICK_IMMUNE, _MODERATORS, _STATS_SERVER, _STATS_COPIES, _FILM_RECEIVERS, _FILM_UPLOAD_KBPS, _UPNP, _AUTO_UPDATE, _AUTO_RELOADThe general settings.
RECLAIMER_DEDICATED_GAME, _CONTENT, _DATA, _BANSThe folders.
RECLAIMER_DEDICATED_MASTER_ENABLED, _MASTER_PORT, _MASTER_PEERS, _MASTER_ORIGIN[master]
RECLAIMER_DEDICATED_RCON_PASSWORD, _RCON_ADDRESS[rcon], the remote console
RECLAIMER_DEDICATED_WORKSHOP_ITEMS, _WORKSHOP_STEAMCMD, _WORKSHOP_USERNAME, _WORKSHOP_PROVISIONER, _WORKSHOP_UPDATE_CHECK_MINUTES[workshop], Workshop downloads
RECLAIMER_DEDICATED_VPN_LISTS, _VPN_ASNS, _VPN_FAIL_CLOSED[vpn] lists, asns and fail_closed, what VPN blocking refuses
RECLAIMER_DEDICATED_MAX_PLAYERS, _MIN_PLAYERS, _POST_GAME_SECONDS, _START_COUNTDOWN_SECONDS, _MAX_PING, _LOAD_TIMEOUT, _CAMPAIGN_SKIP_VOTE_PERCENT, _WELCOME, _VOICE, _VOICE_GLOBAL, _VOICE_TEAM, _VOICE_PROXIMITY, _VOICE_TEAM_ONLY, _VOICE_PROXIMITY_ONLY, _TEXT_CHAT, _CHAT_LOG, _VOTES, _TEAM_CHANGING, _CAMERA, _FRIENDLY_FIRE, _STOCK_MAP_DEFAULTS, _ROUND_OUTLASTS_LEAVERS, _FORCE_MODEL, _MAP_HUD, _TRUST_PLAYER_GAMES, _DRAW_FRAMES, _TICK_RATE, _FILM_RECORDING, _FILM_KEEP, _FILM_MAX_MB, _ANTI_CHEAT, _BLOCK_VPN, _HIDDEN, _PASSWORD, _SHARE_MODS, _SHARE_RATE, _CUSTOMIZATION, _REQUIRE_CUSTOMIZATION, _NO_VANILLA_CHARACTERS, _ODST_OBJECTS, _REACH_OBJECTS, _HALO1_OBJECTS, _HALO2_OBJECTS, _HALO3_OBJECTS, _OTHER_GAME_CHARACTERS, _REACH_CHARACTERS, _KICK_BLOCKS, _FORGE_MODS, _FORGE_PRIMITIVES, _FORGE_EDIT, _RESTORE_STATE, _FORGE_AUTOSAVE_MINUTES, _FORGE_AUTOSAVE_KEEP, _MODERATOR_BAN_MINUTES, _DEVS_AS_VIP, _ALLOW_BOTS, _JOINS, _JOIN_GATES, _QUEUE_MAX, _VIP_QUEUE_MAX, _VIP_PRIORITY, _QUEUE_STARVE_AFTER, _QUEUE_MAX_WAIT, _WEIGHTS, _PLAYLIST, _VARIANT[defaults]: a server's own setting still wins.
RECLAIMER_DEDICATED_ONLYNo setting in the file. The servers this dedicated runs, by position from 1, name or game port, separated by commas (2, Big Team Battle, 49176,49177); the others stay off for it. Docker's container per server uses it.
RECLAIMER_VOIP=0, RECLAIMER_TEXT_CHAT=0Turn voice or text chat off on every server this dedicated runs.
  • A variable replaces the file's setting; an empty one leaves it. ADMINS, VOTE_KICK_IMMUNE, MODERATORS, STATS_COPIES, FILM_RECEIVERS, MASTER_PEERS and WORKSHOP_ITEMS add to the file's lists, separated by commas or spaces, and VPN_LISTS and VPN_ASNS add to theirs. CUSTOMIZATION and FORGE_MODS replace the [defaults] list, separated by commas only, since mod names hold spaces.
  • Flags take true or false (also 1/0, yes/no, on/off).
  • A RECLAIMER_DEDICATED_ name it doesn't know stops the start, so a typo is never silently ignored: RECLAIMER_DEDICATED_MAX_PLAYRS: no such setting ("max_playrs").
  • network_model, coop_network, map, game, playlists, campaign, odst, reach, combat_bots, bot_pilots, failover, the big servers settings and [vpn] asn_table have no variable: set them in dedicated.toml. WEIGHTS takes the table as TOML.

Changing settings while servers run

Servers take up edits to dedicated.toml, the playlists and variants it names, and the maps and game types in content/Maps and content/Game Modes while they run. Save the file, and a couple of seconds later dedicated checks the whole configuration the way dedicated check does, then applies it. Players stay connected, and the game under way finishes under its own rules:

What changedWhen it applies
name, host_name, password, max_players, min_players, max_ping, post_game_seconds, start_countdown_seconds, welcome, admins, vote_kick_immune, moderators, the roles, votes, the voice settings, text_chat, share_mods, share_rate, weights, failover, campaign_skip_vote_percent, the join gates and queue, allow_bots, forge_edit, restore_state, the Forge autosaveAt once. Players already in stay when a limit tightens.
hidden, chat_log, block_vpn, [vpn] fail_closed, rcon_port, rcon_password, [rcon], metrics_http, bans, stats_copiesAt once: the server is listed or taken off the masters, the day's chat log opens or closes, and the console moves, so signed-in tools sign in again.
friendly_fire, stock_map_defaults, round_outlasts_leavers, team_changing, camera, force_model, map_hud, load_timeout, trust_player_games, draw_frames, tick_rate, failover_in_gameFrom the next game.
anti_cheat, customization, require_customization, no_vanilla_characters, film_recording, film_keep, film_max_mb, stats_serverFrom the next game. The game under way keeps its own to its end, and to its report.
A server's playlist or playlists, or the games in them; changing between a playlist, a variant and one map and game typeFrom the next vote. A ballot already open, and the game it picks, still come from the playlist before.
A new [[server]], or enabled = trueIt starts at once.
A server taken out, or enabled = falseIt stops once it has no players.
port, network_model, encode_once, channel_threads, node_threads, combat_bots, bot_pilots, and max_players on a server with fighting bots; a new name that changes the server's folder in data; changing to or from a campaign, ODST or Reach server, or anything about its gameThat server restarts once it has no players (its bots don't count).
vpn-local.txt (see refuse a network at once)Within a minute.
auto_reload, upnp, [master], [vpn] lists, asns and asn_tableAt once, by dedicated itself: ports are forwarded or let go, this machine's master starts again on its new settings, and the VPN lists are fetched from their new sources.
public_address, bind_address, film_receivers, film_upload_kbps, game, dataWhen dedicated restarts. The rest of the reload applies, and its report says so.
content, coop_network, the Forge palette settings, auto_updateNothing is applied: restart dedicated.

If any check fails, nothing changes and every server keeps its settings; the console says what's wrong. The console shows each reload, in lines tagged [reload], with what changed on each server under when it applies: Applied now, Applied from the next game, Restarts once it has no players, or Restart the supervisor to apply for what waits for dedicated itself to start again.

To apply edits when you choose instead, set auto_reload = false at the top of dedicated.toml and run dedicated reload on the server's machine, or reload on a server's remote console. Both wait for the checks and answer with what changed, or what's wrong:

Shell
project-reclaimer dedicated reload
  • Adding mods to content/Mods doesn't start a reload by itself. dedicated reload, or the next saved edit, reads the content folder again, mods included.
  • A Workshop item an edited configuration names and that isn't installed yet is installed first, while the servers play on. That reload answers that the items are being installed, and applies by itself once they're in.
  • Settings the remote console changed (servername, password, maxping, joins, weight) stay until the file's own value of that setting changes.
  • A setting that needs a new process doesn't have to wait for an empty server: a handoff moves the lobby to a new one between games.
  • Environment variables keep the values dedicated started with.
  • A server that restarts after a crash starts with the configuration as last reloaded.
  • WebSocket tools get a control event with action reload for every reload, with what changed on that server, or with ok false and why nothing changed. A reload_applied event follows when a playlist it left waiting takes over.
  • In Docker, each container applies the edits for its own server. A new [[server]] also needs its own service in compose.yaml; see more servers.

Custom playlists

A playlist is a rotation of games, each a map with a game type, optionally with its own rules, or a co-op mission. A server running a playlist of three or more games lets players vote on what to play next:

  • Before each game, the lobby shows three games drawn at random from the whole playlist and None of the above, with a countdown (20 seconds unless you set another). The order of the file plays no part.
  • Each game comes up in proportion to its weight: one with "weight": 2 comes up twice as often as one without. The game just played sits out the next ballot.
  • The game with the most votes is played. Ties go to the game offered first. With no votes, the first game offered starts, so a quiet server plays games in proportion to their weights.
  • If None of the above wins outright, a new ballot opens with games that haven't been turned down yet.
  • An empty server keeps its ballot closed and opens a fresh one when a player arrives, or once min_players players are in.
  • A playlist of one or two games isn't voted on: the next game is drawn by weight.

1. Build the playlist

In the game (recommended)

Pick maps and game types from what you have installed. The editor checks every game and writes the file for you.

By hand

Playlists are short JSON text files. Write one in any text editor, or edit one the game saved.

On the server itself, dedicated playlist new writes one from the command line, checked against the server's content; see names and playlists from the command line.

In the game:

  1. Open the Playlists pageIn a lobby you host, open Playlists, then NEW PLAYLIST.
  2. Add gamesChoose ADD A GAME, pick a map and a game type, and add them. Repeat for at least three games. Installed mod maps are in the map list too. ADD THE LOBBY'S GAME adds whatever the lobby is set up to play, rules included. The map list offers every supported game's maps you have installed, mod maps included. To have a game come up more often, select it and raise its WEIGHT, 1 to 100. REMOVE GAME, or Delete, takes the selected game out.
  3. Change a game's rules (optional)Select the game. RULES & OPTIONS opens them in the lobby, and SAVE TO PLAYLIST brings them back. The game's own rows set SPRINT (see sprint in a playlist), TEAM VOICE ONLY (see team voice in a playlist), ANTI-CHEAT (see single games without it) and its VOTE IMAGE.
  4. Follow the lobby's size (optional)BY PLAYERS, on the playlist and on each game, sets which lobby sizes they're for, and draws the voting time and each numeric option as a graph over the player count, with 2 to 5 points; ADVANCED has the line's shape and a formula. See games by lobby size.
  5. Save itName the playlist and choose SAVE PLAYLIST, which names anything still missing. Games that aren't installed are marked MISSING, and a misspelt name shows the name you probably meant. The file is saved in the Playlists folder of your player folder; OPEN FOLDER shows it.

Custom vote images

Each playlist entry can show its own PNG or JPEG in the vote. Put the file in content/Images on a dedicated server, or the Images folder in your player folder for a game you host. Select an entry in the playlist editor and set VOTE IMAGE to the file, or in JSON add "preview_image": "arena.jpg" to the entry. Without one, ballots show the map's art.

Use files of at most 4 MiB, with filenames rather than paths. A playlist can share up to 32 different images; players receive them from the server without a separate download. A file that isn't a picture is logged, and that game keeps the map's art.

By hand, a playlist looks like this:

playlists/community.playlist.json
{
  "version": 2,
  "name": "Community Rotation",
  "vote_seconds": 30,
  "games": [
    { "map": "Guardian", "game": "Slayer", "weight": 2 },
    { "map": "Valhalla", "game": "Capture the Flag" },
    { "map": "The Pit", "game": "Slayer", "name": "Slayer to 50", "rules": { "score_to_win": 50 } },
    { "map": "Valhalla", "game": "Slayer", "name": "BR Starts",
      "options": { "player.primary_weapon": "Battle rifle", "player.secondary_weapon": "Magnum" } },
    { "map": "Maps/my_arena.json", "game": "Game Modes/snipers.bin" }
  ]
}

Names and playlists from the command line

The server itself lists the names it accepts, and writes and checks playlists, with no game client needed. Run these in the server folder. dedicated content lists every name map, game and playlist games accept: the folder's maps and game types, and its map variants and game variants, then every campaign a campaign server can host, with its missions. Words narrow the list:

Shell
project-reclaimer dedicated content                 # every map and game type; variants are counted
project-reclaimer dedicated content snipers         # only names containing "snipers"
project-reclaimer dedicated content mlg guardian    # every word must match

Halo 3's own and matchmaking variants run into the hundreds, so without words they're counted rather than listed.

dedicated playlist new makes a playlist of every map with every game type, checks each game against the server's content and writes it to playlists/; dedicated playlist checks every playlist file and names the servers that play it; dedicated playlist show lists one playlist's games, how often each comes up, and their options:

Shell
project-reclaimer dedicated playlist new "Team Slayer" --maps "Guardian,Valhalla,The Pit" --games Slayer
project-reclaimer dedicated playlist                # every playlist, its servers, and whether it can be played
project-reclaimer dedicated playlist show slayer    # its games, how often each comes up, what is wrong
Output
Wrote playlists/team-slayer.playlist.json with 3 games:
  Slayer on Guardian
  Slayer on Valhalla
  Slayer on The Pit
In a [[server]] block: playlist = "playlists/team-slayer.playlist.json"
  • --maps and --games take names separated by commas, as dedicated content lists them. playlist new makes at least three games, so name enough maps or game types.
  • A name it doesn't know writes nothing and says what was probably meant. --replace overwrites a playlist file of the same name, and --vote-seconds sets the voting time (20 unless set).
  • Edit the file afterwards to set weights, names, rules and options; see the playlist file reference.
  • playlist show takes the file, or part of its name in playlists/.
  • In Docker, run them in a server's container: docker compose run --rm server-1 dedicated content snipers.

2. Put it on the server

Copy the playlist file into the server folder's playlists/ folder. If it uses your own saved maps or game types, copy those too: saved maps from your player folder's Maps into content/Maps, and game types from its Game Modes into content/Game Modes. Also make sure the server's game/ folder has every base map the playlist uses.

3. Point a server at it

In dedicated.toml, set playlist on a server (or under [defaults] for every server). Remove any map, game or variant from that server.

dedicated.toml
[[server]]
name = "Community Rotation"
port = 49176
playlist = "playlists/community.playlist.json"
max_players = 12

4. Check it

Shell
project-reclaimer dedicated check

check resolves every game in the playlist against the game and content folders and names anything missing, by game number, with the name you probably meant when one is close: game 2: no multiplayer map "Valhala" is installed; as a variant: Map 'Valhala' was not found. Did you mean 'Valhalla'? Running servers check and take up a saved playlist by themselves, from their next vote; see changing settings while servers run.

To add a Halo 3 map missing from a server folder made with --maps, run dedicated init . --from "your game's folder" --maps "the map" in that folder on a PC with the game: it adds the missing files and keeps your settings.

To try a playlist on one PC, use it in a lobby you host: USE IN THIS LOBBY on the Playlists page. In a lobby on this PC alone, it hosts the lobby at once so the vote can open.

Playlist file reference

FieldMeaning
nameThe playlist's name, shown in the lobby.
vote_secondsVoting time, 5 to 120 seconds. Optional; 20 by default. A curve makes it follow the lobby's size.
players, recommended_playersOptional. The lobby sizes the playlist is for, and the sizes it's best with, such as "8-24". See games by lobby size.
versionFile format version. Optional; 2, the only one.
gamesThe rotation: 1 to 256 games, voted on from three up. Their order doesn't matter: ballots draw them at random by weight.

Each game in games is a multiplayer game, or a co-op entry:

FieldMeaning
mapA base map by its title, file name or ID ("Valhalla" or "riverworld"), a saved map in content/Maps ("Maps/my_arena.json"), the name stored inside a saved map, or a mod map: "workshop:item ID/map file name", or its name. Base maps win over saved maps with the same name.
base_mapOptional, only when map names a map variant file: the map it plays on, named as map names one, when a mod shares the map number stored in the file. See Forge variants on mod maps.
gameA game type by its name or key ("Slayer", "Capture the Flag", "ctf"), "Forge", Halo 3's own variants by the names the game shows ("Team Slayer", "Mosh Pit"; their older file names still work), a file in content/Game Modes, or the name stored inside a saved game type. Game types win over saved ones with the same name.
weightOptional. How often ballots offer this game compared with the others, 1 to 100; 1 when left out. A game can't be listed twice: raise its weight instead.
players, recommended_playersOptional. The lobby sizes this game is offered at, and the sizes it's offered more often at. See games by lobby size.
nameOptional. The name players see for this game.
teamsOptional. true or false over the game type's own default.
rulesOptional. Slayer's scoring: score_to_win, kill_points, death_points, suicide_points, betrayal_points, such as { "score_to_win": 50 }. For other game types, use options.
optionsOptional. Game options layered over the game type, keyed section.key. Values are a number, a switch or the option's label as the game shows it, ignoring case. A numeric option also takes a curve over the lobby's size. This includes each game type's rules, such as King of the Hill's moving hill: { "mode.hill_movement": 4, "mode.hill_order": 1 } moves the hill every minute, in the map's order.
worldOptional. World settings for this game: sprint (see sprint in a playlist), player_scale_percent (25 to 300), exposure (0.1 to 4.0) and atmospheric_fog.
anti_cheatOptional. false plays this game without the anti-cheat, for a map or game type whose physics or scripts behave unusually enough to risk a wrong kick. Left out, the server's own setting applies; an entry can only turn the anti-cheat off, never on.
voice_team_onlyOptional. true keeps voice to teammates while this game plays. Left out or false, the server's own settings apply. See team voice in a playlist.
preview_imageOptional. The game's picture on ballots, a PNG or JPEG in content/Images. See custom vote images.

Names are matched ignoring case. A field the file format doesn't know stops the playlist, naming the game. Some option keys to start with:

OptionExample value
player.primary_weapon"Battle rifle", or "Random" for a new one at every spawn
player.secondary_weapon"Magnum", or "Map default" for the map's own
map.weaponswhich weapons are placed on the map
map.vehicles"None"
rounds.limit3 (one round unless set)
rounds.early_victoryoff unless set

The easiest way to get option keys right is to change the options in a lobby and use SAVE TO PLAYLIST: the editor writes only the settings that differ, with their exact keys. An unknown key or label is reported by game number, with the choices it has.

Games by lobby size

A playlist, and each of its games, can name the lobby sizes it's for, so a server offers small maps to a few players and big ones to a full lobby:

playlists/big-team.playlist.json
{ "version": 2, "name": "Big Team", "players": "8-24", "recommended_players": "12-20", "games": [
  { "map": "Sandtrap", "game": "Big Team CTF", "players": "12+" },
  { "map": "Valhalla", "game": "Team Slayer", "recommended_players": "8-16" },
  { "map": "Standoff", "game": "Assault" } ] }
  • players is a limit: outside it, a game is never offered while three other games fit. A game needs both its own range and its playlist's to allow the lobby's size, and an entry's range outside its playlist's is an error.
  • recommended_players is a preference: inside it, a game counts four times its weight.
  • Ranges are written "8-20", "12+", "16" or as a bare number, from 1 to 128. Saved maps and game variants can carry ranges of their own.
  • The lobby's size is its players, split-screen players included, and the server follows it through each game, so someone who joins during play counts for the next ballot. One player coming or going counts once it has lasted 10 seconds, so a player at a range's edge doesn't flip the ballot; two or more, and the first players of an empty lobby, count at once.
  • When too few games fit, the ballot is filled with the games nearest the lobby's size, and the log warns Playlist warning: fewer than three games allow N players. At its start, dedicated names every lobby size from 1 to max_players where that happens.
  • A playlist with no ranges anywhere draws exactly as before.

Several playlists by lobby size

A server can also play several playlists, each for its own lobby sizes. Set playlists on a [[server]] or under [defaults], in place of playlist, with up to 16 files. Each entry may give the sizes it's for, which replace the file's own:

dedicated.toml
[[server]]
name = "Community Rotation"
port = 49176
max_players = 24
playlists = [
  { file = "playlists/small.playlist.json", players = "1-8" },
  { file = "playlists/big.playlist.json", players = "9+", recommended_players = "12-24" },
]
  • Each ballot draws from the games of every playlist whose range allows the lobby's size. A game several of them list is one game, at its best weight.
  • The ballot's title names the playlists in play, such as Small + Big where ranges overlap, and its voting time is the first of those playlists'.
  • The remote console's status gives the lobby size a ballot was drawn for and the playlists in play.
  • Every listed file is watched: an edit applies from the next vote.

Settings by lobby size

A game's numeric options and a playlist's vote_seconds can follow the lobby's size. In place of a number, give a curve through points of players and value:

playlists/grows.playlist.json
{ "version": 2, "name": "Grows",
  "vote_seconds": { "points": [[2, 15], [16, 25], [64, 30]] },
  "games": [
    { "map": "Valhalla", "game": "ctf", "options": {
        "rounds.minutes": { "points": [[4, 5], [16, 10], [32, 15]], "interpolation": "steps" },
        "respawn.seconds": { "formula": "3 + p/8", "max": 6 } } } ] }
  • Points: 1 to 32 of them, with players from 1 to 128 in rising order. The curve holds its first value below the first point and its last above the last.
  • interpolation: "linear", the default, draws straight lines between the points; "steps" keeps each point's value until the next; "smooth" draws a curve through them that never overshoots a point. min and max bound the result.
  • A formula in place of points is written in p, the player count, with numbers, + - * / ^, brackets and min, max, clamp(x, lo, hi), abs, sqrt, ln, log10, exp, round, floor and ceil. It must give a number at every size from 1 to 128. A curve has points or a formula, not both, and an error names the character that's wrong.
  • An option takes its curve's value rounded, and every value the curve can give must be in the option's range, checked as the playlist loads. vote_seconds stays within 5 to 120 at every size.
  • When it's read: an option as the server gets the game ready, for the lobby's size then, and it holds for the whole game. The log says so: Slayer on Guardian for 9 players: rounds.minutes = 8. vote_seconds is read as each ballot opens.
  • Combat Evolved's and Halo 2's maps take no options, so no curves either; their lobby sizes work like any other game's.

Server weights

A server's weights say how often it picks each map, game type or game by itself, over whatever playlists it plays, without editing them. Set them under [defaults.weights], or in a server's own weights:

dedicated.toml
[defaults.weights]
maps = { "Guardian" = 0.5 }
game_types = { "Oddball" = 0 }
games = [{ map = "Sandtrap", game = "Big Team Slayer", weight = 3 }]
  • 1 is normal and 10 the most. 0 means never by itself: the game stays listed and installed, and nextmap, load and queued games still reach it.
  • A game named in games takes that weight alone. Any other game's is its map's weight times its game type's, times its playlist entry's own.
  • They apply at once. The remote console's weights shows each game's share and any name that matches nothing, and weight changes one until a restart or until a reload changes the file's weights.

Sprint in a playlist

Playlist games can play with sprint. It's off for every playlist game unless its entry turns it on, even when the entry's map or game type has sprint. Choose with the playlist editor's SPRINT row, or set "sprint" under "world" in the entry:

Playlist entry
{ "map": "Valhalla", "game": "Slayer", "name": "Sprint Slayer", "world": { "sprint": "stamina" } }
Key in worldMeaning
sprint"off", "unlimited" or "stamina". Off when left out.
sprint_speed_percentSprint speed, 110 to 200 percent; 150 when left out.
sprint_stamina_secondsWith "stamina", how long a full meter lasts, 1 to 30 seconds; 5 when left out.

Players hold Left Shift while running forward to sprint, or click the left stick on a controller.

Co-op games in a playlist

A playlist can hold co-op games beside multiplayer ones. An entry with campaign is a mission of Halo 3's campaign, and an entry with odst a game of Halo 3: ODST, set up as a server's own campaign or odst, with a weight beside it:

playlists/mixed.playlist.json
{
  "version": 2,
  "name": "Mixed",
  "games": [
    { "map": "Guardian", "game": "Slayer", "weight": 3 },
    { "campaign": { "mission": 3010, "difficulty": "heroic" }, "weight": 1 },
    { "odst": { "mission": 6100, "difficulty": "heroic" }, "weight": 1 },
    { "odst": { "mode": "firefight", "mission": 6100, "insertion": 4 } }
  ]
}
  • A co-op game starts with every player, so load_timeout applies to these entries, and to no multiplayer one.
  • A co-op game follows another in the same server. The server starts again between a co-op game and a multiplayer one, which takes a moment: its players are told, and their games join it again by themselves.
  • When a co-op entry's mission is over, won or ended, the playlist's next game follows.
  • The server needs what the entry needs, such as ODST's files, and an entry that needs ODST is named in the listing: players without it see NEEDS ODST.
  • Co-op games hold at most 16 players, so keep such a server's max_players at 16.
  • A playlist's campaign entries play Halo 3's own campaign; an odst entry names its mission by number, file or title, such as { "odst": { "mission": "sc100" } }. Other games' campaigns and mods' campaigns are hosted by a server's own campaign.
  • A server with fighting bots can't have co-op entries in its rotation.

Mod maps in a playlist

Playlist games can be on mod maps. Pick them in the game's editor, which saves them by their Workshop item, or write them by hand: workshop:, the Workshop item's ID, a slash and the map's file name without .map. A mod map's name works too.

playlists/modded.playlist.json
{
  "version": 2,
  "name": "Modded customs",
  "games": [
    { "map": "workshop:2981234567/arena", "game": "Capture the Flag" },
    { "map": "workshop:2981234567/arena", "game": "Slayer" },
    { "map": "Guardian", "game": "Gun Game" }
  ]
}
  • The ID is the number after id= in the item's Workshop address. A server downloads the items its playlist names before it starts (see Workshop downloads), and dedicated mods prints the reference of every mod map it has, ready to paste.
  • Players are told every game's mods as they join, and get them once, from Steam Workshop or the server. Before each game's countdown, every player's game starts preparing the map that won the vote. A multiplayer game then begins with whoever has it ready, and the others come in as theirs finishes.

Forge variants on mod maps

A Forge variant file (.mvar or .bin) stores only its map's number, and some mods reuse another map's: a Warlock port can share Icebox's, for example. A variant that comes in its map's own Workshop package plays on that map with nothing to set. Any other plays on the installed map with that number, unless the entry names the map it was made on in base_map, written like map, such as "workshop:item ID/map file name":

Playlist entry
{ "map": "MLG Warlock V9", "base_map": "workshop:2977651586/warlock", "game": "2V2 HARDCORE TS" }

A server's map and game take it the same way:

dedicated.toml
[[server]]
name = "MLG Warlock"
port = 49176
map = "MLG Warlock V9"
base_map = "workshop:2977651586/warlock"
game = "2V2 HARDCORE TS"
  • A base_map the variant wasn't made on is refused: 'X' was not made on Y.
  • A server downloads the Workshop items base_map names like those in map.
  • A server's or playlist's variant file saved on a mod map may not find that map yet: name the map in map and the variant in game instead.

Forge maps Project Reclaimer saves as .json name their mod map themselves. Name the saved map in map and leave out base_map. The server uses its own installed copy of the mod, even when the map was saved on another PC with the mod in another folder.

Playlist entry
{ "map": "hugegrass_balanced", "game": "Slayer" }

Rules and limits

  • No game may repeat another. Changed rules or options make a different game; a renamed but otherwise identical game is still a repeat. To offer a game more often, give it a weight.
  • A playlist can use up to 23 different mod maps, from at most 16 mods. Two mod maps whose map IDs clash, or two different mods' maps with the same file name, can't be in one playlist.
  • A playlist stores no server settings, so it works for anyone with the same maps and game types. Share it freely.

Maps and game types

Put shared content in the content folder; every server on the machine sees it. The first dedicated check or start makes its folders.

FolderFiles
content/MapsMap variants (.mvar) and saved maps from Forge (.json).
content/Game ModesGame variants (.bin), shareable game types (.json) and game modes (.rmeg).
content/ImagesVote images.
content/ModsOne folder per mod: a Workshop item's folder, or a custom .map, with its .mapinfo if it has one. See Mods.
  • dedicated content lists the names the folder's maps, game types and variants go by, the ones map, game and playlist games take; see names and playlists from the command line.
  • Map and game variants reach players automatically when they join. Mods reach them through Steam Workshop, or from the server when it shares them.
  • The first dedicated check or start puts the game modes that come with Project Reclaimer in content/Game Modes/Project Reclaimer: Gun Game, Growth, One in the Chamber, Zone Control, Flood Infection, UNSC vs Covenant vs Flood, UNSC vs Covenant: Reach and Conquest. Name them like any saved game type, such as game = "Gun Game" or { "map": "Guardian", "game": "Growth" } in a playlist. A script runs on the server only; players don't need the file. See game modes on a dedicated server. A copy you never changed gets each release's update by itself.
  • Flood Infection needs Halo 3's campaign Flood. The server needs campaign.map, which dedicated init copies, and a campaign map that holds all four Flood forms, such as 050_floodvoi.map, which it doesn't: copy that from halo3\maps in the game's folder into game/halo3/maps.
  • A saved map can hold objects from other maps. To host it, the server needs those maps in its game/ folder; the simplest is to run dedicated init --from without --maps to copy every multiplayer map. Campaign vehicles and AI come from campaign.map and 040_voi.map, which dedicated init copies either way.
  • A server with only some maps offers the objects of the maps it has, and players with every map can join it.
  • Players who lack a map a game needs, or a mod they have no way to download, are refused with a message that names it.
  • Servers take up maps and game types added to content/Maps and content/Game Modes by themselves; see changing settings while servers run. After adding mods, run dedicated reload.

Forge on a server

A server plays saved Forge maps like any other map, and game = "Forge" hosts Forge itself. A map holds up to 9,999 Forge objects. Every game of a server's rotation takes these settings, for its palette and the objects it may place:

  • A map's own game's objects are always in its palette, and a mod map's own mod's.
  • odst_objects = true adds Halo 3: ODST's objects on Halo 3's maps. The server's games then need ODST: its listing says so, and a player without it is refused as they join.
  • forge_mods = ["Some Mod", "workshop:2981234567"] adds mods' objects, by title, package folder or Workshop item. Each becomes a mod the games require, which players download as they join.
  • halo3_objects = false leaves Halo 3's objects off ODST's canvases, and forge_primitives = false leaves out Project Reclaimer's primitives.

Saved maps that take objects from other maps need the Forge library, which the server builds the first time a game needs it, keeping it in its caches. Later games wait in the lobby meanwhile. Hosting saved maps in a rotation is tested; editing in Forge by players on a dedicated server hasn't been tried much yet. Of the campaign canvases, a dedicated server hosts ODST's: a Forge entry names one by its file name, such as { "map": "canvas_sc100_z0", "game": "Forge" }, and dedicated content lists them. The other games' canvases play from a lobby you host.

Who edits in Forge

A Forge game type's Allow editing says who may become the monitor: everyone, or the host only. A dedicated server plays nobody, so Host only lets nobody edit and Everyone lets everyone who joins. That's the default, forge_edit = "game_type". With forge_edit = "roles", the server's roles decide instead:

  • Only players whose role holds forge.edit switch to the monitor, and split-screen players at their PC with them. Host and Admin hold it; give it to a role of your own with can = ["forge.edit"], or to everyone under [roles.everyone].
  • Anyone else stays on foot, plays or watches, and is told Your role can't edit in Forge on this server. The server decides, never a player's own game. The game menu's map reset is an editor's too.
  • A monitor whose role loses forge.edit is back on foot at once.
  • The setting applies at once, in [defaults] or a [[server]].

Saving on the server

A player's SAVE MAP writes the Forge map to their own PC. A server saves on its own disk too, in the same format:

  • A named map: the remote console's forge save <name> writes content/Maps/<name>.json, over a map of that name, which a playlist, map or variant then names like any other. A name is 1 to 48 characters that can be a file's name.
  • The server's state: state save, or forge save with no name, writes data/<server>/state.json: the game being played, the rotation with its next game and queue, the Forge map being played, and the console's live settings. state alone shows the saved state, and state discard deletes it.
  • From the game: a player whose role holds forge.save types /forge save [<name>] in chat, or picks SAVE ON SERVER in the game menu, under SAVE MAP. Only they see it.
  • By itself: forge_autosave_minutes = 10 saves the state every 10 minutes of a Forge game, and keeps forge_autosave_keep earlier ones, 3 unless set and 20 at most.
  • The console answers once the file is on disk, so a script can save, wait for the answer and stop the server. A save never holds the game up.

With restore_state = true, a server starts from the state saved last: that game first, on its saved Forge map, with the rotation and the console's settings as they were. The state is then set aside, so the next start doesn't restore it again. Every start counts, a crash's too, so a server that autosaves comes back from a crash at its last autosave.

WhatRestored
The game being played, the next game, the queueExactly.
The Forge map's objects, labels, boundaries, sky, gravity and atmosphereAs SAVE MAP keeps them.
A server name, join password, ping limit, join gates or weight the console changedExactly, while the file's own value hasn't changed since.
Roles the console gave, bans and mutesThey're on disk already.
A round under way: scores, clock, where players standNo: the game starts from its lobby.
A co-op mission's checkpointNo: the mission starts where its setup says.

Campaign co-op

A dedicated server can run a campaign in co-op, with no player as host, for up to 16 players: Halo 3's, Halo: CE's, Halo 2's, Halo 3: ODST's, Halo: Reach's, or a mod's. It plays the missions one after another, from the one you name. Give a [[server]] one campaign line instead of a playlist, variant or map and game, naming the mission by its title, its file or its number:

dedicated.toml
[[server]]
name = "Halo 3 Co-op"
port = 49178
max_players = 16
campaign = { mission = "Sierra 117", difficulty = "heroic" }

[[server]]
name = "Combat Evolved Co-op"
port = 49179
campaign = { campaign = "halo1", mission = "a10", difficulty = "heroic" }

Campaign servers is the whole guide: every game's missions by the names to write, the files each game needs, mods' campaigns, the players' own characters, difficulty, starts and modifiers, and what each refusal means. In short:

  • campaign in the line is "halo3" (the default), "halo1", "halo2", "odst", "reach" or a mod's campaign by its title, such as "Cursed Halo Again". dedicated content lists every campaign and mission the server can host, and dedicated check says which mission the line was found to be.
  • Players find the server in the Server Browser, or join it by address, as they join a co-op lobby, and need the game whose campaign it plays. See campaign servers in the player guide.
  • A campaign server takes up to 16 players: a higher max_players, also from [defaults], stops dedicated check and the start. It can't also have a playlist, variant, map, game, base_map, odst or reach.
  • It starts the mission once min_players players are in its lobby and every connected player is in, or 30 seconds after the last one joined, then counts down start_countdown_seconds. Players can join a mission under way.
  • A won mission leads to the next, ODST's by its own story, and after the last the server starts again from the mission you set. A mission that ended any other way is played again.
  • A mission loads for every player together, and load_timeout removes nobody while it does. A server has no screen of its own, so when every player's game goes out of step with the server's at once, the server checks one player's game and takes it; trust_player_games = false turns that off.
  • Co-op plays lockstep by default (see coop_network), players vote to skip cinematics, and co-op games report no stats. Checkpoints stay in the server's memory, and restarting the server starts the mission you set afresh.
  • The remote console can't choose a campaign server's mission: see co-op servers' console.

Modifiers, skulls and sprint

A campaign server's modifiers set what the Campaign page's Modifiers do, on every game's campaign:

dedicated.toml
campaign = { mission = "Sierra 117", difficulty = "heroic", modifiers = { health_percent = 150, skulls = 513, sprint = true, sprint_stamina_seconds = 10 } }
SettingMeaning
health_percent, damage_percentEnemy health and damage, 25 to 1000 in steps of 25; 100 is the game's own.
health_per_player_percent, damage_per_player_percentHow much they grow per extra player, 0 to 100 in steps of 5.
skullsThe skulls that are on, as one number: add up the values of the skulls you want from the table below. 513 is Iron (1) and Assassin (512). None when left out.
scoringCampaign scoring: "off" (the default), "team" or "free_for_all".
sprinttrue: every player sprints by holding Sprint while running forward. Off when left out.
sprint_speed_percentSprint speed, 110 to 200 percent in steps of 10; 150 when left out.
sprint_stamina_secondsHow long a full meter lasts, up to 30 seconds, or 0 for unlimited; 5 when left out.
third_persontrue: every player sees their character in third person.
players_choose_cameratrue: each player chooses first or third person with their Switch camera key.
disable_friendly_firetrue: players can't hurt each other. friendly_fire = false on the server does the same.
Gold skullValueSilver skullValue
Iron1Assassin512
Black Eye2Blind1024
Tough Luck4Cowbell2048
Catch8Grunt Birthday Party4096
Fog16IWHBYD8192
Famine32
Thunderstorm64
Tilt128
Mythic256

These are Halo 3's and ODST's skulls. On another game's missions, only the skulls that game plays stay on.

Skipping cinematics

A server has no host player to skip a cinematic, so its players vote: each presses skip, and the cinematic is skipped once enough of them have. campaign_skip_vote_percent, in [defaults] or a [[server]], is the share needed, from 1 to 100 and 33 unless set, rounded up to a whole player:

dedicated.toml
[defaults]
campaign_skip_vote_percent = 50   # half the players; 100 takes every player
  • At 33, one vote of 3 players is enough, two of 4, and six of 16.
  • Players who left or haven't spawned don't hold the vote up.
  • It applies at once, on campaign, ODST and Reach co-op servers and to a playlist's co-op entries. A co-op host has the same choice in their lobby.

Campaign files

Besides campaign.map, a campaign server needs each mission's map file and its information. Every game's campaign plays through Halo 3's campaign files, so every campaign server needs campaign in --maps, and another game's campaign that game's files beside it:

Campaign--maps
Halo 3campaign
Halo: CEcampaign,halo1-campaign
Halo 2campaign,halo2-campaign
Halo 3: ODSTcampaign,odst
Halo: Reachreach-campaign,campaign
Shell
project-reclaimer dedicated init . --from "your game's folder" --maps campaign,halo1-campaign
  • halo1-campaign and halo2-campaign copy those games' missions with their multiplayer maps; halo1 and halo2 alone copy only the multiplayer maps, and a server made that way says Halo: Combat Evolved's campaign is not installed (init --maps halo1-campaign). See what the server folder needs.
  • --maps campaign copies every Halo 3 campaign mission, about 4 GB, with Guardian. Name single missions by file name instead, such as --maps 010_jungle,020_base, or add multiplayer maps, as in --maps "Guardian,Valhalla,campaign".
  • Running it on a server folder you already have adds the missing files and keeps your dedicated.toml, playlists and bans: existing files are never replaced.
  • A server goes on only to missions it has, so copy every mission for a server that plays through the whole campaign.
  • For Docker, run it on a PC with the game and upload the folder, as in the quick start.

Halo 3: ODST

A dedicated server can host Halo 3: ODST's campaign or Firefight in co-op, with no player as host, for up to 16 players. It's native to the Reclaimer Engine, the same engine as Halo 3's games. Players who have ODST installed in MCC find it in the Server Browser and join it as any other server; players without it see NEEDS ODST on it and are told how to get it. Give a [[server]] an odst setup instead of a playlist, variant, map and game, or campaign. (campaign = { campaign = "odst", … } hosts ODST's campaign too, with the players' own characters as on every game's campaign: see Campaign servers.)

dedicated.toml
[[server]]
name = "ODST Firefight"
port = 49179
odst = { mode = "firefight", mission = 5000, insertion = 7, variant = "odst_ff_classic", difficulty = "heroic" }

That server plays Firefight on Crater (Night). For a campaign mission instead, such as Tayari Plaza from its start:

dedicated.toml
odst = { mission = "Tayari Plaza", insertion = 0, difficulty = "normal" }
SettingMeaning
mode"firefight" for Firefight. Left out, the server plays the campaign.
missionRequired. A campaign mission by its title, its file's name or its number, such as "Tayari Plaza", "sc100" or 6100; for Firefight, the number its map is listed with below.
insertionIn a campaign, where the mission starts: 0, the default, is its start. For Firefight, the map's own, as listed below.
variantFirefight's game type, by its file's name: "odst_ff_standard_1set" when left out, "odst_ff_classic", "odst_ff_drone_wars_1round", "odst_ff_fiestafight_1set", "odst_ff_floodfight", "odst_ff_gruntpocalypse_1round", "odst_ff_robocalypse_1round", "odst_ff_rocketfight_1set" or "odst_ff_sniperfight_1set". It's the file in halo3odst/game_variants.
difficulty"easy", "normal" (the default), "heroic" or "legendary".
modifiersA campaign's modifiers, written as on a Halo 3 campaign server. Firefight takes only sprint and friendly fire. See skulls, sprint and story characters.
story_charactersCampaign only. On by default: everyone plays as the mission's own characters, the Rookie in the city and Buck, Dutch, Mickey or Romeo in their flashbacks. false: each player plays the trooper they chose in Customize.
optionsFirefight only. The game's settings over its game type's. See Firefight options.
customization, no_vanilla_charactersWith the players' own troopers, and in Firefight: character mods whose characters players may play instead, and whether nobody plays their trooper.
mod_mapA mod's ODST map played instead, by its cache's path, as a game hosted from the menus plays one.
Campaign missionmission: number, fileFirefight mapmission, insertion
Prepare to Drop4100, c100Crater6100, 4
Mombasa Streets5000, h100Crater (Night)5000, 7
Tayari Plaza6100, sc100Lost Platoon6110, 4
Uplift Reserve6110, sc110Rally Point6120, 5
Kizingo Boulevard6120, sc120Rally (Night)5000, 8
ONI Alpha Site6130, sc130Security Zone6130, 4
NMPD HQ6140, sc140Alpha Site6130, 5
Kikowani Station6150, sc150Windward6140, 5
Data Hive5200, l200Chasm Ten5200, 6
Coastal Highway5300, l300Last Exit5300, 7
Epilogue4200, c200

Skulls, sprint and story characters

An ODST campaign server takes ODST's fourteen skulls and sprint, written as on a Halo 3 campaign server: ODST's skulls are Halo 3's, with the same values (see modifiers, skulls and sprint).

dedicated.toml
odst = { mission = 6100, difficulty = "legendary", story_characters = false, modifiers = { skulls = 33, sprint = true } }
  • That server plays Tayari Plaza on Legendary with Iron (1) and Famine (32), every player sprints by holding Sprint while running forward, and players play the troopers they chose.
  • Firefight takes no modifiers but sprint, such as modifiers = { sprint = true, sprint_speed_percent = 150, sprint_stamina_seconds = 5 }, and friendly fire. Its skulls are options.

Firefight options

A Firefight server's options change its game over its game type's, as the Firefight page's options do. Quote each option's name, since it holds a dot:

dedicated.toml
odst = { mode = "firefight", mission = 6100, insertion = 4, options = { "firefight.team_lives" = 3, "firefight.minutes" = 30, "skulls.famine" = 1, "bonus_skulls.iron" = 1 } }
OptionMeaning
"firefight.team_lives"The lives the team starts with, up to 25, or -1 for unlimited.
"firefight.max_lives"The most lives the team may hold, 1 to 50.
"firefight.minutes"The time limit in minutes, up to 120; 0 for none.
"firefight.camera"0 first person only, the default; 1 players choose; 2 third person only.
"skulls.skull"1 turns the skull on for the whole game, 0 off.
"round_1_skulls.skull" to "round_3_skulls.skull"On in that round of every set.
"set_1_skulls.skull" to "set_3_skulls.skull"On through that set.
"later_set_skulls.skull"On through the fourth set and every one after.
"bonus_skulls.skull"On in every bonus round.
"player.trait"Every player's trait over the game type's, such as "player.shields" or "player.speed": the number of its choice in the page's list, counting from 0 for Unchanged.

Skulls are named in lower case with _ for spaces: iron, black_eye, tough_luck, catch, fog, famine, thunderstorm, tilt, mythic, assassin, blind, cowbell, grunt_birthday_party and iwhbyd. An option left out keeps the game type's own, and an option or value the server doesn't know stops dedicated check and the start.

ODST's files

Besides ODST's own files, an ODST server needs Halo 3's campaign list and two of its missions, because it hosts its session through Halo 3's co-op lobby. Copy them together from your own installation:

Shell
project-reclaimer dedicated init . --from "your game's folder" --maps "odst,005_intro,010_jungle"
  • It copies ODST's engine, its maps and its Firefight game types, about 3.5 GB, with Arrival, Sierra 117, Guardian and Halo 3's campaign list. --maps odst on its own isn't enough: dedicated check then stops at halo3/maps/info/halo3.campaign. --maps "odst,campaign" also works, with every Halo 3 mission. A server plays no sound or movies, so it needs neither ODST's sound banks nor its videos.
  • Running it on a server folder you already have adds the missing files and keeps your dedicated.toml, playlists and bans.
  • Without ODST's files, dedicated check and the start say This needs Halo 3: ODST, which isn't installed….
  • For Docker, run it on a PC with the game and upload the folder, as in the quick start. No environment variable sets odst: set it in dedicated.toml.

How an ODST server plays

  • The server waits in its lobby until min_players players are in, counts down and starts the game.
  • Players can join a game under way. Joiners need nothing more than ODST installed: the join names the mission, or the Firefight map and game type.
  • A won mission leads where ODST's story goes, as from the menus: after a flashback mission, back to Mombasa Streets at the point that mission returns to, with the squad's progress in the city carried along; after the city, Data Hive, Coastal Highway and the Epilogue. A mission that ended otherwise, and Firefight, are played again. In a playlist, the playlist's next game follows.
  • It holds at most 16 players, split-screen players included: a higher max_players, also from [defaults], stops dedicated check and the start.
  • Co-op plays lockstep by default: see networking for coop_network. Cinematics are skipped by vote. No stats are reported.
  • Passwords, text and voice chat, kicks, bans, mutes, votes to kick and end the game, and friendly_fire work as on Halo 3's servers. With trust_player_games on, the default, a server whose game drifts out of step with every player's takes one player's game.
  • To play something else, change odst in dedicated.toml: the server restarts with it once it has no players (see changing settings while servers run).

Halo: Reach, Combat Evolved and Halo 2

A server can play Halo: Reach's, Halo: Combat Evolved's and Halo 2's multiplayer maps beside Halo 3's, in one playlist, and Forge on any of them. They're new in 0.10 and early.

Their files

Copy each game's maps into the server's game folder from a PC with the game, as for ODST:

Shell
project-reclaimer dedicated init . --from "your game's folder" --maps "Guardian,Valhalla,reach,halo1,halo2"
  • reach copies Reach's multiplayer and Firefight maps with its engine and shared files, and the two Reach missions Forge's Reach objects need, when they're installed. Since Reach's maps offer Halo 3's objects in Forge, it also copies every Halo 3 multiplayer map, unless you name some of Halo 3's maps beside it (--maps sandbox,reach): then those and Guardian alone. reach-campaign copies Reach's missions too, for a Reach co-op server.
  • halo1 and halo2 copy Combat Evolved's and Halo 2's multiplayer maps with each game's engine, shared maps, sounds and game types. halo1-campaign and halo2-campaign copy their missions as well, for a campaign server.
  • odst, halo1 and halo2 bring Guardian with them, which their maps are built on, and no other Halo 3 map: name Halo 3's maps beside them, or leave --maps out for all of them, when their Forge games should offer Halo 3's objects. dedicated content lists what the server has.
  • A server offers and plays only the objects of the maps in its game folder. dedicated check and the start say what a server's games would miss: odst_objects, reach_objects, halo1_objects or halo2_objects turned on without that game in the folder, Halo 3 multiplayer maps missing for Forge, and the maps a saved map takes objects from. A saved map whose objects no map of the folder has is refused when its turn comes, with the objects' names, on Reach's maps as on Halo 3's. For a server folder made before 0.10.6 with --maps reach, run dedicated init again to add Halo 3's maps.

Every game in one playlist

playlists/every-halo.playlist.json
{ "version": 2, "name": "Every Halo", "vote_seconds": 20, "games": [
  { "map": "Guardian", "game": "Slayer" },
  { "map": "Sword Base", "game": "headhunter_054" },
  { "map": "Blood Gulch", "game": "ctf" },
  { "map": "halo2_lockout", "game": "slayer" },
  { "map": "Forge World", "game": "Forge" } ] }
  • Maps go by title, file name or ID, Halo 3's first, then Reach's, Combat Evolved's and Halo 2's. Where a name is also one of Halo 3's, use the other game's file name: Halo 2's Lockout is halo2_lockout, as plain Lockout is Halo 3's Blackout by its file name.
  • Game types: Reach's maps play Halo 3's game types, or Reach's own game variants by file name, such as headhunter_054. Combat Evolved's and Halo 2's maps play only their own game types: game names one of the variants MCC installs for that game, by name, file or title. A Halo 3 game type there plays that game's nearest one, and options and rules on those maps are refused.
  • One session: the server plays them one after another with its players connected. Each player's game makes the next map from their own copy of the game.
  • Who can join: a player without a game the playlist plays is refused as they join, with that game's name, and the Server Browser marks the server NEEDS REACH, NEEDS HALO: CE or NEEDS HALO 2.
  • Their mods: Reach's, Combat Evolved's and Halo 2's mods go in the content folder's Mods, as Halo 3's do, and a playlist names their maps by title. Players without one get it as they join.
  • Forge: each game's maps have their own objects. reach_objects, halo1_objects and halo2_objects add those games' objects to Halo 3's maps, and the server's games then need that game.
  • Characters: a game mode that names Reach's Spartans or Elites brings them into its games, which then need Reach. other_game_characters = false or reach_characters = false, in [defaults] or a [[server]], leaves them out.

Reach co-op and Firefight

A server's reach hosts one of Halo: Reach's missions, or Firefight on one of its Firefight maps, in co-op for up to 16 players, alone as campaign and odst are:

dedicated.toml
[[server]]
name = "Reach Co-op"
port = 49180
reach = { map = "m10", campaign = true }
# Firefight: reach = { map = "ff20_courtyard", campaign = true, firefight = "firefight_new" }
  • map is the mission's or Firefight map's file name or title, such as "m10" or "Winter Contingency", or a mod's mission or Firefight map by its title, and firefight one of the map's own variants: firefight_new, firefight_classic, firefight_gen, firefight_versus, firefight_score_attack, firefight_rocketfight or firefight_gruntpocalypse.
  • The server needs Reach's missions and Halo 3's Sierra 117: --maps reach-campaign,campaign. Without Reach or the map, dedicated check says so.
  • A won mission leads to Reach's next (a mod's next, for a mod's mission), and after the last, the first again. Firefight is played again.
  • reach plays missions on Normal, as Noble Six. For another difficulty, a start, modifiers or the players' own characters, host the campaign with campaign = { campaign = "reach", mission = "m10", difficulty = "legendary" } instead: see Campaign servers.

Mods

A server can host mod maps, and saved maps with Forge objects from mod maps. A player who lacks a mod gets it as they join, in one of two ways:

  • Through Steam Workshop. A mod from the Workshop downloads through Steam on the player's PC, and is checked against your server's copy. The game asks the player first, and approving subscribes their Steam account to the item. This works with nothing turned on: your server needs no Steam, account or key.
  • From your server. With share_mods on, players can download what they lack from your server itself, over the same encrypted port they play on. The game asks each player first, for each download. That covers mods that aren't on the Workshop, and a Workshop download that fails.

There's no web host, file mirror or Workshop upload to set up.

1. Add the mods

Copy each mod's folder into content/Mods, one folder per mod, or let the server download Workshop mods by ID. Every server on the machine sees them.

A Workshop mod

Copy the item's folder as it is from steamapps/workshop/content/976730 in your Steam library. It holds ModInfo.json, multiplayer, maps and sometimes the mod's own shared.map, sound banks and movies, which players get with its maps. Keep its ModInfo.json: it names the Workshop item players download. You can rename the folder.

A single map

A folder with the .map and its matching .mapinfo, beside it or in an info subfolder, plus any shared.map or campaign.map the mod comes with. A multiplayer .map without a .mapinfo works too: it's listed under its file name, blam_mountain.map as “Blam Mountain”.

content/Mods
content/Mods/
├─ 2981234567/               a Workshop item's folder, copied as it is
│  ├─ ModInfo.json
│  ├─ multiplayer/arena.json
│  ├─ maps/arena.map
│  ├─ halo3/maps/shared.map the mod's own shared.map, if it has one
│  ├─ halo3/fmod/pc/        the mod's own sound banks, if it has any
│  └─ halo3/bink/           the mod's own movies, if it has any
└─ canyon/                   a single map
   ├─ canyon.map
   └─ canyon.mapinfo
  • Folder names don't matter: a mod is known by its files. Every server with the same files offers the same mod, so a player who got it from one server already has it for yours.
  • Players only ever get what a game needs from a mod: its maps and their metadata, images, sound banks and movies, a shared.sounds file beside maps that hold their own sounds, and a Halo: CE mod's own sounds.map. Programs, scripts and any other files in the folder are never sent. A server draws nothing and plays no sound, so it needs no extra files for movies or banks, but it passes them on.
  • A Workshop map is played with the map ID its author set in the mod tools. One that has none, as many Workshop maps do, gets an ID made from its file name, the same on every PC.
  • A mod with its own shared.map, beside its map or in its package's halo3/maps folder, has its maps read from that file, as the mod was built.
  • A Workshop item copied somewhere else, or renamed, is still known by its ModInfo.json. Only an unusual package without that information needs a reclaimer-workshop.json beside its ModInfo.json to name its item, such as {"item": 2899741683, "folder": ""}, where folder is the package's folder inside the item (empty for the item itself).
  • To keep a mod in content/Mods without using it, list its folder in content/disabled-mods.json, such as {"packages": ["Mods/canyon"]}, and restart the servers. It's the file the game's Settings → Mods switches write in a player's folder.

2. Choose what the server plays

  • A mod map with a game type: name the map in map, with a game, like a base map: by its Workshop reference, "workshop:item ID/map file name", or by its name. Or put mod maps in a playlist.
  • A mod map with your own rules: on a PC with the game and the mod, set the game up in a lobby and save it as a variant. Copy the file from your player folder's Game Modes into content/Game Modes, and name it in the server's variant, with the mod in content/Mods. If the server can't find the map that way, name it in map and the variant in game.
  • A saved map with objects from mod maps: copy it into content/Maps and name it in map or in a playlist, like any saved map. The server works out which mods its objects come from.
  • A Forge map made on a mod map: copy the saved map into content/Maps and the mod into content/Mods, and name the saved map in map or a playlist. Players who join merge the same objects into their own copy of the mod; the first game on a mod map takes a few seconds longer to prepare.
dedicated.toml
[[server]]
name = "Community Maps"
port = 49178
variant = "content/Game Modes/canyon-slayer.json"

[[server]]
name = "Arena CTF"
port = 49179
map = "workshop:2981234567/arena"
game = "Capture the Flag"

The session's listing names the mods of every game of a server's rotation from the start, so players get them once as they join, and every player's game gets the next map ready before it starts.

3. Share them

Workshop mods need nothing more: players download them through Steam, even with sharing off. They need Steam running and signed in to an account with MCC; the game asks them to start Steam if it isn't. To send mods from your server too, for mods that aren't on the Workshop and for players whose Workshop download fails, turn on sharing. It's off until you do. Set it in [defaults] for every server, or in one [[server]]:

dedicated.toml
[defaults]
share_mods = true   # players who lack a mod download it from the server
share_rate = 20     # Mbit/s for all of a server's downloads together; 0 is no limit

The environment variables RECLAIMER_DEDICATED_SHARE_MODS and RECLAIMER_DEDICATED_SHARE_RATE set the same two defaults, for example in Docker's .env. A mod that isn't on the Workshop and isn't shared turns away every player who lacks it, so copy Workshop mods with their ModInfo.json, or share.

Workshop downloads

A server can download Workshop mods itself, by item ID, so there's nothing to copy from a game PC. Before the servers start, it downloads every item they name: in map, base_map or a playlist as workshop:item ID/map file name, and the items listed under [workshop]. The ID is the number after id= in the item's Workshop address. List items under [workshop] when you know only their IDs:

dedicated.toml
[workshop]
items = [2981234567]

dedicated mods downloads the items and prints the reference of every mod map the server has, to paste into map or a playlist. dedicated check and dedicated download missing items too.

Shell
project-reclaimer dedicated mods
Output
[workshop] 2981234567: acquiring through Steam Workshop
workshop:2981234567/arena  Arena

The server downloads through Steam in one of two ways:

The Steam app on the same machine

With no steamcmd set, the server asks the Steam app on its machine, which must be running and signed in to an account that owns MCC. It needs Steam's library: with none, it says No Steam runtime was found: install Steam, or put libsteam_api beside the game. On a server, SteamCMD is usually simpler.

SteamCMD

On a machine without the Steam app, install Valve's SteamCMD and sign in to it once yourself with an account that owns MCC, entering the Steam Guard code if asked. Then set steamcmd and username.

Shell, once
/opt/steamcmd/steamcmd.sh +login your_steam_account +quit
dedicated.toml
[workshop]
items = [2981234567]
steamcmd = "/opt/steamcmd/steamcmd.sh"   # on Windows, with single quotes: 'C:\steamcmd\steamcmd.exe'
username = "your_steam_account"          # the account name only, never a password
SettingDefaultMeaning
items[]Workshop item IDs to download, up to 64 in all with those the servers name. A collection isn't an item: list each item's ID.
steamcmdnoneSteamCMD's program. Without it, the Steam app on this machine downloads.
username""The Steam account SteamCMD is signed in with, one that owns MCC. Empty uses the account it has cached, else anonymous, which Steam refuses for MCC's Workshop items.
provisionernoneThe shared folder of a separate SteamCMD service, so Steam's login never reaches the servers. It can't be combined with steamcmd or username. See Workshop downloads in Docker.
update_check_minutes60Minutes between looks for newer versions of the installed items, at least 5; 0 never looks. See keeping Workshop mods up to date.
  • Project Reclaimer uses SteamCMD's saved sign-in and never asks for, sees or stores your Steam password. When the sign-in expires, sign in to SteamCMD again the same way.
  • Each item is installed in content/Mods/Workshop/item ID, data files only: maps, their metadata, pictures, sound banks, movies and variants. Nothing from an item is run. Later starts use it as it is.
  • A download that fails stops the start and names the item. SteamCMD's own log is in data/workshop-cache.
  • Players still get the mods as before: through the Workshop, or from your server with share_mods.

A SteamCMD download that fails says why:

The message saysWhat to do
“signing in as account failed”SteamCMD has no saved sign-in for that account, or it expired. Run the command the message shows, then start the servers again.
“Steam gave account no key for MCC's Workshop content”The account doesn't own MCC. Set username to an account that does, and sign in to SteamCMD with it once.
“Steam gives anonymous logins no access”username is empty. Set it to an account that owns MCC.
Another reason in bracketsSteamCMD's own answer, such as Timeout. Try again later.

Keeping Workshop mods up to date

A player's Steam keeps their copy of a Workshop mod at its newest version, so a server with an older copy has different files. Servers keep the Workshop items they install current:

  • When the servers start, and then every update_check_minutes (60 by default) under [workshop], they ask Steam's public Workshop details for each item's newest version. This needs no Steam sign-in.
  • A newer version downloads the same way as the first install, while the games go on.
  • It replaces the installed item once no server that uses the mod is starting or playing a game; players may wait in its lobby meanwhile. Those servers keep running, offer joiners the new version and make the next game's map from the new files.
  • dedicated check lists each item's installed version and whether Steam has a newer one.
  • Mods put in content/Mods by hand are never updated. To have the servers manage one, list its Workshop ID under [workshop] items and name its maps as workshop:item ID/map file name.
dedicated.toml
[workshop]
items = [2981234567]
update_check_minutes = 60   # 0: never look for updates

Players whose copy differs from your server's get a way forward in REQUIRED MODS as they join: UPDATE & JOIN when your version is newer, and REPLACE & JOIN for a copy they downloaded from another server. When their Workshop copy is newer than yours, only updating the server helps: Steam installs only a mod's newest version.

Workshop downloads in Docker

The Docker image has no Steam, so its servers can't download Workshop items by themselves. A separate SteamCMD service that runs beside them, signed in by you in its own terminal so the servers never see your Steam sign-in, isn't in the downloads yet (the provisioner setting is its side of this). Until then, copy the mods' folders into server/content/Mods and name their maps by name in map or a playlist: a workshop: reference makes the server try to download the item, which fails without Steam.

Mods copied in by hand aren't updated by the servers. When a mod's author publishes an update, players' Steam installs it, and they can't join until your copy matches: stop the servers that use the mod, copy the new version over the old folder, and start them again.

Objects from mods come packed

A saved map that uses a few objects from a big mod doesn't make players download the whole mod. While a server shares mods, it packs just the objects its current game uses from each one, usually a few MB where the mod is hundreds, and players download that instead. Packs are listed as the mod's name followed by "(objects)".

  • Only the game being played comes packed. A playlist's listing still names the full mods of its other games.
  • The server checks that a pack gives exactly the same objects as the mod before it offers it. If it doesn't, players need the whole mod.
  • Packs come only from the server, so they need share_mods. Without it, players download the whole mods through the Workshop instead.

Character mods

Mods can add playable characters: a mod with a customization.json beside its maps brings characters with their own body, armor, colors and physics, who play with every weapon, vehicle and animation of the map they're in. A server adds the characters of the character mods you name to its multiplayer games. Put the mods in content/Mods, or have the server download them by ID, and name them by the names Customize shows for them, with or without the version ("Armor Pack" also names Armor Pack v2), or by their folders, up to 122 of them. Set them in [defaults] for every server, or in one [[server]]:

dedicated.toml
[defaults]
customization = ["Armor Pack", "Sci-Fi Heroes"]
require_customization = false   # true: players must take them to join
no_vanilla_characters = false   # true: every player plays one of their characters
  • Sharing: with share_mods on, players who don't have a mod download its characters from the server as a characters pack, as they do other mods. They can turn a mod down as they join, and then see its characters as Halo 3's own Spartans and Elites, unless require_customization is on. With share_mods off, players who have a mod see its characters and those who don't see Halo 3's own; with require_customization on, only players who have the mods can join.
  • Joining: the join window lists the server's character mods as USE, NOT USE or REQUIRED, and can remember a player's choice for that server. Players whose characters someone turned down appear to them as Spartans and Elites; the server still decides every hit on their real character.
  • no_vanilla_characters: a player who would play Halo 3's own character plays the first of the server's characters in their own list instead.
  • Every multiplayer map: a server with character mods needs all 27 of Halo 3's multiplayer maps in game/halo3/maps, about 5.5 GB: dedicated init <folder> --from "your game's folder" without --maps copies them.
  • Names: dedicated check lists each server's character mods. A name that matches none stops dedicated check and the start, with the name you most likely meant, or the folders it looked in: content/Mods, and content/Mods/Downloaded/packs/characters for character mods the server has only as packs.
  • Every game of a rotation: the server makes each game's map and its pack before the game starts, so the countdown can wait for it.
  • Campaign: a campaign server names its character mods in its setup, such as campaign = { mission = "Sierra 117", difficulty = "heroic", custom_characters = true, customization = ["Armor Pack"] }, on every game's campaign. See the players' own characters.
  • Docker: RECLAIMER_DEDICATED_CUSTOMIZATION=Armor Pack,Sci-Fi Heroes in .env names them, separated by commas. It replaces [defaults] customization, and a server's own customization still wins. RECLAIMER_DEDICATED_REQUIRE_CUSTOMIZATION and RECLAIMER_DEDICATED_NO_VANILLA_CHARACTERS set the other two.
  • Changing them restarts the server once it has no players; see changing settings while servers run.
  • How many: a game takes characters from up to 128 character packs, so every character in it can come from a different mod.
  • Size: a game with many character mods can grow too big for a join to carry. The server's log then says so, and players are refused, told the host needs to use fewer character mods or mod maps' objects.
  • Making one: each release has the customization editor for every system: reclaimer-customization-editor-version.exe on Windows, with -macos-aarch64.zip and -linux-arch.tar.gz for macOS and Linux. Open a mod's folder in it and pick each character's armor, colors and camera bones, and it writes the mod's customization.json.
  • Third-person characters play in first person, like every other character, unless the server's camera lets players choose or puts everyone in third person.

What players see

  • Your server's listing names its mods. The Server Browser tags it with how many: 1 mod when a player has them all, 1 mod when they can download what they lack, through the Workshop or from your server, and 1 mod when a mod has no download source.
  • Joining opens REQUIRED MODS with the exact size to download. It checks the mods your server needs first, so a player with a big library isn't kept waiting, and every download asks the player's permission, within the disk space they allow. Once the files are in and checked, the player joins by themselves, without restarting.
  • The Server Browser lists every mod your server requires, and every player's name, on the server's row and card.
  • A download never replaces a different map with the same file name. When you host another version of a Workshop mod than a player has, REQUIRED MODS compares the two: UPDATE & JOIN has Steam update their copy when yours is newer, REPLACE & JOIN swaps a copy they downloaded from another server for yours, and when theirs is newer it says so with both dates, since only your server can update. Another mod's map with the same file name reads "Map name clashes with mod on this PC" until they delete it in Settings → Mods.

See Mods in the player guide for the rest.

Bandwidth and safety

  • share_rate caps what all of one server's downloads send together, so the games on the machine stay smooth. At the default 20 Mbit/s, a 150 MB mod takes about a minute to reach one player; players downloading at the same time share the limit.
  • Maps travel in checked chunks of about 1 MB. A player who joins from the Server Browser takes them from your server and up to three other listed servers that share the same mod, all at once, so the more servers share a mod, the faster everyone gets it.
  • A server sends up to four downloads at once, at most two to one address. A player whose download stalls for 30 seconds gives up their place.
  • Downloads don't take a player slot, but your bans apply to them.
  • A server only sends the files of the mods its current games use, found by their fingerprint, never by a path a player asks for. Nothing else in the server folder is reachable.
  • Players check every chunk and file against its SHA-256 fingerprint as it arrives. A server that sends a damaged chunk is dropped and the chunk comes from another, and a cut-off download resumes with the chunks it already has.

Limits

  • A server's games can use up to 16 mods, each with up to 8 maps (a campaign mod 32) and 512 files. An objects pack counts as one mod and holds at most 256 MB.
  • A sound bank or a movie can be up to 2 GB and an image 8 MB. A map whose files don't fit is left out of the mod whole.
  • One game session can use at most 23 mod maps. Installed mods don't count until they're played. Rarely, two mod maps whose map IDs clash can't both be used in one session.
  • A playlist can use up to 23 different mod maps; see mod maps in a playlist.

Admins, roles, kicks and bans

Players are identified by their player ID: 64 hexadecimal characters. Players find theirs in the game under Settings → Online services → Your player ID, which has a Copy button. That's their community ID. A server also knows each player by the network key their connection proves, which is what dedicated status, players and the console's events show. In admins, vote_kick_immune and bans.json, either one names the player.

List admins by player ID in admins, for every server or for one; servers take up a change as soon as you save the file (see changing settings while servers run). You can also add and remove admins while the servers run from the remote console: admin add <player | player ID> makes a player an admin on every server sharing the ban list at once, and admin remove takes it back. The console keeps its admins in the shared ban list ("admins" in bans.json), and every server on the machine follows within seconds. In a game, an admin can:

  • Tap Tab to pin the scoreboard and use Kick or Ban on a player's row. Ban asks for a second click.
  • Open a player's card in the lobby or the game menu and use MOVE TO. See team changes.
  • Type in chat: /kick <name> [reason] or /ban <name> [reason]. /banip does the same as /ban, since every ban covers the player's address too. /help (or /?) lists every command and says whether the server takes votes and whether you're one of its admins.

Admins can't be vote-kicked, and neither can players listed under vote_kick_immune, who have no admin rights. Admins can't remove other admins. A kick or ban of a connected player covers three things at once: their player ID, their IP address and, where available, their device, so a new profile or another address doesn't get around it. Windows PCs present a device fingerprint; macOS and Linux have none.

  • Kicks: the player sees why on their main menu and can't rejoin for 10 minutes after a first kick, then 30, 60 and 120 minutes after later ones, staying at 120. The count starts again after 24 hours without a kick, or when the server restarts. Kicks are kept only while the server runs, never in the ban list. kick_blocks = ["10m", "30m", "60m", "120m"], in [defaults] or a [[server]], sets the steps, up to 8 rising ones; [] keeps nobody out. A kick by vote or by the anti-cheat counts like an admin's. The remote console's pardon lets a kicked player rejoin that server now, and their next kick there starts at 10 minutes again. Bans need unban.
  • Bans go on the shared ban list and apply to every server. A ban's player ID, address and device are linked: unban with any one of them, or with the player's name, lifts the whole ban.
  • Players who share a PC share its device bans, and players behind one address share its address bans. Keep that in mind for shared, family and resold PCs.

Manage bans from the command line, from the remote console or by editing bans.json. Changes apply to running servers within seconds. --for bans for a time (30m, 12h, 7d, 2w) instead of for good; a banned player reads how long is left. dedicated unban takes a player ID, a device fingerprint, an address or a name, and lifts the entries linked to it too:

Shell
project-reclaimer dedicated ban 0123…cdef --reason "Cheating"
project-reclaimer dedicated ban 89ab…4567 --for 7d --reason "Team killing"
project-reclaimer dedicated ban 203.0.113.4
project-reclaimer dedicated ban 198.51.100.0/24
project-reclaimer dedicated unban 203.0.113.4
project-reclaimer dedicated bans
bans.json
{
  "players": [{ "id": "0123…cdef", "name": "Bravo", "reason": "Cheating" }],
  "ips": [{ "ip": "198.51.100.0/24", "reason": "Spam" }]
}

Only id or ip is required; a timed ban adds "expires" (Unix seconds) and stops applying then. A ban of a connected player also adds a devices entry when the device is known, and gives its entries the same "group", which links them for unban. Entries without a group stay independent. VPN blocking, on by default, stops a banned player from simply coming back through a VPN.

Roles

Every player holds at most one role on a server, and the role says what they may do there. Four are standard, and a configuration adds up to twelve of its own:

RoleWhat it may doWho holds it
HostEverything.The player hosting a game from the game. A dedicated server has none.
AdminEverything.admins, and the console's admin add.
ModKick, ban for up to moderator_ban_minutes (60 unless set), mute, cancel votes, read reports, and end the round or the game and shuffle the teams without a vote. Never vote-kicked.moderators, at the top of the file or in a [[server]].
VIPNever vote-kicked, and ahead in the join queue.A [roles.vip]'s players, or the console's role add.
dedicated.toml
moderators = ["<player ID>"]

[defaults]
moderator_ban_minutes = 60

[roles.dj]            # a role of your own
title = "DJ"          # beside the name, up to 16 characters
rank = 12             # 1 to 39; 15 when left out
icon = "vip"          # host, admin, mod, vip or none
can = ["say", "voice.music"]
players = ["<player ID>"]

[roles.mod]           # the standard roles change the same way
can = ["preset:mod", "-game.end", "-teams.shuffle"]   # a Mod who ends games by vote only

[roles.everyone]      # what every player may do
can = ["vote.call.kick", "vote.call.endgame"]
  • can takes permission names, wildcards (mute.*), the presets preset:host, preset:admin, preset:mod, preset:vip and preset:everyone, removals (-ban.perm) and ban.temp:minutes for the longest ban, read in order. Among the permissions: kick, ban.temp, ban.perm, unban, mute.text, mute.voice, vote.cancel, vote.pass, vote.exempt, map.change, game.end, teams.move, teams.shuffle, joins.gate, say, see.reports, see.addresses, bypass.queue, roles.grant, password.set, voice.music, forge.edit, forge.save and bots.run.
  • Two groups add permissions without a rank: [roles.members], for the player IDs it lists, and [roles.everyone], by default the four vote calls. votes = false takes the vote calls away.
  • Three rules hold everywhere: nobody acts on a player of an equal or higher rank; a role is given only by someone whose role holds roles.grant, below their own rank and within their own permissions; and only the Host or the console gives Host.
  • In chat, a player with a role types the console's commands as their role allows: /kick, /ban <player> [time] [reason], /mute, /say, /map, /nextmap, /endround, /endgame, /shuffle, /team, /role and the rest; /help lists what theirs allows. /forceendround, /forceendgame and /forceshuffle are other names for the three that skip a vote. Everyone reads who did it, by role: [Mod] Name ended the round.
  • /password <new> sets the join password from chat, /password off clears it and /password alone says whether one is set, for roles with password.set: Host and Admin. Only the caller reads the reply, and the log shows /password ****. It lasts until a restart or until the file's own value changes.
  • Nameplates: each role shows an icon at the end of its players' rows on your server: the Host's crown, and the Admin's, Mod's and VIP's own. A role of your own takes the icon of the standard role at or below its rank, unless its icon names another or "none". A player can hide their role's plate in Customize → Player → Nameplate; that changes what's shown, never what the role may do.
  • From the console: role add <player> <role> gives a role on every server sharing the ban list, and role remove takes it back. devs_as_vip = true gives VIP to Project Reclaimer's developers, as the stats service verifies them.
  • Roles and their holders change live, on a reload. A server's own [server.roles.name] changes a role for that server only.

Games hosted from the game

Players who host multiplayer or campaign games from a lobby moderate them the same way: Tab pins the scoreboard with KICK and BAN on each row, a player's details in the lobby have them too, and /kick and /ban work in chat. With votes on, other players get VOTE KICK. The host's bans are kept in host-bans.json in the host's player folder and apply whenever they host again; to lift one, remove its entries from that file. See how to play.

Chat logs

Each server keeps what its text chat carries in a file of its own, one per day: data/<server>/chat/2026-09-27.log. Times are UTC, like the server log's, so a report can be checked against the joins, kicks and votes around it. Each line names the channel, the sender and their full player ID, the one dedicated ban takes; [Server] lines are the server's own kicks, bans and votes.

chat/2026-09-27.log
14:03:12 [All] Alpha (0123…cdef): gg
14:03:20 [Team Red] Bravo (89ab…4567): push their base
14:05:41 [Server] Charlie was kicked by Alpha.

Set chat_log = false to keep none. Old files are never removed. Chat logs hold what players wrote along with their IDs: keep them only as long as you need them, and tell your players that the server keeps them.

Join queue and gates

A full server lines new players up instead of turning them away. A waiting player holds no connection or player slot, and is free meanwhile: other pages, a film, another game. Their game shows their place and joins by itself when it's called. The Server Browser shows such a server as FULL · N IN QUEUE or FULL · QUEUE OPEN.

SettingDefaultMeaning
queue_max7Players the line holds, 7 at most, on top of max_players.
vip_queue_max3Players the VIP line holds, 3 at most, for roles with bypass.queue: VIP and up.
vip_priority75The share of places, in percent, the VIP line takes while both lines wait: three VIPs, then one other player.
queue_starve_after600Seconds after which a waiting player takes the next place, whatever their line.
queue_max_wait3600Seconds after which a player no place opened for is let go; 0 is no limit.
joins"open""closed" keeps every new player out. "queue" has players a gate holds wait in the line instead of being told to try again.
join_gates[]The phases new players are held in: any of "vote", "countdown", "loading", "in_game" and "post_game".
  • Seats, not entries: a PC with split-screen players, or a party, waits as one entry and gets in when there's room for all of them. Nobody behind passes it meanwhile. A party bigger than the server, or than the line's room, is told at once.
  • A called place is kept for 30 seconds. A player who stops asking leaves the line after 20, and one address holds two places at most.
  • "in_game" holds new players for the end of the game being played, as an Infection server wants: they come in together between games and start the next one with everyone.
  • Players already in are never touched, and a player kept out reads why; their game asks again by itself.
  • Mods come first: a waiting player's game gets the server's mods while it waits.
  • All of these go in [defaults] or a [[server]] and apply at once. The remote console's joins shows who waits and changes the mode and gates live, and joins remove <place | player ID> takes a player out of the line.

Anti-cheat

Servers refuse the events only a host may send, and check that a shot's target lies near where the shooter aims. It's on by default, whether or not dedicated.toml mentions it.

ValueWhat the server does
"enforce"The default. Refuses such events, logs them and kicks the sender, with the usual kick cooldown: 10 minutes for a first kick, longer for repeats. It never bans anyone by itself.
"detect"Refuses and reports them, without kicking anyone.
"off"Nothing is checked.

Set it under [defaults] for every server, or in one [[server]] block. Changing it restarts the server once it has no players.

dedicated.toml
[defaults]
anti_cheat = "enforce"

[[server]]
name = "Custom Sandbox"
port = 49178
anti_cheat = "detect"   # log only, no kicks
  • Under "enforce", a shot whose target lies away from the shooter's aim is fired along the aim instead. One such shot can come from a player whose game showed something in another place for a moment, so it's reported, and the player kicked, only when it names a player or a vehicle and the same player sends several within a few seconds.
  • RECLAIMER_DEDICATED_ANTI_CHEAT sets the [defaults] value, for example in Docker's .env; a server's own setting wins.
  • dedicated check and the remote console's status show the setting. In JSON, status gives anti_cheat and anti_cheat_active, which is false while the setting is "off" or the game's playlist entry turns the anti-cheat off.
  • Each report goes in the server's log, such as anti-cheat: Bravo (player ID …) sent game data that a normal game never sends (R73); blocked, and to remote-console tools as a cheat event with the player's name and ID, whether they were kicked, and a short reference code. If you think a player was kicked wrongly, report it on Discord with that code and the server log.

Single games without it

For a map or game type with unusual physics or scripts that risks a wrong kick, turn the anti-cheat off for that game alone: turn off ANTI-CHEAT for the selected game in the playlist editor, or add "anti_cheat": false to its entry in the playlist file. The other games in the rotation stay protected. While such a game is played, status reads anti-cheat enforce (off for this game).

Playlist entry
{ "map": "Maps/my_arena.json", "game": "Game Modes/my_mode.json", "anti_cheat": false }

Games hosted from the game

Multiplayer games hosted from a lobby have the anti-cheat on by default too. Turn it off or on under Host Settings → Anti-cheat. On, it works as "enforce". See how to play.

VPN blocking

Dedicated servers refuse players who connect through a VPN, proxy or hosting provider, the usual way around a ban. It's on by default. Games hosted from the game don't block VPNs. A refused player reads:

Join error
This server doesn't allow players on a VPN, proxy or hosting provider. Turn off your VPN and join again.

Never refused:

  • admins, for every server or for that server;
  • players on this machine or on your own network, including private, link-local and carrier-grade NAT addresses, such as Tailscale's;
  • player IDs and addresses you allow.

To turn it off, set block_vpn = false under [defaults] for every server or in one [[server]] block, or RECLAIMER_DEDICATED_BLOCK_VPN=false in Docker's .env. The server restarts once it has no players.

The server's card in the Server Browser says Blocks VPNs when it does, and players can pick servers that block VPNs or allow them under Filters.

Letting players through

Some players connect from a hosting provider for good reasons, such as a cloud gaming PC. Allow them, check an address, or fetch the lists now:

Shell
project-reclaimer dedicated vpn                     # which servers block, each list's size and age, who is allowed
project-reclaimer dedicated vpn check 203.0.113.4   # refused? on which list? which network?
project-reclaimer dedicated vpn allow 0123…cdef Cloud PC
project-reclaimer dedicated vpn allow 198.51.100.0/24
project-reclaimer dedicated vpn revoke 0123…cdef
project-reclaimer dedicated vpn update
  • A refused player isn't connected, so take their player ID from the server log ([server] refused 0123…cdef from 203.0.113.4: VPN block, on …) or the remote console's refused event. The console also has vpn, vpnallow and vpnrevoke.
  • Allowances are kept in the shared ban list, so they apply to every server at once, without a restart:
bans.json
{
  "vpn_allowed": [{ "target": "0123…cdef", "note": "Cloud PC", "allowed_by": "host" }]
}

target is a player ID, an address or a range. Allow players by ID where you can: an address allowance lets in everyone who uses that address.

The lists

Each joining player's address is matched against public lists of VPN and datacenter networks: by default, X4BNet's VPN and datacenter lists, for IPv4 and IPv6, their lists of hosting networks, and a few hosting networks of the project's own. Those networks are looked up in iptoasn.com's table, to find the ranges each one announces. dedicated fetches the lists before the servers start when it has none, then every 12 hours, keeps a copy of each in data/vpn/ and writes the combined list data/vpn/ranges.txt. Addresses are matched on your machine: no player's address is sent anywhere. If a list can't be fetched, its last copy is used; a server that has never had one admits every address and says so in its log.

Your own lists replace the defaults, or add to them with "default":

dedicated.toml
[vpn]
lists = ["default", "https://lists.example/vpn.txt", "my-ranges.txt"]

A list has one address or CIDR range per line; # and ; start comments. A line may also name a hosting network by its number, such as AS64500, and every range it announces is refused. A download that isn't such a list, such as an error page, is ignored, keeping the list's last copy. RECLAIMER_DEDICATED_VPN_LISTS adds lists, separated by commas.

Refuse a network or range at once

Servers that block VPNs can refuse whole hosting networks, by their number (ASN), as well as address ranges. Write them into vpn-local.txt beside dedicated.toml, one per line. The servers apply it within a minute, without a restart:

vpn-local.txt
AS64500          # every range this network announces
203.0.113.0/24
2001:db8:100::/48

To name networks in the configuration instead, use asns under [vpn], or RECLAIMER_DEDICATED_VPN_ASNS in Docker's .env (AS64500, 64501):

dedicated.toml
[vpn]
lists = ["default", "https://lists.example/vpn.txt"]
asns = [64500, "AS64501"]
fail_closed = false  # true: no list yet refuses everyone but admins and allowed players
  • Which network is it? dedicated vpn check <IP> names the list and the network announcing an address. Matching happens on your machine: nothing is sent about players.
  • How fresh are the lists? dedicated vpn, and the remote console's vpn, show each list's size and age. A list whose copy is over a week old is reported as stale in the log, in dedicated check and in dedicated vpn.
  • No list yet: a server that has never had a list admits every address and logs NOT WORKING when it starts and every hour. With fail_closed = true under [vpn], or RECLAIMER_DEDICATED_VPN_FAIL_CLOSED=true, it refuses everyone but admins and allowed players instead, until the first list arrives; that turns everyone else away while the lists can't be fetched.
  • Why was someone refused? Each server's log names the list or network behind a refusal, at most once a minute per address, and sums up its refusals every hour:
server.log
[server] refused 0123…cdef from 203.0.113.4: VPN block, on AS64500 EXAMPLE-HOSTING · on [vpn] asns
[server] VPN block: refused 5 joins in the last hour: …

Remote console (RCON)

Moderation tools, Discord bots and web panels can manage your servers through a password-protected remote console: list players with their IDs, scores, health and shields, read the chat, joins and kills as they happen, kick, ban (also for a time), let a kicked player back early, add and remove admins, mute text and voice chat, send server lines to everyone or one player, end the round or the game, change the map, mode or next game, rename the server, set its join password and ping limit, let players through the VPN block, spread players over teams or move one to another team, run votes, reload the configuration, and restart or stop the server. It's off until you set a password in dedicated.toml:

dedicated.toml
[rcon]
password = "a long passphrase only your tools know"   # 8 to 128 characters
address = "127.0.0.1"   # tools on this machine only; "0.0.0.0" for every network

Each server then listens on TCP at its own game port number: the server on UDP 49176 answers RCON on TCP 49176. rcon_port and rcon_password in a [[server]] give one server another port or its own password, for example for a community that moderates only its server. RECLAIMER_DEDICATED_RCON_PASSWORD and RECLAIMER_DEDICATED_RCON_ADDRESS set the two [rcon] settings.

Two protocols on one port

Source RCON

The protocol of Valve's games, which ready-made RCON clients, libraries in most languages and hosting panels speak: commands in, text out.

WebSocket

JSON replies, and live events: chat lines with the sender's player ID, joins, refused joins, leaves, kicks, bans, pardons, admins added and removed, mutes, votes, anti-cheat notices, every kill, the game starting and ending, whether a map change or team change worked, and each configuration reload. Browsers speak it too, so a web panel can connect directly.

WebSocket tools connect to ws://address:port/ with the subprotocol reclaimer-rcon:

WebSocket messages
sign in, within 10 seconds
{"type":"auth","password":"…"}
answer
{"type":"auth","ok":true,"protocol":1,"server":"…","version":"…"}
a command, as a line or as words; by names who acts
{"type":"command","id":7,"command":"kick #3 spam"}
{"type":"command","command":"ban","args":["#3","7d","spam"],"by":"Alice"}
its reply; data is the JSON form of the text
{"type":"reply","id":7,"ok":true,"text":"…","data":{…}}
events as they happen
{"type":"event","event":"chat","time":1793440610,…}
a tool more than 256 events behind
{"type":"lagged","missed":12}

RCON desktop client

Project Reclaimer RCON is a window for moderators. It's the reclaimer-rcon-version download for your system, Reclaimer RCON.app on macOS. It needs no game files and no game or server beside it, and project-reclaimer --rcon-app opens the same window.

  1. ConnectEnter the server's Host (a name or IP address, without a port), its RCON Port, normally the game port such as 49176, and the RCON Password, then choose Connect. An optional Moderator name tells players and the server's log who is acting.
  2. Watch the serverThe player list refreshes every five seconds, with each player's service tag, whether they're alive, their health and shields, and how long ago they last died. The console shows chat, joins, leaves, kills and moderation as they happen, and whether a game or team change worked. JSON shows each event's fields and Copy copies the console.
  3. Act on a playerSelect a player to prepare a tell, kick, ban, mute, unmute or admin add with their player ID, change the message, time or reason, and choose Send. Status, Players, Bans, Admins, Maps, Modes, Next game, Votes and Help run those commands, and any command can be typed; Up and Down bring back earlier ones.
  4. Run the gameThe Manage menu prepares a command to load a map and mode, change only one of them, set the next game, rename the server, set the join password, redistribute or shuffle the teams, start, pass or cancel a vote, pardon a kick or remove an admin. Change it, such as the map's name, and choose Send.
  • It uses the WebSocket protocol and connects to the server directly, not through a wss:// proxy. From outside the server's network, use a VPN or an SSH tunnel (see Security): with ssh -L 49176:127.0.0.1:49176 you@server, connect to host 127.0.0.1, port 49176.
  • It never saves the password or the connection, and clears the password field once you're signed in. A password command is hidden as you type it and left out of the command history. A lost connection isn't retried on its own, and neither are commands, since one that got no answer may already have run: connect again yourself.

From the command line

On the server's machine, dedicated rcon reads the password and port from dedicated.toml, so it needs no setup:

Shell
project-reclaimer dedicated rcon players
project-reclaimer dedicated rcon --server "Community Rotation" kick Bravo spamming
project-reclaimer dedicated rcon --watch

--server names the server when several have RCON, --watch follows a server's chat and events until Ctrl+C, and --json prints replies as JSON. Put options before the command. It always gets in, however many tools are connected (see Security). In Docker, run it in the server's container, such as docker compose exec server-1 dedicated rcon ….

From anywhere else, reclaimer-rcon, or the game's own --rcon, runs one command, or watches:

Shell
reclaimer-rcon 203.0.113.4:49176 "your password" status
reclaimer-rcon --watch --json 203.0.113.4:49176 "your password"
project-reclaimer --rcon 203.0.113.4:49176 "your password" status

reclaimer-rcon is the remote console's own download, on every system, and given no address it opens the window above. The server-only packages don't hold it: on a server, use dedicated rcon. For Windows, the RCON client downloads hold only that program and its checksum.

Commands

CommandWhat it does
statusThe server, its address, what it plays, where the round stands, players and limits, its anti-cheat and VPN blocking settings, and a vote under way.
players, listEvery connected player: number, name, player ID, address, admin or muted, team, score and kills/deaths during a game, split-screen players at their PC, service tag, whether they're alive with health and shields, the last death, and their device.
say <text>, tell <player> <text>A [Server] line in everyone's chat, or in one player's.
kick <player> [time | 0] [reason]Removes the player. They read who and why, and can't rejoin for the time given, 0 for no wait at all, or else for 10, 30, 60, then 120 minutes on successive kicks (see kicks).
ban <player | player ID | IP | range> [time] [reason]Bans a connected player's ID, address and, where available, device together, for good or for a time such as 30m, 12h, 7d or 2w. Also takes the player ID, address or range of someone who isn't connected.
banip <player> [time] [reason]The same as ban, for a connected player.
unban <name | player ID | IP | range>, bansLifts a ban together with its linked entries; lists the bans in force with who banned and how long is left.
pardon <player ID | IP | range | name>Lets a kicked player rejoin this server now and forgets their earlier kicks here, so a next kick starts at 10 minutes again. Name them as they were kicked, or use the player ID or address from their kick or refused event. Bans need unban.
admin [list], adminsThe admins: those dedicated.toml names and those the console added, with the ones online.
admin add <player | player ID>Makes a connected player, or a player ID, an admin on every server sharing the ban list, at once. They can kick and ban from the game and can't be vote-kicked.
admin remove <player | player ID | name>Takes back an admin the console added, also after they left, by the name they were added under. Admins in dedicated.toml change there.
immune [list | add <player> | remove <player>]The same for players no vote can kick, without admin rights.
vpn [IP]Whether the server refuses players on a VPN, proxy or hosting provider, each list's size and age and who may join through one anyway; with an address, whether it's refused, on which list or network. See VPN blocking.
vpnallow <player | player ID | IP | range> [note], vpnrevoke <player ID | IP | range>Lets a player or address join through a VPN on every server sharing the ban list, or takes that back. For a refused player, use the player ID from their refused event.
mute <player> [voice | text | all] [time] [reason] [shadow], unmute <player>, mutesNobody hears the player's voice, text or both: the server stops passing them on, for the time given, until unmute or until the server restarts. Rejoining keeps it. With shadow the player isn't told. mutes lists them.
role [list | add <player> <role> | remove <player>], moderator [list | add | remove]The server's roles, what each may do and who holds them. add gives a role on every server sharing the ban list; remove takes back one given here.
joins [open | closed | queue | gate <phases> | gate none | remove <place | player ID>]Whether new players get in, and who waits in the join queue. It holds until a reload changes the file's joins or join_gates.
bots [kick <name | player ID>]The bots on the server; kick disconnects one.
commands [add <word> ["<usage>"] | remove <word> | clear]Chat commands of your own, which a tool answers: after commands add skip "/skip: vote to skip this map", a player's /skip reaches only the server, as a command event with its words and the player's ID and role, and /help lists its usage. Answer with tell. Up to 16 words, until a restart.
healthHow the server keeps up: frames a second and frame times over the last minute, upload and download, and uptime.
endround, endgameEnds the round as if its time ran out, or ends the game with the scores as they stand.
reloadChecks dedicated.toml, the playlists and variants it names and the content folder, and applies them (see changing settings while servers run). The reply says what changed on this server, or what's wrong; then nothing changes.
handoff <address:port> | cancel | statusMoves the lobby to a standby server between games, with nobody dropped. See handoff and failover.
failover set <address:port> | clear | statusThe standby that takes the lobby over if this server goes down.
forge save [<name>], state [save | discard]Saves the Forge map being played as a named map, or the server's state. See saving on the server.
restart [now], quitRestarts this server once it has no players, or at once with now. quit stops this server until dedicated restarts.
help [command], ?The command list, or one command.

Name a player by their number in players (#3), their player ID, or their name when only one connected player has it; quote names with spaces. Players keep the name they chose even when someone else in the game has it, so two players can share one: use their number or ID then. A name that could mean more than one player is refused, saying so. A split-screen player is named by their host's number. The console acts with the host's authority, so it can kick, ban and mute admins too. Players read “Bravo was kicked by an admin.”, or the name a WebSocket tool says it acts for.

Game, server and vote commands

These change what the server plays, its name and join password, and run its votes.

CommandWhat it does
maps, modesThe maps the server has, or its game types, each with the name to use in the commands below.
map <map>Ends the game and plays this map next, with the same rules.
mode <mode>Ends the game and plays this mode or saved game type next, on the same map.
load <map> <mode>Ends the game and plays both next. Quote names with spaces: load "The Pit" "Capture the Flag".
nextmap [<map> [<mode>] | clear]Sets the next game without ending this one; without a mode, the rules stay as they are. clear takes it back. On its own, says what's next and lists the playlist.
weights, weight [map | gametype] <name> <0-10 | reset>, weight game <map> <mode> <0-10 | reset>Every game of the playlist with its weight and how often it leads a ballot; or weigh a map, game type or game until a restart or a reload. See server weights.
nextEnds the game under way, or changes the lobby's, for the next one.
replayPlays this game again: the one under way ends, and the lobby keeps it.
servername [<name>]Renames the server, or says its name.
password [<password>]Sets the password players need to join, up to 128 bytes, or says whether one is set; password "" opens the server. It never shows the password, and doesn't change the console's own.
maxping [<milliseconds> | off]Shows or sets the highest ping a player may have as they join, up to 1000; off or 0 takes everyone. Players already in stay. See ping limit.
teamcount [2-64]Spreads the players over that many teams, within the map's limit, or says how many teams have players.
shuffle, shuffleteamsShuffles the players across the teams that have players, evening out their numbers.
team <player> <team>, setteamMoves a player to red, blue, green, orange, purple, gold, brown or pink, in the lobby or during a round, whatever the game type and team_changing let players do. A team's last player can't be moved during a round. See team changes.
voteThe vote under way with its count, and the playlist ballot with its games and votes.
startvote <endround | endgame | shuffle | kick | playlist> [player]Calls a vote for the players to answer; kick names the player. Unlike a player's call, it starts with no yes vote. playlist opens the playlist ballot.
passvotePasses the vote under way, or closes the playlist ballot so the leading game wins as usual.
cancelvoteEnds the vote under way with no result, or cancels the playlist ballot. The playlist then waits until startvote playlist or a map, mode, load or nextmap.
  • A map or mode change ends the current game and starts the chosen one in the next lobby; a server waits for a player before starting it. On a playlist server, it replaces one vote, and the playlist goes on after that game. A game picked this way keeps the restrictions of the playlist's entries for it, such as anti_cheat or voice_team_only.
  • The reply only says the change was accepted. Whether it worked comes after, as a control event in the WebSocket stream and the client's console, once the lobby has changed or with why it couldn't. A change that fails is dropped, and the lobby keeps its game while the server picks its next one as usual.
  • Map changes take base maps and saved maps, and the server's mod maps, written as in a playlist: workshop:item ID/map file name. Every player's game gets the new map ready, and a multiplayer game begins with the players who have it while the others come in as theirs finishes; see players still loading.
  • A new server name, join password or ping limit lasts until the server restarts, or until a configuration reload changes that setting in the file; dedicated.toml stays as it is.
  • teamcount and shuffle move the players there are; they don't change the game type or limit the teams players join later. What they came to is a control event with action teams, once every player's game has confirmed it, and the game's chat says it.
  • team moves the player at once, also during a round, and is refused while a game starts and between rounds. The game's chat says how it went.

Co-op servers

On a campaign server, an ODST server or a Reach co-op server, each mission leads to its next or is played again, so the console doesn't choose the game, and status names the mission: map, mode, load, next, replay and nextmap with a game answer This server plays a co-op campaign: each mission won leads to the next (endgame plays this one again). To play something else, change campaign, odst or reach in dedicated.toml.

  • endgame ends the mission, and the lobby plays it again.
  • A mission has no rounds or teams to work with: use endgame, not endround, teamcount or shuffle.
  • In a playlist with co-op entries, next does work: it ends the mission for the playlist's next game.

Events

WebSocket tools and --watch get these as they happen, each with type "event", its name in event, and time:

EventFields
chatchannel (all, team, proximity or server), name, id, text, and team on team chat.
joinnumber, name, id, ip, admin. The name is empty: a player's connection comes before their name. players has it once they're in.
leavenumber, name, id.
refusedname, id, ip, reason.
kickname, id, by, reason, seconds they're kept out.
banname, id, ip, by, reason, expires (0 is for good).
unban, pardontarget, by; a pardon also has name.
admin_added, admin_removed, role_added, role_removedname, id, by.
staff, commandA command a player's role ran from chat, and a player's use of one of your own commands words: word, args, text, the player's id, name and role.
mute, unmutename, id, by; a mute also has reason and expires.
votestate, subject, caller.
phasephase (playing, finished or no_game), map, mode.
server_phaseThe server's own phase at each change: lobby, voting, countdown, loading, in_game or post_game.
queueA player called from the join queue.
standby_joined, standby_lost, handoff_ready, handoff_done, handoff_failed, failover_doneA standby's address and version; a move's from and to; or the reason it failed.
saved, save_failedA save on the server that reached the disk, or didn't.
cheatname, id, category, detail, action (blocked or kicked).
killkiller (null for the world), victim, report, the kind of damage. Every death, suicides and team kills included. killer and victim are the engine_id that players gives, in decimal.
controlaction, ok, text: how a request went. Actions: load, playlist_vote, reload, reload_applied, teams, and kill_feed when deaths had to be dropped.

id is the player's network key, 64 hexadecimal characters. players in JSON gives each player's number, name, id, ip, admin, muted, team, score, kills, deaths, assists, betrayals, suicides, engine_id, device, service_tag, alive, health, shields and seconds_since_last_death, with guests and guest_players for split-screen players. Health and shields are fractions, not percentages. A value the server can't tell yet, such as the last death before anyone has died, is null.

Security

  • RCON is not encrypted. Keep address = "127.0.0.1" and reach it from elsewhere through an SSH tunnel (ssh -L 49176:127.0.0.1:49176 you@server) or a VPN. If the servers must listen on every network, allow only your tools' addresses to the TCP ports in the firewall. A web panel can reach the WebSocket protocol through an HTTPS reverse proxy (wss://).
  • A client has 10 seconds to sign in. Five wrong passwords from one address within ten minutes lock that address out for up to ten minutes.
  • At most 4 tools are signed in to a server's console at once, with up to 16 connections and four signing in per address. One more spot is kept for dedicated rcon on the server's own machine, which reads a key the server writes at each start to data/<server>/rcon-host.key, so you can always run commands there. A fifth tool is told the console is full and disconnected; that doesn't count as a wrong password.
  • The server log records every command that changes something with where it came from and the tool's by. A password is never logged.
  • The password is kept in dedicated.toml: keep the server folder private. Change the password when someone should no longer moderate.
  • In Docker, see the remote console note under Everyday use: on the host's network the consoles listen on the machine's own 127.0.0.1 unless you set the address, and compose.single.yaml publishes them there only.

Live status for panels

Each server writes data/<server>/status.json, for panels and monitoring that read files rather than talk to the console. It's written when what it says changes, such as a player joining or leaving, the phase, the game or the queue, at most every 2 seconds, and at least once a minute while nothing does, so an idle server hardly touches the disk. dedicated status reads the same file, and takes a server whose file is older than 90 seconds, or gone, as not running.

data/<server>/status.json
{
  "name": "Community Rotation",
  "address": "203.0.113.4:49176",
  "map": "Guardian",
  "mode": "Slayer",
  "state": "playing",
  "players": [
    { "number": 1, "name": "Bravo", "id": "0123…cdef", "handle": "…", "address": "198.51.100.7:51234", "admin": false, "guests": ["Bravo 2"] }
  ],
  "max_players": 16,
  "pid": 4312,
  "updated": 1793440610,
  "reported": 3,
  "game": 1,
  "played": 4
}
  • state is lobby, voting, countdown, loading, playing or post-game.
  • A player's id is their network key, not the player ID their profile shows, and address is their address with its port. Tools written for 0.9 keyed on its player IDs and its ip field need to change.
  • guests are the split-screen players at that PC: they count against max_players, and appear only there.
  • updated is Unix seconds, reported how many games this process reported to the stats service, game the playlist's game being played or waited for, from 0, and played how many games this process started.
  • updated can be up to 60 seconds old on a running server. A tool that took a status older than 30 seconds for a stopped server must now allow 90.
  • The file also carries the server's phase (lobby, voting, countdown, loading, in_game or post_game) with phase_since, each player's role, who waits in the join queue as join_queue, and health: the version, uptime, players, frame rate and frame times over the last minute, and upload and download. These are as fresh as the last write.
  • For live figures, ask the remote console's health, or set metrics_http = "127.0.0.1:9310" in a [[server]]: GET /health then answers the same as JSON and GET /metrics as Prometheus text (reclaimer_frame_rate_hz, reclaimer_frame_ms_p99, reclaimer_players and more). It takes a loopback address only, since it has no password.
  • The player count a server advertises, in the Server Browser, /health and the console's status, counts a connection that hasn't joined the game for 30 seconds only, so connections that never join don't make a server look fuller than it is. players and this file still list every connection.
  • The file is replaced whole, so a reader never sees half of it.

Player votes

So a server without an admin online can still deal with a griefer, players can vote to kick a player, end the round, end the game or, in team games, shuffle the teams. Votes are on unless a server (or [defaults]) sets votes = false.

  • A vote passes as soon as more than half of the players on the server have voted yes (2 of 3, 3 of 4 or 5, 9 of 16), and fails after 30 seconds. Whoever called it has already voted yes.
  • A kick vote on a server with more than 16 players needs fewer yes votes than that. Counting the players who were there when the vote opened and still are, the one it names included, the yes votes it needs grow slowly: 9 of 17, 12 of 32, 19 of 64, and a quarter of the players from 120 on. Votes to end the round, end the game or shuffle the teams always need a majority.
  • One vote runs at a time. A kick vote needs at least three players and can't name an admin or a vote_kick_immune player. A shuffle needs a team game with a round being played and at least two players. A round's end needs a round being played, and a game's end a game going on.
  • A player whose vote failed can call the next one after a minute.
  • A player who called a kick vote waits 3 minutes before calling another kick vote, whether the last one passed or failed. Other players can still call kick votes in the meantime.
  • A player kicked by vote is kicked as by an admin: they can't rejoin for 10 minutes after a first kick, longer after later ones (see kicks). Leaving during a kick vote that names you counts as the kick. Ending the game finishes it with the scores as they stand.
  • A passed shuffle deals every player, split-screen players included, at random across the teams in play, so no team has more than one player more than another. Team scores stay with their teams. It evens out player counts, not skill.

Players call and cast votes from the pinned scoreboard or in chat with /vote kick <name> [reason] (also /votekick), /vote endround (also /vote round), /vote endgame (also /vote game) or /vote shuffle (also /vote shuffleteams), and answer one with /yes or /no (also /vote yes and /vote no). /help lists them all; see how to play. The remote console can call, pass and cancel votes too.

Team changes

Players in a team game change teams themselves, as in Halo 3's custom games: in the lobby with the CHANGE TEAM buttons, and during a game with the same buttons in the game menu (Escape). The server decides every change: it checks the rules against the teams as they stand, then moves the player and says so in chat, or tells them why not.

Each game type has a Team changing option (Game Options → ROUNDS & TEAMS). Most of Halo 3's matchmaking game types have it disabled. A server's team_changing, in its [[server]] block or under [defaults], can only make it stricter:

ValueWhat players may do
"balanced"The default. Balancing moves only, even where the game type allows any move, and none where it has team changes disabled.
"game_type"Whatever each game type's Team changing option allows.
"off"No team changes of their own.
dedicated.toml
[defaults]
team_changing = "game_type"   # follow each game type's Team changing option
  • Balancing: a player may join only a team with fewer players than their own, so no move makes the teams more uneven, and may not start a third team out of two.
  • When: in the lobby until the countdown starts, and during a round. Teams are locked while a game starts and between rounds. A player waits 2 seconds between changes in the lobby and 10 seconds in a game.
  • During a round, the player confirms the switch, which then waits for their next death: they respawn on the new team after the usual respawn time, so changing teams never gives a free respawn or gets anyone out of a fight. Choosing their own team again takes the switch back. The last player on a team can't leave it during a round, since the game would end.
  • Admins open a player's card in the lobby or the game menu and use MOVE TO; the remote console does the same with team <player> <team>. Their moves skip these rules and take effect at once, also during a round, but never empty a team mid-round.
  • RECLAIMER_DEDICATED_TEAM_CHANGING sets the [defaults] value, for example in Docker's .env.

Friendly fire

A server can stop players from hurting their own side: teammates in multiplayer team games and partners in co-op. Set friendly_fire = false in [defaults] for every server, or in one [[server]] block. It applies to every game and mission the server hosts, from the next game.

dedicated.toml
[defaults]
friendly_fire = false   # teammates and co-op partners can't hurt each other
  • What stays the same: players still hurt themselves, enemies and AI, AI still hurts players, and free-for-all games play as usual.
  • Left on, the default, the game type's own damage rules apply.
  • In co-op, the choice is set when a mission starts and stays the same through checkpoint reverts, players joining mid-mission and the move to the next mission.
  • RECLAIMER_DEDICATED_FRIENDLY_FIRE=false sets the [defaults] value, for example in Docker's .env.
  • Games hosted from the game have the same switch under Host Settings → Friendly fire.

Camera

A server decides how players see their own character on foot in its multiplayer games. Set camera in [defaults] for every server, or in one [[server]] block:

ValueWhat players see
"first_person"The default, also when left out. Everyone plays in first person, as in Halo 3. Characters made for third person, and game types whose player traits set third person, play in first person too.
"player_choice"Each player switches between first and third person with their Switch camera key: P on the keyboard. It has no controller button until a player binds one. Until a player presses it, the game type's player traits and their character decide.
"third_person"Everyone plays in third person, seen from behind.
dedicated.toml
[defaults]
camera = "player_choice"   # each player switches with their Switch camera key
  • Character mods: on a server left at the default, characters made for third person play in first person. Set "player_choice" or "third_person" to let them play in third person. See character mods.
  • What keeps its own view: game modes built around third person, such as UNSC vs Covenant vs Flood's classes or a game mode script that sets a player's camera, keep it whatever the setting. Vehicles, turrets and the death camera keep Halo 3's own views.
  • The same for everyone: the server tells every PC who plays in third person, so every player's game shows each player the same way, and their shots leave from the same place.
  • Multiplayer only: co-op's camera is set in its own modifiers, and Firefight's in its options.
  • Changing it applies from the next game; see changing settings while servers run. dedicated check shows each server's camera beside its anti-cheat setting.
  • RECLAIMER_DEDICATED_CAMERA (first_person, player_choice or third_person) sets the [defaults] value, for example in Docker's .env; a server's own setting wins.
  • Games hosted from the game have the same choice under Host Settings → Camera.

Voice scopes

A server turns each of the three kinds of voice chat on or off by itself: global voice (V, everyone), team voice (B, current teammates) and proximity voice (N, living players nearby, enemies included). Set voice_global, voice_team and voice_proximity under [defaults] for every server, or in one [[server]] block. All three are true unless set. For proximity chat only:

dedicated.toml
[[server]]
name = "Proximity Slayer"
port = 49178
playlist = "playlists/slayer.playlist.json"
voice_global = false      # V stays silent
voice_team = false        # B stays silent
voice_proximity = true    # N reaches living players nearby
  • A talk key whose voice is off stays silent: V is always global voice, B team voice and N proximity voice, and none of them switches to another.
  • For team voice only, set voice_global = false and voice_proximity = false. Team voice is silent in games without teams and for players without a team.
  • Proximity voice is silent in lobbies, while loading and while dead.
  • voice = false still turns all voice off, whatever the three say.
  • RECLAIMER_DEDICATED_VOICE_GLOBAL, RECLAIMER_DEDICATED_VOICE_TEAM and RECLAIMER_DEDICATED_VOICE_PROXIMITY set the [defaults] values, for example in Docker's .env; a server's own setting wins.
  • The older settings: voice_team_only = true keeps team voice alone and voice_proximity_only = true proximity voice alone, where voice_global, voice_team and voice_proximity don't say otherwise.
  • For the players' side, see voice chat in the player guide.

Team voice in a playlist

To keep voice to teammates for some games of a rotation only, select the game in the playlist editor and turn on TEAM VOICE ONLY, or add "voice_team_only": true to its entry.

Playlist entry
{ "map": "Valhalla", "game": "Team Slayer", "voice_team_only": true }
  • It starts when that game launches and lasts until the next game launches. Voting on and preparing the next game doesn't change voice in the game still being played.
  • An entry can only restrict voice. Left out or false, the server's own settings apply: an entry can't turn on voice, or a voice scope, the server has off.

Games hosted from the game

Host Settings has Global voice, Team voice and Proximity voice below Voice chat, each on to start with. They need voice chat on, and a playlist game that requires team voice keeps global voice off until the next game.

Bots

reclaimer-bot, a download of its own, is a bot for dedicated servers: a DJ, a bridge to another chat, an announcer. It joins with no game, graphics card, display or sound device, so it runs anywhere that can reach the server. Its download comes with BOT.md, the whole guide.

  • A bot is a member of the server's chat and voice and of nothing else: no player slot, team, score or vote, and never in the join queue. Players see its name with [BOT] in chat and the voice widget.
  • It sends music-quality voice, 48 kHz stereo, whatever the server's voice_quality. A server takes 8 bots at most, and a game hosted by a player takes none.
  1. Make its identityreclaimer-bot id makes the key file, reclaimer-bot.key in the current folder, and prints the bot's player ID. Keep the file to keep the ID, and keep it private.
  2. Let it inTurn bots on and give that ID a role with bots.run; the change takes effect on reload:
    dedicated.toml
    [defaults]
    allow_bots = true
    
    [roles.dj]
    title = "DJ"
    rank = 12
    can = ["bots.run"]
    players = ["<the bot's ID>"]
  3. Joinreclaimer-bot join HOST:PORT --name DJ --input wav:music.wav --loop. It stays while its ID holds a role with bots.run, and leaves within a second if it's banned.
  • Sound in: a WAV file, or raw 16-bit PCM from a file or pipe (--input raw:PATH:RATE:CHANNELS), on the all channel.
  • Sound out: what the bot hears, each voice channel or the mix, to a file or pipe of its own (--output).
  • Scripting: one JSON object a line. On its input, {"say": "text"}, {"play": "wav:FILE"}, {"stop": true} and {"quit": true}; on its output, the chat, who's speaking and who's on the server.
  • The remote console's bots lists them, and bots kick disconnects one.
  • On macOS, a bot downloaded in a browser is blocked, as a server is: run xattr -dr com.apple.quarantine on its unzipped folder once.

Fighting bots

A server can also host players of its own that fight in its multiplayer games, to fill a big game or keep one going. Set combat_bots, and bot_pilots for how many of them take vehicles, in [defaults] or a [[server]]:

dedicated.toml
[[server]]
name = "Big Battle"
port = 49180
max_players = 128
combat_bots = 120   # fighting players, pilots included
bot_pilots = 40     # of them in the map's vehicles
  • Places: bots share max_players with people, and must leave at least one place for a person: the server above has room for 8. bot_pilots can't be more than combat_bots. Both are 0 unless set.
  • Pilots take vehicles of the kinds the map has, and the server keeps a fleet of them for the pilots. On a map without vehicles, they fight on foot.
  • Games go on without people: the server starts its multiplayer games with its bots even when no person is connected, and the bots stay through its whole rotation.
  • Multiplayer only: a campaign, ODST or Reach co-op server, or a rotation with co-op entries, can't have fighting bots.
  • The Server Browser's player count includes them, and status.json counts them on their own as combat_bots. They have no network connection and no stats.
  • Changing either setting, or max_players on a server with fighting bots, restarts the server once no person is connected. Neither has an environment variable.

Stats and achievements

Finished games count toward players' ranks and service records through the project's public stats service, the one 0.9 reported to, so every player's record carries on. A server with an empty stats_server reports there, at http://stats.ibigs.us:8792; one that saved the service's earlier address reports there too. Point it at your own service with stats_server = "http://stats.example:8792", or set "off" to report nothing.

  • A server reports a multiplayer game once at least two of its players have proven who they are. Co-op games aren't ranked, so campaign and ODST servers report nothing.
  • Reports are signed with data/stats-key.json, one key for every server in a configuration, made when the servers start. A 0.9 server folder's key is the same file, so a whitelisted server stays whitelisted. dedicated stats-key shows it, with the command a service's operator runs to whitelist it.
  • A service can hold back games from servers it doesn't whitelist, and doesn't count games that look like boosting, such as games under a minute or with no kills or score.
  • stats_server takes http:// only: dedicated check passes an https:// address, but a server given one doesn't start. Plain HTTP is by design here: reports are signed.
  • Unlocks: the server asks the same service which cosmetic unlocks, such as helmet fire, each player has. A choice a player hasn't unlocked shows to everyone else as that slot's default; nobody is kicked for it. With stats_server = "off" there are no lookups, and everything counts as unlocked.
  • A changed stats_server applies from the next game; the game under way still reports to the one it started with.
project-reclaimer dedicated stats-key
Stats key      data/stats-key.json
Public key     XgKK+Btd/7LY…
Whitelist it   stats-server allow --key XgKK+Btd/7LY… --name "<server name>"

Copies of the reports

stats_copies, at the top of dedicated.toml, sends each game's report to more services too: the same signed bytes that go to stats_server, so they verify on any service. Use it for a mirror of your own:

dedicated.toml
stats_copies = ["http://mirror.example:8792"]
  • Each address has its own queue and retries. One that's away, slow or refusing delays nothing else: not the other copies, not stats_server's report and not the game.
  • A copy that fails is tried again for about a day, with waits that grow from 2 seconds to 5 minutes. A queue holds 16 reports, in memory: with it full, newer reports aren't queued for that address, and reports still waiting when the server stops are lost for that copy.
  • It needs a stats_server that isn't "off", takes up to 8 addresses and may not name stats_server itself. A service with a whitelist needs your key on it, as stats_server's does.
  • A change applies at once. RECLAIMER_DEDICATED_STATS_COPIES adds to the list.

Achievements

Players earn achievements on your server, and they show on their player cards. The stats service grants every one of them: the server sees a player earn one and sends a claim, signed with its stats key.

  • Your server must be approved. The service records a claim only from a key or address it whitelists. Until yours is, players earn nothing on it: ask the service's operator with the line dedicated stats-key prints.
  • Claims go to stats_server; with "off", none are sent.
  • A game with campaign barriers off, no-clip or flight earns nothing, Forge's monitors included.

Server films

A server can record each of its games as a film, to look at a report or a disputed game afterwards. It's off until you turn it on, in [defaults] or a [[server]]:

dedicated.toml
[defaults]
film_recording = true
film_keep = 25        # the newest films kept
film_max_mb = 2048    # and the most disk they take together
  • Where: data/<server>/films. Each is an ordinary film that any player's Theater plays, and project-reclaimer --film PATH opens one directly.
  • Limits: the newest film_keep films stay, within film_max_mb, the oldest deleted first. A film that reaches film_max_mb by itself stops. While the disk has under 1 GB free, the oldest films go. A game under 10 seconds isn't kept.
  • Checked: <film>.hash.json beside each film has its size and SHA-256, the same sha256sum gives.
  • When something goes wrong: a write error or a full disk stops that film and is logged once; the game goes on and the next game records again. Only finished films reach films, so a server stopped mid-game leaves none cut short.
  • What it costs: about 0.1 MB a player-minute on disk. Every 10 seconds a recording server does extra work that grows with the map's objects: nothing to notice on an ordinary map, but a short pause on a Forge map with thousands of them.
  • What a film lacks: a game ended from outside, by the console or by every player leaving, doesn't show its end.
  • A change counts from the next game. RECLAIMER_DEDICATED_FILM_RECORDING, _FILM_KEEP and _FILM_MAX_MB set the [defaults].
  • Reports to the stats service don't change: they neither name films nor wait for them.

Film uploads

film_receivers, at the top of dedicated.toml, sends each finished film to a film receiver, a service that stores them. Empty, the default, sends nothing. The receiver's program isn't among the downloads yet.

dedicated.toml
film_receivers = ["https://films.example"]
film_upload_kbps = 0   # the most KB/s uploads may take; 0 paces itself
  • Films hold player IDs, names and all of each game's play: only name receivers you trust, and tell your players.
  • dedicated itself sends them, from one low-priority thread, never a game. Each film goes once, compressed, to the first receiver that takes it.
  • With games on, uploads keep a little ahead of what the games produce; with nobody on, they take up to 1 MB/s. film_upload_kbps is a hard cap over both. Set under what the games produce, the oldest films go unsent once film_keep and film_max_mb remove them.
  • With every receiver down, it waits and the backlog stays on disk. data/film-uploads.json has the backlog, the rate and the counts.
  • Both settings apply when dedicated restarts.

Handoff and failover

A lobby can move to another server process with nobody dropped. A standby, a second server process, joins the lobby as a member with no player, and the players' games take it as their host when the server leaves or goes down, the way they follow a new host in a game a player hosts. Players need nothing new, and read SELECTING NEW HOST…, then CONNECTING TO NEW HOST… over the wait.

A planned handoff

Use it for an update, new content, a setting that needs a new process, or leaving a machine, instead of waiting for the server to empty. On the remote console:

Shell
project-reclaimer dedicated rcon handoff 203.0.113.4:49186
project-reclaimer dedicated rcon handoff status
  • For an address on the server's own machine that's free, dedicated starts the standby there by itself and looks after it from then on.
  • The standby reads the same configuration, joins, and must say it's ready within 60 seconds: the same build, with every map of the playlist. The move then waits for the lobby, never the middle of a game or a countdown.
  • It carries the playlist's place, the next-game and join queues, the console's live settings, mutes, and players' names and split-screen seats. The old server stops once its players have moved.
  • A handoff that fails before the move, such as a standby that never gets ready, changes nothing for the players: the log says handoff failed with the reason. handoff cancel stops one that hasn't moved yet.
  • The new server lists itself under the lobby's name. Its address is the standby's, so players who join by address need the new one.

Failover

With failover, a standby waits in the lobby all the time, and takes it over if the server goes down:

dedicated.toml
[[server]]
name = "Community Rotation"
port = 49176
playlist = "playlists/community.playlist.json"
failover = "203.0.113.4:49186"   # where its standby runs
failover_in_game = false         # true: the standby stays through each game
  • Between games, players' games notice the server is gone after about 22 seconds and follow the standby, which carries on with the playlist.
  • During a game, the standby isn't there by default: it leaves as each game starts and comes back in the next lobby. A server that dies mid-game then drops its players, as one without a standby does.
  • failover_in_game = true keeps the standby through each game, so it can take a game in play over and the round plays on. It then loads every map with the players and holds a whole game's memory: about 1 GB or more per lobby, where a standby in the lobby holds about 0.6 GB. What the old server counted of that round isn't carried over, and the new server reports the game's results from its own end.
  • failover applies at once, in [defaults] or a [[server]], and the console's failover set, failover clear and failover status change and show it live. failover_in_game counts from the next game.
  • A standby on another machine needs its own public_address, so players on the internet can be introduced to it.
  • With no standby reachable, a lost server drops its players as before, and the log says failover: no standby joined with why.
  • On classic networking a lobby moves within 17 machines: the server, the standby and 15 players' PCs. Enhanced networking moves bigger ones.

Running and updating

The first start

No download holds game code, so a server makes the engine's code itself the first time it starts, from halo3/halo3.dll in its game folder, and keeps it in its caches. It does this once per release, with no window, and says so in data/<server>/server.log:

server.log
[translate] the code is not in the cache: translating on 4 threads
[translate] done in 12.4 s

That takes about 5 seconds on four fast cores, 10 to 20 on an ordinary four-core machine, and longer on one or two. The caches are in the Cache folder of the account's player folder (%LOCALAPPDATA%\ProjectReclaimer, ~/.local/share/ProjectReclaimer or ~/Library/Application Support/ProjectReclaimer), RECLAIMER_CACHE_DIR moves them, and in Docker they're in the cache volume. They rebuild if you delete them. The first start on a machine also moves an old Documents\My Games\Project Reclaimer folder to the new player folder; server folders stay where they are.

The dedicated command

Run these in the server folder, or name the file with --config FILE (--server FILE in place of dedicated takes the same commands).

CommandWhat it does
dedicated [--verbose], dedicated runRuns every enabled server and this machine's master. --verbose prints every line of each server's log.
init [DIR] [--from [MCC]] [--maps A,B]Writes a commented dedicated.toml and playlists/slayer.playlist.json, keeping a folder that already has one. --from copies the game files from MCC's folder into game/, hard-linked on the same drive, and --maps names the maps to copy; it also takes campaign, odst, reach, reach-campaign, halo1, halo1-campaign, halo2 and halo2-campaign for whole games. Run again on the same folder, it adds what's missing.
checkInstalls missing Workshop items, then checks the configuration, the game folder, each server's games and rules, RCON, the master and the ports, says which mission a campaign names, and notes the objects a server's games would miss. It exits with an error when something is wrong.
statusWhether the master answers and how many servers it lists, and each server's address, game, state and players. It exits with an error when one is down.
content [WORDS]The maps and game types map, game and playlists name, and every campaign and mission campaign names.
modsInstalls missing Workshop items, then lists the references playlists and map take for installed mod maps.
playlist [list], playlist show FILE, playlist new NAME --maps A,B --games X,Y [--vote-seconds N] [--replace]Every playlist and who plays it; one playlist's games, their share and options; a playlist of every map with every game type.
bans, ban TARGET [--reason R] [--for TIME], unban TARGETThe shared ban list. See admins, kicks and bans.
vpn, vpn check IP, vpn allow TARGET [NOTE], vpn revoke TARGET, vpn updateThe VPN block: its lists and allowances, whether an address is refused, an allowance and its revocation, and fetching the lists now. See VPN blocking.
reloadAsks the running dedicated to apply the edited configuration, and prints its report. See changing settings while servers run.
rcon [--server NAME] [--json] [--watch] [COMMAND]The remote console from this machine. See RCON.
stats-keyThe key this configuration's servers sign their stats reports with. See stats.

Everyday running

  • dedicated prints joins, leaves, kicks, bans, refused players and errors with each server's name; --verbose prints everything. Every line also goes to data/<server>/server.log. The run before is kept as server.previous.log, and once a log passes 20 MB, it starts afresh and keeps the full one as server.log.old. This machine's master logs to data/master/master.log.
  • dedicated status shows whether this machine's master answers and how many servers it lists (Master · TCP 49175 · lists 2 server(s)), then each server's address, game, state and players, such as Big Team Battle · 203.0.113.4:49176 · Slayer on Guardian · playing · 3/16 players, with each player's name, player ID and address. Split-screen players count too, and are named under the player whose PC they play on. It exits with an error while a server is down or the master doesn't answer, so monitoring and health checks can use it. See also live status for panels.
  • A server that stops is started again after 1 second, then after longer waits if it keeps stopping, up to a minute, and at once if it had run for 10 minutes. The notice says why it stopped, such as "Big Team Battle" stopped after 29 s (it crashed (signal 11 …); if this keeps happening, send its log with a bug report): starting again in 1 s. See data/big-team-battle/server.log. It restarts with the game it was playing.
  • A server that stops saying it's alive for 90 seconds is stopped and started again. One that waits for long work that still goes on, such as the Forge library's first build, keeps saying so and isn't.
  • Before it ends a frozen server, dedicated keeps what it was doing: hang-time.txt beside the log, with its last status and, on Linux, what each of its threads was waiting on, and server.hung-time.log, its log up to then. The newest three of each stay. The server's own log also says where its main loop is stuck once it hasn't turned for 30 seconds. Send these with a bug report.
  • A server started again after a crash or a freeze goes on where its playlist was, and counts its games on.
  • An idle server writes little: its log repeats no status line that hasn't changed, and players' playtime is saved at each game's end and every 15 minutes.
  • A server starts again by itself when its game session is lost, so it never stays listed while nobody can join:
    • When the session ended, the server restarts at once. The notice says its game session ended and dropped every player.
    • When four or more players leave at once, the server only watches, and says so in its log. It restarts only when a player who connects since is left waiting: their game asks to join and the session hasn't taken them within 12 seconds. It never restarts while it's simply empty.
  • A server sends the game's packets from a thread of its own, so the game's own thread doesn't wait on the network.
  • Empty servers wait in their lobby using very little processor, and start a game when someone joins, or once min_players players are in. A game every player left ends after 5 seconds.
  • A game that comes to nothing sends the server back to its lobby, with its players kept, and the log says the session did not begin the game or the session left the game with no results. A session lost for a minute starts the server again.
  • A server never stays stuck between games. A player's game that stops answering for 30 seconds while the next map is made no longer holds the others up (it stays connected, and joins when its map is ready). A server whose own making of the next map gets nowhere for 30 seconds, or whose starts keep failing, starts again by itself, and its players' games join it again. A game the server itself can't load twice in a row is passed over for the playlist's next one, or a new ballot.
  • A server that can't keep up while players are on logs Server falling behind once a minute, and every 5 minutes it logs its upload; see servers per machine.
  • Ctrl+C, SIGINT and SIGTERM stop every server and the master, and close any forwarded ports. On Windows, closing the console does too.
  • A server the console's quit stopped stays off until dedicated restarts.

To update Project Reclaimer, stop the servers, replace the program with the new download (on Windows, project-reclaimer-dedicated-v0.10.7.exe renamed the same way; on Linux, the new tarball unpacked over the old one; on macOS, the new zip's files over the old ones, or the new app) and start them again, or turn on automatic updates. In Docker, docker compose pull && docker compose up -d. The first start of a new version prepares the engine again. Players can only join servers on their own version, so update your servers when a release comes out; see one version for everyone. Coming from 0.9? See updating a 0.9 server.

After a game update on Steam, nothing needs doing. The game keeps a copy of the engine files it was built for, in each server's own folder, and carries on from it when the game's own file changes or is gone. Only a server that has never started on the old file can't: a new server folder made after an update needs a Project Reclaimer release for the new file, and the log says which build it found and which it needs.

One version for everyone

Every machine in a game needs the same version of Project Reclaimer. A server admits only players on exactly its own version:

  • The Server Browser's Version column shows the version each server runs, in red when it isn't the player's own. Such a server is marked OTHER VERSION and can't be joined, and its card says which side needs to update.
  • A refused join, by Direct Connect too, names both versions and the side that needs to update.
  • Once a release is out, players who update can't join a server still on the previous one. Update your servers with each release, by hand or with automatic updates, every server that shares your ban list included, and tell your players to update too.
  • 0.9 and 0.10 can't play together at all: the network protocol is new, so servers, players and masters move together.

Automatic updates

Servers can update Project Reclaimer by themselves. It's off until you turn it on, at the top of dedicated.toml (before any [section]), or with RECLAIMER_DEDICATED_AUTO_UPDATE=true. Start the servers again once to start it.

dedicated.toml
auto_update = true
  • The servers check for a new stable release when they start and every hour after. Pre-releases are never installed.
  • A new release downloads while the games go on, and is checked against the release's SHA-256 checksum before it replaces the program. Then every server stops and starts again on the new version, with the same settings. Games under way end, and players have to join again.
  • It installs the release's server package under the program's own file name. On Windows that's project-reclaimer-dedicated-version.exe, so a copy of the game client becomes a server-only build: play from another copy. On Linux it's project-reclaimer-dedicated-version-linux-arch.tar.gz, replacing the program and the package's files beside it. On macOS it's project-reclaimer-dedicated-version-macos-aarch64.zip the same way, or the whole app for a server run from the app.
  • The program's folder must be writable by the account the servers run as. Run one dedicated per copy of the program, so two never update the same file.
  • A failed check or download leaves the servers running and tries again an hour later; the console says why.
  • It updates Project Reclaimer only, and only a release build: [update] auto_update is on, but this build has no release feed means this one isn't. It doesn't apply in Docker, where the image is the update (see Docker).
  • Settings, bans, playlists, content and game files stay as they are. Set auto_update = false and restart to stop updating; the version installed stays.

Troubleshooting

ProblemWhat to do
dedicated init --from says it needs MCC's folderThe game hasn't run on this PC, so no folder is saved. Name the folder: --from "your game's folder".
check names a missing map or game typeCopy the map into game/ (rerun dedicated init --from) or the file into content/, or fix the name in the playlist. check lists every such problem at once and suggests the name you probably meant, and dedicated content lists the names the server has. See check it.
check or the start says “unknown field”The setting is misspelt, or in the wrong section: the message ends in the section it was read in. General settings such as auto_update go before the first [section] header. See the configuration file.
check or the start says it cannot read a playlistFix its path in dedicated.toml. dedicated playlist lists every playlist.
A server won't start, and the log mentions the engine's fileThe game folder's halo3/halo3.dll is another build than this release was made for, and the server has no kept copy. Use a Project Reclaimer release that supports that version, or a copy of the file from before the game's update.
Servers don't appear in the browserOpen each server's UDP port, and forward it on your router or set upnp = true: the browser asks every server and leaves out one that doesn't answer. Masters help players reach a server whose port isn't forwarded, but not through every router; see hosts behind routers. Check public_address, and run project-reclaimer --list-servers http://148.251.153.44:44340 from another network to see what answers.
The server runs and its port is open, but one master doesn't list itA master lists a server only once the server has answered it, from the address it reports from, and lists four servers per IP address at most. Leave public_address empty unless the machine's connections really leave from that address, and for a fifth server on one address ask the master's operator. See discovery.
Players on your own network don't find the server in the browserAllow UDP 44329 in the server machine's firewall, beside its game port: servers answer the browser's search of the local network there.
Players see the server but can't joinOpen or forward the server's UDP port, or set upnp = true. Hole punching can get players in without that, but not between two symmetric NATs. On a home connection behind shared carrier NAT, ask your provider for a public IPv4 address.
The log has no registered with the server list lineThe server is hidden, its public_address is 127.0.0.1, or it can't reach a master's UDP port. Players who reach the server directly still join. See check from another network.
A server keeps restarting, and [master] peers has an https:// addressMasters are plain http://. Fix the address in peers. See the configuration file.
With upnp = true, the log says “Manual setup may be needed”The router didn't answer UPnP or PCP. Check that UPnP is on in the router, or forward the ports by hand.
A port is already in useGive each server its own port, and make sure no other program uses 49175. check names the port.
check stops at halo3/maps/info/halo3.campaign or Campaign mission 3005 is not installed on an ODST serverAn ODST server needs Halo 3's campaign list and two missions: --maps "odst,005_intro,010_jungle". See ODST's files.
Players are asked to start Steam when they joinYour server's mods download through Steam Workshop, which needs Steam running on the player's PC, signed in to an account with MCC. With share_mods = true, they download from your server when Steam isn't available.
Mod downloads are slowRaise share_rate if your upload allows. Sharing the same mod on more servers also helps: players who join from the Server Browser take chunks from up to four servers at once.
Players say a map “clashes with” a mod on their PCThey have another mod with a map of the same file name. They delete it in Settings → Mods, then join again. Another version of the same Workshop mod gets UPDATE & JOIN or REPLACE & JOIN instead; see keeping Workshop mods up to date.
dedicated init says the campaign's maps were not copiedThe servers still run, but can't load saved maps with campaign vehicles or AI. Install the campaign in MCC and rerun dedicated init --from, or copy campaign.map and 040_voi.map from halo3/maps in the game's folder into game/halo3/maps.
check or the start says campaign hosting needs campaign.map, or that a mission isn't installedThe server needs the mission's map file and its information, and campaign.map. Run dedicated init . --from "your game's folder" --maps campaign in the server folder: it adds the missing files and keeps your configuration. See campaign files.
A campaign server skips missions, or starts over before the end of the campaignIt goes on only to the missions it has. Copy every mission with --maps campaign; see campaign files.
check says another game's campaign is not installed, or that a mission is not installed or is in several campaignsCopy that game's missions with --maps halo1-campaign, halo2-campaign, odst or reach-campaign beside campaign, use one of the mission names the message lists, or add campaign = "…" to the line. dedicated content lists every campaign and mission the server can host. See when something is refused.
Forge on a Reach server offers few of Halo 3's vehicles, or check notes objects of maps the game folder lacksA server offers only the objects of the maps in its game folder. Run dedicated init --from again with --maps reach to add every Halo 3 multiplayer map, or name the maps the note lists. See their files.
A server doesn't start, saying campaign co-op or Halo 3: ODST supports at most 16 playersSet max_players to 16 or fewer on that server; a higher value under [defaults] counts too.
Players can't join a private serverThey need the password. Capitals and spaces count. Remove the password, or set password = "" on that server, to open it again.
Players' joins fail, saying the server needs an update, or the browser shows your server's version in redYour server runs another version of Project Reclaimer than they do, and every machine in a game needs the same one. Update the servers to the newest release, or turn on automatic updates. See one version for everyone.
A kicked player can't rejoin for longer than expectedKicks get longer when they repeat: 10, 30, 60, then 120 minutes, until 24 hours pass without one or the server restarts. A kick also covers the player's address and device, so others on the same PC or address wait too. Restarting the server clears every kick, and the remote console's pardon lets one player back at once. See RCON commands.
Players are refused as being on a VPNTheir address is on one of the VPN and datacenter lists. They turn off their VPN, or you let them through by player ID: dedicated vpn allow <player ID>, with the ID from the log's refused line. dedicated vpn check <address> says which list names an address. Set block_vpn = false to turn the block off.
The log or check says the VPN block is NOT WORKING, or names a stale listThe lists couldn't be downloaded yet, or a copy is over a week old. Check that the machine can reach https:// addresses, run dedicated vpn update, and see each list's age with dedicated vpn. To refuse everyone but admins and allowed players while no list has arrived, set fail_closed = true under [vpn]; see refuse a network at once.
The log says “session watch” or “the session was lost”A server whose game session ended restarts by itself, and one whose players all left at once watches whether the next player can get in. See running and updating.
The anti-cheat kicked a player who wasn't cheatingFind the cheat event or the server log's line for it, and report it on Discord with its reference code and the log. Meanwhile, turn the anti-cheat off for that game in its playlist entry ("anti_cheat": false), or set anti_cheat = "detect" for that server to log without kicking. See anti-cheat.
Players are told their ping is over the server's limitThe server has a max_ping. It's checked only as they join; raise it, or set max_ping = 0 (or maxping off in the remote console) to take every ping. See ping limit.
A player was removed while a co-op game loadedIn a playlist's co-op games, their game held the others up for load_timeout seconds (30 by default). They can join again at once. On slow disks, raise load_timeout; 0 waits as long as it takes. Multiplayer games remove nobody for loading slowly. See players still loading.
A panel shows a running server as stoppedstatus.json is written when it changes and at least once a minute, so its updated can be 60 seconds old. Take a status as stale after 90 seconds. See live status for panels.
A server froze and was started againIts folder in data keeps hang-time.txt and server.hung-time.log from the freeze. Send them with a bug report. See running and updating.
Players earn no achievements on your serverThe stats service grants them only on servers it has approved. See achievements.
The log says Server falling behindThe server can't keep up, so its players get fewer updates and see lag. Give it more processor time: fewer servers on the machine, a core of its own (in Docker, cpuset: on its service), fewer players, or tick_rate = 30. See servers per machine.
Players say your server's version of a mod is older than theirsThe mod's author published an update. Servers that installed it by Workshop ID update it within the hour, once nobody is playing on the servers that use it; dedicated check shows the versions. A mod copied into content/Mods by hand isn't updated: copy the new version in and restart the servers that use it. See keeping Workshop mods up to date.
Docker: a port is already in use or the old container still runs after changing compose filesRun docker compose up -d --remove-orphans once. See moving between the two layouts.
Docker: servers are unreachableOn the host's network, the machine's own firewall applies: open the ports with sudo ufw allow 49175:49177/udp and sudo ufw allow 49175/tcp, with your servers' port range. With 0.9's compose.single.yaml, UDP 49175 isn't published: get the new file.
Players can't change teamsBy default, a server lets players join only a team with fewer players than their own. Set team_changing = "game_type" to follow the game type's option instead. Most of Halo 3's matchmaking game types have it disabled, so nobody changes teams in those under either setting. Teams are also locked while a game starts and between rounds. Admins can still move players. See team changes.
RCON tools can't connectSet a password under [rcon]. The console listens on TCP at each game port number, on 127.0.0.1 unless you set address. dedicated check shows where, and whether the ports are free.
An RCON tool is told the console is full4 tools are signed in to that server already. Close one, or have tools keep one connection instead of signing in for every command. dedicated rcon on the server's machine still gets in. See RCON security.
A playlist is rejectedThe log and check name the game number, and dedicated playlist show <file> lists the games. Games can't repeat, a weight is 1 to 100, and a field the format doesn't know stops it. See the playlist file reference.
check or the start stops at a Workshop itemIts download failed. With the Steam app: it must be running, signed in to an account that owns MCC. With SteamCMD: the message says why; see Workshop downloads for what each one means. Usually you sign in to it again with steamcmd +login account +quit, or set username to an account that owns MCC; its log is in data/workshop-cache. In Docker, see Workshop downloads in Docker.
check says a saved game's mod map isn't thereThe server has no copy of it. Copy the mod's whole folder into content/Mods.
A Forge variant made on a Workshop map loads on another mapName its map in base_map. See Forge variants on mod maps.
Servers don't update by themselvesPut auto_update = true at the top of dedicated.toml, before any [section], and start them again. The console says when a check or download fails; the program's folder must be writable. In Docker, update the image.
A server with players in stays in its lobby and starts no gameIt may have a min_players higher than the players in it, split-screen players included. Lower it, or set it to 1 to start as soon as someone is there. See minimum players.
A player can't call another kick voteA player who called a kick vote waits 3 minutes before calling another, whether it passed or failed. Other players can still call one. See player votes.
A talk key does nothing on your serverThat voice is off: a key whose voice the server turned off stays silent instead of switching to another. Check voice_global, voice_team and voice_proximity, and an older voice_team_only or voice_proximity_only. See voice scopes.
Edits to dedicated.toml don't apply, or the console says “Configuration not reloaded”A reload applies nothing while any check fails, and every server keeps its settings: the lines after that message say what's wrong. Fix it and save again. With auto_reload = false, run dedicated reload. Some changes wait for a server to have no players, or for dedicated to restart; see changing settings while servers run.
Players see Halo 3's own characters where the server's character mods should beThe server's game folder may lack some of Halo 3's 27 multiplayer maps. Copy them all with dedicated init <folder> --from "your game's folder" without --maps. Players may also have turned a mod down as they joined, or lack it on a server with share_mods off. See character mods.
Players see NEEDS ODST on your serverThey don't have Halo 3: ODST installed in MCC, which that server's games need. They enable it in Steam, as the game tells them, and join once its download finishes. See Halo 3: ODST.
Players' third-person characters play in first personA server's camera is "first_person" unless set, which also covers characters made for third person and game types whose traits set third person. Set camera = "player_choice" to let each player switch with their Switch camera key, or camera = "third_person" for everyone. See camera.
A 0.9 server came back, but your bot or panel lost track of playersPlayer IDs in status.json and the console's events are network keys now, and ip in status.json is address. See updating a 0.9 server.

When reporting a problem, include the server's log from data/<server>/server.log, and server.previous.log if it restarted, with any hang- report beside them.