@bountyboard/arcade-sdk 1.4.3 → 1.4.5

package/AGENTS.md

@@ -51,7 +51,7 @@ lockToHost() → init() → [getPlayer()] → gameLoadingFinished()
 ```
 
 `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
+analytics (feed ranking counts play sessions and ratings, not these calls), 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.
 
@@ -91,4 +91,5 @@ the safe/default experience the alphabetically-first name. Don't re-randomize cl
 ## 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.
+decisions, not integration details. The playbook separates platform facts (enforced by the SDK and
+host) from design guidance backed by cited public sources.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @bountyboard/arcade-sdk
 
+## 1.4.5
+
+### Patch Changes
+
+- 7a75783: Restyle the arcade player frame's controls on the Design Kit, and keep the CSS pseudo-fullscreen overlay above the site sidebar.
+
+## 1.4.4
+
+### Patch Changes
+
+- Host the official Spotify embedded player beside build-backed arcade games, and let embedded-player popups escape the game iframe's sandbox.
+
 ## 1.4.3
 
 ### Patch Changes

package/docs/game-design-playbook.md

@@ -1,75 +1,190 @@
 # 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.
+Read this BEFORE designing a new game or porting one in. The SDK wiring is the easy part; the
+choices below shape how a run feels, how the leaderboards behave, and how ads land.
 
-> Draft co-owned with our partner studios. Challenge anything here with data.
+How to read it. Two kinds of statement live here, and each one says which it is:
+
+- **Platform fact.** Behavior the SDK or the Bounty Board host enforces in code. These are
+  checkable in this package and in the host, and they change only with a release.
+- **Guidance.** Design advice. Where public research or another platform's published developer
+  docs back it, the source is cited as [n] (see Sources at the end). Guidance without a citation
+  is a design judgment, not a measured result. Nothing in this file is a claim about how games
+  perform on Bounty Board; we have not published that data.
 
 ## Session shape
 
-- **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
-  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".
+- **Guidance: keep a full run short.** A complete arc (start, tension, payoff) in roughly one to
+  three minutes suits players who arrive while browsing and keeps a restart cheap. This range is
+  our judgment, not a measured threshold. Longer games should checkpoint through cloud saves
+  (see Platform fit).
+- **Guidance: get to the first input fast.** Poki's developer docs note that players tend to move
+  to another game when loading takes more than 10 seconds [1], and recommend an initial download
+  of no more than 5MB and 8MB in total [2]. CrazyGames puts attention starting to wander at 10
+  seconds of waiting [3]. Aim well under that: defer heavy assets past the first playable moment.
+- **Platform fact: `gameLoadingFinished()` means "the player can start now".** It is an alias of
+  `ready()` and tells the host the game has loaded and is playable. Call it at that moment, not at
+  script load and not after a menu the player must click through.
+- **Guidance: make restart instant.** Game over to a new run should be one input and under a
+  second. Super Meat Boy's postmortem names this directly: "Remove lives, reduce respawn time, keep
+  the levels short and keep the goal always in sight" [4].
 
 ## 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 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
