Server configuration

The server reads server.toml from its working directory (or --config <path>). Every key is optional and the values below are the defaults; a command-line flag overrides the file (--max-players 64 beats [server] max_players). The file the server ships carries the same keys with a line per group and a link here; without any server.toml the server runs on the defaults alone, which for two keys - the player records and the game’s tables - means less than the shipped file gives (noted below). Where a key shapes what a game mode sees, its API page is linked.

[server]

Key	Default
name	"KCD:MP dev server"	the server’s name in the browser and the welcome
motd	""	a message shown to every joining player
port	7777	UDP
max_players	32	the slot count; player ids run to max_players - 1 (GetMaxPlayers). Fifty players walking, riding and fighting at once cost the server about a tenth of one core and 1.5 MB/s outbound; the count is yours to choose
password	""	players must send it to join; "" = open
level	"klaster"	the level every client boots - klaster, trosecko or kutnohorsko (levels, GetLevel)
build_hash	""	require this game build; "" = any
stale_session_seconds	5.0	a fresh join under a name in use replaces its holder once that client has been silent this long; 0 = never
log_file	"server.log"	every line the console shows is written to this file too, next to the server; the previous run’s file is kept as server.log.1. "" = the console only

[gamemode]

Key	Default
script	"gamemodes/freeroam.lua"	a .lua script or a .dll compiled against KcdMp.Api (path.dll:TypeName picks a type); "" = the built-in freeroam
watch	false	true re-reads the script when its file changes on disk - a development server (ReloadGameMode); the client scripts’ folder is watched too

[client]

The game mode’s client half: Lua files the server sends to every joining player and runs in their game, in a sandbox that reaches nothing outside the game (the client guide). A mode without one needs nothing here.

