Server configuration

Every setting in server-config.json: name and port, the server list, relay, player limits, file downloads and updates.

Where the file is

server-config.json lives in the main server folder, next to resources/ and admins.xml. The server creates it by itself the first time it starts in an empty folder, together with the starter resources. A server created in the launcher gets a ready file with its server list key.

The file is read at startup. After a change, save it and restart the server. A wrong value (e.g. a name that is too short or a port out of range) stops the start, and the console tells you which option to fix.

This is JSON: names and texts in quotes "...", a comma after every option except the last one, true / false without quotes. A missing comma or bracket will stop the server from starting.

Full example

{
  "title": "My server",
  "subtitle": "Freeroam, races and drift",
  "port": 7777,
  "public_port": null,
  "max_slots": 32,
  "password": "",

  "server_id": 123,
  "server_key": "key-from-the-launcher",

  "relay": true,
  "upnp": true,

  "max_ping": 300,
  "max_ping_seconds": 30,
  "require_verified_client": false,
  "launcher_skins": true,

  "disabled_resources": ["test"],
  "client_loadstring": true,
  "max_event_kb": 64,

  "http_download_url": "",
  "download_kbps": 0,

  "browser_domains": ["youtube.com"],
  "browser_devtools": false,

  "max_connections_per_ip": 8,
  "connections_per_minute": 30,
  "flood_ban_seconds": 60,

  "auto_update": true,
  "db_key": ""
}

These are all the options with their default values (except the name, the key and the sample lists). null or an empty text "" means the option is not used. You don't have to list everything: every option you leave out has the default value from the tables below.

Basics

Option	Default	Meaning
`title`	`"Serwer Trilogy Hub"`	Name on the server list, 3-40 characters.
`subtitle`	`""`	Short description under the name, up to 80 characters.
`port`	`7777`	Game port, 1024-65535. On a hosting, use the port assigned by the panel. The same number is used for TCP and UDP: open (forward) both protocols.
`public_port`	none	The port seen from the internet, when the hosting forwards a different external port to the one in `port`. This is the one shown on the list.
`max_slots`	`32`	Player limit.
`password`	`""`	Server password, up to 64 characters. Empty = open server.

The name and description can't contain HTML tags or profanity.

Players type the password in the launcher when joining. After 5 wrong tries they wait a minute, and every next 5 makes the lock longer (up to an hour). The password only works on a server with a server_key.

Server list

Option	Meaning
`server_id`	The server's number in Trilogy Hub.
`server_key`	The key the server uses to appear on the list.

You get both in the launcher when you create a server. Without them the server works, but it won't show up on the list, and players can only join by IP:port.

server_key is like a password to your server's list entry. Never share it, and don't run the same server in two places at once (e.g. locally in the launcher and on a hosting).

Connection and relay

Option	Default	Meaning
`relay`	`true`	`true`: players connect directly, and through the Trilogy Hub relay when the server port can't be reached from the internet. `"always"`: always through the relay, the server's IP address stays hidden. `false`: no relay.
`upnp`	`true`	The server tries to open its port on the router by itself (UPnP), TCP and UDP. When that works, players connect directly.
`udp`	`true`	Player movement (positions, animations, vehicles) goes over UDP on the same port number, so a lost packet doesn't hold up everything else. If UDP is blocked, the player switches to TCP on their own after a few seconds. `false` turns UDP off. Through the relay, movement always goes over TCP.
`admission`	on in the launcher	Overload protection. When the computer running the server can't keep up (CPU, memory, server delay or the host's game FPS dropping), new players from outside wait in a queue and join on their own once the load drops. Players already in the game and a player on the same computer always get in. On a hosting, enable it with `{"enabled": true}`.

Thanks to the relay, a server running at home can be joined without port forwarding and without tools like Hamachi.

Players

Option	Default	Meaning
`max_ping`	`300`	Highest allowed ping in ms. `0` turns the limit off.
`max_ping_seconds`	`30`	How many seconds the ping may stay too high before the server kicks the player.
`require_verified_client`	`false`	`true` only lets in players with a verified device (signed in to the launcher).
`launcher_skins`	`true`	`false`: players join as CJ, without the outfit chosen in the launcher.

Resources and scripts

Option	Default	Meaning
`disabled_resources`	`[]`	Resources that DON'T start with the server, e.g. `["test", "old_mode"]`. Everything else in `resources/` starts by itself. Start a disabled resource with the `start <name>` command.
`client_loadstring`	`true`	`false` turns off `load` / `loadstring` in client scripts. On the server they always work. Safer when resources don't compile code on players' computers.
`element_data_client_changes`	`"allow"`	`"deny"`: client scripts cannot change any element data (client `setElementData` is rejected, the server gets `onPlayerChangesProtectedData`). Single keys: the fifth argument of `setElementData`.
`max_event_kb`	`64`	Largest size of the arguments of an event sent by a player (`triggerServerEvent`), in kilobytes. Bigger events are rejected.

File downloads

Option	Default	Meaning
`http_download_url`	none	Address of a web server with the resource files. Players download `<address>/<resource>/<file>` from it instead of from the game server.
`download_kbps`	`0`	Per-player download speed limit for files from the game server, in KB/s. `0` = no limit.

Files from http_download_url are checked against their checksum. If a file fails to download or differs from the one on the server, the player gets it from the game server, so a wrong address never blocks joining.

In-game browser

Option	Default	Meaning
`browser_domains`	`[]`	Domains that resources may open in the in-game browser, e.g. `["youtube.com", "my-site.com"]`. Subdomains included. The player still has to agree (`requestBrowserDomains`).
`browser_devtools`	`false`	`true` allows opening the browser developer tools (`toggleBrowserDevTools`).

Connection flood protection

Option	Default	Meaning
`max_connections_per_ip`	`8`	How many connections one IP address may have at once.
`connections_per_minute`	`30`	How many new connections per minute the server accepts from one IP address.
`flood_ban_seconds`	`60`	For how many seconds the server blocks an address that went over the limit.

The defaults suit most servers. Raise them when many players join from one address (e.g. an internet cafe or a dorm).

Updates and databases

Option	Default	Meaning
`auto_update`	`true`	Every 15 minutes the server checks for new versions and installs them when nobody is playing. Resources and the config are not touched. `false` turns updates off.
`db_key`	none	Key for the encrypted `databases.json.enc` file with MySQL connection details (you can set the `TH_DB_KEY` environment variable instead).

Every update is signed by Trilogy Hub, and the server rejects a file without a valid signature. When players stay on the server all the time, the new version waits up to 2 hours and then comes in with a countdown in the chat. If the new version fails to start, the server goes back to the previous one by itself.