Server Configuration

Server Configuration

The server reads one TOML file, server.toml beside it (another file: --config <file>). A missing file means every default. The file is read strictly:

• An unknown table or key is an error, so a typing mistake never goes unnoticed.
• Every error names the file, line and column: server.toml:3:1: …. The server does not start, and check exits 2.
• The file may be at most 64 KiB.

Run avalanche-server check after every change.

A complete example

A race server with three drops in turn, answering the server browser and the LAN tab:

# server.toml: a race server with a rotation of three drops

[server]
name = "Alps Race Night"
description = "Three Alps races in turn. Be nice in the chat."
bind = "0.0.0.0"          # "::" listens on IPv6 and IPv4
port = 27450              # UDP for the game, TCP for the join; the query uses port + 1
max_players = 16
password = ""             # empty: anyone may join
# icon = "icon.png"       # a 96 x 96 PNG beside this file, at most 64 KiB

[game]
mode = "race"
rotation = ["exp_alps_grandgolliat_drop_1_race", "exp_alps_grandgolliat_drop_4_race", "exp_alps_grandgolliat_drop_7_race"]
rewinds = 3               # "on", "off", or 1 to 99 rewinds a run
ghosts = "off"
ghost_style = "character" # how other riders are drawn: "character" or "hologram"
min_players = 1
lobby_wait = 15
load_timeout = 60
countdown = 5
round_limit = 600
results_time = 15

[chat]
enabled = true

[discovery]
query = true              # answer the server browser's ping (UDP, port + 1)
lan = true                # answer the LAN tab (UDP 35450)
region = "eu-central"
tags = ["race", "alps"]

[port_mapping]
enabled = false           # true: ask your router to open the ports (UPnP, PCP, NAT-PMP)

[metrics]
enabled = false           # true: GET /metrics on the game port (TCP), Prometheus format
allow = ["127.0.0.1", "::1"]

[stop]
round_end = 60            # a stop waits at most this long for a round under way

check prints what the server will do with it:

server.toml: valid
  name "Alps Race Night"
  …
  instance 1: race on exp_alps_grandgolliat_drop_1_race, rewinds Limit(3), the event's explore ghosts off, riders drawn as character, at most 16 riders
    rounds: at least 1 riders, the lobby 15 s, loading at most 60 s, the countdown 5 s, a round at most 600 s, the results 15 s; the rotation exp_alps_grandgolliat_drop_1_race, exp_alps_grandgolliat_drop_4_race, exp_alps_grandgolliat_drop_7_race

check reads the drop names as names. The server's start loads each drop's rules and refuses a name the disc does not have, or a drop whose event is of another kind than the mode, for example: instance 1: exp_alps_grandgolliat_drop_1_race is not a trick event (its event type is EventType_RaceGhosts).

[server]

Key	Default	Allowed
name	"Project Avalanche server"	1 to 40 characters the game can draw; no space at either end, no runs of spaces
description	""	at most 250 characters, no control characters
bind	"0.0.0.0"	an IPv4 or IPv6 address to listen on, not a multicast address. "0.0.0.0": every IPv4 address. "::": IPv6 and IPv4
port	27450	1 to 65535. The game uses this port on UDP, the join on TCP, the query port + 1 on UDP
max_players	16	1 to 64
password	"" (open)	at most 64 bytes, no control characters
icon	none	a .png path relative to server.toml, beside it or below it, no .., at most 255 bytes. The image must be 96 × 96 pixels and at most 64 KiB. The server browser shows it

[game] and [[instance]]

A server runs one or more instances: rooms, each with its own track, mode, players, standings and chat. One instance goes in [game]; several go in [[instance]] tables (1 to 8), never both. A joining player goes to the first instance with room.

