OnClientEvent

A player’s client script sent an event.

The client’s SendServerEvent(name, payload) lands here. payload is whatever string the client sent - trust it no further than any other input from a player (parse defensively, check the pid may do what it asks). At most 30 events a second per client, a name of at most 64 bytes and a payload of at most 4096 bytes (bytes of UTF-8, not characters); an event over any of these limits is dropped and never reaches the mode, and the server log says so once a second at the most.

A page of the web interface sends events too: its KcdMp.emitServer(name, value) lands here with the frame’s name as source (a text goes as it is, any other value as its JSON - read it with JsonDecode). A page’s payload may be up to 16384 bytes and its names are limited by the frame’s events_out in ui.toml, which the player’s game enforces - the server only checks that the frame exists and that the name is one a page may send. A client script’s events and a page’s share one budget of 30 events and 64 KB a second for the player; what is over it is dropped and counted, never a reason to kick. source is what the player’s game says, so use it to route, not to trust.

Syntax

function OnClientEvent(pid, name, payload, source)
  -- ...
end

Parameter	Type
pid	number	whose client sent it
name	string	the event’s name
payload	string	the string the client sent; "" when none
source	string	"lua" for a client script’s SendServerEvent, the frame’s name for a page’s emitServer - the player’s game’s word, advisory

Returns

nothing

Example

function OnClientEvent(pid, name, payload)
  if name == "echo" then
    SendClientEvent(pid, "echo", payload)               -- a round-trip test
  elseif name == "marker_reached" then
    local n = tonumber(payload)
    if n and n == nextMarker[pid] then advance(pid) end
  end
end

See also

SendClientEvent · SendClientEventToAll · SetGlobalState · the Script events group of the index