> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```ts theme={"dark"}
box.submitEvent("match.start", { mode: "arena", seed: 4815162342 });
```

```rust theme={"dark"}
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:

```rust theme={"dark"}
sdk.start_wallet_stream(Some(cursor))?;
loop {
    for update in sdk.poll_wallet_updates(100)? {
        handle(update);
    }
}
```

Browser:

```ts theme={"dark"}
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:

```bash theme={"dark"}
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](/guides/purchase-flow-sdk-bridge).