Initialization & lifecycle

The MusterBox SDK lifecycle — initialize, start, authenticate, refresh, logout, shutdown.

The SDK is an explicit state machine. You drive it through well-defined steps, and every step reports its result through stable errors and status.

The lifecycle

Uninitialized ──initialize──▶ Stopped ──start──▶ Running
                                                    │
                             ┌───────────authenticate──▶ Authenticated
                             ▼                            │
                         refresh ◀─────────────────── refresh_session
                             │                            │
                             ▼                            ▼
                         logout ────▶ Running          logout (session revoked)
                                                   
 Stopped ──shutdown──▶ Shutdown (resources released)

Initialize

Parsing and validating configuration happens here. Invalid configuration fails fast — nothing is sent over the network.

use musterbox_sdk::{MusterBoxSdk, MusterBoxConfig};

let config = MusterBoxConfig::from_env()?;
let sdk = MusterBoxSdk::initialize(config)?;

Web (browser):

import { createMusterBox } from "@musterbox/sdk-js";
const box = createMusterBox({
  gameId: "my-arena-game",
  gameKey: "gk_...",
  environment: "sandbox",
});
box.addEventListener("ready", () => { /* now safe to start */ });

Once initialized the SDK reports Stopped. Nothing is scheduled until start.

Start

Starts the worker machinery (event flush scheduler, realtime poller, wallet stream). In Threaded runtime mode a background thread is spawned; in Manual mode you drive progress by calling tick.

sdk.start();

Authenticate

Exchanges credentials (or a persisted token) for a backend session. See Authentication.

let player = sdk.authenticate("[e-mail]", "secret")?;

The SDK owns the resulting credentials: access token, refresh token, expiry, session id. Your game never touches the raw tokens.

Refresh

The SDK rotates tokens automatically when the access token nears expiry, using POST /api/v1/auth/validate with the refresh token. You can also trigger a manual refresh:

sdk.refresh_session()?;

Logout

Revokes the server-side session and clears local credentials.

sdk.logout()?;

Shutdown

Releases the runtime. shutdown_timeout_ms (default 5000 ms) bounds the graceful drain before resources are freed.

sdk.shutdown();

shutdown is idempotent and safe to call from any thread.

Runtime options

Option	Meaning
RuntimeMode::Threaded	Background worker drives timers and flushes (default for most engines)
RuntimeMode::Manual	You call tick() with a TickBudget each frame
TickBudget	Max commands/timers/elapsed-ms per tick — keeps a game frame honest

Single-threaded engines (Unity, Godot main thread, web) generally prefer Manual, letting the SDK process bounded work per frame.

The blocking variants of SDK calls run on their own current-thread runtime. Do not call blocking variants from inside another Tokio runtime context.