State bags

A state bag holds string keys and values the mode sets on the world, a player or an entity, and every client’s Lua reads — the way a mode’s client half learns a team, a round, a marker or a flag carrier without a script event per client.

Setting state

Function
SetGlobalState(key, value), GetGlobalState(key), GetGlobalStates() → {key = value}	the world’s bag
SetPlayerState(pid, key, value), GetPlayerState(pid, key), GetPlayerStates(pid)	a player’s
SetEntityState(id, key, value), GetEntityState(id, key), GetEntityStates(id)	an entity’s, by net id

A value is kept as a string — numbers and booleans are converted; nil removes the key.

SetGlobalState("round", 3)
SetPlayerState(pid, "team", "red")
SetEntityState(id, "owner", GetPlayerName(pid))

What the clients see

On every client: kcd2mp.state.global.round, kcd2mp.state.player[pid].team (every player’s, from the join on; the client’s own pid is kcd2mp.player_id), kcd2mp.state.entity[netId].owner (while the entity is in view: the bag follows its spawn and is dropped with its despawn). Two hooks — kcd2mp.on_state_change for everything and kcd2mp.on_state(key, fn) for one key. See Client API → State.

The global and the players’ bags are roster-wide: a newcomer gets them whole after the roster, before their own spawn. A change goes out at once, one reliable message per key.

Limits and lifetime

• A key is 1–48 characters without control characters; a value at most 1 KB; 64 keys a bag. A set beyond them returns false and logs a line.
• Nothing is persisted: a player’s bag goes with the session, an entity’s with the entity, and a hot reload clears them all.
• SetPlayerData / SetEntityData stay the mode’s private storage — the clients never see those. SetServerData / SetSavedData are the persisted stores.