@bountyboard/arcade-sdk 1.2.0 → 1.4.0

package/dist/multiplayer.js

@@ -1,6 +1,6 @@
 import {
   BBArcade
-} from "./chunk-KDBBR532.js";
+} from "./chunk-PYW5F45R.js";
 
 // src/multiplayer.ts
 var WELCOME_TIMEOUT_MS = 1e4;

package/dist/{types-dtsNXYZW.d.cts → types-B5bqWnHH.d.cts}

@@ -42,6 +42,46 @@ interface BBArcadeRewardedAdsConfig {
 interface BBArcadeConfig {
     rewardedAds?: BBArcadeRewardedAdsConfig;
 }
+/**
+ * What is backing `window.localStorage` right now.
+ * - `native` — a real Storage works here; the SDK changed nothing.
+ * - `cloud` — the shim is installed and syncs to the player's Bounty Board save.
+ * - `memory` — the shim is installed but nothing can persist (guest, standalone,
+ *   off-host); reads and writes work for the session and are then discarded.
+ */
+type BBArcadeStorageMode = 'native' | 'cloud' | 'memory';
+/**
+ * localStorage compatibility for hosted builds. Bounty-Board-hosted uploads run
+ * in an opaque-origin sandbox where `localStorage` THROWS rather than returning
+ * empty, which breaks engine exports (GameMaker `ini_*`, Godot, Unity) that
+ * assume synchronous storage. The shim replaces it with a Storage-shaped object
+ * backed by the SDK's own cloud save, so those builds persist per player and
+ * across devices with no engine changes.
+ *
+ * The script-tag build installs it automatically at load. Module consumers keep
+ * a side-effect-free import and call `install()` themselves before boot.
+ */
+interface BBArcadeStorage {
+    /**
+     * Install the shim if this origin has no working localStorage, and return the
+     * resulting mode. Idempotent, and a no-op when native storage works. Call it
+     * BEFORE the engine/game script runs.
+     */
+    install(): BBArcadeStorageMode;
+    /**
+     * Resolves once the cloud read has landed (or settled as unpersistable).
+     * `getItem` is synchronous but the cloud read is not, so a game that reads
+     * saved progress during boot should await this first.
+     */
+    ready(): Promise<BBArcadeStorageMode>;
+    /**
+     * Force pending writes out now instead of waiting for the debounce. Rejects
+     * with the same BBArcadeError codes as save().
+     */
+    flush(): Promise<void>;
+    /** The current backing mode. */
+    readonly mode: BBArcadeStorageMode;
+}
 /**
  * The logged-in player's public display identity, as delivered by the Bounty
  * Board host. Display name + avatar ONLY — the host never sends ids, emails,
@@ -402,6 +442,11 @@ interface BBArcadeSDK {
      * 'error' after the same 15s request timeout when no host answers).
      */
     load(): Promise<string | null>;
+    /**
+     * localStorage compatibility for hosted builds — the escape hatch for engine
+     * exports that can't be rewired to call save()/load(). See BBArcadeStorage.
+     */
+    storage: BBArcadeStorage;
     /**
      * The logged-in player's display identity for in-game UI. Resolves
      * { name, avatarUrl } once the host's config handshake completes (or after
@@ -436,4 +481,4 @@ interface BBArcadeSDK {
     version: number;
 }
 
-export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeMpJoinOptions as o, BBArcadeMpRoom as p, BBArcadeMultiplayer as q, BBArcadeMpPlayer as r, BBArcadeMpResult as s, BBArcadeMpRoomEvents as t };
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeStorage as o, BBArcadeStorageMode as p, BBArcadeMpJoinOptions as q, BBArcadeMpRoom as r, BBArcadeMultiplayer as s, BBArcadeMpPlayer as t, BBArcadeMpResult as u, BBArcadeMpRoomEvents as v };

package/dist/{types-dtsNXYZW.d.ts → types-B5bqWnHH.d.ts}

@@ -42,6 +42,46 @@ interface BBArcadeRewardedAdsConfig {
 interface BBArcadeConfig {
     rewardedAds?: BBArcadeRewardedAdsConfig;
 }
+/**
+ * What is backing `window.localStorage` right now.
+ * - `native` — a real Storage works here; the SDK changed nothing.
+ * - `cloud` — the shim is installed and syncs to the player's Bounty Board save.
+ * - `memory` — the shim is installed but nothing can persist (guest, standalone,
+ *   off-host); reads and writes work for the session and are then discarded.
+ */
+type BBArcadeStorageMode = 'native' | 'cloud' | 'memory';
+/**
+ * localStorage compatibility for hosted builds. Bounty-Board-hosted uploads run
+ * in an opaque-origin sandbox where `localStorage` THROWS rather than returning
+ * empty, which breaks engine exports (GameMaker `ini_*`, Godot, Unity) that
+ * assume synchronous storage. The shim replaces it with a Storage-shaped object
+ * backed by the SDK's own cloud save, so those builds persist per player and
+ * across devices with no engine changes.
+ *
+ * The script-tag build installs it automatically at load. Module consumers keep
+ * a side-effect-free import and call `install()` themselves before boot.
+ */
+interface BBArcadeStorage {
+    /**
+     * Install the shim if this origin has no working localStorage, and return the
+     * resulting mode. Idempotent, and a no-op when native storage works. Call it
+     * BEFORE the engine/game script runs.
+     */
+    install(): BBArcadeStorageMode;
+    /**
+     * Resolves once the cloud read has landed (or settled as unpersistable).
+     * `getItem` is synchronous but the cloud read is not, so a game that reads
+     * saved progress during boot should await this first.
+     */
+    ready(): Promise<BBArcadeStorageMode>;
+    /**
+     * Force pending writes out now instead of waiting for the debounce. Rejects
+     * with the same BBArcadeError codes as save().
+     */
+    flush(): Promise<void>;
+    /** The current backing mode. */
+    readonly mode: BBArcadeStorageMode;
+}
 /**
  * The logged-in player's public display identity, as delivered by the Bounty
  * Board host. Display name + avatar ONLY — the host never sends ids, emails,
@@ -402,6 +442,11 @@ interface BBArcadeSDK {
      * 'error' after the same 15s request timeout when no host answers).
      */
     load(): Promise<string | null>;
+    /**
+     * localStorage compatibility for hosted builds — the escape hatch for engine
+     * exports that can't be rewired to call save()/load(). See BBArcadeStorage.
+     */
+    storage: BBArcadeStorage;
     /**
      * The logged-in player's display identity for in-game UI. Resolves
      * { name, avatarUrl } once the host's config handshake completes (or after
@@ -436,4 +481,4 @@ interface BBArcadeSDK {
     version: number;
 }
 
-export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeMpJoinOptions as o, BBArcadeMpRoom as p, BBArcadeMultiplayer as q, BBArcadeMpPlayer as r, BBArcadeMpResult as s, BBArcadeMpRoomEvents as t };
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeStorage as o, BBArcadeStorageMode as p, BBArcadeMpJoinOptions as q, BBArcadeMpRoom as r, BBArcadeMultiplayer as s, BBArcadeMpPlayer as t, BBArcadeMpResult as u, BBArcadeMpRoomEvents as v };

package/docs/external-authoritative-servers.md

@@ -7,7 +7,7 @@ adapter contract; it does not relay traffic or run a second simulation.
 
 External authorities are reviewed and enabled per game. Registration is not
 self-service. Contact Bounty Board before implementing the adapter so the game
-slug, endpoints, room-code rules, ticket keys, and result model can be agreed
+slug, endpoints, room code rules, ticket keys, and result model can be agreed
 for staging and production.
 
 ## What stays authoritative
@@ -23,7 +23,7 @@ Your server remains the only source of truth. It must:
 - keep endless rooms endless instead of inventing a terminal result.
 
 The SDK handles ticket acquisition, WebSocket connection, reconnection, and a
-small room-message envelope. It never grants a client authority over identity,
+small room message envelope. It never grants a client authority over identity,
 state, roles, or results.
 
 ## Registration information
@@ -32,9 +32,9 @@ Provide Bounty Board with the following for each environment:
 
 - the exact Arcade game slug;
 - one fixed `wss:` endpoint dedicated to authenticated SDK rooms;
-- the room-code format and maximum length your server accepts;
+- the room code format and maximum length your server accepts;
 - whether missing room codes may create rooms;
-- any validated, game-defined `joinData` fields;
+- any validated, game defined `joinData` fields;
 - whether the game has finite matches or endless sessions; and
 - an operational contact for key rotation or incident response.
 
@@ -42,9 +42,9 @@ The registered endpoint must not contain userinfo, query parameters, or a
 fragment. Use `ws:` only for loopback development. Staging and production need
 different endpoints and different secrets.
 
-Bounty Board provisions a dedicated ticket-verification secret for the game
+Bounty Board provisions a dedicated ticket verification secret for the game
 and environment. Store it only on servers. Do not put it in the game bundle,
-browser storage, logs, analytics, crash reports, or client-visible environment
+browser storage, logs, analytics, crash reports, or client visible environment
 variables. Do not reuse credentials from another game or room service.
 
 ## Connection flow
@@ -100,7 +100,7 @@ Before accepting a connection, verify all of the following:
 - `sub` is non-empty; and
 - required claim types and lengths are valid.
 
-Treat `sub` as an opaque game-scoped identity. Never attempt to map it to a
+Treat `sub` as an opaque game scoped identity. Never attempt to map it to a
 Bounty Board account or correlate it with another game. `name` and `avatarUrl`
 are display data, not authorization data. `avatarUrl` may be `null` for any
 player.
@@ -129,12 +129,12 @@ if (!room.trySend({ type: 'move', x: 1, y: 0 })) {
 }
 ```
 
-Script-tag builds use `BBArcade.multiplayer.joinRoom(...)`.
+Script tag builds use `BBArcade.multiplayer.joinRoom(...)`.
 
 `joinData` is an optional JSON object capped at 1 KiB. Validate every field,
 reject unknown or oversized values, and never accept credentials or identity
 claims from it. If your server distinguishes create from join, use a documented
-game-defined intent field and rate-limit room creation. That field is still
+game defined intent field and rate limit room creation. That field is still
 untrusted and grants no role or permission by itself.
 
 ## WebSocket URL
@@ -147,7 +147,7 @@ wss://multiplayer.example.com/bountyboard?ticket=<encoded>&join=<encoded-json>
 
 The `join` parameter is omitted when no `joinData` was supplied. Keep this path
 separate from any anonymous or legacy socket endpoint so a guessed room code
-cannot cross the authentication boundary. Redact or disable request-URI logging
+cannot cross the authentication boundary. Redact or disable request URI logging
 on this route because the short-lived ticket is in the query string.
 
 ## SDK room envelope
@@ -174,7 +174,7 @@ Send authoritative state snapshots as:
 }
 ```
 
-Send game-defined transient events without changing their payload:
+Send game defined transient events without changing their payload:
 
 ```json
 { "t": "event", "data": { "type": "round_started", "round": 2 } }
@@ -204,23 +204,23 @@ Reject an invalid ticket before `welcome` with an error and close the socket:
 ```
 
 Use `rejected` for invalid admission or `joinData`. After admission, error codes
-remain game-defined strings and are surfaced through `room.on('error', ...)`.
+remain game defined strings and are surfaced through `room.on('error', ...)`.
 
 ## Reconnection
 
 The SDK automatically makes a small number of reconnect attempts. It requests
 a fresh ticket for the same room and reuses the original `joinData`. Rebind the
 seat using the verified `(ticket.sub, ticket.roomId)` pair. Never trust a
-client-supplied player id or reconnect token as the proof of identity.
+client supplied player id or reconnect token as the proof of identity.
 
-Send the latest complete viewer-safe state in the new `welcome` frame. If your
+Send the latest complete viewer safe state in the new `welcome` frame. If your
 client uses prediction, include the last processed input sequence in that state
 so it can discard acknowledged inputs. Clear held controls while the socket is
 absent.
 
 ## Finite matches and endless rooms
 
-Only a server-authoritative finite game may emit `match_end`:
+Only a server authoritative finite game may emit `match_end`:
 
 ```json
 {
@@ -239,7 +239,7 @@ Only a server-authoritative finite game may emit `match_end`:
 
 The client receives this as `room.on('end', ({ results }) => ...)`. Persistent
 Bounty Board results, when enabled, use a separately provisioned
-server-to-server reporting credential. Never accept a client-originated result
+server to server reporting credential. Never accept a client originated result
 or reporting credential.
 
 Endless rooms must not emit `match_end`. Death, respawn, a round transition, or
@@ -248,18 +248,18 @@ a player leaving is not automatically a terminal match result.
 ## Production checklist
 
 - Use an isolated staging endpoint and secrets before production.
-- Confirm tampered, expired, wrong-slug, and wrong-room tickets fail closed.
-- Test both guest and logged-in opaque subjects.
+- Confirm tampered, expired, wrong slug, and wrong room tickets fail closed.
+- Test both guest and logged in opaque subjects.
 - Reject malformed, unknown, or oversized `joinData`.
 - Send `welcome` only after ticket and admission validation succeeds.
 - Verify every snapshot is safe for its specific viewer.
-- Test disconnect, held-input cleanup, fresh-ticket reconnect, and `leave()`.
-- Rate-limit upgrades, room creation, joins, and inputs.
+- Test disconnect, held input cleanup, fresh ticket reconnect, and `leave()`.
+- Rate limit upgrades, room creation, joins, and inputs.
 - Redact tickets and join payloads from access logs and error telemetry.
 - Rotate the dedicated ticket secret without reusing another environment's key.
 - Emit final results only from a real authoritative terminal condition.
 - Keep the game playable when multiplayer is unsupported or temporarily down.
 
 For SDK integration basics, see https://www.bountyboard.gg/arcade/sdk. For the
-agent-readable API contract, see
+agent readable API contract, see
 https://www.bountyboard.gg/arcade/sdk/llms.txt.

package/docs/game-design-playbook.md

@@ -1,17 +1,17 @@
 # Bounty Board game design playbook (the "design brain")
 
 What actually performs on the Bounty Board arcade, distilled from operating it. Read this
-BEFORE designing a new game or porting one in — the SDK wiring is the easy part; these choices
+BEFORE designing a new game or porting one in. The SDK wiring is the easy part; these choices
 decide whether the game earns plays, retention, and revenue.
 
-> Draft co-owned with our partner studios — challenge anything here with data.
+> Draft co-owned with our partner studios. Challenge anything here with data.
 
 ## Session shape
 
-- **Target a 60–180 second core loop.** Arcade traffic arrives mid-browse; games that deliver a
+- **Target a 60 to 180 second core loop.** Arcade traffic arrives mid browse; games that deliver a
   complete emotional arc (start → tension → payoff) in under three minutes get replays, and
-  replays drive feed ranking. Longer-form games need checkpointed sessions via cloud saves.
-- **Time-to-first-input under 5 seconds.** Call `gameLoadingFinished()` honestly; players who
+  replays drive feed ranking. Longer form games need checkpointed sessions via cloud saves.
+- **Time to first input under 5 seconds.** Call `gameLoadingFinished()` honestly; players who
   bounce on a spinner never come back. Defer heavy assets past the first playable moment.
 - **Instant restart.** Death → new run should be ONE input and under a second. Restart friction
   is the top killer of "one more run".
@@ -19,31 +19,31 @@ decide whether the game earns plays, retention, and revenue.
 ## Score design (this is leaderboard design)
 
 - **Scores must be integers with a meaningful gradient.** A good score curve separates a casual
-  run from a great one by 10–100x, not 2x — that's what makes a board worth climbing.
+  run from a great one by 10 to 100x, not 2x. That's what makes a board worth climbing.
 - **Skill ceiling over grind ceiling.** If score scales with time played rather than skill, the
-  board saturates and goes stale. Cap or decay pure-survival scoring; reward risk.
-- **Design the "one point short" feeling.** Near-miss visibility (show the player's best and the
+  board saturates and goes stale. Cap or decay pure survival scoring; reward risk.
+- **Design the "one point short" feeling.** Near miss visibility (show the player's best and the
   next board rank in-game via your own UI) measurably lifts replays.
-- **Daily mode**: if your game has procedural content, ship a shared-seed daily run and submit
+- **Daily mode**: if your game has procedural content, ship a shared seed daily run and submit
   it with `{ mode: 'daily' }`. Daily boards reset at midnight UTC and are the strongest
-  retention surface on the platform — everyone plays the SAME level, so the board is fair chat.
+  retention surface on the platform. Everyone plays the SAME level, so the board is fair chat.
 
-## Multiplayer design (for room-based games)
+## Multiplayer design (for room based games)
 
-- **Latency-tolerant mechanics win.** Positional games at 10–20Hz snapshots with client
+- **Latency tolerant mechanics win.** Positional games at 10 to 20Hz snapshots with client
   interpolation feel great for chase/tag/social deduction; twitch duels don't. Design around
-  prediction-friendly movement (momentum, grid steps) rather than instant-hit actions.
+  prediction friendly movement (momentum, grid steps) rather than instant hit actions.
 - **Information asymmetry is a server feature.** The room server sends each player only what
   they may know (hiders invisible to the seeker). Lean into designs where hidden information IS
-  the game — it's cheat-proof by construction here.
-- **2-minute rounds, drop-in lobbies.** Rooms fill from friends sharing codes; short rounds
-  forgive mid-round joins as spectators and keep groups cycling.
+  the game. It's cheat proof by construction here.
+- **2-minute rounds, drop in lobbies.** Rooms fill from friends sharing codes; short rounds
+  forgive mid round joins as spectators and keep groups cycling.
 - **Send inputs, not outcomes.** If your design needs the client to decide who got tagged, the
-  design is wrong — move the rule server-side.
+  design is wrong. Move the rule server-side.
 
 ## Monetization etiquette (rewarded ads)
 
-- **Ads are a player's trade, never a toll.** Best-performing placements: revive ("continue this
+- **Ads are a player's trade, never a toll.** Best performing placements: revive ("continue this
   run?"), doubler ("2x this run's coins"), cosmetic unlock. Never gate core progression.
 - **One organic placement beats three pushy ones.** Interrupting flow trains players to leave;
   prepare one rewarded placement at a natural fail state and offer it once.
@@ -54,13 +54,13 @@ decide whether the game earns plays, retention, and revenue.
 
 ## Platform fit
 
-- **Mobile-first inputs.** Most arcade sessions are touch. One-thumb controls, generous hit
-  targets, no hover dependence, portrait-friendly if possible. Keyboard is the enhancement.
-- **Performance budget: 60fps on a mid-range phone.** Cap DPR, pool objects, avoid layout
+- **Mobile first inputs.** Most arcade sessions are touch. One thumb controls, generous hit
+  targets, no hover dependence, portrait friendly if possible. Keyboard is the enhancement.
+- **Performance budget: 60fps on a mid range phone.** Cap DPR, pool objects, avoid layout
   thrash. Players don't report jank, they just leave.
-- **Own your standalone build.** The same bundle must run off-platform (the SDK no-ops). Don't
-  fork builds; feature-detect through the SDK's own fallbacks.
-- **Cloud saves make your game feel native.** Load on boot, save on checkpoint/game-over, and
+- **Own your standalone build.** The same bundle must run off platform (the SDK no-ops). Don't
+  fork builds; feature detect through the SDK's own fallbacks.
+- **Cloud saves make your game feel native.** Load on boot, save on checkpoint/game over, and
   greet returning players with their progress (pair with `getPlayer()` for the name). Hosted
   builds have no localStorage, so wire this early, not as a retrofit.
 
@@ -71,5 +71,5 @@ decide whether the game earns plays, retention, and revenue.
 - [ ] The score of a great run embarrasses the score of a lucky run
 - [ ] Daily mode if content is procedural
 - [ ] Rewarded placement is a trade the player initiates
-- [ ] Playable one-thumb on a phone at 60fps
+- [ ] Playable one thumb on a phone at 60fps
 - [ ] Boots and plays with the SDK fully offline