# Playtest hosting: agent guide

> Deploy a web game build (Unity WebGL, Godot web export, or plain HTML/JS) and get back a
> link that plays it. You (the agent) do the whole loop over HTTP; your human only approves
> you once in a browser.

## Before you deploy: game state must live in browser storage

Analytics here (progress, pinned metrics, save replay) are read from the game's saved state,
with no platform code in the game. That only works if the game keeps its state in one of the
supported places:

1. localStorage, as JSON under readable keys (e.g. "save" → {"level": 3, "deaths": 12}). Preferred.
2. IndexedDB (what Unity PlayerPrefs / persistentDataPath and Godot user:// use in web builds).

If you are writing or changing the game, use one of these. If it keeps state anywhere else
(memory, cookies, its own backend), add the save.js wrapper from "Game state" below so the
state is mirrored into localStorage at checkpoints. Tell your human if you can't.

Three rules that protect the game and its players:
- Builds are public. Anyone with the play link can download every file of every build (there
  are no private builds yet). Never put secrets in a build: API keys, tokens, credentials.
- Games share a parent domain. Each game's localStorage and IndexedDB are its own, but a
  cookie set for the parent domain is visible to every other game. Cookies a game sets are
  kept to its own origin (any Domain= is removed). Don't use cookies for anything private;
  keep state in localStorage.
- Keep each saved key under 64 KB. A larger value isn't kept, and save points that hold one
  can't be restored or rewound. Split state by what it is (settings, progress, world) instead
  of one large key, and write only the keys that changed.

API base: https://api.betacade.com
OpenAPI spec: https://api.betacade.com/openapi.json (YAML: https://api.betacade.com/openapi.yaml, human docs: https://api.betacade.com/)
All API requests and responses are JSON. Every success carries a `next` hint saying what to do
next; every error is {"error": {"code": "...", "message": "... Fix: ..."}} — branch on `code`,
follow the fix in `message`.

## Start here: concepts

Read this first; the steps below use these words.

- Save: the game's localStorage keys (or IndexedDB). The play page syncs them to us about 2
  seconds after the game writes, at most once every 30 seconds, plus once when a session ends.
- Save point (also "checkpoint"): one synced snapshot of those keys at a moment.
- Save history: one tester's save points in order, across their sessions and builds.
- Branch: a line of save history. A new branch starts whenever a tester, or you, resume from
  an older save point; the old line is kept as it was. Resuming in the studio (a restore link,
  or the replay viewer's "Open in-game") starts a new branch FROM THE POINT YOU CHOSE, never
  from the tester's latest save, and never changes the tester's own history.
- Tester: one player of one game, shown as {"testerId", "displayName", "nameSource"}. They
  have an alias ("Amber Fox"), never an email you can see.
- Resumable (a build setting): this build loads its whole state from the saved keys. It lets
  testers carry on across builds and devices, and lets you open any save point in this build.
- Replayable (a build setting): this build records its live state, so a session plays back
  smoothly. It needs code in the game (section 11).

    Main            ●───●───●───●───●        one ● per save point, oldest left
                            │
    "From 12:40"            └───●───●        resumed from an older point: a new branch

The two kinds of replay:

|                       | Save-point replay                         | Smooth replay                                   |
| --------------------- | ----------------------------------------- | ----------------------------------------------- |
| Build setting         | resumable: true                           | replayable: true (and resumable, usually)       |
| What's recorded       | the saved keys, at each sync              | the game's own snapshots, up to 30 a second     |
| What the game must do | load from its save; in replay skip input, | register wt.onSnapshot and wt.onReplay, keep a  |
|                       | saves and tracking, then wt.ready()       | stateVersion in the snapshot                    |
| What the viewer shows | a still frame per save point              | continuous playback, scrubbing, 0.5x to 8x      |
| What breaks it        | state kept outside the saved keys         | changing the snapshot's shape without changing  |
|                       |                                           | stateVersion                                    |

Ask your human first: quick, or thorough? Before changing the game, ask which they want, and
say what each costs for THIS game (you've seen its code; judge it, don't guess from this page):
- Quick: deploy the build as it is. Playable in minutes, with sessions, play time, errors and
  feedback. Progress and save-point replay work only if the game already keeps its state in
  localStorage.
- Thorough: also make the game resumable (all state in localStorage, loaded at startup) and,
  if they want smooth replay, replayable (the hooks in section 11), then test that a resumed
  save and a replay look right. This can take a while: it depends on how the game keeps its
  state and how its loop is written.
Either way, deploy the quick version first if you can, so they have a link while you work.

Which settings to choose:
- All the game's state is in localStorage, loaded at startup: set resumable: true.
- State lives anywhere else: add the save.js wrapper ("Game state" below) first, then resumable.
- You can split the game into state = step(state, input, dt) and render(state): also set
  replayable: true and add the hooks (section 11). Otherwise leave it off; save-point replay
  still works.

stateVersion (smooth replay only):
- Change it when the snapshot's SHAPE changes (a field renamed, added with new meaning, or its
  type changed). Don't change it on every build.
- A recording always plays in the build it was recorded on, so old recordings keep working
  after you change it. The viewer refuses a recording whose stateVersion isn't the one that
  build's wt.onReplay registers, and falls back to save points with a note; it never guesses.

Lists and limits:
- Every list takes ?limit= (default 20, at most 100; the tester timeline at most 50) and pages
  with ?cursor=<nextCursor> from the previous page; nextCursor is null on the last page. Newest
  first unless the section says otherwise. A limit out of range is 400 "invalid_request".
- A saved value over 64 KB isn't kept: it shows as {"tooLarge": true} and can't be fetched.
- Feedback text is "body"; a bug's text is "description".

A minimal working game: one file, every hook. REQUIRED parts make the platform's analytics,
resume and save-point replay correct; OPTIONAL parts add to them. It runs the same on any other
host (every wt call is optional-chained).

```html
<!doctype html>
<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>Tiny Toad</title><style>html,body{margin:0;height:100%;background:#111}canvas{display:block}</style></head>
<body><canvas id="c"></canvas>
<script>
const wt = window.wt;                     // our script loads before yours; undefined elsewhere
const replaying = wt?.replaying === true; // REQUIRED: true in both kinds of replay

// REQUIRED: all state in one JSON key, loaded at startup, written with setItem.
const KEY = "save";
const fresh = () => ({ stateVersion: 1, level: 1, x: 40 });
let state;
try { state = { ...fresh(), ...JSON.parse(localStorage.getItem(KEY) ?? "{}") }; } catch { state = fresh(); }
function save() { if (!replaying) localStorage.setItem(KEY, JSON.stringify(state)); } // no saves in replay

// REQUIRED: no input during a replay.
let held = false;
addEventListener("pointerdown", () => { if (!replaying) held = true; });
addEventListener("pointerup", () => { held = false; });

// OPTIONAL: milestones (never during a replay), and a checkpoint when it happens.
function levelUp() {
  state.level += 1; state.x = 40; save();
  if (!replaying) wt?.track?.("level.complete", { level: state.level - 1 });
}

// OPTIONAL: pause. requestAnimationFrame is already frozen for you; this resets the frame clock.
let paused = false;
wt?.onPause?.(() => { paused = true; save(); });
wt?.onResume?.(() => { paused = false; last = performance.now(); });

// OPTIONAL (replayable builds): smooth replay hands states back; we only draw them.
const events = [];
wt?.onSnapshot?.(() => ({ ...state, events: events.splice(0) }));
wt?.onReplay?.({ stateVersion: 1, state(s) { state = { ...fresh(), ...s }; } });

const c = document.getElementById("c"), g = c.getContext("2d");
let last = performance.now();
function frame(now) {
  const dt = Math.min(0.05, (now - last) / 1000); last = now;
  if (!paused && !replaying) {            // simulate only in real play
    state.x += (held ? 160 : 40) * dt;
    if (state.x > innerWidth - 40) { events.push("ding"); levelUp(); }
  }
  if (c.width !== innerWidth || c.height !== innerHeight) { c.width = innerWidth; c.height = innerHeight; }
  g.fillStyle = "#16173a"; g.fillRect(0, 0, c.width, c.height);
  g.fillStyle = "#5fcf7a"; g.fillRect(state.x, c.height / 2, 24, 18);
  g.fillStyle = "#fff"; g.fillText("Level " + state.level, 12, 20);
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

// REQUIRED (resumable builds): in save-point replay, freeze once the saved state is drawn.
if (replaying) requestAnimationFrame(() => requestAnimationFrame(() => wt?.ready?.()));
</script></body></html>
```

Changelog (breaking changes marked; tell your human when one affects them):
- 2026-10-01: a player who plays without sharing data gets a tester when they first write (their
  alias, no play data), so you can reply; feedback's "tester" is null only for a note with no
  browser key.
- 2026-10-01: builds carry "warnings" (finalize says if a file uses cookies), and cookies a
  game sets are kept to its own origin (any Domain= is removed).
- 2026-10-01: production moved to https://api.betacade.com. Games are served from their own domain,
  <slug>.<games domain> (see each build's buildUrl; don't build these URLs yourself).
  Existing tokens, games, builds and testers carried over.
- 2026-09-30: you can write to testers: POST /v1/games/<gameId>/players/<testerId>/messages
  (section 7). BREAKING: feedback no longer has "email", and nameSource is never "email":
  testers are the studio's name for them or their alias.
- 2026-09-29: saves are a tree (section 9). BREAKING: checkpoints carry "branchId", and
  restore links need it ({"branchId", "at"}).
- 2026-09-28: BREAKING: testers became objects {"testerId", "displayName", "nameSource"}
  everywhere they were numbers; address them by testerId.

## 1. Sign in (device authorization, one time)

POST https://api.betacade.com/v1/device/authorize
Content-Type: application/json

{"clientName": "Claude Code"}

→ 200 {"deviceCode": "...", "userCode": "ABCD-EFGH", "verificationUrl": "https://api.betacade.com/device?code=ABCD-EFGH", "interval": 5, "expiresIn": 900, "next": "..."}

Tell your human: "Open <verificationUrl>, check the code matches <userCode>, sign in with
your email and approve." They get a 6-digit code by email; no account is needed beforehand
(one is created when they approve). Then poll:

POST https://api.betacade.com/v1/device/token
Content-Type: application/json

{"deviceCode": "<deviceCode>"}

- 400 {"error": {"code": "authorization_pending"}}: not approved yet; wait `interval` seconds and poll again.
- 400 "slow_down": you polled too fast; add 5 seconds to your interval.
- 400 "access_denied": the human denied it. Stop.
- 400 "expired_token": 15 minutes passed. Start again at /v1/device/authorize.
- 200 {"accessToken": "bc_pat_...", "tokenType": "Bearer", "scopes": ["games:read", "games:write"]}

The token is returned exactly once. Store it (e.g. in an env var or your project's local,
git-ignored config) and send it on every request below:

Authorization: Bearer <accessToken>

## 2. Create a game (once per game)

Before creating it, ask your human what their studio is called (the name players should see
the game is by). Players see it on the play page's welcome: "Space Frogs by Pond Studio".

POST https://api.betacade.com/v1/games
{"name": "Space Frogs", "studioName": "Pond Studio"}

→ 201 {"id": "<gameId>", "slug": "space-frogs", "studioName": "Pond Studio", "playUrl": "https://play.betacade.com/g/space-frogs", ...}

studioName is optional (at most 60 characters). Leave it out if your human has none: the page
then names only the game, never your account. Set or change either name later (the slug and
every link stay): PATCH https://api.betacade.com/v1/games/<gameId> {"studioName": "Pond Studio"}; null clears it.

GET https://api.betacade.com/v1/games lists your games; reuse the id on later deploys instead of creating another.

## 3. Start a build

POST https://api.betacade.com/v1/games/<gameId>/builds
Idempotency-Key: <any unique string, e.g. a UUID; reuse it only to retry the same request>

Pick the upload mode by what you can do:

| You can…                                              | Use                                                                 |
| ----------------------------------------------------- | ------------------------------------------------------------------- |
| Run a shell (macOS, Linux, Windows 10+)               | `tar -czf build.tar.gz -C <build-folder> .` then archive mode        |
| Run a shell with `zip`                                | `cd <build-folder> && zip -r ../build.zip .` then archive mode        |
| Only make HTTP requests, or have just one HTML file   | files mode (`sha256` optional; without it every file is uploaded)    |

tar with gzip ships with all three desktop OSes; zip often isn't installed on minimal Linux.
Archives (.zip, .tar, .tar.gz) are recognized by their bytes, not their file name.

Archive mode:

{"mode": "archive", "sizeBytes": <archive size in bytes>, "notes": "optional release notes"}

→ 201 {"number": 1, "mode": "archive", "uploadUrl": "https://...", "uploadExpiresAt": "...", "next": "..."}

Files mode (one entry per file, paths relative to the build folder):

{"mode": "files", "files": [{"path": "index.html", "sizeBytes": 1234, "sha256": "<hex, optional>"}]}

→ 201 {"number": 1, "mode": "files", "uploads": [{"path": "index.html", "uploadUrl": "https://..."}], "alreadyStored": [], ...}

Files whose sha256 we already store for you are left out of `uploads` (listed in
`alreadyStored`), so a rebuild only sends what changed. Send sha256 to get this.

Limits: 100 MB unpacked per build, 5000 files, no absolute paths or "..".

## 4. Upload

PUT the raw bytes to each uploadUrl (no Authorization header; the URL is pre-signed):

curl -sS -T build.tar.gz "<uploadUrl>"

## 5. Finalize

POST https://api.betacade.com/v1/games/<gameId>/builds/<number>/finalize

→ 200 {"number": 1, "status": "ready", "preset": "unity|godot|html", "fileCount": 42, "warnings": [],
       "playUrl": "https://play.betacade.com/g/space-frogs", "buildUrl": "https://play.betacade.com/g/space-frogs/1", "next": "..."}

We check every upload landed (and matches its sha256), unpack the archive, detect the engine
preset, and find the entry index.html (at the root, or inside a single top-level folder).
- The response carries "warnings" (usually []): what we noticed but didn't reject, e.g.
  "game.js uses document.cookie: ...". The build is ready; fix them in your next build.
- 409 "upload_missing": PUT the missing files, then finalize again.
- 422 (e.g. "no_entry", "path_escape", "build_too_large", "sha256_mismatch"): the build is
  marked failed; fix what the message says and start a new build.

## 6. Hand back the links

- playUrl always plays the latest ready build. Give this to your human.
- buildUrl plays that exact build forever.
- GET https://api.betacade.com/v1/games/<gameId>/builds lists builds and their status.
- Tell your human they can see who played at https://api.betacade.com/studio (they sign in with an email code).

## 7. Who played (when your human asks)

Players are anonymous testers. The play page asks each player first, and records nothing for one
who chooses to play without sharing data. Everywhere below a tester is
{"testerId": "3f9a1c07be", "displayName": "Amber Fox", "nameSource": "alias"}: address them by
testerId (a random id, unique in the game) and refer to them by displayName, which is your own
name for them ("studio"), else a random alias drawn once for them in this game ("alias"). Nothing
is numbered. Testers have no email you can see, even ones signed in on the play page.

GET https://api.betacade.com/v1/games/<gameId>/players

→ 200 {"items": [{"tester": {"testerId": "3f9a1c07be", "displayName": "Amber Fox", "nameSource": "alias"},
       "alias": "Amber Fox", "studioName": null, "firstSeenAt": "...", "lastSeenAt": "...",
       "playSeconds": 312, "sessionCount": 2, "builds": [1, 2], "errorCount": 1, ...}], "next": "..."}

Name a tester for your human (private: the tester never sees it; games:write):

PATCH https://api.betacade.com/v1/games/<gameId>/players/<testerId>
{"name": "Sam from Discord"}

→ 200 {"tester": {"testerId": "3f9a1c07be", "displayName": "Sam from Discord", "nameSource": "studio"},
       "alias": "Amber Fox", "studioName": "Sam from Discord", "next": "..."}
At most 60 characters; {"name": null} clears it.

GET https://api.betacade.com/v1/games/<gameId>/sessions?limit=20

→ 200 {"items": [{"id": "<sessionId>", "tester": {"testerId": "3f9a1c07be", ...}, "buildNumber": 2, "startedAt": "...",
       "playSeconds": 190, "status": "playing|idle|ended", "errorCount": 1,
       "display": {"viewportW": 390, "viewportH": 664, "screenW": 390, "screenH": 844, "dpr": 3,
                   "orientation": "portrait", "touch": true}}], "nextCursor": null, "next": "..."}
Newest first; pass nextCursor back as ?cursor= for the next page. To answer "who played today?",
page until startedAt is before today. "display" is the size the session opened with: viewportW ×
viewportH is the game's own frame in CSS pixels (what your layout gets, smaller than the screen),
screen is the device's; null when the page recorded none. Resizes during play are kept too, and
the studio's replay shows each save point at the size the tester had then.

GET https://api.betacade.com/v1/games/<gameId>/sessions/<sessionId>

→ 200 {..., "errors": [{"message": "...", "stack": "...", "at": "...", "lines": ["log: ...", "warn: ..."]}],
       "endLines": ["..."]}
Each error carries the console lines leading up to it (the last 200, each cut to 500 characters).
Play time is the span from a session's start to its last heartbeat (sent every 30 s while the tab
is visible). All three need the games:read scope your token already has. Each player also
carries "metrics": every pinned metric's latest and highest value for them (see step 8).

