Lua Event API

Status date: 2026-02-12

This document reflects the current runtime Event API.

Event API coverage: 100% for the documented function contract.

Implementation Status

Component	Status	Notes
Event transport (LuaEventPacket)	Implemented	Explicit EventName, enum EventType, Data payload.
Client -> Server transport	Implemented	NetworkClient.SendLuaEvent(eventName, data, reliable)
Server -> Client transport	Implemented	NetworkServer.EmitToClient/EmitToAll
AddEventHandler	Implemented	Shared on client + server runtime.
RemoveEventHandler	Implemented	Remove by handler id, function ref, or all for pattern.
TriggerEvent	Implemented	Local dispatch + optional network routing by target.
Event envelope schema	Implemented	name/payload/source/target/timestamp/correlationId/version
Namespace/permission policy	Implemented	Role-aware namespace ACL + target restrictions for remote clients.
Deterministic policy	Implemented	Enforced on client publish, server publish, and remote inbound.
Reliability control-plane	Implemented	system:event_ack, retry, timeout, dedup, durable pending state.

API Surface

AddEventHandler

S Shared (Client & Server)

local handlerId, err = AddEventHandler(eventName, handler)

Parameters:

• eventName (string): event name or wildcard pattern ("resource:*").
• handler (function): callback called with a single envelope argument.

Returns:

• handlerId (string): unique id on success.
• err (nil|string): nil on success or error code.

Handler envelope fields:

• name
• payload
• source
• target
• timestamp
• correlationId
• version

RemoveEventHandler

S Shared (Client & Server)

local err = RemoveEventHandler(eventName, handlerIdOrHandler)

Parameters:

• eventName (string): event name or wildcard pattern used at registration.
• handlerIdOrHandler (string|function|nil):
• string: remove specific handler id
• function: remove by function reference
• nil: remove all handlers registered for that pattern

Returns:

• err (nil|string): nil on success or error code.

TriggerEvent

S Shared (Client & Server)

local err = TriggerEvent(eventName, payload, options)

Parameters:

• eventName (string): namespaced event name.
• payload (table): event payload.
• options (table, optional):
• target: routing target
• reliable (bool, default true)
• deterministic (bool, default false)
• correlationId (string, optional)

Returns:

• err (nil|string): nil on success or error code.

Target Routing Rules

Server runtime TriggerEvent(..., options.target=...):

• "local": local handlers only
• "server": local/server domain only
• "all": all connected clients
• number: one client id
• table: list of client ids

Client runtime TriggerEvent(..., options.target=...):

• allowed: "local"/"client" (local only), "server" (route upstream)
• denied: "all", explicit client id, explicit client id list (ERR_PERMISSION_DENIED)

Envelope Schema

Runtime envelope used by handlers and transport for custom events:

local event = {
    name = "custom:example",
    payload = { value = 1 },
    source = "client",
    target = "server",
    timestamp = 1739366400000,
    correlationId = "uuid-like-id",
    version = "1.0",
    reliable = true,
    deterministic = false
}

Namespace + Permission Policy

Namespaces:

• resource
• player
• chat
• ui
• system
• custom

Role-aware publish model:

• server system: all namespaces
• server admin: resource, player, chat, ui, custom
• server moderator: player, chat, ui, custom
• client runtime / remote player: player, chat, ui, custom

Subscribe model:

• client + server runtime can subscribe to all namespaces.

Compatibility:

• unscoped names (no :) resolve to custom namespace policy.

Deterministic Policy

Rules:

• deterministic events must be reliable=true
• client cannot publish deterministic events to remote targets (server/clients)
• remote inbound deterministic events are rejected
• server deterministic publish requires deterministic tick context
• server deterministic allowlist enforcement is available (configured pattern list)

Deterministic violations return:

• ERR_DETERMINISTIC_POLICY

Reliability Model

Reliable custom events (reliable=true) use:

• lane: reliable ordered transport
• ack event: system:event_ack
• timeout event: system:event_timeout
• retry interval: 1000ms
• timeout window: 5000ms
• max retries: 3
• inbound dedup by correlationId

Best effort (reliable=false) uses:

• lane: unreliable transport
• no ack/retry tracking

Durability:

• pending reliable state is persisted and restored on restart/reconnect for both server and client runtimes.

Error Codes

• ERR_INVALID_EVENT_NAME
• ERR_NAMESPACE_NOT_ALLOWED
• ERR_INVALID_HANDLER
• ERR_HANDLER_NOT_FOUND
• ERR_PAYLOAD_INVALID
• ERR_INVALID_OPTIONS
• ERR_PERMISSION_DENIED
• ERR_TRANSPORT_FAILED
• ERR_NOT_CONNECTED
• ERR_NOT_FOUND
• ERR_DETERMINISTIC_POLICY

Runtime Hooks (Function Callback Model)

Legacy/compatibility function hooks remain supported:

• OnLuaEvent(playerId, eventName, data) (server)
• onResourceStart(resourceName) (server)
• onResourceStop(resourceName) (server)
• onResourceRestart(resourceName) (server)
• onResourceStartError(resourceName, error) (server)
• onResourceStopError(resourceName, error) (server)
• onClientResourceStart(resourceName) (client)
• onClientResourceStop(resourceName) (client)

Scope Matrix

API Function	Client	Server	Shared
AddEventHandler	Implemented	Implemented	Implemented
RemoveEventHandler	Implemented	Implemented	Implemented
TriggerEvent local	Implemented	Implemented	Implemented
TriggerEvent deterministic publish	Local-only policy	Tick-gated	Policy-enforced
TriggerEvent cross-client publish	Denied	Implemented	Policy-enforced

Production Notes

• Event API function contract is complete and production-usable.
• Operational hardening continues in runbooks/soak testing (incident workflows, long soak under packet-loss/jitter, observability tuning).