======== Dedicated Server Settings ========

**Server hosting for TTT is VERY early and subject to MANY changes.** We will update this page and add more under this category over time.

This page does **not** explain how to install or start a baseline s&box dedicated server. For general s&box dedicated server setup, see: [[https://sbox.game/dev/doc/networking/dedicated-servers/|s&box Dedicated Servers]]


===== Basics =====

**Our game ident:** 
<code text>
thieves.terrortown
</code>

**TTT-specific config file:**

<code text>
server_settings.json
</code>

On a SteamCMD dedicated install, this should be under the terrortown data folder:

<code text>
steamcmd/ttt/data/thieves/terrortown/server_settings.json
</code>

===== Important! =====

For TTT dedicated servers, set the server starting map in ''server_settings.json'':

<code text>
Server.StartupMap
</code>

**Do not use** a native server manager map field (+map) for your startup map. **It will break on map change**.

If your server manager requires a map value, **use a blank or placeholder value** there, then configure the real startup map in ''server_settings.json''. 

===== Basic Example =====

//The file will be automatically generated the first time you launch TTT.//
//Shortened example. The generated file will include the full curated map list.//


<file json server_settings.json>
{
  "SchemaVersion": 1,
  "Server": {
    "StartupMap": "thieves.rooftops"
  },
  "Lobby": {
    "MaxPlayers": 24,
    "Privacy": 0,
    "MinPlayerCount": 2,
    "MaxRounds": 6,
    "RoundTimeMinutes": 30,
    "PrepareDurationSeconds": 20,
    "HasteMode": true,
    "MapVoteOptionCount": 8,
    "AllowPlayerCosmetics": true
  },
  "MapVote": {
    "Maps": ""
  },
  "AdminSteamIds": []
}
</file>

======= Server settings =======

==== SchemaVersion ====

Generated by the game for future migrations (Leave this alone).

==== Server.StartupMap ====

The map the dedicated server should load on startup.

Example:

<code json>
"StartupMap": "thieves.rooftops"
</code>

This is also used as the server's reset map (the map we load when everyone leaves the server). Keep in mind that the currently available maps are still gated by our whitelist. You can check the current whitelisted maps with 


===== Lobby Settings =====

==== Lobby.MaxPlayers ====

Maximum player count for the Terror Town lobby.

<code json>
"MaxPlayers": 24
</code>

Keep this aligned with any external server manager max-player setting.

==== Lobby.Privacy ====

Controls lobby privacy.

^ Value ^ Meaning ^
| 0 | Public |
| 1 | Private |
| 2 | Friends Only |

For public dedicated servers, use:

<code json>
"Privacy": 0
</code>

==== Lobby.MinPlayerCount ====

Minimum number of players required before normal round start behavior can proceed.

<code json>
"MinPlayerCount": 2
</code>

==== Lobby.MaxRounds ====

Maximum number of rounds before the normal end-of-match or map-vote flow.

<code json>
"MaxRounds": 6
</code>

==== Lobby.RoundTimeMinutes ====

Base round time limit, in minutes.

<code json>
"RoundTimeMinutes": 30
</code>

==== Lobby.PrepareDurationSeconds ====

Preparation phase duration before a round starts, in seconds.

<code json>
"PrepareDurationSeconds": 20
</code>

==== Lobby.HasteMode ====

Controls whether haste mode timing is enabled.

<code json>
"HasteMode": true
</code>


==== Lobby.MapVoteOptionCount ====

Maximum number of map choices shown during a map vote.

<code json>
"MapVoteOptionCount": 8
</code>

Allowed range: 3 to 12.

==== Lobby.AllowPlayerCosmetics ====

Controls whether player cosmetics are allowed.

<code json>
"AllowPlayerCosmetics": true
</code>

===== Map vote rotation =====

The map vote pool is configured through:

<code json>
"MapVote": {
  "Maps": "thieves.rooftops;thieves.dolls;throwupproducs.islandtropical"
}
</code>

Separate map idents with semicolons:

<code text>
org.map;org.map;
</code>

//Duplicate entries are collapsed. Maps outside the built-in curated list are ignored (for now). Make sure at least one valid map remains.//

You can print the current built-in map lists from the server console with:

<code text>
t.server.maps
</code>

===== Admin Steam IDs =====

Dedicated servers can bootstrap admins with:

<code json>
"AdminSteamIds": [
  00000000000000000,
  11111111111111111
]
</code>

Use SteamID64 values.

Invalid or zero IDs are ignored.

===== Required config mode =====

By default, if ''server_settings.json'' is missing, the server may create a default config automatically.

If you want the server to close instead when the config is missing or invalid, launch it with:

<code text>
+t.dedicated.require_server_settings 1
</code>

===== Other dedicated server options =====

These are launch/convar options, not fields inside ''server_settings.json''.

^ Option ^ Default ^ Description ^
| t.dedicated.require_server_settings | 0 | Require a valid ''server_settings.json''. |
| t.dedicated.empty_reset | 1 | Reset the server back to its startup map after all real players leave. |
| t.dedicated.empty_reset.delay | 2.0 | Delay, in seconds, before empty-server reset runs. |

===== Example file =====

You can generate an example settings file from the server console:

<code text>
ttt_write_server_settings_example
</code>

This writes:

<code text>
server_settings.example.json
</code>

The example file is only a template. The active config file must still be named:

<code text>
server_settings.json
</code>

===== Troubleshooting =====

If your settings are not applying:

  * Make sure the file is named ''server_settings.json''.
  * Make sure the file is in the correct game ident's data folder.
  * Restart the dedicated server after editing the file.
  * Check that your JSON is valid.
  * Check the server console for ''[server.settings]'' messages.

Useful successful load message:

<code text>
[server.settings] loaded path=server_settings.json startup_map=thieves.rooftops lobby=True vote_maps=18 admin_count=1
</code>

Useful failure message:

<code text>
[server.settings] failed_to_load path=server_settings.json error=...
</code>

===== Current limitations =====

  * Settings are read once when the server process starts.
  * Restart the server after editing ''server_settings.json''.
  * ''server_settings.example.json'' is only a template.
  * Missing fields may be filled in with defaults on startup.
  * Existing values in your active config should not be overwritten.
  * Keep ''Lobby.MaxPlayers'' aligned with any external server-manager player limit.
  * Dedicated server support is still early and may change.