How many were playing over time (counts only, no testers named; games:read too):

GET https://api.betacade.com/v1/games/<gameId>/activity?window=1h

→ 200 {"window": "1h", "bucketSeconds": 60, "buckets": [{"at": "...", "players": 2,
         "byBuild": [{"buildNumber": 4, "players": 2}], "new": 1, "returning": 1}, ...],
       "builds": [{"buildNumber": 4, "label": "build 4", "players": [0, ..., 2]}, ...],
       "playingNow": 3, "playingNowBreakdown": {"new": 1, "returning": 2,
       "byBuild": [{"buildNumber": 4, "testers": 2}, {"buildNumber": 3, "testers": 1}],
       "signedIn": 1, "anonymous": 2}, "peak": {"at": "...", "players": 3}, "next": "..."}
window is 1h (1-minute buckets, the default), 24h (15-minute) or 7d (hourly). Each bucket counts
the distinct players with a session overlapping it, oldest first, zeros included; the last bucket
holds now. A bucket's byBuild counts each of its players once, on the newest build they played
in it (so it sums to players); "new" players' first session on this game overlaps the bucket,
the rest are "returning". builds is the chart legend: the builds in any bucket, newest first, at
most five, then {"buildNumber": null, "label": "older"} summing the rest; each entry's players
lines up with buckets. playingNow counts players whose session heartbeated in the last 75 seconds.
playingNowBreakdown splits them: "new" had no earlier session on this game, "returning" did;
byBuild is newest build first (someone playing two builds at once counts under each); "signedIn"
signed in to a player account on the play page, "anonymous" didn't.

