@bountyboard/arcade-sdk 1.0.0

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Arcade SDK integration guide for coding agents
+
+You are integrating a game with the Bounty Board Arcade SDK (`@bountyboard/arcade-sdk`, or the
+script tag at `https://www.bountyboard.gg/arcade-sdk/v1.js`). This file is the canonical set of
+rules. The API reference lives in the package types and at
+https://www.bountyboard.gg/arcade/sdk/llms.txt — this file is about using it CORRECTLY.
+
+## Golden rules (breaking these ships bugs or gets a game flagged)
+
+1. **The SDK must never be load-bearing.** Every feature has an offline/standalone outcome:
+   fire-and-forget calls no-op, `save`/`load` reject with `code: 'unsupported'`, `getPlayer`
+   resolves `null`, `getVariant` resolves its alphabetical control, `joinRoom` rejects
+   `'unsupported'`. The game must run perfectly with all of those outcomes at once.
+2. **Rewarded ads**: only ever triggered by an explicit player gesture on YOUR UI ("Watch ad to
+   revive"). Grant the reward if and only if `rewardedBreak(...)` resolves exactly `true`.
+   Pause gameplay and audio in `onStart`. Never loop or auto-retry a dismissed ad.
+3. **Scores are integers and `gameOver` fires exactly once per run.** Don't submit
+   post-game-over corrections; the server enforces per-game plausibility caps and rejects
+   implausible values. Call `submitScore` freely during play — the host throttles.
+4. **Always handle `getPlayer() === null`** (guests, standalone, off-host). The SDK never
+   provides ids, emails, or roles — do not design features that need them.
+5. **One save blob.** Serialize the whole progress object into a single `save(string)` (~1MB
+   cap). Save on checkpoints/game-over, never per frame. Handle all five rejection codes; keep
+   localStorage as the standalone fallback (hosted builds have no localStorage — the sandbox is
+   opaque-origin — so the SDK save IS primary there).
+6. **`lockToHost()` before boot** when the studio wants anti-theft, with their own domains in
+   `allow`. It's a deterrent, not DRM — never present it as more.
+7. **Multiplayer: clients send inputs, never state.** The room server simulates and validates;
+   design the game so all authority lives server-side. Don't trust or display any value another
+   client sent directly.
+
+## Correct lifecycle order
+
+```
+lockToHost() → init() → [getPlayer()] → gameLoadingFinished()
+  → per run: gameplayStart() → submitScore()* → gameplayStop() → gameOver()
+  → save() on checkpoint/game-over
+```
+
+`gameplayStart`/`gameplayStop` bracket ACTIVE play only (not menus). They drive playtime
+analytics and feed ranking, so missing `gameplayStop` on pause inflates numbers and will look
+anomalous. WebXR games must call `xrSessionStart()`/`xrSessionEnd()` around immersive sessions
+or their playtime flatlines while the headset hides the page.
+
+## Module vs script tag
+
+- Build step → `import { BBArcade } from '@bountyboard/arcade-sdk'` (typed; no global installed;
+  SSR-safe import).
+- No build step → script tag; global `window.BBArcade`; standalone typings via
+  `/// <reference path="./arcade-sdk.d.ts" />` (download from /arcade-sdk.d.ts).
+- Never mix both in one page. Both are built from the same source and behave identically.
+
+## A/B experiments
+
+`getVariant(key, variants)` is deterministic per player+game+key, even split. The
+alphabetically-first variant doubles as the control/fallback (standalone play, errors), so make
+the safe/default experience the alphabetically-first name. Don't re-randomize client-side.
+
+## Verifying an integration
+
+- Standalone smoke test: open the build from `file:` or a bare local server with NO host page.
+  It must boot, play, and never hang on an SDK promise.
+- Mock-host test: embed the game in an iframe and answer its postMessage traffic (`source:
+'bb-arcade'`) with a scripted parent — reply to `init`/`ready` with a `bb-arcade-host` config
+  message, answer `save`/`load` requests by `requestId`. This is how Bounty Board's own
+  Playwright harnesses verify games; it exercises the real protocol without the real site.
+- Ads: on localhost the SDK auto-enables Google's test-ads mode; `rewardedBreak` resolving
+  `false`/`'unavailable'` locally is normal — verify the grant-only-on-true path both ways.
+- Multiplayer: run the room server locally (`wrangler dev` with `DEV_ALLOW_UNSIGNED=1`) and pass
+  `{ roomUrl, ticket }` overrides to `joinRoom` for development.
+
+## Design intent (read docs/game-design-playbook.md before building a NEW game)
+
+Leaderboard shape, daily-seed modes, session length, and ad-placement etiquette are design
+decisions, not integration details. The playbook covers what actually performs on Bounty Board.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bounty Board
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @bountyboard/arcade-sdk
+
+Connect your HTML5 game to the [Bounty Board arcade](https://www.bountyboard.gg/arcade):
+global leaderboards, cross-device cloud saves, player identity, A/B variants, rewarded-ad
+revenue (90% studio share), site-lock anti-theft, and authoritative multiplayer rooms.
+Zero dependencies. Every call is optional and safe standalone — off Bounty Board the SDK
+quietly does nothing, so the same build runs anywhere.
+
+## Install
+
+```bash
+npm install @bountyboard/arcade-sdk
+```
+
+```ts
+import { BBArcade } from '@bountyboard/arcade-sdk';
+
+BBArcade.lockToHost(); // optional: refuse to run on scrape-and-reupload sites
+BBArcade.init(); // handshake with the host (fire-and-forget is fine)
+BBArcade.gameLoadingFinished(); // the player can press start
+BBArcade.gameplayStart(); // a run began
+BBArcade.submitScore(score); // as the score changes (host throttles)
+BBArcade.gameOver(finalScore); // once per run — feeds the leaderboards
+```
+
+Full TypeScript definitions are included. Importing the module never installs a
+`window.BBArcade` global and is SSR-safe; if your setup wants the global, use
+`import '@bountyboard/arcade-sdk/global'`.
+
+No build step? Use the script tag instead — same code, same protocol:
+
+```html
+<script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
+```
+
+with standalone typings at [`/arcade-sdk.d.ts`](https://www.bountyboard.gg/arcade-sdk.d.ts).
+
+## The surface in one look
+
+| Call                                     | What it does                                                                |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `lockToHost({ allow? , signed? })`       | Block scraped re-hosts of your build (deterrent, not DRM)                   |
+| `init(options?)` / `configure(options?)` | Configure modules (rewarded ads), announce to the host                      |
+| `ready()` / `gameLoadingFinished()`      | Loading finished, player can start                                          |
+| `gameplayStart()` / `gameplayStop()`     | Bracket active play (playtime + feed ranking)                               |
+| `submitScore(n, { mode?: 'daily' })`     | Live integer score; server enforces plausibility caps                       |
+| `gameOver(n, { mode?: 'daily' })`        | Final score, once per run                                                   |
+| `save(blob)` / `load()`                  | 1MB cloud save per player (hosted builds; always catch rejections)          |
+| `getPlayer()`                            | `{ name, avatarUrl }` or `null` — display identity only, always handle null |
+| `getVariant(key, variants)`              | Deterministic A/B split; alphabetical first variant = control               |
+| `rewardedBreak(opts)`                    | Rewarded ad; grant only when it resolves `true`                             |
+| `xrSessionStart()` / `xrSessionEnd()`    | Keep WebXR headset time counting as playtime                                |
+| `multiplayer.joinRoom(...)`              | Authoritative multiplayer rooms — see below                                 |
+
+Rejections from `save()`/`load()` are real `Error`s carrying a typed machine-readable
+`code`: `'unsupported' | 'unauthenticated' | 'too_large' | 'rejected' | 'error'`.
+
+## Multiplayer
+
+```ts
+import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
+
+const room = await joinRoom({ create: true }); // or { code: 'ABCD' }
+room.on('snapshot', ({ state }) => render(state)); // server-authoritative state
+room.on('end', ({ results }) => showResults(results));
+room.send({ move: dir }); // inputs only — the server simulates
+```
+
+Rooms run on Bounty Board's authoritative room servers: clients send inputs, the server
+validates and simulates, and each player receives only the state they're allowed to see
+(your hiders stay hidden). Auth is a short-lived signed ticket the SDK obtains from the
+host automatically; off Bounty Board `joinRoom` rejects with `code: 'unsupported'`.
+
+Multiplayer is currently a curated integration: Bounty Board must add and deploy a
+server-side game module for your slug before `joinRoom()` can accept players. The
+initial reference module is `hide-and-seek`; arbitrary games do not become
+authoritative multiplayer games merely by importing the client SDK.
+
+## Docs
+
+- Human docs: https://www.bountyboard.gg/arcade/sdk
+- Agent-readable reference: https://www.bountyboard.gg/arcade/sdk/llms.txt
+- Integration best practices for coding agents: [`AGENTS.md`](./AGENTS.md)
+- What makes a game perform on Bounty Board: [`docs/game-design-playbook.md`](./docs/game-design-playbook.md)
+- Submit your game: https://www.bountyboard.gg/arcade/submit
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).