Events & realtime

Design good gameplay events and a healthy flow — validation limits, buffering, batching, and polling.

The event plane is the SDK’s two-way messaging channel. This guide is about using it well.

Outbound events — the payload contract

The protocol validator enforces hard limits. Keep your payloads inside them:

Dimension	Limit
String length	8,192 chars
Array length	1,024 items
Object properties	128
Nesting depth	10 levels
Total payload	64 KiB (65,536 bytes)
Extensions per message	16

Submit events the same way across targets:

box.submitEvent("match.start", { mode: "arena", seed: 4815162342 });

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

Buffering, batching, backpressure

Config	Default	Effect
offline_buffering	true	Queue while offline; flush on reconnect
batch_size	25	Events per flush batch
flush_interval_ms	1000	Flush cadence
event_queue_capacity	1000	Hard queue ceiling (backpressure)

When the queue is full the SDK reports EventQueueFull rather than growing memory without bound — do not silence it. Drain by reducing submit rate or restoring connectivity.

Realtime flow

Native:

sdk.start_wallet_stream(Some(cursor))?;
loop {
    for update in sdk.poll_wallet_updates(100)? {
        handle(update);
    }
}

Browser:

box.addEventListener("event", (e) => {
  if (e.data.type === "wallet") applyWalletUpdate(e.data);
});

The plane supports resume-from-cursor, so a brief disconnect does not lose events. Simulate/disagnose with:

musterbox web-socket resume-simulate
musterbox web-socket diagnose
musterbox pipeline status

Event types you will meet

• session — lifecycle transitions (authenticated, expired, refreshed)
• wallet — wallet stream updates (post-purchase balance, custody events)
• status — runtime health transitions

Design rules

• Keep event payloads canonical and small; they feed analytics and audit.
• Never place secrets (tokens, PINs) in payloads.
• Treat the event plane as best-effort messaging for telemetry and UX — the HTTP contract (sessions, results, purchases) remains authoritative.

Next: Purchase flow.