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

> 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

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

Browser:

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

```rust theme={"dark"}
sdk.start_wallet_stream(None)?;
let update = sdk.poll_wallet_updates(100)?; // up to 100 updates
```

Browser (event listeners):

```ts theme={"dark"}
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](/sdk/initialization)).

## 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](/sdk/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](/sdk/status-and-lifecycle).