Key	Default	Allowed
mode	"freeride"	freeride, race, trick, survive, death (a survive instance whose maps run as survive-to-death)
drop	"exp_alps_vorassay_drop_3"	one of the disc's drops, by its name. The launcher's HOST page lists every name
map	none	a map of the server's resources, by its content id (slope:map/course). See Maps and Gamemodes on a Server
rotation	none	1 to 32 levels ridden in turn: drop names, map ids (they contain :), or { map = "<id>", gamemode = "<id>" }. Not for freeride
gamemode	none	a gamemode of the server's resources (gm:gamemode/bots): the instance's maps run under its rules
rewinds	"on"	"on" (the event's own count), "off", or a number 1 to 99 (rewinds per run)
ghosts	"off"	"on" keeps the event's own ghost riders
ghost_style	"character"	how other players are drawn: "character" (their rider) or "hologram" (the Explore racers' glitching look)
capacity	max_players	[[instance]] only: 1 to 64 riders in this instance (never more than max_players)
min_players	1	1 to 64, at most the capacity: riders needed before a round starts

Use one of drop, map and rotation. A freeride instance rides one level, so it takes drop or map, no rotation.

The round cycle. Race, trick and survive instances run rounds: the lobby, loading, the countdown, the run, the results, then the next level of the rotation. A player who joins during a round watches it and rides the next one. Freeride has no rounds and refuses these keys. All values are seconds.

Key	Default	Allowed	What it is
lobby_wait	15	0 to 600	the lobby waits this long once min_players are there (a full instance starts at once)
load_timeout	60	10 to 600	riders whose level has not loaded by then watch the round
countdown	5	3 to 60	the countdown before GO
round_limit	600	30 to 3600	a round ends at the latest after this
results_time	15	5 to 120	how long the results stay up

Kinds of drops per mode. A drop's event decides what it is: race takes the disc's race events, trick its trick events, survive and death its survive events; freeride takes any drop.

Two instances, a free ride room and a trick room:

[server]
name = "Two Rooms"
max_players = 24

# a free ride room for 8 riders
[[instance]]
mode = "freeride"
drop = "exp_alps_vorassay_drop_3"
capacity = 8

# a trick room for 16, two drops in turn, at least 2 riders per round
[[instance]]
mode = "trick"
rotation = ["exp_alps_grandgolliat_drop_1_trick", "exp_alps_grandgolliat_drop_4_trick"]
capacity = 16
min_players = 2
round_limit = 300

[chat]

Key	Default	Allowed
enabled	true	false turns the players' chat off (the console's say still reaches them)

[discovery]

How players find the server. See Query and LAN Discovery; whether the server is on the project's list: The Server List.

Key	Default	Allowed
public	true	false keeps the server off the project's server list: it sends the list no heartbeat (The Server List)
query	same as public	true answers the server browser's UDP query on port + 1 (its ping and player count). The list checks a listed server's query: public = true with query = false is refused, and query = false without public makes the server unlisted
lan	false	true answers the game's LAN tab (UDP broadcast, port 35450)
region	""	at most 32 characters of a-z, 0-9 and -
tags	[]	at most 8 tags, each 1 to 24 characters of a-z, 0-9 and -, none twice
contact	""	at most 128 printable ASCII characters: how the server list's operator can reach you (never shown to players)
blocklist	none	a file of your own blocked resource files (Blocklists); relative paths are below the data folder

region and tags describe the server in the project's server list.

There is no key for the server list itself: it is always the project's. A server.toml from an earlier version with masters = [...] still loads; the key is not read, and check says so. masters = [] there, without public, keeps the server unlisted.

[port_mapping]

Off by default. See Ports and Firewalls.

Key	Default	Allowed
enabled	false	true asks the router to forward the game, join and query ports. Refused when bind is an IPv6 address alone
methods	["upnp", "pcp", "natpmp"]	the methods to try, in order; at least one, none twice
gateway	""	the router's IPv4 address; empty: the default route's gateway
lifetime	7200	120 to 86400 seconds per mapping; renewed at half of it

[resources] and [mods]

See Server Resources and Client Mods on Servers.

Key	Default	Allowed
[resources] folder	"resources"	where the resources are; relative paths are below the data folder
[resources] start	[]	at most 256 resource names (1 to 64 characters of a-z, 0-9, _, ., -; not ssx or ava; none twice), started in this order
[resources] files_url	[]	at most 4 download mirrors, each http:// or https://host[:port]/path
[mods] client_mods	"presentation"	"presentation", "any" or "none": what players' own mods may do on this server
[mods] client_scripts	true	whether players' own mods may run their scripts on this server

[metrics]

See Logs and Metrics.

Key	Default	Allowed
enabled	false	true serves GET /metrics on the game port (TCP)
allow	["127.0.0.1", "::1"]	at most 32 addresses or ranges (10.0.0.0/8, 192.168.1.*) that may read it

[stop]

Key	Default	Allowed
round_end	60	0 to 600 seconds a stop waits for a round under way to finish

[data] and [validation]

You rarely need these.

Key	Default	Allowed
[data] folder	"big"	the rules data setup wrote; relative paths are below the data folder

The server checks every run it is told about. [validation] sets what a failed check does: "warn" (logged, the result stands), "invalidate" (the result leaves the standings, the rider rides on) or "kick" (the rider's connection ends). Every check defaults to "invalidate".

Key	What it checks
speed	the rider's speed against the game's speed limits
step	the distance between two reports: no teleports beyond what a rewind or respawn allows
splits	the splits in order, each at its height
finish	the finish inside the finish volume
clock	the run's clock against the server's time
tricks	the rate of trick points against the trick table's maximum