-  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.
+- **Platform fact: scores are positive integers with a per game ceiling.** The SDK truncates
+  fractional scores, the submit endpoint accepts only positive integers up to the 32 bit limit,
+  and a score above the game's cap is rejected. Unless Bounty Board sets a per game cap, that
+  ceiling is 10,000,000; games scored by time survived can instead get a per second allowance.
+  Keep a great run comfortably inside the range, and tell the reviewer what a top score looks like.
+- **Guidance: let skill show up in the score.** A great run should clearly beat a lucky one. If
+  score grows mainly with time played rather than with skill, long sessions crowd the top of the
+  board. Reward risk and precision; cap or decay pure survival scoring. This is design judgment;
+  we found no public study that sets a target spread.
+- **Guidance: show players how close they came.** In a gambling study, near misses raised the
+  desire to keep playing when the player had some control over the outcome [5]. Research on goal
+  proximity finds effort rises as people near a goal: café customers bought coffee more often as
+  they approached a free one [6]. Both findings come from outside score chasing games, so treat
+  them as a reason to try this, not a promised lift. In your own UI, show the player's best and
+  the gap to it.
+- **Platform fact: the host already shows a near miss.** After a run that sets no personal best
+  but lands just below a top three spot, the game page shows how many points short the player was.
+  Your in game UI can add finer detail (the gap to their own best, the next rank).
+- **Platform fact: the Today board resets at midnight UTC.** Every submitted score lands on both
+  the all time board and the Today board. A run counts toward the UTC day its play session
+  started, so a run that crosses midnight stays on the day it began.
+- **Daily mode.** If your game has procedural content, a shared seed daily run gives every player
+  the same level, so the board compares like with like. Spelunky's Daily Challenge is a well known
+  example: one attempt per day on a shared level, with a leaderboard [7]. Platform fact: submit
+  those runs with `{ mode: 'daily' }` on `submitScore()` / `gameOver()` so the Today board can mark
+  them.
 
 ## Multiplayer design (for room based games)
 
-- **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.
-- **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.
+- **Platform fact: clients send inputs; the room authority simulates.** On a Bounty Board hosted
+  module or a registered external server, the server runs the rules and validates every input.
+  If your design needs a client to decide who got tagged, move that rule to the server. Gambetta's
+  guide states the same principle: the server is the only authority, and you should assume
+  players will try to cheat [8].
+- **Guidance: prefer latency tolerant mechanics.** Other players are normally drawn slightly in
+  the past between snapshots (entity interpolation) [9]; Valve's Source engine defaults to 20
+  snapshots per second and a 100 ms interpolation delay [10]. That delay suits movement based
+  play (chase, tag, social deduction) and makes instant hit duels hard: when you aim at a target
+  drawn 100 ms in the past, precise hits need server side lag compensation [9][10]. Momentum,
+  grid steps, and proximity rules forgive latency better than frame perfect hits.
+- **Platform fact: tick and snapshot rates are set per module.** A hosted module's simulation
+  runs at 1 to 60 Hz, and its snapshot rate can be lower than its tick rate. The reference hide
+  and seek module ticks at 12 Hz; relay rooms batch messages at 20 Hz.
+- **Platform fact: hosted modules filter state per viewer.** Every snapshot goes through the
+  module's per viewer serializer, so a player receives only what they are allowed to know. In the
+  reference hide and seek module, the seeker's snapshot simply does not contain unfound hiders,
+  so a modified client has nothing to reveal. Riot uses the same idea against wallhacks in
+  VALORANT: do not send an enemy's position until it could be seen [11]. This holds for refereed
+  modules and external authorities you build that way. Relay rooms do not interpret game payloads,
+  so their outcomes are client trusted and never feed results or leaderboards.
+- **Platform fact: rooms fill by share code or quick match.** `joinRoom()` can create a room with
+  a share code, join a friend's code, or quick match into the game's open public room. Guidance:
+  plan for players arriving mid round. The reference hide and seek module runs a 5 second
+  countdown, 10 seconds of hiding, and 90 seconds of seeking, and late joiners spectate until the
+  next round.
 
 ## 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;
