Getting started

A KCD:MP server is one program that the players’ games connect to. It runs one game mode - the rules of that server: where players spawn, what the chat and the commands do, who may hurt whom, what stands in the world. A game mode is a script or a plugin you write; the server calls it when something happens (a player joins, dies, types a command) and the script calls the server back (send a message, move a player, spawn a horse). A mode may also have a client script: its own half that runs inside each player’s game, for the things only the player’s screen can show.

Piece	What it is	Written in
The server	the dedicated server program, a folder you run on Windows or Linux: server.toml, the game modes, the data it keeps	-
A game mode	the rules of one server; one per server, reloaded without a restart	Lua or C#
A client script	the mode’s half on the player’s game: a marker, a sound, a bit of UI, a value read from the game; sent to the players by the server	Lua
A web interface	the mode’s pages drawn over the game: menus, shops, a login screen, its own chat, scoreboard or loading screen; sent to the players by the server with the client scripts	HTML, CSS and JavaScript (the guide)
The world data	the level’s tables, terrain, navigation mesh and collision geometry, exported from your own copy of the game	-

The server works out of the box: the modes that ship with it - freeroam.lua, duel_arena.lua and basicrp.lua (role-play on a database of your own) - are complete servers, and a mode that defines nothing is a valid mode - the server spawns everyone at its default point and answers its own chat commands. Everything on these pages is what you add.

The pages, in order

1. Setting up - the server folder, the first run, joining it, picking a mode, giving the server the game’s data, your editor. Step by step, whatever language you script in.
2. AI assistants - this documentation as plain text and as language-server definitions, and a CLAUDE.md that starts a game-mode project with a coding agent.
3. Server configuration - every key of server.toml, with its default.
4. Guides - one job per page: exporting the game’s tables, the terrain, the navigation mesh and the collision geometry from your game; putting a server on the public list; connecting a database; cart routes and players’ own carts; a character creation screen; knocking players out and carrying them; picking pockets; throwing riders and pulling them from the saddle; keeping what a player discovered, and a character’s stats, skills and perks; changing the interface and making a web interface of your own.
5. The API for your language: Lua (the server and the client side, every callback and function on its own page) or C# (the same server API as typed interfaces); for a web interface’s pages, the web interface SDK (the KcdMp object every page gets).
6. The reference - the game’s lists: every item, soul, buff, perk, mesh, preset, animation clip, door and container, and the stats and skills, by the keys the functions take; and the built-in chat commands.

Conventions

The same everywhere, whatever the language:

• metres in the level’s world space, as the server’s /pos command reports positions; z below 0 when spawning or teleporting means “on the terrain”;
• degrees for a yaw, 0 = facing +Y, counter-clockwise;
• 0xRRGGBBAA colors - 0xFF0000FF is opaque red;
• milliseconds for times and timers; the world clock in hours (13.5 = 13:30);
• a player is a pid (0 to the slot count minus one, reused after a disconnect); a world entity - a horse, a pickup, a prop, an NPC actor, a dog - is an id, unique while it lives;
• the keys of game things - items, souls, buffs, meshes - are an id, a name or a GUID from the reference; a call given an unknown key fails quietly (nil, false) and the server log says why.