---@meta

-- KCD:MP (KCD Multiplayer) - the client script API - the `KcdMp` table, Lua 5.4.
-- Definitions for the Lua language server (LuaLS - the VS Code "Lua" extension and its kin): completion, hover
-- documentation and diagnostics while writing a script. Generated from the reference - do not edit.
-- https://docs.kcd-mp.com

---@class KcdMp
KcdMp = {}

-- ======== Script events =========================================================
-- 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.

---Registers the handler for one event name from the game mode.
---
---One handler per name; a second call replaces the first. The handler gets the payload and the name. An error inside it
---is logged (`[KcdMp] event 'name' handler: ...`), never fatal. Events without a handler go to `KcdMp.on_any_event`.
---@param name string the event's name, as the mode sends it
---@param fn function `function(payload, name) end`
function KcdMp.on_event(name, fn) end

---Sends an event to the game mode's OnClientEvent.
---
---The server accepts at most 30 events a second and 4 KB each from one client; more is dropped. The payload travels as the
---string given (`""` without one) - the mode trusts it no further than any other input.
---@param name string the event's name
---@param payload? string the string to send
function KcdMp.send_event(name, payload) end

---A catch-all handler for events without one of their own.
---
---Set it to a function to receive every event no `KcdMp.on_event` handler claims. `nil` (the default) ignores them.
---@type function|nil
KcdMp.on_any_event = nil

-- ======== State bags ============================================================
-- 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.

---Registers a handler for one key, whatever bag it changes in.
---
---One handler per key. The handler gets the new value (`nil` when removed), the scope (`"global"`, `"player"`, `"entity"`)
---and the id. Runs before `KcdMp.on_state_change` for the same change.
---@param key string the key to watch
---@param fn function `function(value, scope, id) end`
function KcdMp.on_state(key, fn) end

---The bags - global, per player, per entity - as tables of strings.
---
---`KcdMp.state.global[key]` is the world's bag; `KcdMp.state.player[pid][key]` a player's (every player's, from the join
---on; the client's own pid is `KcdMp.player_id`); `KcdMp.state.entity[id][key]` an entity's while it is in view. A
---player's table appears with their first key and goes with their leave; read `KcdMp.state.player[pid]` defensively.
---@type table
KcdMp.state = nil

---This client's own player id.
---
---Set when the server welcomes the client; `nil` before. The key into `KcdMp.state.player` for the client's own bag, and
---the pid the mode sees this player as.
---@type number
KcdMp.player_id = nil

---A hook called on every change of any bag.
---
---Set it to a function to hear every change: `scope` is `"global"`, `"player"` or `"entity"`; `id` the pid or entity id
---(`0` for the global bag); `value` the new string, `nil` when the key was removed. An error inside it is logged, never fatal.
---@type function|nil
KcdMp.on_state_change = nil

-- ======== Helpers ===============================================================
-- 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.

---Runs a function every frame - where a script draws.
---
---The game's drawing functions (`System.DrawLabel`, `System.DrawLine` ...) show what they draw for one frame only, so a
---mark that should stay is drawn again every frame from here; a timer would blink. The handler gets the frame's length in
---seconds. Several handlers may be registered; one that raises an error is logged (`[KcdMp] frame handler: ...`) and
---removed, so a broken script cannot fill the log sixty times a second. The handlers go with the script set on a
---`/reload`. Keep the work small: it runs on the game's thread, every frame.
---@param fn function `function(dt) end` - `dt` the frame time in seconds
function KcdMp.on_frame(fn) end

---The name of the level the game runs.
---@return string `klaster`, `trosecko`, `kutnohorsko`; `nil` when unknown
function KcdMp.level() end

---The local player's position as a string.
---
---A quick readout for logs - `"1280.5 1088.0 26.3"`. For numbers, read the player entity directly:
---`player:GetWorldPos()` gives `{x=, y=, z=}`.
---@return string `"x y z"` with one decimal; `"none"` before the player exists
function KcdMp.player_pos() end

---How many entities of a class the level holds.
---@param cls string an entity class name (`"NPC"`, `"Horse"`, `"AnimDoor"`, `"Stash"` ...)
---@return number `0` when none or the class is unknown
function KcdMp.count(cls) end

---The entity classes of the level with the most instances.
---@param top number how many classes to list
---@return number total `total, list` - the number of entities and a string `"Class n, Class n, ..."` of the `top` most common
---@return string list
function KcdMp.census(top) end

---Whether the labels over the other players hide behind walls.
---
---`true` by default: a label is hidden when something stands between the player's eyes and the body. Set it to `false` to see
---every label through everything - a debugging aid, and a choice a mode may make for its players.
---@type boolean
KcdMp.label_occlusion = nil

-- ======== The party =============================================================
-- 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.

---The party as the server last sent it.
---
---`id` is 0 in no party. `members` come in join order, the client's own player among them; each has the pid, the name,
---the mode's `label`, and the vitals of the last update - `health`, `maxHealth`, `stamina`, `maxStamina`, `injuries`
---(bits as the game's body parts 1-6), `dead`, `bleeding`, `loading` (not in the world) - with `vitals` false until the
---first update arrived (the own entry never has them: the game's HUD does). `frames` says whether the server's frames are
---shown to this player. Read it live; a copy goes stale within half a second.
---@type table
KcdMp.party = nil

---A hook called with the party after every change.
---
---Set it to a function to hear every PartyState (membership, leader, name, labels, the frames switch) and every vitals
---update (at most twice a second). The argument is `KcdMp.party`; an empty party (`id` 0) means the player left or the
---party ended. An error inside is logged (`[KcdMp] on_party_change: ...`).
---@type function|nil
KcdMp.on_party_change = nil