-  prepare one rewarded placement at a natural fail state and offer it once.
-- **The Watch Ad click must show directly.** Enable it only after `prepareRewardedAd()` returns
-  ready, then call the retained `show()` before any `await`, microtask, timer, or other work.
-- **Always pause audio/game in `onStart`** and grant only when the final status is `'viewed'`.
-  A raw provider `breakStatus`, dismissal, timeout, or error never earns the reward.
+- **Guidance: make the ad a trade the player chooses, never a toll.** Google's AdMob policy
+  requires rewarded ads to be served only after the user opts in, and says declining must not
+  interfere with normal use of the app [12]. CrazyGames recommends stating the reward on the button
+  ("Watch Ad for +50 Gems"), offering it at natural pauses, and suggests revives ("Respawn now",
+  "Keep your score", capped at once per session) and doubled end of level rewards [13]. A cosmetic
+  item also fits. Never gate core progression.
+- **Guidance: one placement at a natural fail state beats several interruptions.** Prepare one
+  rewarded placement where the run ends and offer it once. Cap anything that repeats [13].
+- **Platform fact: ads are host gated.** Rewarded ads run only when Bounty Board has enabled them
+  for the game (or in local test mode). Otherwise preparation returns `'unavailable'`, so the
+  game must be complete and fair without ads.
+- **Platform fact: the Watch Ad click must show directly.** Enable it only after
+  `prepareRewardedAd()` returns ready, then call the retained `show()` before any `await`,
+  microtask, timer, or other work. Browsers grant a short lived "transient activation" after a
+  click, and it expires after a timeout [14]; the SDK checks for it and fails closed with
+  `'direct_user_action_required'` when it is gone.
+- **Platform fact: always pause audio/game in `onStart`** and grant only when the final status
+  is `'viewed'`. A raw provider `breakStatus`, dismissal, timeout, or error never earns the reward.
 
 ## 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.
+- **Guidance: design for touch first.** One thumb controls, generous hit targets, no hover
+  dependence, portrait friendly if possible. Keyboard is the enhancement. WCAG sets 24 by 24 CSS
+  pixels as the minimum target size and 44 by 44 as the enhanced level [15]. Platform fact: a game
+  listed without touch support shows touch device players a desktop only notice, and only games
+  with touch support list "mobile and tablet browser" under supported devices.
+- **Guidance: budget for 60fps on a mid range phone.** A frame at 60fps has about 16 ms, and
+  web.dev's RAIL model advises producing each animation frame in 10 ms or less because the browser
+  needs the rest [16]. Render into a smaller back buffer when you need speed (cap the
+  devicePixelRatio you honor) [17], and pool objects to keep garbage collection pauses out of play
+  [18]. Avoid layout thrash.
+- **Platform fact: the SDK stays inert off platform.** Off Bounty Board the fire and forget calls do
+  nothing, `save()` / `load()` reject fast with `'unsupported'`, and `getPlayer()` resolves null.
+  Ship one bundle that runs standalone and on the arcade; don't fork builds.
+- **Platform fact: hosted builds have no native localStorage.** Bounty Board hosted uploads run in
+  an opaque origin sandbox where reading `localStorage` throws. Cloud saves (`save()` / `load()`)
+  work for hosted uploads with a logged in player: load on boot, save on checkpoint and game over,
+  and greet returning players with their progress (`getPlayer()` gives the display name, or null
+  for guests). Engine exports that need synchronous storage can use the SDK's cloud backed
+  `storage` shim instead; the script tag installs it automatically, module builds call
+  `storage.install()` before boot. 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
+- [ ] A stranger understands the goal within the first few seconds of play
+- [ ] Loading reaches a playable screen well under 10 seconds [1][3]
+- [ ] A full run is short; restart is one input
+- [ ] The score of a great run clearly beats the score of a lucky run, inside the score cap
+- [ ] Daily mode if content is procedural, submitted with `{ mode: 'daily' }`
+- [ ] Rewarded placement is a trade the player initiates, and the game is complete without it
+- [ ] Playable one thumb on a phone, aiming for 60fps
 - [ ] Boots and plays with the SDK fully offline