How long testers played in a window (counts only; games:read):

GET https://api.betacade.com/v1/games/<gameId>/play-time?window=1h

→ 200 {"window": "1h", "buckets": [{"label": "<1 min", "minSeconds": 0, "maxSeconds": 60, "testers": 2},
       {"label": "1–5 min", "minSeconds": 60, "maxSeconds": 300, "testers": 3}, ...,
       {"label": "60+ min", "minSeconds": 3600, "maxSeconds": null, "testers": 0}],
       "testers": 5, "medianSeconds": 140, "next": "..."}
Each tester active in the window (a session overlapping it, as activity counts them) is counted
once, by their total play time inside the window: every session's start → last heartbeat, clipped
to the window, summed. Buckets are [minSeconds, maxSeconds). Same windows as activity.

What size of screen they play on (counts only; games:read):

GET https://api.betacade.com/v1/games/<gameId>/displays?window=1h

→ 200 {"window": "1h", "testers": 6, "unknown": 0,
       "classes": [{"name": "phone", "label": "Phone", "minWidth": 1, "maxWidth": 599, "testers": 4},
                   {"name": "tablet", ..., "testers": 0}, {"name": "desktop", ..., "maxWidth": null, "testers": 2}],
       "portrait": 4, "landscape": 2, "touch": 4,
       "sizes": [{"viewportW": 390, "viewportH": 664, "testers": 3}, ...], "next": "..."}
