sdk.action_broker

@type library Global action broker for coordinating independent scripts. Actions reserve one or more channels atomically, then keep those channels until their acknowledgement arrives (or the action fails/cancels). Network callbacks only enqueue copied evidence; pump() is the sole callback execution point.

local M = require("sdk.action_broker")

Constants

Lua 5.4 has no enums — these are integer (or string) fields on the module.

Name	Value	Summary
terminal_ticket_limit	TERMINAL_TICKET_LIMIT	—
ack	Ack	Acknowledge a finished action ticket so the broker can release its channel.
acks	Ack	Alias of ack.
Owner	Owner	Owner class used to claim channels.
Ticket	Ticket	Ticket class representing one in-flight action.
Lease	Lease	Lease class for a temporary exclusive channel hold.
normalize_channels	normalize_channels	Normalize a channel name or list into the canonical set.

channel

alias · channel = channels

Same as channels.

Alias

Same as channels.

priority

alias · priority = priorities

Same as priorities.

Alias

Same as priorities.

bind_runtime

function · bind_runtime()

Ensure the tick pump and session-boundary events are subscribed. WorldEntered / SessionEnd* bump generation; without them a relog keeps old leases.

rebind_runtime

function · rebind_runtime()

Hot-reload recovery: game.off leftover handles, clear the pumping latch, bind again. ScriptHost drops entrypoint callbacks but cached SDK modules keep stale numeric ids. An aborted tick can leave pumping=true forever; this is the explicit unstick.

runtime_tick_bound

function · runtime_tick_bound()

Whether the global tick pump handle is registered on this epoch. Tests assert this after bind/rebind instead of poking state.bindings.

owner

function · owner(name, opts)

Owner API ------------------------------------------------------------------

event

function · event(name, ev, now)

Event queue and pump --------------------------------------------------------

observe

alias · observe = event

Same as event.

Alias

Same as event.

notify

alias · notify = event

Same as event.

Alias

Same as event.

pump

function · pump(now)

Sole user-callback execution point: expire, inbound, send, then completions. Re-entry is rejected; the pumping latch is cleared even when the body throws. Network callbacks only enqueue — they never call this.

generation

function · generation()

Current session generation. Bumps on WorldEntered / SessionEnd*, not on test reset. Tickets captured against an older generation are ignored by inbound matching.

event_sequence

function · event_sequence()

Monotonic inbound sequence. Each M.event() increments this. A ticket ignores packets with sequence <= sent_event_sequence (echoes of its own send).

blocker

function · blocker(channels, priority)

First live lease intersecting the channels, plus whether a priority could preempt it. Scripts probe this before submit() when they want a busy reason without enqueueing.

snapshot

function · snapshot()

Full broker dump: owners, tickets (including the terminal tail), leases, diagnostics. Tables are copied; the live state must not be reachable from a snapshot.

diagnostics

function · diagnostics()

Diagnostic tail only (copy via snapshot). Prefer this over M.snapshot() when a script just needs last_error history.