AI assistants

Every page here is written once, as Markdown, and published twice: as the page you are reading and as plain text an assistant can read whole. Point a coding agent at the files below and it works from the same reference you do - the real syntax of every function, the real keys of every item - instead of what it remembers of some other game’s API.

The files

/llms.txt - the index: what KCD:MP is, how to read the rest, links to every file below. A few KB.
/llms-small.txt - everything a game mode is written from, in one file: these getting-started pages, the guides, every server callback and function, the client API, the web interface SDK, the map of the reference lists. About 1.9 MB, ~475k tokens - more than most assistants hold at once: give it whole to one with a very large context, or keep a copy an agent searches. An agent working in a project does better with the definitions below and the pages as Markdown, one at a time (the CLAUDE.md says how).
/_llms-txt/getting-started-and-guides.txt - these getting-started pages and the guides, for any language. About 300 KB.
/_llms-txt/lua-server-api.txt - the Lua server API alone: the Lua guides, every callback and function. About 1.4 MB.
/_llms-txt/lua-client-api.txt - the client API alone. About 140 KB.
/_llms-txt/web-interface-sdk.txt - the JavaScript a web interface’s pages call: every function, handler and property of the KcdMp object. About 90 KB.
/_llms-txt/reference-overview.txt - the map of the reference lists, the weather presets, the built-in chat commands, stats and skills. About 35 KB.
/_llms-txt/reference-<list>.txt - one file per reference list, 60 KB to 2.7 MB each: items, souls, looks, buffs, meshes, clothing-presets, animations, particle-effects, audio-triggers, levels, voice-lines. The shorter lists - consumables, weapon presets, perks, decal materials, activities - are single pages: fetch them as Markdown (below).
/_llms-txt/c-plugins.txt - the C# tier. About 120 KB.
/llms-full.txt - everything, the reference lists included. About 11 MB - more than a context window holds; use the sets.
/KcdMp.d.lua and /KcdMp-client.d.lua - the API as Lua language server definitions: every function, callback and constant with its types and documentation, in LuaLS ---@param / ---@return form. About 700 KB and 60 KB.
/KcdMp-web.d.ts - the web interface SDK as TypeScript types: the KcdMp object a web interface’s pages call, with its documentation, for an editor’s completion and type checks in plain JavaScript or TypeScript. About 30 KB.

The three definition files ship in the server folder’s sdk/ too (Setting up).

Every page has a Markdown twin. Replace the trailing / of a page’s address with .md: /lua/server/functions/setspawninfo/ is also /lua/server/functions/setspawninfo.md - the source of the page, without the navigation, in one request. Names are lowercase in addresses (SetSpawnInfo → setspawninfo). An agent that looks pages up as it works should fetch these, not the HTML.

The files follow llmstxt.org and are built from the same source as the site on every publish, so they cannot fall behind it. Nothing here is behind a login or a rate limit; a plain curl gets any of them.

A game mode with Claude Code

A game mode is one Lua file next to the server, named in its server.toml (Setting up). Two files in the folder the mode lives in - the server’s gamemodes/ folder or a repository of its own - turn a coding agent from a guesser into a colleague who has read the manual:

The definitions. The server’s gamemodes/ folder already carries a .luarc.json that points the Lua language server at sdk/KcdMp.d.lua. For a mode in a folder of its own, copy the file (or download it, above) next to the script and add:

{ "runtime.version": "Lua 5.4", "workspace.library": ["."], "workspace.checkThirdParty": false }

An editor with the “Lua” extension (sumneko / LuaLS) then completes every name and flags one that does not exist; an agent working in the folder reads the same file and can run the same check.

The instructions. Save this as CLAUDE.md - Claude Code reads it at the start of every session; the same file as AGENTS.md serves Codex, Cursor and the others. It tells the agent where the API is, what it must not invent, and the handful of rules a mode lives by.

# <mode name> - a KCD:MP game mode

This is a game mode for KCD:MP (KCD Multiplayer), the multiplayer platform for Kingdom Come: Deliverance II:
one Lua 5.4 script the dedicated server runs. The server calls the script's callbacks (`OnPlayerConnect`,
`OnPlayerDeath`, `OnTick` ...) and the script calls the server's functions (`SendClientMessage`, `SetSpawnInfo`,
`CreateActor` ...).

## The API is documented, never guessed

- `KcdMp.d.lua` in this folder is the whole game mode API - every function, callback and constant with its types
  and documentation, in Lua language server form. Look every name up there before using it; it is large, so search
  it rather than reading it whole. If it is missing, fetch https://docs.kcd-mp.com/KcdMp.d.lua.
- Before the first change of a session read https://docs.kcd-mp.com/lua/server/getting-started.md - how the server
  runs a script, the tick, ids and units, errors. The index by topic, https://docs.kcd-mp.com/lua/server.md, lists
  every callback and function in a line each: the way to find the function for a job.
- For a job a guide covers - building on the map, a web interface, carts, saving progress, the interface - read the
  guide as Markdown; https://docs.kcd-mp.com/guides.md lists them.
