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 two default master servers, which every player's Server Browser reads, and to the master this machine runs. 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 and chat log
├─ 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 Halo 3: ODST server also needs Halo 3: ODST installed there. |
| Windows | Windows 10, 11 or Server 2019 or newer (x64). No runtime to install. |
| Linux | x86-64 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 them, 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. 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 Halo 3: ODST hold at most 16 players: a campaign server or an ODST server with a higher
max_playersdoesn't start. - 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, andcampaignfor the campaign's missions orodstfor ODST's files, 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. 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.0-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.0-macos-aarch64.zip . mv project-reclaimer-dedicated-v0.10.0-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.0.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 and its stats service to 8792, beside 0.9's. A
[master] peerslist orMASTER_PEERSnaming 0.9's public masters, and astats_servernaming 0.9's stats 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. 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://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), "host" | How co-op games play: campaign, ODST, Firefight and a playlist's co-op entries. "lockstep" is Halo 3's own: every machine runs the game together. 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, 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.
- 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.
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 always play at 60, 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.
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. |
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. |
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 two 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 two default masters (the project's public master and a second master), 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 other keeps your servers listed. A hidden server reports nowhere; players reach it by Direct Connect.
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: the mission, where it starts, the difficulty, the characters and modifiers. See campaign co-op. |
odst | Halo 3: ODST's campaign or Firefight instead. See Halo 3: ODST. |
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. |
| In either | Default | Meaning |
|---|---|---|
playlist | none | A playlist file: a rotation players vote on from three games up. |
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" or "host", experimental. See networking. |
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 | 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. See players stuck 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. |
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, ODST and Firefight always play at 60. 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. |
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. |
Choose one of playlist, map + game, variant, campaign or odst 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.
[[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.
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 stuck loading
Between games, every player's game gets the next map ready and loads it, and 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.
- Only a player the others wait for counts: one loading on their own is never removed for it.
- 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 do the same, with Host Settings → Kick stalled players; the host is never removed.
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, _STATS_SERVER, _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, _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, _TRUST_PLAYER_GAMES, _DRAW_FRAMES, _TICK_RATE, _ANTI_CHEAT, _BLOCK_VPN, _HIDDEN, _PASSWORD, _SHARE_MODS, _SHARE_RATE, _CUSTOMIZATION, _REQUIRE_CUSTOMIZATION, _NO_VANILLA_CHARACTERS, _ODST_OBJECTS, _HALO3_OBJECTS, _FORGE_MODS, _FORGE_PRIMITIVES, _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,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,gameand[vpn] asn_tablehave no variable: set them indedicated.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, votes, the voice settings, text_chat, share_mods, share_rate | At once. Players already in stay when a limit tightens. |
friendly_fire, stock_map_defaults, team_changing, camera, load_timeout, trust_player_games, draw_frames, tick_rate | From the next game. |
| A server's playlist, or the games in it | 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, rcon_port, rcon_password, [rcon], hidden, chat_log, anti_cheat, block_vpn, network_model, bans, stats_server, customization, require_customization, no_vanilla_characters, [vpn] fail_closed; a new name that changes the server's folder in data; changing between a playlist, a variant and one map and game type; anything about a campaign or ODST server's game | That server restarts once it has no players. |
vpn-local.txt (see refuse a network at once) | Within a minute. |
public_address, bind_address, upnp, auto_reload, [master], [vpn] lists, asns and asn_table | When dedicated restarts. The reload's report says so. |
game, content, data, 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 and when it applies.
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 or replacing mods in
content/Modsdoesn't start a reload: restart the servers that use them. - Settings the remote console changed (
servername,password,maxping) stay until the file's own value of that setting changes. - 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. To have a game come up more often, select it and raise its WEIGHT, 1 to 100.
- 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.
- 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. 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.
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. |
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 team variants by name ("Team Slayer"), 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. |
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. 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.
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 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.
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 prepares the map that won the vote, so everyone loads it together.
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 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. Restart the servers after adding mods.
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. Campaign canvases can't be hosted on a dedicated server yet: canvases play from a lobby you host.
Campaign co-op
A dedicated server can run Halo 3's campaign in co-op, with no player as host, for up to 16 players. Give a [[server]] a campaign setup instead of a playlist, variant or map and game:
[[server]]
name = "Halo 3 Co-op"
port = 49178
max_players = 16
campaign = { mission = 3010, insertion = 0, difficulty = "heroic" }
| Setting | Meaning |
|---|---|
mission | Required. The mission's number: 3005 Arrival, 3010 Sierra 117, 3020 Crow's Nest, 3030 Tsavo Highway, 3040 The Storm, 3050 Floodgate, 3070 The Ark, 3100 The Covenant, 3110 Cortana, 3120 Halo or 3130 Epilogue. |
insertion | Where the mission starts: 0, the default, is its start, and 1 and up its rally points, in the order the Campaign page's rally points list them. |
difficulty | "easy", "normal" (the default), "heroic" or "legendary". |
custom_characters | true: everyone plays as their own Spartan or Elite. false, the default, plays as the Master Chief and the Arbiter. |
customization | Character mods whose characters players can play as, by name, such as customization = ["Armor Pack"], with custom_characters = true. Co-op players all use the server's. |
no_vanilla_characters | With custom_characters: nobody plays as Halo 3's own Spartan or Elite. |
campaign | A mod's campaign, by its key, instead of Halo 3's. Untested on a server so far. |
modifiers | Campaign modifiers: see modifiers, skulls and sprint. |
- Players find the server in the Server Browser, or join it by address, as they join a co-op lobby. 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,gameorbase_map. - 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. - A won mission leads to the next, and after the last, the server starts again from the mission you set. A mission that ended any other way, such as every player leaving, is played again. After
post_game_secondsthe lobby starts the next one. - Players can join a mission under way: they catch up with the server's game while everyone else plays on.
- A mission loads for every player together, and
load_timeoutremoves nobody while it does. - A server has no screen of its own, so its game can drift from its players' while theirs agree. 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.
trust_player_games = false, under[defaults]or in the server's block, turns that off. - Co-op plays host-authoritative networking by default: see networking.
- Co-op games aren't ranked: a campaign server reports no stats.
- Checkpoints stay in the server's memory, for players who join and for reverts. Restarting the server starts the mission you set afresh, and the server never writes a checkpoint for players' own continue.
- The remote console can't choose a campaign server's mission: see co-op servers' console.
Not yet proven on a server:
custom_characters: a server whose players play their own characters is untested, and its lobby may take no joiner.- A mod's campaign (
campaign = "…"in the setup) is untested. - Passenger seats, on the missions that have them, can be wrong for a player who stayed through the end of the campaign, when the server plays its first mission again.
Modifiers, skulls and sprint
A campaign server's modifiers set what the Campaign page's Modifiers do:
campaign = { mission = 3010, 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 |
Campaign files
Besides campaign.map, a campaign server needs each mission's map file and its information. Copy the whole campaign you have installed with --maps campaign:
project-reclaimer dedicated init . --from "your game's folder" --maps campaign
--maps campaigncopies every 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:
[[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 = 6100, insertion = 0, difficulty = "normal" }
| Setting | Meaning |
|---|---|
mode | "firefight" for Firefight. Left out, the server plays the campaign. |
mission | Required. A campaign mission's number, or the number its Firefight 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 | Firefight map | mission, insertion |
|---|---|---|---|
| Prepare to Drop | 4100 | Crater | 6100, 4 |
| Mombasa Streets | 5000 | Crater (Night) | 5000, 7 |
| Tayari Plaza | 6100 | Lost Platoon | 6110, 4 |
| Uplift Reserve | 6110 | Rally Point | 6120, 5 |
| Kizingo Boulevard | 6120 | Rally (Night) | 5000, 8 |
| ONI Alpha Site | 6130 | Security Zone | 6130, 4 |
| NMPD HQ | 6140 | Alpha Site | 6130, 5 |
| Kikowani Station | 6150 | Windward | 6140, 5 |
| Data Hive | 5200 | Chasm Ten | 5200, 6 |
| Coastal Highway | 5300 | Last Exit | 5300, 7 |
| Epilogue | 4200 |
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.
- When the game is over, the same game is played again: an ODST server doesn't go on to a next mission yet. 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 host-authoritative networking by default: see networking. 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, andreach-campaignits 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.- Each brings Guardian with it, which their maps are built on.
dedicated contentlists what the server has.
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.
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. 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. 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 whose games use the mod has players: the servers that use it stop, the item is swapped and they start again. Servers that don't use it carry on.
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 merged map and its pack before the game starts, players' too, so the countdown can wait for it.
- Campaign: a campaign server names its character mods in its setup, such as
campaign = { mission = 3010, difficulty = "heroic", custom_characters = true, customization = ["Armor Pack"] }. A server playing its players' own characters is still untested: see campaign co-op. - 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. Once the files are in and checked, the player joins by themselves, without restarting.
- 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, 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. A kick by vote or by the anti-cheat counts like an admin's. The remote console's
pardonlets 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.
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.
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
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> [reason] | Removes the player. They read who and why, and can't rejoin 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> [time] [reason], unmute <player>, mutes | Nobody hears the player's text or voice chat: the server stops relaying them, for the time given, until unmute or until the server restarts. Rejoining keeps it. mutes lists them. |
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. |
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>]] | Sets the next game without ending this one; without a mode, the rules stay as they are. On its own, says what's next and lists the playlist. |
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 first, and the lobby changes to it once everyone has it. A player whose game can't, withinload_timeout, is removed so the others can play. - 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 or an ODST server, each mission leads to its next or is played again, so the console doesn't choose the game: 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 or odst 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 | name, id, by. |
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. |
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 every 2 seconds, for panels and monitoring that read files rather than talk to the console. dedicated status reads the same file, and takes a server whose file hasn't changed for 30 seconds 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.- 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 relay 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.
Stats
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. 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. - Changing
stats_serverrestarts the server once it has no players.
Stats key data/stats-key.json
Public key XgKK+Btd/7LY…
Whitelist it stats-server allow --key XgKK+Btd/7LY… --name "<server name>"
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; campaign and odst are names it takes too. |
check | Installs missing Workshop items, then checks the configuration, the game folder, each server's games and rules, RCON, the master and the ports. 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. |
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 whose live status stops changing for 90 seconds is stopped and started again.
- 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 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.0.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. |
| 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. |
| 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 the next map loaded | 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. See players stuck loading. |
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.
