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.
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:
| Where | The 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 … |
| Docker | docker 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
| What | Details |
|---|---|
| Software | The 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 files | Your 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. |
| Windows | Windows 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. |
| Linux | x86-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. |
| macOS | macOS 11 or newer, Apple Silicon. |
| Docker | x86-64 Linux with Docker Engine and Compose 2.24 or newer. The image runs natively, with no Wine. It holds no game files. |
| Disk | About 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, CPU | Per 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. |
| Network | One 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]]:
[[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_playersdoesn't start. - Fighting bots take places within
max_playerstoo, 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:
| Server | Memory | Processor |
|---|---|---|
| Waiting for players | about 110 MB | next to none |
| In a small game | about 0.6 GB, more on a Forge map | about 0.6 of a core on Apple Silicon |
| In a full game | about 0.6–0.9 GB, more for a moment while a map loads | about 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_rateof 30) says so in its log once a minute, such asServer 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
- Download the programMake a folder for your servers, such as
C:\reclaimer. Getproject-reclaimer-dedicated-version.exefrom the newest release, put it in that folder, rename itproject-reclaimer.exe, the name the commands below use, and open a terminal there. The game client from the download page works the same way. -
Create the server folder from your game install
This writes a commented
dedicated.tomland an example playlist, and copies the game files a server needs intogame, including the campaign'scampaign.mapand040_voi.mapfor 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"--fromon its own uses the folder the game saved on this PC, so it works once the game has run here. Without--mapsit copies every multiplayer map. Add--maps "Guardian,Valhalla"to copy only the maps you host,campaignfor the campaign's missions,odstfor ODST's files, orreach,halo1andhalo2for the other games, alone or among the maps. On the same drive, files are hard-linked instead of copied. - Edit
dedicated.tomlSet your server names, ports, admins and what each server plays..\project-reclaimer.exe dedicated contentlists the maps and game types you can name, anddedicated playlist newmakes 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. -
Check, then start
PowerShell
.\project-reclaimer.exe dedicated check .\project-reclaimer.exe dedicatedcheckgoes 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 fromgame\halo3\halo3.dll, which takes seconds and happens once per release. -
Open the ports
In a terminal opened as administrator, with your own game ports:
Behind a home router, forward the same ports to this PC, or setPowerShell (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 Allowupnp = trueindedicated.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.
-
Unpack the server-only package
Get
project-reclaimer-dedicated-version-linux-x86_64.tar.gz, or-linux-aarch64.tar.gzfor ARM64, from the newest release. It holds the program and its texts:Shellmkdir -p ~/reclaimer tar -xzf project-reclaimer-dedicated-v0.10.7-linux-x86_64.tar.gz -C ~/reclaimer --strip-components=1 cd ~/reclaimer -
Create the server folder from your game install
With the game installed on this machine, give it the game's folder:
With the game on another PC, runShell
./project-reclaimer dedicated init . --from "$HOME/.local/share/Steam/steamapps/common/Halo The Master Chief Collection"dedicated initthere, as in the Windows quick start, and copy the folder over, keeping the program you unpacked here:Or leave the files where they are and setPowerShell, on the Windows PCscp -r C:\reclaimer\game C:\reclaimer\dedicated.toml C:\reclaimer\playlists you@host:reclaimer/gameindedicated.tomlto the game's own folder:./project-reclaimer dedicated init .writes the file without copying anything. -
Check and start
Edit
dedicated.toml, then:Shell./project-reclaimer dedicated check ./project-reclaimer dedicated -
Open the ports
Open the same in your provider's firewall or security group. Servers don't need root.Shell
sudo ufw allow 49175:49177/udp && sudo ufw allow 49175/tcp -
Run it as a service (optional)
Then/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.targetsudo systemctl enable --now reclaimer, and follow it withjournalctl -u reclaimer -f. The account needs a home folder: its caches go in~/.local/share/ProjectReclaimer/Cache, or whereverRECLAIMER_CACHE_DIRsays.
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.
-
Unpack the server-only package
Get
project-reclaimer-dedicated-version-macos-aarch64.zipfrom 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, withxattr:Terminalcd ~/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 -
Create the server folder
Give it your copy of the game.
--fromalone 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" -
Check and start
Edit
dedicated.toml, then:Terminal./project-reclaimer dedicated check ./project-reclaimer dedicated - 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 = trueindedicated.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.
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
-
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 -
Make the folder and add
compose.yamlSave compose.yaml inShellmkdir reclaimer cd reclaimerreclaimer, or copy it from the file below. -
Put the game files in
server/gameOn a PC with the game, rundedicated init C:\reclaimer --from "your game's folder"as in the Windows quick start and upload that folder asserverwith thescpWindows includes; that brings adedicated.tomltoo:PowerShell, on the Windows PCscp -r C:\reclaimer you@host:reclaimer/serverreclaimer/servermustn't exist yet, or the upload lands inside it asserver/reclaimer. Or make the folders withmkdir -p server/gameand copy the files in by hand, keeping their folders, such asserver/game/halo3/halo3.dll. With the game installed on this machine through Steam, copy nothing: make the same folders and setGAME_DIRin.envto the game's folder. Make the folders yourself before the first start: a folder Docker has to create for you belongs to root. - Choose settings (optional)Save env.example as
.envnext tocompose.yamland uncomment what you change, such asRECLAIMER_DEDICATED_HOST_NAMEorRECLAIMER_DEDICATED_ADMINS. See environment variables. -
Start
The first start downloads the image, writesShell
docker compose up -d docker compose logs -fserver/dedicated.tomlwith 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: containerserver-1runs the first,server-2the 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. -
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
ufwapplies.Shellsudo 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).
# 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:
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.
| Task | Command |
|---|---|
| Follow the log | docker compose logs -f, or one server's: docker compose logs -f server-2 |
| Every server's players and addresses, the master | docker compose exec -e RECLAIMER_DEDICATED_ONLY= server-1 dedicated status |
| One server's | docker compose exec server-2 dedicated status |
| Ban, lift a ban | docker compose exec server-1 dedicated ban <target> --reason "…", … dedicated unban <target> |
| Let a player through the VPN block | docker compose exec server-1 dedicated vpn allow <player ID> (see VPN blocking) |
| Remote console commands | docker compose exec server-2 dedicated rcon players, for the server that container runs (see RCON) |
| Check files and settings | docker compose run --rm server-1 dedicated check |
The maps and game types dedicated.toml and playlists can name | docker compose run --rm server-1 dedicated content <words> (see names and playlists) |
| List and check the playlists; one in detail | docker compose run --rm server-1 dedicated playlist, … dedicated playlist show <file> |
| Make a playlist | docker compose run --rm server-1 dedicated playlist new "Team Slayer" --maps "Guardian,Valhalla,The Pit" --games Slayer |
Apply dedicated.toml, playlist or content edits | They 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 edits | docker compose up -d |
| Stop, start | docker compose stop, docker compose start |
| Update | docker 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.
PUIDandPGIDin.envchoose another user and group; use those rather than Compose'suser:. - Mods and playlists: put shared maps, game types and mods in
server/content, and playlists inserver/playlists. The image has no Steam, so copy Workshop mods intoserver/content/Modsyourself; see Workshop downloads in Docker. - Remote console: set
RECLAIMER_DEDICATED_RCON_PASSWORDin.env. On the host's network, each server's console then listens on the machine's own127.0.0.1, at its game port number, where tools on the machine reach it.RECLAIMER_DEDICATED_RCON_ADDRESS=0.0.0.0opens 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:
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_ONLYpicks the server a container runs: its position indedicated.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 incompose.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 ascpus: "1.5"),cpuset:(such ascpuset: "2,3") ormem_limit:to its service. A full server wants about a core of its own; see servers per machine. - Outside Docker,
RECLAIMER_DEDICATED_ONLYworks the same: eachdedicatedstarted 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:
docker compose -f compose.single.yaml up -d
COMPOSE_FILE=compose.single.yaml
- Its one service is
reclaimer:docker compose exec reclaimer dedicated statuslists every server, and the other commands above takereclaimerin place ofserver-1. - More servers: add a
[[server]]block with the next port, widenGAME_PORTSin.envto cover it (GAME_PORTS=49176-49180) and rundocker compose up -d. A configuration runs up to 32 servers. - Ports: Docker publishes the master's TCP and UDP ports and the
GAME_PORTSrange itself, pastufw; 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_PASSWORDandRECLAIMER_DEDICATED_RCON_ADDRESS=0.0.0.0in.env, and uncomment the TCP line underports:incompose.single.yaml, which publishes the consoles on the host's own127.0.0.1only.
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:
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 = trueupdates itself. Otherwise stop the servers, replaceproject-reclaimer.exewithproject-reclaimer-dedicated-v0.10.7.exe, renamed the same, and start them again. See automatic updates. - In Docker,
docker compose pull && docker compose up -dwith your own compose file,.envand server folder. The new image runs natively. It takes 0.9's mounts, commands and settings, and removes 0.9's Windows copies fromserver/.reclaimeron its first start.RECLAIMER_XVFBandRECLAIMER_EXEmean nothing any more, andRECLAIMER_DEDICATED_AUTO_UPDATEis 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.tomlloads 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.jsonstays, so a whitelisted server stays whitelisted.- Masters must be
http://. Apeersentry withhttps://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.jsonand in RCON's events are players' network keys now, not 0.9's community IDs, and a player'sipinstatus.jsonisaddress, with its port. Tools keyed on 0.9's player IDs need to change. Inadmins,vote_kick_immuneandbans.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] peerslist orMASTER_PEERSnaming 0.9's public masters, and astats_servernaming 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-statusandlocal-serverare gone.project-reclaimer --list-servers http://148.251.153.44:44340shows 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 side | The player's side | Joins |
|---|---|---|
| Public address, forwarded port, UPnP or PCP | Any | Yes, directly |
| An ordinary home router (cone NAT) | An ordinary home router | Yes |
| Behind the same router as the player | Behind the same router | Yes, on local addresses |
| A new port per destination (symmetric NAT) | Cone NAT, full or address-restricted | Yes |
| Symmetric NAT with ports handed out in order | Port-restricted cone NAT | Yes, usually: the player tries the likely ports |
| Port-restricted cone NAT | Symmetric NAT with ports in order | Yes, usually: the server tries the likely ports |
| Cone NAT that filters by address alone | Symmetric NAT | Yes |
| Symmetric NAT with random ports | Port-restricted cone or symmetric NAT | No |
| Port-restricted cone NAT | Symmetric NAT with random ports | No |
| Symmetric NAT | Symmetric NAT | No, at most by chance |
| UDP blocked on either side | No | |
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 = trueasks 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 whendedicatedstops. The router's public IPv4 address then becomes the address listed, unlesspublic_addressnames one. If it fails, the log saysManual 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:
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:
[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]]:
| Setting | Values | Meaning |
|---|---|---|
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. |
[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_modelplays enhanced networking. To host Halo 3's own, setnetwork_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_rateto 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_ratecaps 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_pingsees 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_networksets, in a playlist too. - The value is 30 or 60, and a change counts from the next game.
RECLAIMER_DEDICATED_TICK_RATEsets it too. Server falling behindgoes 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.
| Setting | Default | Meaning |
|---|---|---|
encode_once | on above 32 places | Each 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_threads | automatic above 32 places, else 1 | The 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_threads | 1 | The 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:
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].
| Setting | Default | Meaning |
|---|---|---|
game | game beside the file, else the folder the game saved | Folder 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. |
upnp | false | Ask the router to forward the ports, through UPnP or else PCP. Leave it off on a VPS. |
auto_update | false | Install new stable releases by themselves and restart the servers, which interrupts their games. Ignored in Docker. See automatic updates. |
auto_reload | true | Apply 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 | [], 0 | Where the servers' finished films are uploaded, and the most KB/s that may take. See film uploads. |
Discovery ([master])
| Setting | Default | Meaning |
|---|---|---|
enabled | true | Run 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. |
port | 49175 | Its 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_addressset 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. Leavepublic_addressempty 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])
| Setting | Default | Meaning |
|---|---|---|
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])
| Setting | Default | Meaning |
|---|---|---|
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_table | iptoasn.com's table | The 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_closed | false | While 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 |
|---|---|
name | Required, up to 48 characters. Its folder in data is made from it: lower case, Latin letters and digits, at most 40 characters. |
port | Required. The UDP game port, different for each server. Use 1024 or higher. |
enabled | false keeps the entry without running it. true by default. |
base_map | With 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. |
campaign | Campaign 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. |
odst | Halo 3: ODST's campaign or Firefight instead. See Halo 3: ODST. |
reach | A Halo: Reach mission or Firefight instead. See Reach co-op and Firefight. |
host_name | This server's own host name. |
admins, vote_kick_immune | More player IDs, for this server only, added to the ones at the top of the file. |
rcon_port | This server's remote console TCP port, 1024 or higher. Its game port number unless set. |
rcon_password | Its own console password, in place of [rcon] password. |
metrics_http | A 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 either | Default | Meaning |
|---|---|---|
playlist | none | A playlist file: a rotation players vote on from three games up. |
playlists | none | Several playlist files, each for its own lobby sizes, instead of playlist. See playlists by lobby size. |
weights | none | How 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. |
variant | none | A saved custom game or shareable game type (.json). A saved co-op game makes it a campaign server. |
max_players | 16 | Players 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_players | 1 | Players 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_seconds | 15 | Seconds the post-game screen stays before the next game. |
start_countdown_seconds | 3 | Seconds the lobby counts down once min_players are in it and its ballot chose the game. |
hidden | false | Online but never listed; players join by address. |
password | "" | A password players need to join. See private servers. |
welcome | none | A 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_threads | by the server's size | How a big server spreads its network and animation work. See big servers. |
campaign_skip_vote_percent | 33 | Co-op games: the share of players, 1 to 100, who must press skip before a cinematic is skipped. See skipping cinematics. |
failover, failover_in_game | none, false | A 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_mb | false, 25, 2048 | Record 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_wait | see the section | Whether new players get in, and the line a full server keeps. See join queue and gates. |
moderator_ban_minutes, devs_as_vip | 60, false | A Mod's longest ban, and whether Project Reclaimer's developers hold VIP. See roles. |
allow_bots | false | Let bots join. |
combat_bots, bot_pilots | 0, 0 | Fighting players the server hosts in its multiplayer games, and how many of them fly or drive vehicles. See fighting bots. |
voice, text_chat, votes | true | Voice chat, text chat and player votes. |
voice_global, voice_team, voice_proximity | true | Turn global voice (V), team voice (B) and proximity voice (N) on or off. See voice scopes. |
voice_team_only, voice_proximity_only | false | Older shorthands: team voice alone, or proximity voice alone. |
chat_log | true | Keep 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_vpn | true | Refuse players who connect through a VPN, proxy or hosting provider. See VPN blocking. |
max_ping | 0 | The highest ping, in milliseconds, a player may have as they join, up to 1000; 0 takes everyone. See ping limit. |
load_timeout | 30 | Co-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_fire | true | false stops players from hurting their teammates and co-op partners. See friendly fire. |
round_outlasts_leavers | false | true 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_model | none | "spartan" or "elite": every player plays that character in multiplayer games on Halo 3's maps. Unset, each player's own pick. |
map_hud | false | true: every player sees the HUD of the map's own character, whatever character they play. false: each character brings its own HUD. |
stock_map_defaults | true | Halo 3's maps played without a saved map get the extra respawn points of Bungie's default variants. false leaves them out. |
trust_player_games | true | For 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_frames | false | A server draws no frames. true has it draw them all the same, against no graphics card: a way back if a server misbehaves. |
tick_rate | 60 | Ticks 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_mods | false | Let 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_rate | 20 | Upload limit for downloads from the server together, in Mbit/s. 0 is no limit. |
customization, require_customization, no_vanilla_characters | none, false, false | The 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_objects | false | Forge 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_objects | false | Forge 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_objects | true | Forge 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_primitives | true | Forge 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_keep | false, 0, 3 | Start 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:
[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 = falsecan't have one:dedicated checkand the start say so. RECLAIMER_DEDICATED_WELCOMEsets a one-line[defaults]welcome, for example in Docker's.env. For several lines, use a list indedicated.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.
[[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
hiddenfor that. RECLAIMER_DEDICATED_PASSWORDsets 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.
[[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_PLAYERSsets the[defaults]value, for example in Docker's.env. A value above a server'smax_playersstopsdedicated checkand 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.
[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
maxpingshows the limit, andmaxping 120ormaxping offchanges it until the server restarts or a configuration reload changesmax_ping. RECLAIMER_DEDICATED_MAX_PINGsets 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 = 0waits as long as it takes.RECLAIMER_DEDICATED_LOAD_TIMEOUTsets 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.
| Variables | Settings |
|---|---|
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_RELOAD | The general settings. |
RECLAIMER_DEDICATED_GAME, _CONTENT, _DATA, _BANS | The 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_ONLY | No 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=0 | Turn 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_PEERSandWORKSHOP_ITEMSadd to the file's lists, separated by commas or spaces, andVPN_LISTSandVPN_ASNSadd to theirs.CUSTOMIZATIONandFORGE_MODSreplace the[defaults]list, separated by commas only, since mod names hold spaces. - Flags take
trueorfalse(also1/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_tablehave no variable: set them indedicated.toml.WEIGHTStakes 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 changed | When 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 autosave | At 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_copies | At 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_game | From the next game. |
anti_cheat, customization, require_customization, no_vanilla_characters, film_recording, film_keep, film_max_mb, stats_server | From 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 type | From the next vote. A ballot already open, and the game it picks, still come from the playlist before. |
A new [[server]], or enabled = true | It starts at once. |
A server taken out, or enabled = false | It 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 game | That 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_table | At 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, data | When dedicated restarts. The rest of the reload applies, and its report says so. |
content, coop_network, the Forge palette settings, auto_update | Nothing 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:
project-reclaimer dedicated reload
- Adding mods to
content/Modsdoesn'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
dedicatedstarted with. - A server that restarts after a crash starts with the configuration as last reloaded.
- WebSocket tools get a
controlevent withactionreloadfor every reload, with what changed on that server, or withokfalse and why nothing changed. Areload_appliedevent 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 incompose.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": 2comes 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_playersplayers 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:
- Open the Playlists pageIn a lobby you host, open Playlists, then NEW PLAYLIST.
- 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.
- 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.
- 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.
- 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
Playlistsfolder 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:
{
"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:
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:
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
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"
--mapsand--gamestake names separated by commas, asdedicated contentlists them.playlist newmakes 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.
--replaceoverwrites a playlist file of the same name, and--vote-secondssets the voting time (20 unless set). - Edit the file afterwards to set weights, names, rules and options; see the playlist file reference.
playlist showtakes the file, or part of its name inplaylists/.- 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.
[[server]]
name = "Community Rotation"
port = 49176
playlist = "playlists/community.playlist.json"
max_players = 12
4. Check it
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
| Field | Meaning |
|---|---|
name | The playlist's name, shown in the lobby. |
vote_seconds | Voting time, 5 to 120 seconds. Optional; 20 by default. A curve makes it follow the lobby's size. |
players, recommended_players | Optional. The lobby sizes the playlist is for, and the sizes it's best with, such as "8-24". See games by lobby size. |
version | File format version. Optional; 2, the only one. |
games | The 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:
| Field | Meaning |
|---|---|
map | A 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_map | Optional, 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. |
game | A 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. |
weight | Optional. 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_players | Optional. The lobby sizes this game is offered at, and the sizes it's offered more often at. See games by lobby size. |
name | Optional. The name players see for this game. |
teams | Optional. true or false over the game type's own default. |
rules | Optional. 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. |
options | Optional. 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. |
world | Optional. 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_cheat | Optional. 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_only | Optional. 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_image | Optional. 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:
| Option | Example 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.weapons | which weapons are placed on the map |
map.vehicles | "None" |
rounds.limit | 3 (one round unless set) |
rounds.early_victory | off 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:
{ "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" } ] }
playersis 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_playersis 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,dedicatednames every lobby size from 1 tomax_playerswhere 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:
[[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 + Bigwhere ranges overlap, and its voting time is the first of those playlists'. - The remote console's
statusgives 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:
{ "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.minandmaxbound the result.- A formula in place of points is written in
p, the player count, with numbers,+ - * / ^, brackets andmin,max,clamp(x, lo, hi),abs,sqrt,ln,log10,exp,round,floorandceil. 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_secondsstays 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_secondsis 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:
[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,loadand queued games still reach it. - A game named in
gamestakes 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
weightsshows each game's share and any name that matches nothing, andweightchanges 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:
{ "map": "Valhalla", "game": "Slayer", "name": "Sprint Slayer", "world": { "sprint": "stamina" } }
Key in world | Meaning |
|---|---|
sprint | "off", "unlimited" or "stamina". Off when left out. |
sprint_speed_percent | Sprint speed, 110 to 200 percent; 150 when left out. |
sprint_stamina_seconds | With "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:
{
"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_timeoutapplies 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_playersat 16. - A playlist's
campaignentries play Halo 3's own campaign; anodstentry 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 owncampaign. - 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.
{
"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), anddedicated modsprints 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":
{ "map": "MLG Warlock V9", "base_map": "workshop:2977651586/warlock", "game": "2V2 HARDCORE TS" }
A server's map and game take it the same way:
[[server]]
name = "MLG Warlock"
port = 49176
map = "MLG Warlock V9"
base_map = "workshop:2977651586/warlock"
game = "2V2 HARDCORE TS"
- A
base_mapthe variant wasn't made on is refused: 'X' was not made on Y. - A server downloads the Workshop items
base_mapnames like those inmap. - A server's or playlist's
variantfile saved on a mod map may not find that map yet: name the map inmapand the variant ingameinstead.
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.
{ "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.
| Folder | Files |
|---|---|
content/Maps | Map variants (.mvar) and saved maps from Forge (.json). |
content/Game Modes | Game variants (.bin), shareable game types (.json) and game modes (.rmeg). |
content/Images | Vote images. |
content/Mods | One folder per mod: a Workshop item's folder, or a custom .map, with its .mapinfo if it has one. See Mods. |
dedicated contentlists the names the folder's maps, game types and variants go by, the onesmap,gameand 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 checkor start puts the game modes that come with Project Reclaimer incontent/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 asgame = "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, whichdedicated initcopies, and a campaign map that holds all four Flood forms, such as050_floodvoi.map, which it doesn't: copy that fromhalo3\mapsin the game's folder intogame/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 rundedicated init --fromwithout--mapsto copy every multiplayer map. Campaign vehicles and AI come fromcampaign.mapand040_voi.map, whichdedicated initcopies 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/Mapsandcontent/Game Modesby themselves; see changing settings while servers run. After adding mods, rundedicated 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 = trueadds 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 = falseleaves Halo 3's objects off ODST's canvases, andforge_primitives = falseleaves 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.editswitch 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 withcan = ["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.editis 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>writescontent/Maps/<name>.json, over a map of that name, which a playlist,maporvariantthen names like any other. A name is 1 to 48 characters that can be a file's name. - The server's state:
state save, orforge savewith no name, writesdata/<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.statealone shows the saved state, andstate discarddeletes it. - From the game: a player whose role holds
forge.savetypes/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 = 10saves the state every 10 minutes of a Forge game, and keepsforge_autosave_keepearlier 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.
| What | Restored |
|---|---|
| The game being played, the next game, the queue | Exactly. |
| The Forge map's objects, labels, boundaries, sky, gravity and atmosphere | As SAVE MAP keeps them. |
| A server name, join password, ping limit, join gates or weight the console changed | Exactly, while the file's own value hasn't changed since. |
| Roles the console gave, bans and mutes | They're on disk already. |
| A round under way: scores, clock, where players stand | No: the game starts from its lobby. |
| A co-op mission's checkpoint | No: 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:
[[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:
campaignin the line is"halo3"(the default),"halo1","halo2","odst","reach"or a mod's campaign by its title, such as"Cursed Halo Again".dedicated contentlists every campaign and mission the server can host, anddedicated checksays 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], stopsdedicated checkand the start. It can't also have aplaylist,variant,map,game,base_map,odstorreach. - It starts the mission once
min_playersplayers are in its lobby and every connected player is in, or 30 seconds after the last one joined, then counts downstart_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_timeoutremoves 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 = falseturns 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:
campaign = { mission = "Sierra 117", difficulty = "heroic", modifiers = { health_percent = 150, skulls = 513, sprint = true, sprint_stamina_seconds = 10 } }
| Setting | Meaning |
|---|---|
health_percent, damage_percent | Enemy health and damage, 25 to 1000 in steps of 25; 100 is the game's own. |
health_per_player_percent, damage_per_player_percent | How much they grow per extra player, 0 to 100 in steps of 5. |
skulls | The 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. |
scoring | Campaign scoring: "off" (the default), "team" or "free_for_all". |
sprint | true: every player sprints by holding Sprint while running forward. Off when left out. |
sprint_speed_percent | Sprint speed, 110 to 200 percent in steps of 10; 150 when left out. |
sprint_stamina_seconds | How long a full meter lasts, up to 30 seconds, or 0 for unlimited; 5 when left out. |
third_person | true: every player sees their character in third person. |
players_choose_camera | true: each player chooses first or third person with their Switch camera key. |
disable_friendly_fire | true: players can't hurt each other. friendly_fire = false on the server does the same. |
| Gold skull | Value | Silver skull | Value |
|---|---|---|---|
| Iron | 1 | Assassin | 512 |
| Black Eye | 2 | Blind | 1024 |
| Tough Luck | 4 | Cowbell | 2048 |
| Catch | 8 | Grunt Birthday Party | 4096 |
| Fog | 16 | IWHBYD | 8192 |
| Famine | 32 | ||
| Thunderstorm | 64 | ||
| Tilt | 128 | ||
| Mythic | 256 |
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:
[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 3 | campaign |
| Halo: CE | campaign,halo1-campaign |
| Halo 2 | campaign,halo2-campaign |
| Halo 3: ODST | campaign,odst |
| Halo: Reach | reach-campaign,campaign |
project-reclaimer dedicated init . --from "your game's folder" --maps campaign,halo1-campaign
halo1-campaignandhalo2-campaigncopy those games' missions with their multiplayer maps;halo1andhalo2alone 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 campaigncopies 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.)
[[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:
odst = { mission = "Tayari Plaza", insertion = 0, difficulty = "normal" }
| Setting | Meaning |
|---|---|
mode | "firefight" for Firefight. Left out, the server plays the campaign. |
mission | Required. 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. |
insertion | In a campaign, where the mission starts: 0, the default, is its start. For Firefight, the map's own, as listed below. |
variant | Firefight'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". |
modifiers | A 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_characters | Campaign 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. |
options | Firefight only. The game's settings over its game type's. See Firefight options. |
customization, no_vanilla_characters | With the players' own troopers, and in Firefight: character mods whose characters players may play instead, and whether nobody plays their trooper. |
mod_map | A mod's ODST map played instead, by its cache's path, as a game hosted from the menus plays one. |
| Campaign mission | mission: number, file | Firefight map | mission, insertion |
|---|---|---|---|
| Prepare to Drop | 4100, c100 | Crater | 6100, 4 |
| Mombasa Streets | 5000, h100 | Crater (Night) | 5000, 7 |
| Tayari Plaza | 6100, sc100 | Lost Platoon | 6110, 4 |
| Uplift Reserve | 6110, sc110 | Rally Point | 6120, 5 |
| Kizingo Boulevard | 6120, sc120 | Rally (Night) | 5000, 8 |
| ONI Alpha Site | 6130, sc130 | Security Zone | 6130, 4 |
| NMPD HQ | 6140, sc140 | Alpha Site | 6130, 5 |
| Kikowani Station | 6150, sc150 | Windward | 6140, 5 |
| Data Hive | 5200, l200 | Chasm Ten | 5200, 6 |
| Coastal Highway | 5300, l300 | Last Exit | 5300, 7 |
| Epilogue | 4200, 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).
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:
odst = { mode = "firefight", mission = 6100, insertion = 4, options = { "firefight.team_lives" = 3, "firefight.minutes" = 30, "skulls.famine" = 1, "bonus_skulls.iron" = 1 } }
| Option | Meaning |
|---|---|
"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:
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 odston its own isn't enough:dedicated checkthen stops athalo3/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 checkand 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 indedicated.toml.
How an ODST server plays
- The server waits in its lobby until
min_playersplayers 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], stopsdedicated checkand 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_firework as on Halo 3's servers. Withtrust_player_gameson, the default, a server whose game drifts out of step with every player's takes one player's game. - To play something else, change
odstindedicated.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:
project-reclaimer dedicated init . --from "your game's folder" --maps "Guardian,Valhalla,reach,halo1,halo2"
reachcopies 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-campaigncopies Reach's missions too, for a Reach co-op server.halo1andhalo2copy Combat Evolved's and Halo 2's multiplayer maps with each game's engine, shared maps, sounds and game types.halo1-campaignandhalo2-campaigncopy their missions as well, for a campaign server.odst,halo1andhalo2bring Guardian with them, which their maps are built on, and no other Halo 3 map: name Halo 3's maps beside them, or leave--mapsout for all of them, when their Forge games should offer Halo 3's objects.dedicated contentlists what the server has.- A server offers and plays only the objects of the maps in its game folder.
dedicated checkand the start say what a server's games would miss:odst_objects,reach_objects,halo1_objectsorhalo2_objectsturned 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, rundedicated initagain to add Halo 3's maps.
Every game in one playlist
{ "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 plainLockoutis 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:gamenames 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, andoptionsandruleson 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_objectsandhalo2_objectsadd 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 = falseorreach_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:
[[server]]
name = "Reach Co-op"
port = 49180
reach = { map = "m10", campaign = true }
# Firefight: reach = { map = "ff20_courtyard", campaign = true, firefight = "firefight_new" }
mapis 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, andfirefightone of the map's own variants:firefight_new,firefight_classic,firefight_gen,firefight_versus,firefight_score_attack,firefight_rocketfightorfirefight_gruntpocalypse.- The server needs Reach's missions and Halo 3's Sierra 117:
--maps reach-campaign,campaign. Without Reach or the map,dedicated checksays 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.
reachplays missions on Normal, as Noble Six. For another difficulty, a start, modifiers or the players' own characters, host the campaign withcampaign = { 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_modson, 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/
├─ 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.soundsfile beside maps that hold their own sounds, and a Halo: CE mod's ownsounds.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'shalo3/mapsfolder, 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 areclaimer-workshop.jsonbeside itsModInfo.jsonto name its item, such as{"item": 2899741683, "folder": ""}, wherefolderis the package's folder inside the item (empty for the item itself). - To keep a mod in
content/Modswithout using it, list its folder incontent/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 agame, 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 Modesintocontent/Game Modes, and name it in the server'svariant, with the mod incontent/Mods. If the server can't find the map that way, name it inmapand the variant ingame. - A saved map with objects from mod maps: copy it into
content/Mapsand name it inmapor 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/Mapsand the mod intocontent/Mods, and name the saved map inmapor 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.
[[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]]:
[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:
[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.
project-reclaimer dedicated mods
[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.
/opt/steamcmd/steamcmd.sh +login your_steam_account +quit
[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
| Setting | Default | Meaning |
|---|---|---|
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. |
steamcmd | none | SteamCMD'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. |
provisioner | none | The 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_minutes | 60 | Minutes 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 says | What 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 brackets | SteamCMD'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 checklists each item's installed version and whether Steam has a newer one.- Mods put in
content/Modsby hand are never updated. To have the servers manage one, list its Workshop ID under[workshop] itemsand name its maps asworkshop:item ID/map file name.
[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]]:
[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_modson, 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, unlessrequire_customizationis on. Withshare_modsoff, players who have a mod see its characters and those who don't see Halo 3's own; withrequire_customizationon, 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--mapscopies them. - Names:
dedicated checklists each server's character mods. A name that matches none stopsdedicated checkand the start, with the name you most likely meant, or the folders it looked in:content/Mods, andcontent/Mods/Downloaded/packs/charactersfor 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 Heroesin.envnames them, separated by commas. It replaces[defaults] customization, and a server's owncustomizationstill wins.RECLAIMER_DEDICATED_REQUIRE_CUSTOMIZATIONandRECLAIMER_DEDICATED_NO_VANILLA_CHARACTERSset 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.exeon Windows, with-macos-aarch64.zipand-linux-arch.tar.gzfor 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'scustomization.json. - Third-person characters play in first person, like every other character, unless the server's
cameralets 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_ratecaps 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]./banipdoes 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'spardonlets a kicked player rejoin that server now, and their next kick there starts at 10 minutes again. Bans needunban. - Bans go on the shared ban list and apply to every server. A ban's player ID, address and device are linked:
unbanwith 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:
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
{
"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:
| Role | What it may do | Who holds it |
|---|---|---|
| Host | Everything. | The player hosting a game from the game. A dedicated server has none. |
| Admin | Everything. | admins, and the console's admin add. |
| Mod | Kick, 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]]. |
| VIP | Never vote-kicked, and ahead in the join queue. | A [roles.vip]'s players, or the console's role add. |
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"]
cantakes permission names, wildcards (mute.*), the presetspreset:host,preset:admin,preset:mod,preset:vipandpreset:everyone, removals (-ban.perm) andban.temp:minutesfor 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.saveandbots.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 = falsetakes 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,/roleand the rest;/helplists what theirs allows./forceendround,/forceendgameand/forceshuffleare 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 offclears it and/passwordalone says whether one is set, for roles withpassword.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
iconnames 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, androle removetakes it back.devs_as_vip = truegives 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.
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.
| Setting | Default | Meaning |
|---|---|---|
queue_max | 7 | Players the line holds, 7 at most, on top of max_players. |
vip_queue_max | 3 | Players the VIP line holds, 3 at most, for roles with bypass.queue: VIP and up. |
vip_priority | 75 | The share of places, in percent, the VIP line takes while both lines wait: three VIPs, then one other player. |
queue_starve_after | 600 | Seconds after which a waiting player takes the next place, whatever their line. |
queue_max_wait | 3600 | Seconds 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'sjoinsshows who waits and changes the mode and gates live, andjoins 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.
| Value | What 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.
[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_CHEATsets the[defaults]value, for example in Docker's.env; a server's own setting wins.dedicated checkand the remote console'sstatusshow the setting. In JSON,statusgivesanti_cheatandanti_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 acheatevent 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).
{ "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:
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:
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'srefusedevent. The console also hasvpn,vpnallowandvpnrevoke. - Allowances are kept in the shared ban list, so they apply to every server at once, without a restart:
{
"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":
[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:
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):
[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'svpn, show each list's size and age. A list whose copy is over a week old is reported as stale in the log, indedicated checkand indedicated vpn. - No list yet: a server that has never had a list admits every address and logs
NOT WORKINGwhen it starts and every hour. Withfail_closed = trueunder[vpn], orRECLAIMER_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] 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:
[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:
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.
- 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. - 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.
- Act on a playerSelect a player to prepare a
tell,kick,ban,mute,unmuteoradmin addwith 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. - 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): withssh -L 49176:127.0.0.1:49176 you@server, connect to host127.0.0.1, port49176. - It never saves the password or the connection, and clears the password field once you're signed in. A
passwordcommand 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:
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:
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
| Command | What it does |
|---|---|
status | The 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, list | Every 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>, bans | Lifts 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], admins | The 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>, mutes | Nobody 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. |
health | How the server keeps up: frames a second and frame times over the last minute, upload and download, and uptime. |
endround, endgame | Ends the round as if its time ran out, or ends the game with the scores as they stand. |
reload | Checks 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 | status | Moves the lobby to a standby server between games, with nobody dropped. See handoff and failover. |
failover set <address:port> | clear | status | The 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], quit | Restarts 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.
| Command | What it does |
|---|---|
maps, modes | The 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. |
next | Ends the game under way, or changes the lobby's, for the next one. |
replay | Plays 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, shuffleteams | Shuffles the players across the teams that have players, evening out their numbers. |
team <player> <team>, setteam | Moves 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. |
vote | The 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. |
passvote | Passes the vote under way, or closes the playlist ballot so the leading game wins as usual. |
cancelvote | Ends 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_cheatorvoice_team_only. - The reply only says the change was accepted. Whether it worked comes after, as a
controlevent 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.tomlstays as it is. teamcountandshufflemove the players there are; they don't change the game type or limit the teams players join later. What they came to is acontrolevent withactionteams, once every player's game has confirmed it, and the game's chat says it.teammoves 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.
endgameends the mission, and the lobby plays it again.- A mission has no rounds or teams to work with: use
endgame, notendround,teamcountorshuffle. - In a playlist with co-op entries,
nextdoes 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:
| Event | Fields |
|---|---|
chat | channel (all, team, proximity or server), name, id, text, and team on team chat. |
join | number, name, id, ip, admin. The name is empty: a player's connection comes before their name. players has it once they're in. |
leave | number, name, id. |
refused | name, id, ip, reason. |
kick | name, id, by, reason, seconds they're kept out. |
ban | name, id, ip, by, reason, expires (0 is for good). |
unban, pardon | target, by; a pardon also has name. |
admin_added, admin_removed, role_added, role_removed | name, id, by. |
staff, command | A 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, unmute | name, id, by; a mute also has reason and expires. |
vote | state, subject, caller. |
phase | phase (playing, finished or no_game), map, mode. |
server_phase | The server's own phase at each change: lobby, voting, countdown, loading, in_game or post_game. |
queue | A player called from the join queue. |
standby_joined, standby_lost, handoff_ready, handoff_done, handoff_failed, failover_done | A standby's address and version; a move's from and to; or the reason it failed. |
saved, save_failed | A save on the server that reached the disk, or didn't. |
cheat | name, id, category, detail, action (blocked or kicked). |
kill | killer (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. |
control | action, 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 rconon the server's own machine, which reads a key the server writes at each start todata/<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.1unless you set the address, andcompose.single.yamlpublishes 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.
{
"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
}
stateislobby,voting,countdown,loading,playingorpost-game.- A player's
idis their network key, not the player ID their profile shows, andaddressis their address with its port. Tools written for 0.9 keyed on its player IDs and itsipfield need to change. guestsare the split-screen players at that PC: they count againstmax_players, and appear only there.updatedis Unix seconds,reportedhow many games this process reported to the stats service,gamethe playlist's game being played or waited for, from 0, andplayedhow many games this process started.updatedcan 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_gameorpost_game) withphase_since, each player's role, who waits in the join queue asjoin_queue, andhealth: 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 setmetrics_http = "127.0.0.1:9310"in a[[server]]:GET /healththen answers the same as JSON andGET /metricsas Prometheus text (reclaimer_frame_rate_hz,reclaimer_frame_ms_p99,reclaimer_playersand more). It takes a loopback address only, since it has no password. - The player count a server advertises, in the Server Browser,
/healthand the console'sstatus, 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.playersand 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_immuneplayer. 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:
| Value | What 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. |
[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_CHANGINGsets 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.
[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=falsesets 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:
| Value | What 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. |
[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 itsoptions. - Changing it applies from the next game; see changing settings while servers run.
dedicated checkshows each server's camera beside its anti-cheat setting. RECLAIMER_DEDICATED_CAMERA(first_person,player_choiceorthird_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:
[[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 = falseandvoice_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 = falsestill turns all voice off, whatever the three say.RECLAIMER_DEDICATED_VOICE_GLOBAL,RECLAIMER_DEDICATED_VOICE_TEAMandRECLAIMER_DEDICATED_VOICE_PROXIMITYset the[defaults]values, for example in Docker's.env; a server's own setting wins.- The older settings:
voice_team_only = truekeeps team voice alone andvoice_proximity_only = trueproximity voice alone, wherevoice_global,voice_teamandvoice_proximitydon'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.
{ "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.
- Make its identity
reclaimer-bot idmakes the key file,reclaimer-bot.keyin the current folder, and prints the bot's player ID. Keep the file to keep the ID, and keep it private. - Let it inTurn bots on and give that ID a role with
bots.run; the change takes effect onreload:dedicated.toml[defaults] allow_bots = true [roles.dj] title = "DJ" rank = 12 can = ["bots.run"] players = ["<the bot's ID>"] - Join
reclaimer-bot join HOST:PORT --name DJ --input wav:music.wav --loop. It stays while its ID holds a role withbots.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
botslists them, andbots kickdisconnects one. - On macOS, a bot downloaded in a browser is blocked, as a server is: run
xattr -dr com.apple.quarantineon 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]]:
[[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_playerswith people, and must leave at least one place for a person: the server above has room for 8.bot_pilotscan't be more thancombat_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.jsoncounts them on their own ascombat_bots. They have no network connection and no stats. - Changing either setting, or
max_playerson 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-keyshows 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_servertakeshttp://only:dedicated checkpasses anhttps://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_serverapplies from the next game; the game under way still reports to the one it started with.
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:
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_serverthat isn't"off", takes up to 8 addresses and may not namestats_serveritself. A service with a whitelist needs your key on it, asstats_server's does. - A change applies at once.
RECLAIMER_DEDICATED_STATS_COPIESadds 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-keyprints. - 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]]:
[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, andproject-reclaimer --film PATHopens one directly. - Limits: the newest
film_keepfilms stay, withinfilm_max_mb, the oldest deleted first. A film that reachesfilm_max_mbby 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.jsonbeside each film has its size and SHA-256, the samesha256sumgives. - 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_KEEPand_FILM_MAX_MBset 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.
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.
dedicateditself 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_kbpsis a hard cap over both. Set under what the games produce, the oldest films go unsent oncefilm_keepandfilm_max_mbremove them. - With every receiver down, it waits and the backlog stays on disk.
data/film-uploads.jsonhas the backlog, the rate and the counts. - Both settings apply when
dedicatedrestarts.
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:
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,
dedicatedstarts 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 failedwith the reason.handoff cancelstops 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:
[[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 = truekeeps 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.failoverapplies at once, in[defaults]or a[[server]], and the console'sfailover set,failover clearandfailover statuschange and show it live.failover_in_gamecounts 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 joinedwith 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:
[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).
| Command | What it does |
|---|---|
dedicated [--verbose], dedicated run | Runs 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. |
check | Installs 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. |
status | Whether 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. |
mods | Installs 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 TARGET | The shared ban list. See admins, kicks and bans. |
vpn, vpn check IP, vpn allow TARGET [NOTE], vpn revoke TARGET, vpn update | The VPN block: its lists and allowances, whether an address is refused, an allowance and its revocation, and fetching the lists now. See VPN blocking. |
reload | Asks 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-key | The key this configuration's servers sign their stats reports with. See stats. |
Everyday running
dedicatedprints joins, leaves, kicks, bans, refused players and errors with each server's name;--verboseprints everything. Every line also goes todata/<server>/server.log. The run before is kept asserver.previous.log, and once a log passes 20 MB, it starts afresh and keeps the full one asserver.log.old. This machine's master logs todata/master/master.log.dedicated statusshows 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 asBig 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,
dedicatedkeeps what it was doing:hang-time.txtbeside the log, with its last status and, on Linux, what each of its threads was waiting on, andserver.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.
- When the session ended, the server restarts at once. The notice says
- 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_playersplayers 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 gameorthe 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 behindonce 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
quitstopped stays off untildedicatedrestarts.
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.
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'sproject-reclaimer-dedicated-version-linux-arch.tar.gz, replacing the program and the package's files beside it. On macOS it'sproject-reclaimer-dedicated-version-macos-aarch64.zipthe 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
dedicatedper 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 feedmeans 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 = falseand restart to stop updating; the version installed stays.
Troubleshooting
| Problem | What to do |
|---|---|
dedicated init --from says it needs MCC's folder | The 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 type | Copy 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 playlist | Fix its path in dedicated.toml. dedicated playlist lists every playlist. |
| A server won't start, and the log mentions the engine's file | The 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 browser | Open 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 it | A 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 browser | Allow 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 join | Open 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 line | The 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:// address | Masters 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 use | Give 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 server | An 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 join | Your 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 slow | Raise 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 PC | They 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 copied | The 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 installed | The 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 campaign | It 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 campaigns | Copy 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 lacks | A 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 players | Set max_players to 16 or fewer on that server; a higher value under [defaults] counts too. |
| Players can't join a private server | They 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 red | Your 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 expected | Kicks 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 VPN | Their 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 list | The 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 cheating | Find 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 limit | The 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 loaded | In 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 stopped | status.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 again | Its 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 server | The stats service grants them only on servers it has approved. See achievements. |
The log says Server falling behind | The 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 theirs | The 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 files | Run docker compose up -d --remove-orphans once. See moving between the two layouts. |
| Docker: servers are unreachable | On 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 teams | By 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 connect | Set 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 full | 4 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 rejected | The 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 item | Its 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 there | The 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 map | Name its map in base_map. See Forge variants on mod maps. |
| Servers don't update by themselves | Put 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 game | It 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 vote | A 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 server | That 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 be | The 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 server | They 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 person | A 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 players | Player 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.