Each tester active in the window counts once, by their most recent session there and the game
frame size it opened with: phone under 600 CSS pixels wide, tablet 600–1024, desktop wider.
"sizes" is the five most common exact sizes. If most testers are on phones, make sure the game
fits a narrow portrait frame and takes touch.

Feedback testers sent from the play page's pause menu (newest first, paged like sessions):

GET https://api.betacade.com/v1/games/<gameId>/feedback

→ 200 {"items": [{"tester": {"testerId": "3f9a1c07be", "displayName": "Amber Fox", "nameSource": "alias"},
       "buildNumber": 2, "sessionId": "<sessionId>", "atSeconds": 95, "createdAt": "...",
       "body": "The jump feels floaty"}], "nextCursor": null, "next": "..."}
"atSeconds" is how far into the session it was sent. A player who plays without sharing data
still has a tester once they write (their alias, no play data, sessionId null), so you can reply;
"tester" is null only for the rare note sent with no browser key. There is no email: a tester is
their alias, or your name for them.

Reply to a tester, or write first (games:write). They see it from your studio's name (the game's
studioName, else "the developer"), never your human's account or you; Betacade emails a tester who
has an account (at most once per thread every 6 hours, sooner once they've read it), and you never
see their address:

POST https://api.betacade.com/v1/games/<gameId>/players/<testerId>/messages
{"body": "Thanks! Fixed in build 3. Does the jump feel better now?"}

→ 201 {"tester": {"testerId": "3f9a1c07be", "displayName": "Amber Fox", "nameSource": "alias"},
       "items": [{"id": "...", "sender": "player", "body": "The jump feels floaty", "buildNumber": 2,
                  "atSeconds": 95, "createdAt": "..."},
                 {"id": "...", "sender": "developer", "body": "Thanks! Fixed in build 3. ...",
                  "buildNumber": null, "atSeconds": null, "createdAt": "..."}],
       "blocked": false, "contactable": true}
Read the thread with GET on the same path (games:read). 1 to 2,000 characters. 403
"tester_blocked_messages": they block your studio's messages. 403 "tester_not_contactable": they
turned sharing off and never wrote (reply once they send a note). 429 "studio_messages_too_fast":
at most 100 an hour per game and 10 per tester; wait Retry-After seconds. Never ask a tester for
contact details on your human's behalf unless your human asked you to.

## 8. Pin metrics: how far testers get

The play page syncs each tester's localStorage (keys starting with "secret:" never leave the
browser). Pin up to 5 metrics per game, each pointing at a number inside a key's JSON value,
e.g. "save" → "level". Only JSON numbers count; strings and missing values are ignored.

