@bountyboard/arcade-sdk 1.0.0

package/docs/game-design-playbook.md

@@ -0,0 +1,73 @@
+# 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
+decide whether the game earns plays, retention, and revenue.
+
+> 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
+  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
+  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".
+
+## 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.
+- **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
+  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
+  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.
+
+## Multiplayer design (for room-based games)
+
+- **Latency-tolerant mechanics win.** Positional games at 10–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.
+- **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.
+- **Send inputs, not outcomes.** If your design needs the client to decide who got tagged, the
+  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
+  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;
+  `rewardedBreak` after a natural fail state converts best.
+- **Always pause audio/game in `onStart`** and only grant on `true`. A game that grants on
+  dismissed ads gets its ad access revoked.
+
+## 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
+  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
+  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.
+
+## Ship checklist (design, not code)
+
+- [ ] A stranger reaches "I get it" inside 10 seconds of play
+- [ ] A full run fits in 3 minutes; restart is one input
+- [ ] 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
+- [ ] Boots and plays with the SDK fully offline

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@bountyboard/arcade-sdk",
+  "version": "1.0.0",
+  "description": "Bounty Board Arcade SDK — leaderboards, cloud saves, rewarded ads, A/B variants, and multiplayer rooms for games on bountyboard.gg",
+  "keywords": [
+    "bountyboard",
+    "arcade",
+    "game",
+    "sdk",
+    "leaderboard",
+    "html5"
+  ],
+  "homepage": "https://www.bountyboard.gg/arcade/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachery-moore/bounty-board.git",
+    "directory": "packages/arcade-sdk"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./multiplayer": {
+      "types": "./dist/multiplayer.d.ts",
+      "import": "./dist/multiplayer.js",
+      "require": "./dist/multiplayer.cjs"
+    },
+    "./global": {
+      "types": "./dist/global-sdk.d.ts",
+      "default": "./dist/global.js"
+    }
+  },
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": true,
+  "scripts": {
+    "build": "tsup && node scripts/build-global-dts.mjs",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  }
+}