A client script is a Lua file the server sends to every player who joins and their game runs, in a sandbox - the mode’s
own half on the screen: a marker, a sound, a bit of UI, a value read from the game. It talks to the server’s game mode through
script events and reads the mode’s state bags; everything else it does is the game’s own Lua, as far as the sandbox
lets it. The KcdMp table is the whole API on this side; the guide says how a script reaches
the player and what the game gives it.
| Guide |
|
| Getting started |
what a client script is, how the server sends it, what of the game’s Lua the sandbox gives it, limits and logging |
Named events with a string payload, both ways between the game mode and the client script: the mode’s SendClientEvent
lands in a handler registered with KcdMp.on_event; KcdMp.send_event goes up into the mode’s OnClientEvent. The
payload is whatever string the two halves agree on - a number, a comma list, JSON.
| Function |
What it does |
KcdMp.on_event |
Registers the handler for one event name from the game mode. |
KcdMp.send_event |
Sends an event to the game mode’s OnClientEvent. |
| Property |
What it holds |
KcdMp.on_any_event |
A catch-all handler for events without one of their own. |
The game mode’s state bags as every client sees them: string keys and values the mode set with SetGlobalState,
SetPlayerState and SetEntityState. The global and the players’ bags arrive whole when the client joins and every change
arrives at once; an entity’s bag comes with the entity when it enters view and goes when it leaves. Values are strings
("3", "true"); a removed key reads nil. Two hooks tell a script about changes.
| Function |
What it does |
KcdMp.on_state |
Registers a handler for one key, whatever bag it changes in. |
The frame hook, small conveniences the KcdMp table offers on top of the game’s own Lua, and a switch a script may flip.
Everything else a client script does - drawing, sounds, reading the player - is the game’s Lua, described in the
guide.
| Function |
What it does |
KcdMp.on_frame |
Runs a function every frame - where a script draws. |
KcdMp.level |
The name of the level the game runs. |
KcdMp.player_pos |
The local player’s position as a string. |
KcdMp.count |
How many entities of a class the level holds. |
KcdMp.census |
The entity classes of the level with the most instances. |
| Property |
What it holds |
KcdMp.label_occlusion |
Whether the labels over the other players hide behind walls. |
The client adds a few commands to the game’s console. A player reaches them through the F9 window of the KCD:MP overlay -
a line typed there is a console command, and a line starting with lua runs Lua directly. The window is closed unless the
server opens it ([client] console in its configuration; a development server does, a public one has no reason to) or the
game runs offline with -KcdMp_console. A script the server sent has no console at all - the sandbox keeps
System.ExecuteCommand away from it - and talks to the server through the script events; a script run by hand through
KcdMp_exec has the game’s whole Lua and may call System.ExecuteCommand("..."). Two things to know about the game’s console:
it splits a line on ; and treats a=b as a variable assignment, so a text with either has to avoid them (the script events
encode their payload for exactly this reason).
| Command |
What it does |
KcdMp_exec |
Runs a Lua file from disk - the development way to try a client script. |
KcdMp_log |
Writes a line into the KCD:MP client log. |
KcdMp_say |
Sends a chat line, as if typed. |
KcdMp_net |
The connection’s figures - snapshots decoded, bytes, the acknowledgement. |
The party this player is in (v38), as the server keeps it - the members with their labels and the others’ vitals at any
distance - for a script that draws its own frames or reacts to the group. The server draws the standard frames unless the
mode hides them per player (ShowPartyFrames on the server); a script that draws its own reads KcdMp.party and hooks
KcdMp.on_party_change. The invitation toast and its keys (Y / N, KcdMp_party_keys changes them) are the client’s own.
