Events & realtime

Submit gameplay events and consume realtime session, wallet, and status events.

The SDK bridges two directions: outbound gameplay events you submit, and inbound realtime events (session, wallet, status) the SDK polls for you.

Submit an event

let event_id = sdk.submit_event("match.start", json!({ "mode": "arena" }))?;

Browser:

box.submitEvent({ kind: "match.start", payload: { mode: "arena" } });

Outbound events are:

• validated — protocol value limits apply (string ≤ 8192 chars, array ≤ 1024 items, object ≤ 128 properties, payload ≤ 64 KB, nesting ≤ 10 levels, extensions ≤ 16);
• buffered offline — offline_buffering (default on) queues events while disconnected and flushes them later;
• flushed in batches — batch_size (25) and flush_interval_ms (1000).

Receive realtime events

Native:

sdk.start_wallet_stream(None)?;
let update = sdk.poll_wallet_updates(100)?; // up to 100 updates

Browser (event listeners):

box.addEventListener("event", (evt) => {
  if (evt.data.type === "session") { /* ... */ }
});

Event types

Catalog	Purpose
Session events	Lifecycle transitions (started, authenticated, expired, …)
Wallet events	Wallet stream updates (balance, custody, …)
Status events	Runtime status and health transitions

The SDK dispatches inbound events to registered handlers; in Manual runtime mode a tick call is what drives dispatch and polling (see Initialization & lifecycle).

The event plane

The event plane is a WebSocket-based channel. The SDK:

• maintains the connection with resume-from-cursor support (diagnose with musterbox web-socket resume-simulate),
• polls with backpressure-aware batching,
• exposes pipeline and storage diagnostics through the CLI.

Backpressure

The outbound queue is bounded (event_queue_capacity, default 1000). Filling it triggers explicit backpressure signalling rather than unbounded memory growth. Monitor pipeline pressure via musterbox pipeline status.

Next: Status & lifecycle.