First, see what the saves hold:

GET https://api.betacade.com/v1/games/<gameId>/save-keys

→ 200 {"items": [{"key": "save", "players": 4, "sample": "{\"level\":3,\"deaths\":12}",
       "paths": [{"path": "level", "sample": 3}, {"path": "deaths", "sample": 12}]}], "next": "..."}

Then pin one (games:write). path is a dot path into the value ("stats.deaths"; numeric segments
index arrays), or "" when the value itself is the number:

POST https://api.betacade.com/v1/games/<gameId>/metrics
{"label": "Level", "key": "save", "path": "level"}

→ 201 {"metric": {"id": "<metricId>", "label": "Level", "key": "save", "path": "level", ...},
       "backfill": {"changes": 57, "truncated": false}, "next": "..."}
Pinning replays the saves already synced, so earlier plays count too.
- 409 "metric_limit_reached": 5 are pinned; unpin one with DELETE https://api.betacade.com/v1/games/<gameId>/metrics/<metricId>.
- 409 "metric_exists": that key and path are already pinned.
- 422 "invalid_metric": fix the label, key or path as the message says.

Then read it:

GET https://api.betacade.com/v1/games/<gameId>/metrics/<metricId>

→ 200 {"metric": {...}, "playersWithValue": 4,
       "reached": [{"value": 1, "players": 4, "medianPlaySeconds": 40}, {"value": 3, "players": 2, "medianPlaySeconds": 610}],
       "latest": [{"value": 2, "players": 2}, {"value": 3, "players": 2}], ...}
"reached" answers "how many testers got to level 3, and after how much play time?" (median
of their total play time, across sessions, when they first reached it). GET
https://api.betacade.com/v1/games/<gameId>/metrics lists the pinned ones.

The same for recent testers only: GET https://api.betacade.com/v1/games/<gameId>/metrics/<metricId>?window=1h adds

       "window": "1h", "activeTesters": 5,
       "reachedRanges": [{"from": 1, "to": 3, "testers": 5, "medianPlaySeconds": 40},
                         {"from": 4, "to": 4, "testers": 2, "medianPlaySeconds": 610}]
counting only the testers active in the window (a session overlapping it, as activity counts
them), though each one's highest value is their highest ever, not just the window's. Values
reached by the same number of testers are merged into one range (the same testers reached them
all); medianPlaySeconds is to reach "from". window is 1h (the default), 24h or 7d and scopes only
these fields; "reached" and "latest" always cover every tester.

One tester's current save (the tip of the save branch they last played, see 9) and change
timeline (newest first, paged like sessions):

GET https://api.betacade.com/v1/games/<gameId>/players/<testerId>/save

## 9. Resumable builds: testers resume, you play from their saves

Mark a build resumable ONLY after the game keeps ALL its state in localStorage as described in
"Game state" below: it loads everything from those keys at startup and writes them with
setItem / removeItem / clear. Restoring a save into a game that keeps state anywhere else can
corrupt it. When you turn it on, tell your human you did and why it's safe.

Set it when starting the build ({"mode": ..., "resumable": true}), or toggle it later
(games:write):

PATCH https://api.betacade.com/v1/games/<gameId>/builds/<number>
{"resumable": true}

{"resumable": false} turns it off. `resumable` shows on every build, and on the game (its latest
ready build). On a resumable build the play page offers each tester who sends data "Switch save"
(their saves, on any device they're signed in on: continue, rename or delete one) and "Go back in
time" (one save's checkpoints; loading an older one is marked as a rewind).

Saves are a tree. Each save sync is a checkpoint on a branch; going back to an older checkpoint and
saving starts a new branch from there ("From <time>", the tester can rename it), so the old future
stays as it was. The state at a checkpoint is its own branch up to it, on top of its parent at the
fork point: never what another branch wrote. A tester's branches (deleted ones never show):

GET https://api.betacade.com/v1/games/<gameId>/players/<testerId>/branches

→ 200 {"items": [{"branchId": "<uuid>", "name": "Main", "named": true, "createdAt": "...",
       "forkedFrom": null, "tipAt": "...", "tipBuildNumber": 2, "checkpoints": 14, "lastPlayedAt": "..."},
       {"branchId": "<uuid>", "name": "From 2026-01-01 12:40 UTC", "named": false, ...,
       "forkedFrom": {"branchId": "<Main's>", "name": "Main", "at": "2026-01-01T12:00:00.000Z"}, ...}], "next": "..."}

To play from a tester's save yourself, list their checkpoints (one per save sync, each with its
branch) and mint a restore link for one:

