Settings

A setting is a value the server owner sets: the server’s name, its password, the rotation, or a mod’s own, such as a score limit.

Where a value comes from

Each source wins over the ones above it:

1. the setting’s default
2. the file, --config server.jsonc
3. the environment: SET_ and the name in capitals, as SET_HOSTNAME
4. the command line: --set name=value
5. an admin’s /set, or the mod: these last until the server stops or /reset

--lock name=value wins over all of them: /set and the mod are refused, as server.score_limit is locked at 30. A mod that writes a locked setting as it loads does not start.

The server reads the file again as each match starts, so an edit takes effect at the next match for any value no one /set since.

server.jsonc

{
  "hostname": "Hill #1",
  "admins": ["3f9a0c41d2e87b6a5c0f1e2d3c4b5a69"],
  "rotation": [
    { "map": "yard", "gametype": "tdm" },
    { "map": "testbed", "gametype": "zombies" }
  ],
  "score_limit": 30
}

Values are JSON. On the command line and in /set, a string may be written as plain text: /set hostname Hill #1. A value outside its range is refused, with the range: score_limit: 1 to 999, got 2000.

A bad value in the file is printed, and the one under it used. A bad --lock locks the value under it. A bad --set or environment variable stops the server. A value for a setting no module declares is kept, and checked once one does.

The engine’s settings

Setting	Default	What it does
hostname	engine	the server’s name in the server list
password	none	a password to join; see below
rotation	none	the matches to play in turn; see matches
rotation_order	in_order	in_order or shuffle
max_rate	256 KB	the most bytes a second a player is sent
max_per_ip	4	the most players from one address
max_snapshot_rate	60	the most updates a second a player is sent: 10, 12, 15, 20, 30 or 60
developer	false	for mappers: an admin’s /set show_triggers true and /set show_nav true show them the triggers and the navmesh near them
admins	none	the admins, by identity; the file’s alone
masters	the public list	the server lists the server is on, read again at each match start; the file’s alone
download_urls	none	up to 4 mirrors of the server’s files, read once at start; the file’s alone
server_content_cleanup_delay_hours	24	how long files of an old version of the mod are kept for players still downloading them, 0 for none; read once at start

/set can’t change a setting marked “the file’s alone”. Give it in the file, the environment or --set.

The password

password locks the server: players type it to join, and the server list shows a padlock. It is up to 32 letters, digits and symbols, without spaces. /set password "" unlocks the server. A new password keeps everyone playing; only new joins need it. Admins need none.

Only admins read it, with /set password. Nothing else shows it: /set answers password set, the console prints who set it, and a refused one is never repeated. The server prints each join it refuses for a wrong or missing password.

A mod’s settings

A mod declares its own. The stock mod has two:

Setting	Default	What it does
score_limit	50	the team points that win team deathmatch, 1 to 999
rounds	5	the rounds of a zom match, 1 to 99

Name one bare, or as module.name when two modules share a name: tdm.score_limit. In the environment, __ stands for the dot: SET_TDM__SCORE_LIMIT=30.

/set score_limit shows a setting’s value, default, range and help.

Secrets

A mod’s secret, such as a database password, is a setting the mod declares as one. Give it in the file or the environment: --set and --lock refuse it, as others on the machine can read a command line, and /set does not know it. The server never prints a secret: logs and errors show <secret players_db> in its place. An optional secret left blank is unset.