Differences

This shows you the differences between two versions of the page.

--- configuring_your_server [2026/05/10 22:40] – frank_lee_smith
+++ configuring_your_server [2026/05/15 02:45] (current) – removed frank_lee_smith
@@ Line 1: / Line 1: @@
-======== Dedicated Server Settings ========
-**Server hosting for TTT is still early and subject to change.** This page documents the current dedicated-server setup as of 5/10/26.
-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/systems/networking-multiplayer/dedicated-servers/|s&box Dedicated Servers]]
-**For the easiest and most stable server hosting on s&box**, your best option is using [[http://physgun.com/thieves|physgun]]. You can use their **built-in package browser** and find us directly!
-{{::phys_ttt.png?400|}}
-===== Basics =====
-**Live package ident:**
-<code text>
-thieves.terrortown
-</code>
-**TTT dedicated config file:**
-<code text>
-server_settings.json
-</code>
-This file lives under the package's game data folder.
-{{::filepath.png?600|}}
-<code text>
-steamcmd/ttt/data/thieves/terrortown/server_settings.json
-</code>
-The game creates this file with active defaults the first time a dedicated server starts without one. We recommend launching the server with the game once before attempting configuration, like so:
-{{::gameident.png?600|}}
-========== Important Startup Map Rule ==========
-Choose the server startup map with the native s&box dedicated launch command as shown above.
-The map ident after the game ident is the boot map. TTT also uses that boot map as the empty-server reset map.
-Do **not** configure the startup map in ''server_settings.json''. The old ''Server.StartupMap'' field is deprecated and ignored.
-===== Launch Example =====
-Typical dedicated launch shape (replace port with your port):
-<code text>
--headless +game thieves.terrortown thieves.rooftops +hostname "Test" +port 00000 +net_query_port 00000 +net_hide_address 0
-</code>
-===== Basic server_settings.json Example =====
-//The generated file includes the full curated map list. This shortened example shows the current editable shape.//
-<file json server_settings.json>
-{
-  "SchemaVersion": 1,
-  "Server": {},
-  "Lobby": {
-    "MaxPlayers": 24,
-    "Privacy": 0,
-    "MinPlayerCount": 2,
-    "MaxRounds": 6,
-    "RoundTimeMinutes": 5,
-    "PrepareDurationSeconds": 20,
-    "HasteMode": true,
-    "HasteStartingMinutes": 5,
-    "HasteMinutesPerDeath": 0.5,
-    "MapVoteOptionCount": 8,
-    "AllowPlayerCosmetics": true,
-    "ProximityVoiceEnabled": false,
-    "ProximityVoiceRange": 2000,
-    "KarmaEnabled": true,
-    "KarmaLowAutoKick": false,
-    "RockTheVoteEnabled": true
-  },
-  "MapVote": {
-    "Maps": "thieves.rooftops;thieves.whitehouse;thieves.minecraft_t5"
-  },
-  "AdminSteamIds": []
-}
-</file>
-{{:server_settings.png?1200|}}
-====== How Settings Persist ======
-==== server_settings.json ====
-''server_settings.json'' is a dedicated-server bootstrap file.
-  * It is read once per server process.
-  * Edit it while the server is stopped, then restart the dedicated server.
-  * Missing fields are backfilled with defaults on startup.
-  * Values from this file survive map changes and full server restarts.
-  * Runtime console edits do not write back into ''server_settings.json''.
-==== Runtime Console Edits ====
-Some settings are also real console variables. Changing them in the server console affects the running server.
-  * Runtime console edits survive normal map travel during the same server process.
-  * Runtime console edits are lost on full server restart unless you also set the matching value in ''server_settings.json'', pass the ConVar from your launch tooling, or persist it through another server-manager mechanism.
-  * Most lobby/bootstrap-only fields have no live console command yet.
-{{::console.png?1200|}}
-==== Map Transitions ====
-Normal map changes, RTV map changes, admin-forced map votes, and empty-server resets snapshot the current host settings before travel. That is why live changes such as ''ttt_karma 0'' or ''ttt_rtv_enabled 0'' carry to the next map in the same process.
-====== Dedicated Config Settings ======
-===== SchemaVersion =====
-Generated by the game for future migrations. Leave this alone.
-===== Server =====
-Currently no active settings are required under ''Server''. Older configs may contain:
-<code json>
-"StartupMap": "thieves.rooftops"
-</code>
-This field is ignored. Set the startup map in the native launch command instead as described earlier.
-===== Lobby =====
-^ Setting ^ Default ^ Console? ^ Takes Effect ^ Persists Restart? ^ Description ^
-| ''MaxPlayers'' | 24 | No | Startup; carried across map travel | Yes | Maximum player count for the lobby. Keep this aligned with any external server-manager player limit. |
-| ''Privacy'' | 0 | No | Startup; carried across map travel | Yes | Lobby privacy: 0 public, 1 private, 2 friends only. Public dedicated servers should use 0. |
-| ''MinPlayerCount'' | 2 | No | Startup; carried across map travel | Yes | Minimum eligible players required before normal round start behavior proceeds. |
-| ''MaxRounds'' | 6 | No direct ConVar | Startup or next round; carried across map travel | Yes | Rounds to play before match end and map vote. |
-| ''RoundTimeMinutes'' | 5 | No direct ConVar | Startup or next round; carried across map travel | Yes | Round duration when haste mode is off. |
-| ''PrepareDurationSeconds'' | 20 | No | Startup or next round; carried across map travel | Yes | Preparation phase duration before a round starts. |
-| ''HasteMode'' | true | No direct ConVar | Startup or next round; carried across map travel | Yes | Enables haste mode. |
-| ''HasteStartingMinutes'' | 5 | No direct ConVar | Startup or next round; carried across map travel | Yes | Public round timer duration before haste overtime starts. Allowed range: 1 to 30. |
-| ''HasteMinutesPerDeath'' | 0.5 | No direct ConVar | Startup or next round; carried across map travel | Yes | Minutes added to the hidden round limit each time a player dies. Allowed range: 0 to 5. |
-| ''MapVoteOptionCount'' | 8 | No direct ConVar | Live for newly-created map votes | Yes | Maximum map choices shown during a map vote. Allowed range: 3 to 12. |
-| ''AllowPlayerCosmetics'' | true | No direct ConVar | Startup or next round; carried across map travel | Yes | Allows s&box player cosmetics. |
-| ''ProximityVoiceEnabled'' | false | No direct ConVar | Live; carried across map travel | Yes | Limits normal alive-player voice by distance during active rounds. Team voice and dead/alive voice filtering are separate. |
-| ''ProximityVoiceRange'' | 2000 | No direct ConVar | Live; carried across map travel | Yes | Voice range in world units when proximity voice is enabled. Allowed range: 500 to 5000. |
-| ''KarmaEnabled'' | true | ''ttt_karma'' | Next round | Yes if set in config | Enables karma penalties, rewards, and low-karma damage scaling. |
-| ''KarmaLowAutoKick'' | false | ''ttt_karma_low_autokick'' | Next round / round end checks | Yes if set in config | Kicks non-host players below the low-karma threshold at round end. |
-| ''RockTheVoteEnabled'' | true | ''ttt_rtv_enabled'' | Live | Yes if set in config | Allows players to start Rock the Vote map-change votes. Votekick and admin-forced map votes are unaffected. |
-===== Karma Console Tuning =====
-Only ''KarmaEnabled'' and ''KarmaLowAutoKick'' are stored in ''server_settings.json''. The lower-level karma tuning values below are runtime ConVars.
-^ ConVar ^ Default ^ Persists Map Travel? ^ Persists Restart? ^ Description ^
-| ''ttt_karma'' | 1 | Yes | Only if also set in ''server_settings.json'' or launch tooling | Enables/disables the karma system. |
-| ''ttt_karma_low_autokick'' | 0 | Yes | Only if also set in ''server_settings.json'' or launch tooling | Enables/disables low-karma auto-kick. |
-| ''ttt_karma_low_amount'' | 300 | Yes | No, unless launch/server tooling reapplies it | Low-karma threshold used by auto-kick. |
-| ''ttt_karma_strict'' | 1 | Yes | No, unless launch/server tooling reapplies it | Uses stricter low-karma damage scaling. |
-| ''ttt_karma_ratio'' | 0.001 | Yes | No, unless launch/server tooling reapplies it | Scales karma penalties from victim karma. |
-| ''ttt_karma_kill_penalty'' | 30 | Yes | No, unless launch/server tooling reapplies it | Base full team-kill penalty percentage. |
-| ''ttt_karma_starting'' | 1000 | Yes | No, unless launch/server tooling reapplies it | Normal starting karma. |
-| ''ttt_karma_max'' | 1100 | Yes | No, unless launch/server tooling reapplies it | Maximum karma. |
-| ''ttt_karma_min_required'' | 800 | Yes | No, unless launch/server tooling reapplies it | Karma value below which damage scaling applies. |
-| ''ttt_karma_round_increment'' | 15 | Yes | No, unless launch/server tooling reapplies it | Round-end karma recovery. |
-| ''ttt_karma_round_heal_on_teamkill'' | 10 | Yes | No, unless launch/server tooling reapplies it | Round-end recovery when the player team-killed. |
-| ''ttt_karma_clean_bonus'' | 25 | Yes | No, unless launch/server tooling reapplies it | Extra clean-round karma bonus. |
-| ''ttt_karma_traitorkill_bonus'' | 10 | Yes | No, unless launch/server tooling reapplies it | Bonus for valid traitor kills. |
-| ''ttt_karma_clean_half'' | 0 | Yes | No, unless launch/server tooling reapplies it | Optional falloff for high-karma recovery bonuses. |
-Example:
-<code text>
-ttt_karma 0
-ttt_karma_low_autokick 1
-ttt_karma_low_amount 250
-</code>
-===== Map Vote Rotation =====
-The dedicated map vote pool is configured through:
-<code json>
-"MapVote": {
-  "Maps": "thieves.rooftops;thieves.dolls;throwupproducs.islandtropical"
-}
-</code>
-Separate map idents with semicolons, commas, or newlines.
-<code text>
-orgident.mapident;orgident.mapident
-</code>
-Duplicate entries are collapsed. Maps outside the built-in curated list are ignored for dedicated map vote rotation. Make sure at least one valid map remains.
-You can print the current built-in map whitelist from the server console with:
-<code text>
-t.server.maps
-</code>
-The old ''MapVote.Whitelist'' and ''MapVote.Blacklist'' fields are migrated into ''MapVote.Maps'' when possible. Use ''MapVote.Maps'' going forward.
-===== Admins And Roles =====
-Dedicated servers can bootstrap admins with:
-<code json>
-"AdminSteamIds": [
-  00000000000000000,
-  11111111111111111
-]
-</code>
-Use SteamID64 values. Invalid or zero IDs are ignored.
-''AdminSteamIds'' bootstraps Admin role assignments from ''server_settings.json''. Live role edits are stored separately in ''admins.json'' in the same data area and survive map transitions and server restarts.
-Useful role commands:
-^ Command ^ Persists? ^ Description ^
-| ''ttt_addadmin STEAMID64'' | Yes, to ''admins.json'' | Assign Admin. |
-| ''ttt_removeadmin STEAMID64'' | Yes, to ''admins.json'' | Remove Admin. |
-| ''ttt_addmod STEAMID64'' / ''ttt_removemod STEAMID64'' | Yes, to ''admins.json'' | Add or remove Moderator. |
-| ''ttt_addowner STEAMID64'' / ''ttt_removeowner STEAMID64'' | Yes, to ''admins.json'' | Add or remove Owner. |
-| ''ttt_setrole STEAMID64 ROLE'' | Yes, to ''admins.json'' | Replace assignable roles with one role. ROLE is ''mod'', ''admin'', or ''owner''. |
-| ''ttt_clearrole STEAMID64'' | Yes, to ''admins.json'' | Remove assignable roles. Founder is not removed. |
-| ''ttt_listadmins'' | No change | Print admin IDs. |
-| ''ttt_listroles'' | No change | Print assigned roles. |
-The listen host/founder is derived per session and is not written to ''admins.json''.
-===== Other Runtime Console Options =====
-These are launch/convar/runtime options, not fields inside ''server_settings.json''.
-===== Map And Vote Commands =====
-^ Command ^ Description ^
-| ''rtv'' | Starts a Rock the Vote map-change vote if ''ttt_rtv_enabled'' is true. Players can also type ''/rtv'' or ''!rtv'' in chat. |
-| ''votekick PLAYERNAME'' | Starts a public votekick. Players can also type ''/votekick'' or ''!votekick'' in chat. |
-| ''ttt_forcemapvote'' | Admin/host command that forces the map-vote flow. It is not blocked by ''ttt_rtv_enabled''. |
-| ''changelevel MAPIDENT'' | Changes to a map ident. |
-| ''map MAPIDENT'' | Alias for ''changelevel''. |
-| ''scene SCENEFILE'' | Host-only scene change command for scene files. Use map idents for normal server operation. |
-===== Deprecated Or Ignored Settings =====
-^ Old Setting ^ Current Status ^
-| ''Server.StartupMap'' | Ignored. Use the native ''+game org.game org.map'' launch argument. |
-| ''MapVote.Whitelist'' | Migrated to ''MapVote.Maps'' if ''Maps'' is missing. |
-| ''MapVote.Blacklist'' | No longer the dedicated rotation model. If only ''Blacklist'' is present, defaults are backfilled into ''MapVote.Maps''. |
-===== 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 ''server_settings.json''.
-  * Check that your JSON is valid.
-  * Check the server console for ''[server.settings]'' messages.
-  * Check the server console for ''[lobby.settings] applied'' to confirm the resolved lobby/rule settings.
-  * Check the server console for ''[server.launch]'' messages to confirm the native boot map.
-Useful successful load message:
-<code text>
-[server.settings] loaded path=server_settings.json lobby=True vote_maps=18 admin_count=1
-</code>
-If an old config still contains ''Server.StartupMap'', you may see:
-<code text>
-[server.settings] loaded path=server_settings.json lobby=True vote_maps=18 admin_count=1 legacy_startup_map_ignored=thieves.rooftops
-</code>
-Useful default/backfill messages:
-<code text>
-[server.settings] missing path=server_settings.json; created active defaults. Edit server_settings.json and restart the dedicated server to customize settings.
-[server.settings] defaults_backfilled path=server_settings.json
-</code>
-Useful failure message:
-<code text>
-[server.settings] failed_to_load path=server_settings.json error=...
-</code>
-Useful launch message:
-<code text>
-[server.launch] boot_context game=thieves.terrortown boot_map=thieves.rooftops launch_map=thieves.rooftops source=GameNetworkManager.OnStart dedicated=True
-</code>
-Useful applied settings message:
-<code text>
-[lobby.settings] applied public, 6 rounds, 5m, prep 20s, haste 5m +0.5m/death, curated, 8 vote maps
-</code>
-===== Current Limitations =====
-  * ''server_settings.json'' is read once per server process.
-  * Restart the dedicated server after editing ''server_settings.json''.
-  * Runtime console changes are convenient for the current process, but should be mirrored into config or launch tooling if they need to survive a full restart.
-  * Not every ''server_settings.json'' field has a matching live ConVar yet.
-  * Keep ''Lobby.MaxPlayers'' aligned with any external server-manager player limit.
-  * Set the startup map with the native launch command, not ''server_settings.json''.
-  * Dedicated server support is still early and may change.