GET https://api.betacade.com/v1/games/<gameId>/players/<testerId>/checkpoints

→ 200 {"items": [{"at": "2026-01-01T12:00:00.000Z", "buildNumber": 2, "changes": 3, "branchId": "<uuid>",
       "branch": {"branchId": "<uuid>", "name": "Main", "named": true, "createdAt": "...", "forkedFrom": null}}],
       "next": "..."}

POST https://api.betacade.com/v1/games/<gameId>/players/<testerId>/restore-links
{"branchId": "<the checkpoint's branchId>", "at": "<its at>"}

→ 201 {"url": "https://play.betacade.com/g/space-frogs/2#restore=...", "expiresAt": "...", "buildNumber": 2, "next": "..."}
Give your human the url. It works once and expires after 10 minutes; their play is recorded as
their own, marked restored, and the tester's history is never touched. Add "buildNumber" to
open the save in another (resumable) build.
- 409 "build_not_resumable": that build isn't resumable; PATCH it first (see above).
- 404 "not_found": no checkpoint at that time (on that branch); list them again.

## 10. Replay a tester's session and flag bugs

A tester's timeline: their sessions (newest first, paged like sessions), each with its save points
(one per save sync), errors, feedback and bugs at their times (games:read):

GET https://api.betacade.com/v1/games/<gameId>/players/<testerId>/timeline

→ 200 {"tester": {"testerId": "3f9a1c07be", "displayName": "Amber Fox", "nameSource": "alias"},
       "sessions": [{"id": "<sessionId>", "buildNumber": 2,
       "resumable": true, "startedAt": "...", "playSeconds": 410, "restoredBy": null,
       "branch": {"branchId": "<uuid>", "name": "Main", "named": true, "createdAt": "...", "forkedFrom": null},
       "savePoints": [{"branchId": "<uuid>", "at": "2026-01-01T12:00:00.000Z", "atSeconds": 95, "changes": 2,
                       "replayUrl": "https://api.betacade.com/studio/games/space-frogs/testers/3f9a1c07be/replay?session=...&at=..."}],
       "errors": [{"at": "...", "atSeconds": 120, "message": "..."}], "feedback": [...], "bugs": [...],
       "truncated": false}], "nextCursor": null, "next": "..."}
A session's branch is the save its save points are on (see 9); null when the tester deleted it,
and its save points are then left out.
Give your human a save point's replayUrl: the studio's replay viewer opens there, on one scrubber
over the whole save (every session that led to it), and steps through its save points, loading
each save into its session's build (smooth sessions play, 0.5x to 8x), with errors, feedback and
bugs marked at their times. It shows the game only when that
build is resumable (see 9); otherwise just the timeline. It uses their browser's own storage for
the game, setting their own save aside under the key "wt:replay-stash" until they exit, so don't
use that key in a game. This is replay from saves: the game at each save point, not the
movement between (for smooth replay from the game's own state, see 11; a session recorded that
way opens there instead, and falls back to this). Here the
game loads with "?wt-replay=1" in its URL, reads its save and, at the end of the next animation
frame, is frozen with the same pause as the play page's menu (it hears "wt:pause", see Pausing
below), so it shows that moment instead of playing on. In replay the clock is pinned to the
save's time (Date.now() and new Date() start there; nothing advances while frozen) and
setTimeout/setInterval are held while frozen, so "time since last save" is seconds, not the
days since the tester played. The game should still help: when window.wt.replaying is true, load and draw the saved state and skip
catch-up or offline progress, intro tweens and random events, then call window.wt.ready() once
drawn to freeze right there:

```js
const replaying = window.wt?.replaying === true;
const state = loadGame();
if (!replaying) applyOfflineProgress(state, Date.now() - state.savedAt);
render(state, { skipIntro: replaying });
window.wt?.ready?.();
```

wt.replaying is false and wt.ready() does nothing outside a replay, and on other hosts neither
exists, so with optional chaining the game runs the same anywhere.

Flag a bug at a moment (games:write), usually a save point, so it opens back up exactly there:

POST https://api.betacade.com/v1/games/<gameId>/bugs
{"testerId": "3f9a1c07be", "sessionId": "<sessionId>", "at": "<a save point's at>", "buildNumber": 2,
 "description": "The door stays locked after the key is picked up", "reproSteps": "1. ..."}

→ 201 {"bug": {"id": "<bugId>", "status": "open", "tester": {"testerId": "3f9a1c07be", ...}, "sessionId": "...",
       "buildNumber": 2, "at": "...", "atSeconds": 95, "description": "...", "reproSteps": "...",
       "replayUrl": "https://api.betacade.com/studio/...", ...}, "next": "..."}
Only buildNumber and description are required. With a session, testerId must be its tester
and buildNumber its build, and "at" must lie within it.
- 422 "invalid_bug": the tester, session, build or moment don't belong to this game or each
  other; the message says which.

List them (newest first; status=open, the default, closed or all) and close one when fixed:

GET https://api.betacade.com/v1/games/<gameId>/bugs?status=open

PATCH https://api.betacade.com/v1/games/<gameId>/bugs/<bugId>
{"status": "closed"}

{"status": "open"} reopens it. Your human sees them on the game's studio page.

## 11. Replayable sessions: smooth replay

With the game's help the studio's replay viewer plays a session back smoothly (play, pause,
scrubbing, 0.5x to 8x, the same markers) by feeding the game's own recorded state back into the
same build. The contract:

