Hosting a Server

Hosting a Server

avalanche-server is Project Avalanche's dedicated multiplayer server. It runs the rides of up to 64 players, checks every run against the game's rules, relays the riders to each other, runs server scripts and sends its resources (maps, gamemodes, riders, scripts) to the players who join. It is headless: it needs no GPU, sound card, display or input device, so it runs on any small Linux or Windows machine or in a container.

There are two ways to host:

• From the launcher (HOST): the launcher's HOST page makes a server folder, starts the same avalanche-server on your computer and joins it with the game. Good for playing with friends.
• A dedicated server: download the server on its own, set it up once and run it from a console, as a service or in Docker. This is what the rest of these pages describe.

Downloads

Every release on the project's GitHub Releases page has:

File	What it holds
ProjectAvalanche-server-windows-x64.zip	avalanche-server.exe, server.toml.example, windows-service.txt, README.txt, THIRD_PARTY_NOTICES.txt
ProjectAvalanche-server-linux-x64.tar.gz	the folder ProjectAvalancheServer with avalanche-server, server.toml.example, avalanche-server.service, README.txt, THIRD_PARTY_NOTICES.txt
ProjectAvalanche-windows-x64.zip, ProjectAvalanche-linux-x64.tar.gz	the game and the launcher; they carry avalanche-server too (for HOST)

The Linux build needs only the C and C++ runtime libraries every Linux system has. For a container, see Running in Docker.

The game data: your own disc

The server reads part of the game's rules (21 MB: the tuning, the events, the drops' courses) from your own SSX (2012) Xbox 360 disc image. No game data ships with the server. setup takes exactly the files it needs from the image and checks each against the known retail disc:

avalanche-server setup /path/to/your/ssx.iso --out data

On Windows:

.\avalanche-server.exe setup D:\path\to\your\ssx.iso --out data

The output ends with a summary such as data: 342 members, 21.2 MB (342 written, 0 kept) in 0.3 s; the known pressing (660dcce05812cf68). If you already set the game up with the launcher, you can take the files from its game data folder instead: setup --from-extraction <the launcher's GameData folder>.

Some features need more of the disc. Add them with --with:

Class	Needed for
verify	a custom map in a round mode (race, trick, survive): the server simulates the map's start with a rider
collision	a map that is a layout on a disc drop (it needs that drop's terrain)
ghosts	the events' rival replays (optional; nothing on a server requires them today)

For example avalanche-server setup /path/to/your/ssx.iso --out data --with verify,collision. Running setup again is safe, also on a server's data folder after it ran: it keeps what is already correct and leaves alone what the server writes there (the table under The data folder) and the folders and files server.toml names there (the resources and rules folders, your own blocklist). Anything else at the folder's top makes it refuse ("holds files that are not a server's (…)"), so it never writes into a folder that is not a server's.

First start

1. Copy server.toml.example to server.toml and edit it (every key: Server Configuration).

2. Check everything:

   avalanche-server check
   

   check reads server.toml, the keys and every file of the rules data, checks every drop the instances name against the rules (a drop of your disc, not a tutorial, an event of the instance's mode, and in a round mode a start the server knows; each problem at its line and column in server.toml), prints what the server would do and exits with code 0, or 2 on any problem. A missing server.toml is not an error: the defaults are used. When [resources] start names resources, an event's mode is only noted: a resource may change an event, and the server checks it again at its start with the resources running.

3. Run it:

   avalanche-server
   

   run is the default command. The first start makes the server's two key files in the data folder, netcode.key and identity.key. Keep them and back them up. Players' games remember the server's identity key and refuse a server whose key changed. Never share them.

The server prints listening on 0.0.0.0:27450 (UDP and TCP); identity key … once it is up. Open the ports in your firewall (Ports and Firewalls). Type help in its console for the commands (Server Console).

Stopping: type stop, press Ctrl-C, or send SIGTERM. The server lets a round under way finish (at most [stop] round_end seconds, 60 by default), tells the riders, leaves the server list, then exits. A second Ctrl-C or signal ends it at once.

The command line

The server's own help (avalanche-server --help):

Project Avalanche's dedicated multiplayer server

Usage: avalanche-server [OPTIONS] [COMMAND]

Commands:
  run     Run the server (the default)
  keygen  Make the data folder's keys (refused if a key file exists: keys are never replaced)
  setup   Take the rules subset (the files a server reads) from your own SSX (2012) disc image into the data folder (the resources folder the configuration names there is left as it is)
  check   Check the configuration, the data folder's keys, its rules subset (every member and hash) and the configured drops against the rules, and say what the server would do
  rcon    Run a console command on a server with an operator key (the remote console) and print its answer
  help    Print this message or the help of the given subcommand(s)

Options:
      --config <CONFIG>  The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>      The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help             Print help
  -V, --version          Print version

avalanche-server setup --help:

Take the rules subset (the files a server reads) from your own SSX (2012) disc image into the data folder (the resources folder the configuration names there is left as it is)

Usage: avalanche-server setup [OPTIONS] [ISO]

Arguments:
  [ISO]  The disc image (an Xbox 360 ISO of the retail disc)

Options:
      --from-extraction <GAME_DATA>  Take the members from the game's own data folder (the launcher's GameData, with big/) instead of an image
      --out <OUT>                    The folder to write (default: the data folder, --data)
      --with <WITH>                  Optional classes besides the rules: collision, ghosts, verify (comma separated). Maps: a map in a round mode needs verify (the start is checked with a rider's animation), a layout needs collision (its base drop's terrain)
      --config <CONFIG>              The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>                  The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help                         Print help

avalanche-server run --help:

Run the server (the default)

Usage: avalanche-server run [OPTIONS]

Options:
      --stop-with-input  Stop when stdin ends (a program that starts the server and holds its stdin, as the launcher's Host does, so the server never outlives it)
      --config <CONFIG>  The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>      The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help             Print help

avalanche-server check --help:

Check the configuration, the data folder's keys, its rules subset (every member and hash) and the configured drops against the rules, and say what the server would do

Usage: avalanche-server check [OPTIONS]

Options:
      --config <CONFIG>  The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>      The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help             Print help

keygen and rcon are described on Operators and Remote Console.

Exit code	Meaning
0	done (check: nothing wrong; run: stopped normally)
1	run: the server could not start, or a second stop signal ended it at once; rcon: the command failed on the server
2	check, setup, keygen, rcon: a problem with the configuration, the data folder, the disc image, a key file or the connection
3	rcon: the server refused the request

The data folder

Everything the server writes is in its data folder (--data, data by default):

Path	What
big/, content.tsv, subset.json	the rules data setup took from your disc
netcode.key, identity.key	the server's keys (made at the first start, never replaced)
acl.toml, bans.toml	the Access Control List and the bans and mutes
logs/server.log	the log (Logs and Metrics)
resources/	your server resources
resource-state/	the server's own checked copies of its running resources
script-data/<resource>/storage.bin	the server scripts' saved data
Blocklists/	the blocklists the server follows (Blocklists)

Hosting from the launcher

The launcher's HOST page sets a server folder up for you (<app folder>/Server, see Installing Mods for the app folder): name, port, player count, password, the drop or one of your installed maps and its mode, LAN and query answers, port mapping. Prepare the folder takes the rules from the game data the launcher already set up (no disc needed again) and copies a chosen map's packages into the folder's resources. Start runs avalanche-server with that folder, shows its output and joins it with the game. A server.toml you edited by hand is kept: the page asks before it replaces it. The server stops with the launcher.

Next

• Server Configuration: every key of server.toml
• Running as a Service and Running in Docker
• Maps and Gamemodes on a Server