- For one function or callback fetch its page as Markdown: https://docs.kcd-mp.com/lua/server/functions/<name>.md
  or https://docs.kcd-mp.com/lua/server/callbacks/<name>.md, the name in lowercase (`SetSpawnInfo` → `setspawninfo.md`).
- Only the functions and callbacks the documentation lists exist. There is no `Player` object, no event emitter,
  no `require("KcdMp")`, no API from any other game. If a function is not on https://docs.kcd-mp.com/lua/server/
  it does not exist - say so rather than inventing one.
- Keys of game things - items, souls, looks, buffs, meshes, outfits, animation clips, sounds, doors, voice lines -
  come from the reference lists (https://docs.kcd-mp.com/reference.md; one file per list at
  https://docs.kcd-mp.com/_llms-txt/reference-<list>.txt - they are big, fetch the one you need). Never make a
  key up. Keep the name or the GUID in the script, not the numeric id: ids shift with game patches.
- A web interface - the mode's own pages drawn over the game - is HTML and JavaScript calling the `KcdMp` object:
  the guide is https://docs.kcd-mp.com/guides/web-interface.md, the types https://docs.kcd-mp.com/KcdMp-web.d.ts.

## How the server runs the script

- Plain Lua 5.4 with the standard library; one file, or a folder of files joined by `require` (relative to the
  script). The API is globals the server registers before the script runs; the callbacks are globals the
  script defines.
- Everything runs on the simulation thread, one tick at a time, 30 times a second. No threads, no locks, no
  races - and a slow callback stalls every player. Heavy work goes on a timer (`SetTimer`), not in `OnTick`.
- `pid` is a player, `0` to `GetMaxPlayers() - 1`, reused after a disconnect: keep the pid while a player is on,
  check `IsPlayerConnected(pid)` before trusting one kept across ticks. `id` is a world entity (a horse, a
  prop, an NPC actor), `nil` from every getter once it is gone.
- Positions are metres in the level's world space (`z < 0` = on the terrain), yaw is degrees, colors are
  `0xRRGGBBAA` (the constants name the usual ones), times are milliseconds, the world clock is hours.
- A bad key or id never raises: the call returns `nil` or `false` and the server log says why. Check returns.
- A runtime error inside a callback is logged and that callback's effect is skipped; a syntax error stops the
  server at start (after a `/reload` it leaves the built-in freeroam in charge until the next reload).
- Chat commands arrive in `OnPlayerCommandText(pid, cmd, args)`; parse `args` with `sscanf(args, "ud")`
  (`u` a player, `d` a whole number, `f` a number, `s` a word, `z` the rest of the line, `?` optional). Return
  `true` when handled, `false` to let the server's built-in commands have it.
- What a player carries, their purse, their levels and their perks are records the server checks (`[audit]` in
  `server.toml`): give and take only through `GivePlayerItem`, `GivePlayerMoney`, `SetPlayerInventory` and
  `SetPlayerProgress` - they count at once, and `GetPlayerInventory` reads them back - and save on
  `OnPlayerInventoryChange`. An item that reaches a game any other way is removed once the server runs `[audit] mode =
  "enforce"` (it starts in `observe`, which only logs); a mode that hands out in another way vouches in
  `OnPlayerNativeItem`, `OnPlayerAuditViolation` or `OnPlayerProgressViolation`.
- `Log(...)` writes to the server log with a `[lua]` prefix.

## Working here

- The mode is `<mode>.lua` in this folder. `server.toml` names it under `[gamemode] script`; `watch = true` there
  reloads it on save, `/reload` in chat does the same by hand.
- Before calling a change done, run the Lua language server's check over the folder
  (`lua-language-server --check .` - `.luarc.json` points it at `KcdMp.d.lua`): an unknown name or a wrong
  argument type is a diagnostic there and a silent `nil` on the server. Zero diagnostics is the bar.
- Run a local server with `KcdMp.Server --gamemode <mode>.lua` and read its log for `[lua]` lines.
- The modes that ship with the server - `freeroam.lua`, `basicrp.lua` (with a web interface of its own),
  `duel_arena.lua`, `plots.lua` (building plots with the in-game editor) and the `marker` example with its client
  half - are the style to follow.

Then ask for the mode in plain words - a capture-the-flag with two teams, a flag prop in each camp, ten minutes on the HUD clock - and the agent fetches what it needs. Claude Code fetches the URLs itself; for an agent without web access, keep the whole reference beside the mode - it searches the file like the rest of the folder:

curl -O https://docs.kcd-mp.com/llms-small.txt

A C# plugin project works the same way with sdk/KcdMp.Api.dll and its .xml in place of the definitions file - the agent reads the interfaces and their summaries from the project’s reference - and c-plugins.txt in place of the Lua API in the instructions.

Other assistants

ChatGPT, Gemini, a chat window: attach llms-small.txt as a file - at ~475k tokens it is too long to paste, and only a very large context takes it whole - or just the set the job needs (the guides, the server API, the web interface SDK); add the reference list the mode needs.
Cursor: Settings → Indexing & Docs → Add Doc with https://docs.kcd-mp.com/llms-small.txt, then @Docs in a prompt.
Anything that crawls: robots.txt allows every agent, and /sitemap-index.xml lists every page.

Privacy Cookie settings