1. Everything needed to draw a frame lives in one JSON-serializable state object (positions,
   animation phase, camera, visible UI, score, random values already drawn), and render(state)
   draws the same frame every time.
2. Simulation and rendering are separate: state = step(state, input, dt); render(state).
3. The game registers a snapshot getter with window.wt?.onSnapshot?.(() => state). We call it
   right after the game's animation frames, up to 30 times a second (stepping down to 15, 10, 5
   while it takes over ~1.5 ms, and back up); a snapshot identical to the last is skipped, and
   one over 32 KB is skipped with a marker. Include "stateVersion" (a number, or 1–64 of
   A-Z a-z 0-9 . _ : -) and change it whenever the state's shape changes.
4. The game registers replay hooks with window.wt?.onReplay?.({ enter(meta), state(s, opts),
   exit() }). In replay it doesn't step or take input; it draws what it's handed. opts is
   { t, next, alpha, events, seeking }: next and alpha (0–1 of the way to next) allow optional
   interpolation; t is the snapshot's time (Date.now() reads it too).
5. One-shot effects (sounds, particles) go in the snapshot as "events": [...], the ones since the
   previous snapshot (empty the list each time the getter runs). Replay never recomputes them: it
   hands back opts.events, every event passed since the last call, and none while seeking.
6. No save writes during replay (we drop them too).

```js
const state = { stateVersion: 3, player: { x: 0, y: 0 }, camera: { x: 0 }, score: 0 };
const pending = [];                              // one-shots since the last snapshot
function sfx(name) { pending.push(name); playSound(name); }

window.wt?.onSnapshot?.(() => ({ ...state, events: pending.splice(0) }));

let replaying = false;
window.wt?.onReplay?.({
  stateVersion: 3,                               // what this build reads; a mismatch isn't played
  enter(meta) { replaying = true; },             // stop stepping and reading input
  state(s, { next, alpha, events, seeking }) {
    render(next ? lerpState(s, next, alpha) : s);
    if (!seeking) events.forEach(playSound);
  },
  exit() { replaying = false; },
});

function frame(now) {
  if (!replaying) { step(state, readInput(), now); render(state); }
  requestAnimationFrame(frame);
}
```

Each registration returns an unsubscribe function. On other hosts, and on builds that aren't
replayable, the hooks are never called, so the game runs the same anywhere. States travel as
RFC 7386 merge patches between full snapshots, so a key set to null comes back missing: treat
null and absent alike.

Then mark the build replayable (games:write), or set it when starting the build
({"mode": ..., "replayable": true}):

PATCH https://api.betacade.com/v1/games/<gameId>/builds/<number>
{"replayable": true}

Tell your human you turned it on. From then on sessions of testers who share data record the
game's state (their notice says so); nothing is recorded for testers who play without sharing,
on builds that aren't replayable, or before the game calls wt.onSnapshot. `replayable` shows on
every build, and on the game (its latest ready build). {"replayable": false} stops recording;
what was recorded stays.

How one session can be replayed, its recording (metadata only) and markers (games:read):

GET https://api.betacade.com/v1/games/<gameId>/sessions/<sessionId>/replay

→ 200 {"mode": "smooth", "sampleRate": 30, "stateVersions": ["3"],
       "chunks": [{"seq": 1, "startAt": "...", "endAt": "...", "bytes": 48211, "snapshotCount": 870,
                   "keyframeOffsetsMs": [0, 5003, 10010], "sampleRate": 30, "stateVersion": "3",
                   "replayHooks": true}],
       "savePoints": [...], "errors": [...], "feedback": [...], "bugs": [...],
       "viewerUrl": "https://api.betacade.com/studio/games/space-frogs/testers/3f9a1c07be/replay?session=...", "next": "..."}
"mode" is "smooth" (a replayable build, recorded with wt.onReplay registered), "saves" (save
points, see 10) or "timeline". Give your human viewerUrl. The recording is served only to their
studio viewer; downloading chunks with your token comes later.

In the viewer the build loads with "?wt-replay=state": it boots as usual (its localStorage
writes are dropped), and once it registers wt.onReplay it gets enter(meta), then state() for
every frame shown. Its clock is pinned to each snapshot's time, its timers run only while the
viewer plays (held while paused), and requestAnimationFrame keeps running, so it can draw from
its own loop or inside state(). If it
doesn't register wt.onReplay within 25 seconds, or its onReplay stateVersion isn't the
recording's, the viewer goes back to save points (10) and says why; a mismatch is never guessed.

Sound in replay: the game's simulation doesn't run, so a sound it would trigger from step()
never plays. Play one-shot sounds from opts.events in state() (skip them while seeking), start
background music in enter(), and stop it in exit(). The viewer unlocks audio for you (the frame
can't be clicked: Play resumes your AudioContext and retries media the browser refused), and
Pause or its Sound off toggle suspends it; don't resume audio yourself in replay.

```js
window.wt?.onReplay?.({
  enter() { music.play(); },                                  // background music
  state(s, { events, seeking }) { render(s); if (!seeking) events.forEach(playSound); },
  exit() { music.stop(); } });
```

Engines:
- Unity WebGL: bridge with a small .jslib. C# keeps the latest state JSON on the JS side each
  frame (JsonUtility.ToJson in LateUpdate → WtPushState), since the getter must answer at once,
  and replay hands JSON back through SendMessage to a "ReplayBridge" object that
  JsonUtility.FromJson's it and draws. Keep the instance from createUnityInstance(...).then(i =>
  window.unityInstance = i) in index.html.

