@castarcade/sdk

The standalone browser bridge for Cast Arcade developer-beta games. Import createGame, register lifecycle handlers, then call ready(). The host connects one private MessagePort; lifecycle, semantic input, mute, and viewport events arrive only on that port.

reportResult() accepts safe whole-number score rows or positive whole-number elapsedMs rows for started players. Do not mix the two metrics in one report. Optional metadata is a flat object with at most 31 custom keys because account history adds the score or time; keys match [A-Za-z0-9_]{1,64}, and values are booleans, safe whole numbers, or strings of at most 512 Unicode characters without control characters. The complete report is limited to 4 KB.

Browser results can feed a player's private personal history. They are not verified public leaderboard records because players can change browser code. Results are never payout or monetary events. The package has no runtime imports, so index.js may also be vendored into a self-contained game build.

Games declaring play.privateViews: true can replace a started player's phone content with game.setControllerView({ playerId, title?, text?, actions?: [{ id, label? }] }). IDs must belong to the fixed start roster and declared manifest actions. Content is text rendered by the trusted phone UI, never HTML or game-provided components. The complete view is limited to 4 KiB of UTF-8 JSON; title, text and action labels are limited to 80, 2048 and 60 characters respectively. { playerId } clears the view. The method returns false before start, after disposal, when unsupported, or when invalid.

Games declaring play.checkpoint: 'versioned' can call game.saveCheckpoint({ version: 1, state: { round: 2 } }). version is a positive safe integer chosen by the game; state is JSON data. The complete checkpoint is limited to 32 KiB of UTF-8 JSON, 32 nesting levels and bounded node count. Cycles, sparse arrays, accessors, class instances, undefined and non-finite numbers are rejected. The method returns a boolean and snapshots accepted data.

Register createGame({ onRestore(checkpoint) { /* restore game state */ }, start(event) { /* attach players and render restored state */ } }) for recovery. The host sends a capability declaration, optional restore, then the unchanged start event. onRestore runs before start and input; returning a promise delays all subsequent lifecycle messages until it resolves. A missing restore handler, a rejection, a 15-second timeout or more than 256 queued messages aborts recovery and reports a generic host error. Disposal cancels the queue. Do not reset restored state unconditionally in start.

The host scopes recovery to the immutable game release and room session. Checkpoints and phone content are client-reported data; they do not establish verified scores. Older hosts do not enable these optional methods, and older SDKs continue to receive the existing start shape.

For games declaring schema v2 server rules, createGame({ state(display) {} }) receives the bounded server display projection after start. The host must declare an authoritative session; ordinary browser sessions cannot send this callback. Keep rules state and result decisions in the isolated rules module. This handler does not turn browser results or checkpoints into verified records.