Key	Default
scripts	""	a folder of .lua files, sent in name order; "" = the client/ folder next to the game mode’s script or plugin (gamemodes/arena/arena.lua + gamemodes/arena/client/*.lua) - the built-in mode has none unless a folder is named. At most 64 files, 256 KB each, 2 MB together. /reload sends the folder again
console	false	true lets the players open the F9 window of the KCD:MP overlay on this server - the console line and the debug view. A convenience for a development server, not a security boundary: the server never trusts what a client says either way

[rates]

Key	Default
tick_hz	30	the simulation rate - how often OnTick runs
snapshot_hz	30	snapshot rounds per second, at most tick_hz
workers	0	threads for the per-client phase; 0 = the cores minus two

[aoi]

Key	Default
radius	200.0	metres a client sees around itself; 0 = everyone sees everyone
cell	64.0	the grid cell size, metres

[world]

Key	Default
time	"07:30"	the world clock at start (SetWorldTime)
time_ratio	15.0	game seconds per real second; 0 freezes the clock (SetTimeRatio)
rain	-1.0	rain forced on every client, 0 .. 1; below 0 = the weather’s own (SetRain)
weather	""	the sky every client follows - a preset or a profile; "" = the level’s own (SetWeather)
weather_blend	10.0	seconds a weather change blends in over
max_entities	256	horses, pickups, props, actors and dogs the world holds at once

[persistence]

Key	Default
file	"data/players.json"	the player records - visits, play time, last position, the mode’s saved data (GetSavedPlayer); "" = memory only (the value without a server.toml). The server store (server.json) and the bans (bans.json) live beside it

[validation]

Key	Default
max_speed	12.0	metres per second a report may move a player; faster is refused and the client pulled back; 0 = off
heightmap	""	the level’s terrain, e.g. "data/heightmaps/{level}.hmap" - the files tools/KcdMp.ExportHeightmap.exe writes from your own game (Exporting the terrain); "" = no terrain check (GetTerrainHeight)
navmesh	""	the level’s navigation mesh, e.g. "data/navmesh/{level}.knav" - the files tools/KcdMp.ExportNavmesh.exe writes from your own game (Exporting the navigation mesh); with it the NPC actors walk around walls and FindPath answers; "" = straight lines
collision	""	the level’s collision geometry, e.g. "data/collision/{level}.kcol" - the files tools/KcdMp.ExportCollision.exe writes from your own game (Exporting the collision geometry); with it RayCast answers and the floor under a player counts as the ground; "" = none
line_of_sight	false	with the geometry: a hit or shot claimed through a wall (or a closed door) is refused; off, the server only logs what it would have refused
no_clip	false	with the geometry: a player whose reported step goes through a wall (or a closed door) is pulled back to the last accepted position; off, the server only logs what it would have refused
max_below_terrain	6.0	metres a player may be under the terrain (cellars, mines)
max_above_terrain	60.0	metres over it (towers, cliffs); with the collision geometry the floor under the player - a bridge, an upper storey - is the ground, so a storey’s worth (10) does

[master]

The server list: the server announces itself there every interval_seconds and shows up in every launcher’s Servers tab. The environment variables KCDMP_MASTER_URL and KCDMP_MASTER_ADDRESS replace the two addresses when set, and the command line’s --master / --master-address beat both.

Key	Default
url	"https://kcd-mp.com/server-list"	the public list; another list’s address, or "" = announce nowhere (a private server)
interval_seconds	60	how often
public_address	""	the address the list should show; "" = the one the master sees the heartbeat come from

[accounts]

Key	Default
registration	true	false = no new /register (existing names still log in)
login_grace_seconds	180	a registered name has this long after joining to /login
login_hold	true	a registered name waits frozen in a world of its own until its login; false = it plays as a guest among everyone meanwhile
min_password_length	4
admins	[]	registered names whose owners are admins once logged in (IsPlayerAdmin); a name not registered yet becomes an admin the moment its owner registers it

[commands]

Key	Default
builtin	true	false = no built-in chat commands at all; the mode answers everything
public	["help", "pos", "players", "items", "uptime"]	the built-ins anyone may use; every other one answers admins only
disabled	[]	built-ins switched off by name, e.g. ["horse", "rain"]; the mode may still answer them

[audit]

The inventory audit (OnPlayerAuditViolation): the server keeps a shadow of what each player’s records explain and compares it with the inventory the client reports.

Key	Default
enabled	true
action	"log"	log, kick or ban when a violation stands
strikes	2	reports in a row a discrepancy must show in
ban_seconds	0	for action = "ban"; 0 = for good
guarded_categories	"Armor,MeleeWeapon,MissileWeapon,Ammo,Helmet,Hood"	the item categories judged (items); the rest are learned, never judged

[combat]

The model is the Combat guide.

Key	Default
pvp	true	false: players cannot lock on to or hurt each other
respawn_seconds	10	a dead player stands up again at their spawn after this; 0 = the mode calls SpawnPlayer
max_reach	4.0	metres the attacker and the target may be apart for a claim to count
fight_timeout	30.0	seconds without a blow that end a fight; 0 = never by time
claim_window_ms	1500	a hit counts only this long after the attacker’s swing; 0 = always
damage_scale	1.0	a multiplier on every hit
max_claim_damage	80.0	without the tables, a claim above this is clamped
tables	"data/combat/items.json"	the game’s tables: weapons, armour, the item, soul, buff and mesh catalogues - the file tools/KcdMp.ExportTables.exe writes from your own copy of the game (Exporting the game’s tables); "" (the value without a server.toml) = no tables: the damage the clients report, clamped by max_claim_damage, and the catalogues by GUID only
claimed_buffs	[]	the buff classes the server takes over (buffs, ClaimBuffClasses)
potion_speed	2.0	a potion’s regeneration runs this many times faster than the game’s own
alcohol_per_content	0.01	a drink’s alcohol content × this on the blood-alcohol level
alcohol_decay	0.00125	taken off the level per second
drunk_threshold	0.32	drunk from here up; sober again from half of it down
hangover_seconds	120.0	the hangover after sobering
attack_scale	0.32	a weapon’s table attack × this = its damage before armour
ranged_scale	0.0077	an ammunition’s attack × the launch speed × this = a projectile’s damage before armour
armour_pivot	50.0	the armour on the struck part that halves a hit (d / (d + pivot), 85 % at most)
fist_damage	6.0	bare-handed, before armour
body_parts	""	rewrites of the claim’s body part, "claim=part,..."; normally empty
max_stamina	100.0
stamina_regen	15.0	per second, after 1.5 s without a cost; halved with an injured head or torso
attack_stamina_cost	10.0	a swing (× 1.2 slash or smash, × 0.5 bare-handed, × 1.25 with an injured arm)
hit_stamina_damage	12.0	a hit taken
shot_stamina	15.0	a shot
shot_interval_ms	400	shots closer than this are refused
shot_window_seconds	6.0	a ranged hit counts within the flight time plus this
block_stamina_cost	10.0	a swing blocked
sprint_stamina_cost	4.0	per second at a sprint
jump_stamina_cost	6.0	per jump
injury_threshold	15.0	a hit of at least this injures the part struck
bleed_per_damage	0.015	a stab or a slash bleeds this × the damage in health per second
max_bleed	1.0	health per second at most
bleed_seconds	40.0	how long a bleed lasts

[party]

The groups the server keeps for the game mode’s own commands (the parties guide): the invitation, the frames on the members’ screens, the no-friendly-fire rule. The commands themselves - /invite, /accept, /p - are the mode’s; the shipped freeroam mode has them.

Key	Default
max_size	5	members per party (at least 2)
invite_timeout	30	seconds until an unanswered invitation runs out
frames	true	the party frames on every player’s screen; a mode can switch them per player (ShowPartyFrames)
leader_leaves	"next"	what the leader’s leaving does: "next" hands the lead to the next member in join order, "disband" ends the party
friendly_fire	false	true lets members hurt each other; off, a hit between members is refused before the mode hears of it, like one between teammates

[effects]

Key	Default
range	150.0	metres from the point within which players get a mode’s effect, decal or sound (SpawnEffect, SpawnDecal, PlaySound); 0 = everyone in that virtual world

[actors]

How an NPC actor fights back and blocks; its wounds follow the [combat] injury and bleeding keys like a player’s.

Key	Default
fight_back	true	a blow on an actor makes the attacker its opponent
swing_interval	1.8	seconds between its swings
reach	2.2	metres it swings from; an unarmed actor closes to 0.7 of it
chase_speed	2.0	metres per second after its opponent
chase_range	30.0	an opponent farther than this is given up
attack_scale	1.0	a multiplier on the blow the victim’s game computed
max_damage	60.0	a blow does at most this
block_chance	0.5	how often an armed actor raises its guard against a swing; 0 never, 1 every time
block_hold	0.7	seconds the guard stays up
drop_weapons	true	a dying actor’s held weapon and shield fall as pickups everyone can take (its preset’s first melee weapon and first shield); false = it drops nothing

[spawn]

Key	Default
x, y, z, yaw	1280.0, 1088.0, -1.0, 0.0	the default spawn (GetDefaultSpawn); z below 0 = on the terrain
horse_soul	Horse2’s GUID	the breed of horses made without one (horses; a name or an id works too)
clothing_preset	UC_HenryTrosky’s GUID	the outfit players spawn in (clothing presets)
weapon_preset	sword_shield_4_01’s GUID	their weapons (weapon presets)
items	["torch_weapon"]	given at a player’s first spawn of a session, on top of the presets (items)
stat_level	15	strength, agility, vitality and speech raised to this at the spawn; 0 = the level’s own 5
appearances	thirteen generic men	the souls whose faces players get, one each by a hash of the name, unless the mode sets one (souls, SetSpawnInfo)