@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/saving-player-progress.md

@@ -0,0 +1,457 @@
+# Saving a player's progress
+
+Games do not have to save anything. This is a capability, not an obligation — a puzzle game
+that ends when the tab closes is a complete game. Read this if yours has progress worth keeping.
+
+If it does, keep it here rather than in the browser. A save in browser storage is lost when the
+player changes device, changes browser, or clears site data. The platform holds one instead, and
+the routes are reachable with the token your frame already holds.
+
+A save often holds a snapshot of what the player owns — a level, a party, a bag of items. What a
+player holds on the platform, as opposed to what your game chooses to serialise into a save, lives
+in [`inventory-and-catalogs.md`](inventory-and-catalogs.md); the two are neighbours in a reader's
+head, and a game with both usually reads them together.
+
+## Two roles, and they are not the same person
+
+This is the thing to get straight before anything else, because the two halves happen at
+different times and only one of them is code:
+
+|                                | Who                      | When                                                                 |
+| ------------------------------ | ------------------------ | -------------------------------------------------------------------- |
+| **Declaring the slot**         | you, the developer       | once, in your game config — the same way a room template is declared |
+| **Writing and reading a save** | your game's running code | every session, once per player                                       |
+
+A save lives in a **slot**, and a slot is something you publish. Game code cannot create one:
+writing to a key you never declared is refused with `not_found` naming the key, at the first
+call and at every retry after it. That is the wall almost everyone hits first, and it is why
+this page starts with the config rather than with the API.
+
+## 1. Declare the slot, in your game config
+
+Save slots are a section of the game config, alongside the room templates:
+
+```yaml
+save_schemas:
+  - key: campaign
+    max_size_bytes: 262144
+  - key: settings_blob
+```
+
+Only `key` is required. `max_size_bytes` defaults to **1048576** — 1 MiB — and is the ceiling for
+that slot alone. The access fields default to what a single-player game wants: the player may
+read and write their own save, your dedicated server may read and write it, and no other player
+can do either. Letting other players read a slot is its own kind of slot — a
+[showcase slot](#showcase-slots-a-little-progress-your-friends-can-read), declared with
+`visibility`, and it trades the whole upload flow away for that.
+
+**Why the declaration exists at all**, rather than a first write creating the slot: the ceiling
+is checked _before_ your game is given anywhere to upload, so a payload that would not fit is
+refused in the first call rather than after the bytes have been pushed. A slot invented at
+runtime would have no ceiling to check against.
+
+It ships the way the rest of your config ships — no new build, versioned, rollback-able:
+
+```bash
+gemctl config schema                                # the authoritative field list
+gemctl config upload --wait                         # registers a version; validation is ASYNC
+gemctl config promote <version> --channel <channel> # this is what makes it live
+```
+
+**Uploading is not shipping.** Until a `gemctl config promote` puts the version on the channel
+your game is running, the slot does not exist for that channel and every save against it is a
+`not_found`. This is the same rule room templates follow; see
+[`platform-rules.md` §5](platform-rules.md#5-templateslug-what-it-resolves-against-and-what-you-can-pass-today)
+for why uploading alone is not enough.
+
+**Rolling back is promoting the earlier version**, not deleting the new one. A config version no
+channel points at can be deleted, and stays recoverable by support for 30 days; one a channel
+still points at cannot. See
+[Deleting a version you no longer want](getting-started.md#deleting-a-version-you-no-longer-want).
+
+Three things worth knowing about save keys and slots:
+
+- **Keys are 1–64 characters**, ASCII letters, digits and underscores, and may not begin with `_`
+  or `$` — those prefixes are reserved. No hyphens, unlike a template slug. Config validation and
+  every save call agree on all of that, and the SDK refuses a bad key locally before any call.
+- ⚠️ **They did not always agree.** Config validation used to accept up to 128 characters and a
+  leading `_`, so a slot declared that way validated, uploaded, shipped to players and could then
+  never be written to — every save against it failed, permanently. If you have such a slot, your
+  next config upload will refuse it: rename it. Nothing was ever stored in it.
+- **Your game cannot read its own slot list back at runtime.** The published config document a
+  game fetches carries items, currencies and room templates, and does not carry the save slots.
+  The key your game code writes to is a literal in that code, and the only thing that checks the
+  two agree is a save that works.
+
+## 2. Writing and reading a save, from the game
+
+One call each way. `gem.me` is the signed-in player.
+
+```js
+// After a level, a purchase, a run ending.
+await gem.me.saves.put('campaign', { level: 7, party, inventory });
+
+// On boot. `null` means this player has never saved.
+const state = await gem.me.saves.get('campaign');
+if (state) resumeFrom(state);
+```
+
+`put` serialises with `JSON.stringify` and resolves once the save is the current one, with the
+stored record: its size, its version and whatever metadata you attached. `get` fetches the
+stored bytes and parses them back. **Nothing about either is device-specific, and that is the
+whole point** — the same player signing in on another machine holds a token naming the same
+player, so `get` there returns what `put` stored here.
+
+**A save is three round trips**, two of them to the API and one carrying your payload to
+storage. The SDK does all three and rolls back nothing halfway: either the save became the
+current one or it did not. What that costs you is time, so save on the events that matter — a
+level cleared, a purchase, a run ended — and never on a frame timer. A load is two, and asking
+whether you need to load at all is one.
+
+**Do not leave the save until `onWillTerminate`.** Three round trips and a payload is a lot to
+fit inside a grace period the parent chose and you cannot negotiate, and Back, a closed tab and a
+reload give you no warning at all. Treat that callback as a last flush of something small, and
+keep the last completed save recent enough that losing the seconds after it is survivable.
+[Saving against a deadline](#saving-against-a-deadline) is the whole of what to do about it.
+
+### Deciding whether to load at all
+
+```js
+const record = await gem.me.saves.describe('campaign');
+if (record?.etag !== lastLoadedEtag) {
+  const state = await gem.me.saves.get('campaign');
+}
+```
+
+`describe` reads the record without downloading the payload — size, metadata, and a version that
+changes whenever the save does. Pass a version you already hold as `ifNoneMatch` and it resolves
+`null` for "still yours", which is one small request instead of a download.
+
+`metadata` is the field that makes this worth doing: attach `{ level: 7, chapter: 'The Vault' }`
+to a `put` and a save-slot menu can be drawn from `list()` alone, with nothing downloaded.
+
+### The rest of the surface
+
+```js
+await gem.me.saves.list(); // every save this player holds, newest state, no payloads
+await gem.me.saves.delete('campaign'); // immediate; deleting one that is not there is not an error
+await gem.me.saves.putBytes('replay', bytes, { contentType: 'application/msgpack' });
+await gem.me.saves.getBytes('replay');
+```
+
+`list` pages at 20 by default and 100 at most, and carries no download links — a listing cannot
+be turned into a bulk read. Follow `nextCursor` if you have more slots than a page.
+
+**Binary has its own pair of methods on purpose.** `JSON.stringify` turns a `Uint8Array` into
+`{"0":1,"1":2}` without complaining, so a `put` of raw bytes would store something wrong and
+silently. Use `putBytes` and `getBytes`, and name the content type you are actually sending.
+
+**Characters have the same accessor.** `gem.characters.get(id)` resolves a character carrying
+`saves` exactly like the player's, scoped to that character — the same declared slots, separate
+stored saves. Most browser games have no characters and can ignore this.
+
+## Showcase slots: a little progress your friends can read
+
+Everything above is the player's own document, read back by the same player. A **showcase
+slot** is the other thing games want from this section of the config: a value _other players_
+may read — how far each friend has progressed, drawn on a map screen without pulling profiles
+and without anyone downloading anyone's save.
+
+A slot becomes one where it is declared, by saying who may see it:
+
+```yaml
+save_schemas:
+  - key: campaign
+    max_size_bytes: 262144
+  - key: map_progress
+    visibility: friends # or `public`; the default, `self`, is an ordinary save slot
+```
+
+Declaring a non-`self` visibility changes what the slot _is_, not just who reads it. The value
+becomes a small JSON document — **4096 bytes** serialised at most, and a `max_size_bytes` above
+that will not validate — stored inline and carried on the calls themselves. Nothing about the
+three-round-trip upload flow above applies: a write is one request, a read is one request, and
+the batch read is the point of the whole feature:
+
+```js
+// After clearing a level: publish where you are. One round trip.
+await gem.showcase.set('map_progress', { level: 12 });
+
+// The friends screen: every accepted friend's value, one request.
+const { entries } = await gem.showcase.friends('map_progress');
+for (const row of entries) {
+  const name = row.displayName ? text.toPlain(row.displayName) : 'Anonymous player';
+  pin(name, row.value, { you: row.isViewer });
+}
+```
+
+The friend graph is resolved on the platform — your game receives values and display names,
+never the graph. Friends who have written nothing are absent, an empty list is a real answer,
+and the player's own row arrives marked `isViewer`, so "you" renders from the same list as
+everyone else. `gem.showcase.of(playerId, key)` reads one player instead, and
+`gem.showcase.clear(key)` removes your value; clearing an empty slot is not an error. And when
+what you are building is a whole **inspect-this-player screen** — identity plus every visible
+value at once, not one slot at a time — that is `gem.profiles.of(playerId)`, one request; the
+profiles section of [`friends.md`](friends.md) covers it.
+
+Four things to hold on to:
+
+- **The batch is a rendering, not live state.** It is cached per viewer for a short window —
+  `generatedAt` dates it — so a friend's write moments ago may not be in it yet. The same
+  freshness rule as the friend leaderboard: display data lags a little, and polling harder
+  re-downloads the same rendering. These calls also share the saves routes' 120-a-minute
+  bucket, which is one more reason not to.
+- **`of()` resolves `null` for every refusal at once, deliberately.** The platform answers one
+  indistinguishable not-found whether nothing was written, the slot's visibility does not admit
+  you, that player blocked you, or the key is not a showcase slot at all — so a response can
+  never reveal whether a hidden value exists. The corollary bites in development: a mistyped
+  key looks exactly like a player with nothing to show. If every read is `null`, check the key
+  against your config before anything else. `friends()` is the exception — its not-found can
+  only mean the slot itself, so it throws as the config error it is.
+- **A showcase value is display data.** The player writes their own, which means a modified
+  client writes whatever fits — a shown-off number was never trustworthy. A game that wants
+  unforgeable values declares `access_self_write: false` and `access_game_server_write: true`
+  on the slot and writes it from the dedicated server, the same shape as an unforgeable save.
+- **Keep the save and the showcase separate on purpose.** Real progress goes in the save;
+  `set()` publishes the small displayable summary next to it, and nothing updates one when the
+  other changes. Last writer wins on a showcase slot — display data carries no version to race
+  on — and there is no binary form: a value is JSON, or it is refused.
+
+## Saving against a deadline
+
+Most saves happen with all the time in the world — a level cleared, a shop closed. Two do not,
+and both of them are clocks somebody else set.
+
+**A browser's `onWillTerminate` has whatever the embedder allows** — it arrives as `graceMs` on
+the notice, so you are told the number but do not get to argue with it, and it can be a couple of
+seconds. That is the tight one. Back, a closed tab and a reload give you no warning at all.
+
+**A dedicated server's `shutdown` has ten minutes** when the match is over. It is long on
+purpose: saving what just happened is exactly what a bundle is expected to do there, and the pod
+holding fleet capacity for a few minutes is the cheaper side of that trade. A node drain is not
+even bounded by that — the runtime waits for the bundle however long it takes, out to the pod's
+own two-hour limit.
+
+### Does a save fit?
+
+**Comfortably on both clocks, unless the payload is large and the uplink is poor.** The
+arithmetic is short, because there is only one thing to count:
+
+> **a save ≈ 3 × round-trip time + payload ÷ uplink**
+
+The SDK's own cost is not in it. Measured on this branch, `put` spends **0.35 ms** of its own on
+a 4 KiB save and **4.5 ms** on one at the 1 MiB default ceiling — serialising, encoding and
+sequencing the hops. Against any of these budgets that is nothing, and it is why the number that
+decides whether a save fits is your payload and your connection rather than anything the SDK
+does.
+
+Measured end to end, driving the real helper with each hop's latency injected:
+
+| Round trip | Uplink     | 256 KiB save | 1 MiB save |
+| ---------- | ---------- | ------------ | ---------- |
+| 10 ms      | datacenter | 0.03 s       | 0.04 s     |
+| 50 ms      | 10 Mbit/s  | 0.36 s       | 1.0 s      |
+| 100 ms     | 10 Mbit/s  | 0.51 s       | 1.2 s      |
+| 200 ms     | 1 Mbit/s   | 2.7 s        | **9.0 s**  |
+
+A dedicated server writes from inside a datacenter, on a connection it has been using all match,
+so it lands in the top row: four hundredths of a second against a ten-minute window. **A bundle's
+end-of-match save is not the case to worry about.** The three round trips are the same three from
+a server bundle, which makes them through `gem.api.*` rather than `gem.me.saves` — see
+[`server-bundles.md`](server-bundles.md) for the calls a game-server token makes — so the table
+holds there too.
+
+The bottom row is a browser on a poor uplink, and that is the case that bites, because the budget
+there is the embedder's and may be shorter than the save. The number to take from it is that a
+payload near the 1 MiB ceiling needs about **eight seconds of uplink alone** at 1 Mbit/s. That is
+what makes a big save unsaveable in a teardown window — the payload, not the round trips.
+
+**How this was measured, so you can weigh it:** the SDK's own cost is a real measurement of the
+shipped code. The round trips are injected latency rather than a live save timed from inside a
+match pod, so read the table as the arithmetic confirmed rather than as a production trace.
+
+### Give the call the deadline you actually have
+
+The helper waits **30 seconds** by default, which outlives most browser teardown windows and sits
+well inside a bundle's ten minutes. Left at the default in a window shorter than it, a save that
+stalls is killed mid-flight: the promise never settles, nothing is logged, and your game ends up
+with neither the save nor a reason.
+
+Every save and load takes the budget you are actually racing, and rejects inside it:
+
+```js
+const gem = createGem({
+  onWillTerminate(notice) {
+    // The parent told you how long it will wait. Spend a little less than that,
+    // so a failure still has somewhere to be handled.
+    gem.me.saves
+      .put('campaign', state, { timeoutMs: Math.max(1000, notice.graceMs - 500) })
+      .catch(report);
+  },
+});
+```
+
+`timeoutMs` is on `put`, `putBytes`, `get` and `getBytes`; it covers every hop together, and it
+is a ceiling rather than a target — it does not make a save faster, it decides when to stop
+waiting for one. A save that misses it rejects as `GemSaveError` with reason `save_timeout`,
+naming the budget you gave it rather than the default, so a log tells you which of the two you
+were running under.
+
+**The save that fits a teardown window is a small one.** Nothing here turns three round trips
+into fewer, so the durable answer is not to be holding a megabyte of unsaved progress when the
+clock starts — save on the events that matter, and let the teardown flush be a small delta.
+
+## What can go wrong, and which of it is worth retrying
+
+| What you get          | What happened                                                                                                    | What to do                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `not_found`           | the slot is not declared on this channel, or `get` found no save                                                 | publish the slot; or treat a null read as a new player                                       |
+| `invalid`             | the key is malformed, or the metadata is not what the slot takes                                                 | fix the call; no retry helps                                                                 |
+| `precondition_failed` | something else saved this slot while yours was in flight                                                         | re-read, rebuild, save again — **never** retry the same payload                              |
+| `too_large`           | the payload is over the slot's ceiling, or this player's or this game's save storage is full — `code` says which | **do not retry.** Store less or raise `max_size_bytes`; or delete a save, or tell the player |
+| `forbidden`           | the player's session ended while the save was in flight                                                          | a fresh session, not a retry                                                                 |
+| `rate_limited`        | too many save calls from this network address                                                                    | back off by what it tells you; then save less often                                          |
+| `GemSaveError`        | the payload could not be pushed to or pulled from storage                                                        | see below                                                                                    |
+
+**`too_large` is the one to get right.** It used to reach game code labelled as a retryable
+server fault, so a game that honoured that flag retried a refusal that can never succeed —
+against a limit counted per network address, which two players behind one connection share. It
+is now its own error, and `retryable` on it is `false`. A player whose saves have filled their
+allowance meets this on every save until something is deleted; that is a message to show, not a
+loop to enter.
+
+**`GemSaveError` is the half that does not go through the API.** Your payload travels to and
+from storage over a short-lived signed link, so a failure there is not an API error and cannot
+be classified as one. It carries `reason`: `upload_failed`, `download_failed`, `save_timeout`,
+or `save_malformed` for a payload that is not what it claims.
+
+**If you see `upload_failed` on every save, from every player, in a browser** — that is not a
+transient fault and no amount of retrying moves it. Two causes have that shape, both platform
+side, and neither is anything your game can change:
+
+- The storage account does not allow your game's origin to `PUT`. This is what the arcade's own
+  storage rules decide; a game origin was read-only until 2026-08, which meant **no browser game
+  could store a save at all** for the whole of gem-web-sdk v2.2.0 through v2.4.2.
+- The upload reached storage without a header that storage requires. The SDK sends whatever the
+  platform's grant names in `upload_headers` and nothing it invented, so a mismatch here is a
+  disagreement between the platform and its own storage, not a call you made wrong.
+
+Either one is worth reporting rather than working around. It is **not** a content-security-policy
+problem: game origins carry no fetch directives by design.
+
+## The bounds, as numbers
+
+|                                      |                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Key name                             | 1–64 characters, ASCII letters, digits and underscores; cannot begin with `_` or `$`                                                                                                                                                                                                                       |
+| Slots per config                     | 1000                                                                                                                                                                                                                                                                                                       |
+| One save's payload                   | whatever its slot declares; **1 MiB** if it does not say                                                                                                                                                                                                                                                   |
+| One showcase value                   | **4096 bytes** of JSON, serialised — the ceiling for any slot whose `visibility` is `friends` or `public`, and such a slot cannot declare more                                                                                                                                                              |
+| One player, one game                 | **100 MiB** across all their slots                                                                                                                                                                                                                                                                         |
+| One game                             | **10 GiB** across all its players, per channel                                                                                                                                                                                                                                                             |
+| Metadata                             | **4096 bytes** of JSON after normalization, ≤50 keys per object, keys ≤64 bytes, string values ≤1024 bytes, nested no more than two levels below the top                                                                                                                                                   |
+| Content type                         | `application/octet-stream` (the default for bytes), `application/json`, `application/x-protobuf`, `application/msgpack`, `application/cbor`, `application/x-binary`                                                                                                                                        |
+| Saves in flight, per player per game | **5**                                                                                                                                                                                                                                                                                                      |
+| How long one save has to complete    | **10 minutes** for a browser game, from the first of its three calls. This is the upload credential's own clock, not the end-of-match shutdown grace that happens to share the number. That credential is not bound to your origin, so it is deliberately shorter-lived than the hour a native client gets |
+| A download link                      | **15 minutes**                                                                                                                                                                                                                                                                                             |
+| Request rate                         | **120 a minute** across these routes, counted per network address, and refused rather than waved through if the limiter is unreachable                                                                                                                                                                     |
+
+Two players behind one home connection share that last bucket. It is the reason a per-frame
+autosave is the shape to avoid, and it is why the answer to `rate_limited` is to save less
+often rather than to retry harder.
+
+## For something small, reach for settings instead
+
+`gem.me.settings` needs no declaration and is one call: `put(key, value)` with a **string**
+value, up to **8 KiB** each and **32** keys per player per game. It is the right home for a
+chosen difficulty, a control scheme, a level counter.
+
+Reach for a save when the payload is a document rather than a value — a world, an inventory, a
+replay. Something that belongs to **this device** rather than to the player — a volume, a graphics
+quality — belongs in neither; that is the next section. Progress a player would be upset to lose
+belongs in a save, and nowhere else.
+
+### Device settings: local to this device, and only that
+
+`gem.deviceSettings` is the third store, and the one that does **not** follow the player. The
+Arcade keeps a small object for your game on the device it is being played on, hands it to your
+game once per session, and stores whatever your game puts back. It exists because your game's own
+browser storage cannot do this: every build of a web game runs on its own origin, so a value your
+game kept in `localStorage` is gone the moment you publish again. The Arcade's own storage outlives
+your builds; that is the whole mechanism.
+
+**What goes here:** a master volume and the music/SFX mix, a graphics quality or resolution scale,
+a chosen input layout, a tip the player dismissed, a "skip intro" toggle. Configuration that is
+about **this screen and these speakers**.
+
+⚠️ **What never goes here: progression, unlocks, currency, anything a player would mind losing,
+and anything that must follow them to another device.** This is not a save and it is not a
+substitute for one:
+
+- **It does not roam.** Another device, another browser, or the same browser after clearing site
+  data starts from nothing. A save follows the player; `gem.me.settings` follows the player; this
+  does not.
+- **It is shared by every account on the device.** Two players on one family television share a
+  volume level. Nothing about the player is in the key.
+- **It can vanish at any time**, and the Arcade may evict it. A game must boot correctly from
+  `null` — apply your defaults and carry on — and must never treat "nothing stored" as a first run
+  for progression purposes.
+- **It is capped at 16 KiB** of serialised JSON, on purpose: a cap a save does not fit inside is the
+  surest way to keep saves out of it. Over the cap, `put` resolves `too_large` and nothing is
+  stored.
+
+```js
+// On boot. Short budget; `null` means "use your defaults" and is the common case.
+const settings = (await gem.deviceSettings.wait(1_500)) ?? {};
+audio.setMasterVolume(settings.volume ?? 1);
+renderer.setQuality(settings.quality ?? 'auto');
+
+// When the player changes a setting: the WHOLE object, every time.
+async function applySettings(next) {
+  audio.setMasterVolume(next.volume);
+  renderer.setQuality(next.quality);
+  const outcome = await gem.deviceSettings.put({ v: 1, ...next }); // 'stored' | 'too_large' | 'unavailable'
+}
+```
+
+Three things the shape above is doing on purpose:
+
+- **Whole-object replace, no keys.** There is no `put(key, value)`; send the entire object with the
+  field that changed changed. The Arcade stores what it is sent and nothing else, and last writer
+  wins — across two tabs of the same game too.
+- **Version your blob** (`v: 1`) and treat any shape as possible on read. What you read back was
+  written by a previous build of your game, not this one.
+- **Every outcome resolves, none is an error.** `unavailable` means the Arcade could not store it
+  just now — a private window, a full quota. Keep running on the value you hold; a device that
+  cannot remember a volume is a device where the player sets it again. Do not retry in a loop, and
+  debounce a slider: the Arcade meters writes at thirty a minute.
+
+You never say which game or which channel this is for. The Arcade files the object by the game and
+the channel it is running — so a `dev` build's settings never reach the `release` build of the same
+game, and a key you experiment with on `dev` cannot break a shipped build.
+
+| You want | Where it goes | Follows the player? |
+| -------- | ------------- | ------------------- |
+| a world, an inventory, a replay | `gem.me.saves` — a declared slot | yes |
+| a difficulty, a control scheme, a level counter | `gem.me.settings` — a string per key | yes |
+| a volume, a quality preset, a dismissed tip | `gem.deviceSettings` — one object per device | **no** |
+
+## What the platform already does with these, so you do not
+
+**A player's erasure covers their saves.** When an account is erased the stored payloads go with
+the rows, and the game's usage is reconciled afterwards. **A data export covers them too** — by
+reference, as short-lived download links against the same payloads, so a player asking what you
+hold gets the saves as well as everything else.
+
+Neither is something you implement, and both are reasons not to keep a second authoritative copy
+of a player's progress somewhere the platform cannot see: a copy in your own backend is a copy
+neither of those reaches.
+
+## Where the rest of it is
+
+- [`what-a-game-must-do.md`](what-a-game-must-do.md) — what a game still owes the platform, and
+  the boot sequence that decides whether the handshake lands at all.
+- [`platform-rules.md`](platform-rules.md) — how config is published and promoted, and the rules
+  gem-api enforces that no client-side signature states.
+- [`server-bundles.md`](server-bundles.md) — the server half of a dedicated match calls these
+  same save operations, under Saves, and its `shutdown` is the ten-minute window above.