+
+## Sources
+
+Platform facts are backed by the code in this package (`src/types.ts`, `src/core.ts`,
+`src/storage.ts`, `src/multiplayer.ts`), the room server (`packages/arcade-mp-server`), and the
+Bounty Board host, not by the links below.
+
+[1] Poki Developer Docs, "Requirements".
+    https://developers.poki.com/guide/requirements-quality
+[2] Poki Developer Docs, "Choosing your web game engine".
+    https://developers.poki.com/guide/web-engine
+[3] CrazyGames Docs, "Game loading tips".
+    https://docs.crazygames.com/resources/getting-to-the-first-frame/
+[4] Edmund McMillen, "Postmortem: Team Meat's Super Meat Boy", Game Developer, 2011.
+    https://www.gamedeveloper.com/audio/postmortem-team-meat-s-i-super-meat-boy-i-
+[5] Clark, Lawrence, Astley-Jones and Gray, "Gambling near-misses enhance motivation to gamble
+    and recruit win-related brain circuitry", Neuron 61(3), 2009. doi:10.1016/j.neuron.2008.12.031
+    https://pmc.ncbi.nlm.nih.gov/articles/PMC2658737/
+[6] Kivetz, Urminsky and Zheng, "The Goal-Gradient Hypothesis Resurrected", Journal of Marketing
+    Research 43(1), 2006. doi:10.1509/jmkr.43.1.39
+    https://journals.sagepub.com/doi/abs/10.1509/jmkr.43.1.39
+[7] Mossmouth, "The Spelunky Daily Challenge".
+    https://spelunkyworld.com/dailychallenge/
+[8] Gabriel Gambetta, "Fast-Paced Multiplayer (Part I): Client-Server Game Architecture".
+    https://www.gabrielgambetta.com/client-server-game-architecture.html
+[9] Gabriel Gambetta, "Fast-Paced Multiplayer (Part III): Entity Interpolation".
+    https://www.gabrielgambetta.com/entity-interpolation.html
+[10] Valve Developer Community, "Source Multiplayer Networking".
+    https://developer.valvesoftware.com/wiki/Source_Multiplayer_Networking
+[11] Riot Games, "Demolishing Wallhacks with VALORANT's Fog of War", 2020.
+    https://www.riotgames.com/en/news/demolishing-wallhacks-valorants-fog-war
+[12] Google AdMob Help, "Policies for ad units that offer rewards".
+    https://support.google.com/admob/answer/7313578
+[13] CrazyGames Docs, "Mastering Rewarded Ads: A Deep Dive".
+    https://docs.crazygames.com/resources/rewarded-ads-deep-dive/
+[14] MDN Web Docs, "User activation".
+    https://developer.mozilla.org/en-US/docs/Web/Security/User_activation
+[15] W3C, "Understanding SC 2.5.8 Target Size (Minimum)" and "Understanding SC 2.5.5 Target Size
+    (Enhanced)", WCAG 2.2.
+    https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
+    https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html
+[16] web.dev, "Measure performance with the RAIL model".
+    https://web.dev/articles/rail
+[17] MDN Web Docs, "WebGL best practices".
+    https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices
+[18] web.dev, "Static Memory JavaScript with Object Pools".
+    https://web.dev/speed-static-mem-pools/

package/docs/llms.txt

@@ -2,12 +2,12 @@
 
 Human guide: https://www.bountyboard.gg/arcade/sdk
 Package: @bountyboard/arcade-sdk (https://www.npmjs.com/package/@bountyboard/arcade-sdk)
-Stable npm release: 1.4.3
+Stable npm release: 1.4.5
 Wire protocol: 1
 
 This file is the complete integration contract for coding agents integrating an
 HTML5 game. The package TypeScript declarations remain the exact public type
-reference. npm 1.4.3, the /arcade-sdk/v1.js browser artifact, and repository
+reference. npm 1.4.5, the /arcade-sdk/v1.js browser artifact, and repository
 source all expose the same surface. Rooms open on all three approved rails:
 Bounty shared service referee modules, Bounty shared service relay rooms, and
 host routed registered external authorities. code/create works on every rail;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bountyboard/arcade-sdk",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Bounty Board Arcade SDK: leaderboards, cloud saves, rewarded ads, A/B variants, and multiplayer rooms for games on bountyboard.gg",
   "keywords": [
     "bountyboard",