```js
// Assets/Plugins/WebGL/Replay.jslib
mergeInto(LibraryManager.library, {
  WtPushState: function (json) { window.wtUnityState = UTF8ToString(json); },
  WtRegister: function () {
    if (!window.wt) return;
    var send = function (method, arg) { if (window.unityInstance) window.unityInstance.SendMessage("ReplayBridge", method, arg); };
    window.wt.onSnapshot(function () { return window.wtUnityState ? JSON.parse(window.wtUnityState) : undefined; });
    window.wt.onReplay({
      enter: function () { send("Enter", ""); },
      state: function (s) { send("State", JSON.stringify(s)); },
      exit: function () { send("Exit", ""); },
    });
  },
});
```
- Godot 4: through JavaScriptBridge. Put the JS side in the export's Head Include, and from
  GDScript keep the latest state JSON on window each frame and give it a callback for states
  (keep a reference to the callback):

```js
// Export → HTML → Head Include (inside <script>)
window.wt?.onSnapshot?.(() => (window.wtGodotState ? JSON.parse(window.wtGodotState) : undefined));
window.wt?.onReplay?.({ state: (s) => window.wtGodotOnState?.(JSON.stringify(s)) });
```

```gdscript
var _on_state_cb = JavaScriptBridge.create_callback(_on_state)
func _ready():
    JavaScriptBridge.get_interface("window").wtGodotOnState = _on_state_cb
func _process(_delta):
    JavaScriptBridge.get_interface("window").wtGodotState = JSON.stringify(state)
func _on_state(args):
    state = JSON.parse_string(args[0]); render(state)
```

## Game state (required for analytics)

The agent that deploys is often the one writing the game. Keep its state in a supported place
so saves sync, replay and pinned metrics work with no platform code.

Saved state: use browser storage, at checkpoints.
- Keep the game's saved state in localStorage (or IndexedDB). Our script syncs, replays and
  restores it with no platform code in the game.
- Store it as JSON under readable keys, so pinned metrics can point into it (save.level,
  save.deaths).
- Write at checkpoints (level start, level complete, settings change), not every frame.
- Write with localStorage.setItem / removeItem / clear (not localStorage.foo = ...), so each
  change is seen as it happens.
- Never put login tokens or secrets in these keys; put anything sensitive under a key starting
  with "secret:", which we never sync.
- Keep each key under 64 KB (see "Three rules" above): split a big state into several keys.
- Unity (PlayerPrefs, Application.persistentDataPath) and Godot (user://) already save to
  IndexedDB in web builds; call PlayerPrefs.Save() or close the file at checkpoints so the
  write actually lands.
- Start cleanly from empty storage. Players can pick New game in our menu: we clear the game's
  localStorage (except "secret:" keys) and IndexedDB, then load it again.

If the game keeps state somewhere else (in memory, cookies, its own backend), mirror it into
localStorage at checkpoints with a small wrapper. It has no dependency on us, so the game runs
the same on itch.io or anywhere else:

```js
// save.js: one place to save and load, mirrored to localStorage so the
// playtest platform can sync, replay and restore it. Works anywhere.
const KEY = "save";

export function saveGame(state) {
  // Keep your existing save path too (cookie, backend, memory) if you have one.
  localStorage.setItem(KEY, JSON.stringify(state));
}

export function loadGame(defaults = {}) {
  try {
    return { ...defaults, ...JSON.parse(localStorage.getItem(KEY) ?? "{}") };
  } catch {
    return { ...defaults };
  }
}
```

Events and logs (optional, never required):
- Uncaught errors, unhandled promise rejections and the last 200 console lines are captured
  automatically (when the player agreed to share data); nothing to add.
- Our page provides window.wt when a game runs on the platform. Call it with optional chaining
  so nothing breaks elsewhere: window.wt?.track("level.complete", { level: 3 })
- console.info meaningful moments ("boss phase 2", "shop opened"); they become breadcrumbs on
  each player's timeline.

Each game runs on its own origin (<slug>.<games domain>), inside a sandboxed iframe with scripts,
same-origin storage, pointer lock and fullscreen allowed. Use relative URLs for assets.

## Pausing

The play page has a Pause button, and pauses when the player leaves the tab. On pause we freeze
requestAnimationFrame (the frames the game scheduled wait, then run on resume) and suspend its
running AudioContexts and playing <audio>/<video>, and pause CSS animations; on resume only what
we paused starts again. Timers (setTimeout/setInterval), Web Workers and animated GIFs are NOT
paused (a page can't pause a GIF: swap it for a still image on "wt:pause"). If the game loops on timers or
workers, counts real time, or should show its own pause screen, listen for the events:

```js
window.addEventListener("wt:pause", () => game.setPaused(true));
window.addEventListener("wt:resume", () => game.setPaused(false));
// Same, via window.wt (each returns an unsubscribe function):
window.wt?.onPause?.(() => game.setPaused(true));
window.wt?.onResume?.(() => game.setPaused(false));
// Reset your frame delta on resume so the paused time isn't simulated.
```

This works anywhere: on other hosts the events simply never fire.
- Unity WebGL: from the listener call into C# with the instance createUnityInstance returned,
  e.g. unityInstance.SendMessage("GameManager", "SetPaused", 1), and in SetPaused set
  Time.timeScale = 0 (back to 1 on resume).
- Godot: in GDScript, JavaScriptBridge.get_interface("window").addEventListener("wt:pause", cb)
  with cb = JavaScriptBridge.create_callback(...) (keep a reference to it), and set
  get_tree().paused = true there (false on "wt:resume").