@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/structure/round.md

@@ -0,0 +1,229 @@
+---
+title: Round
+description: A round of play that ends won or lost, timed, scored, raced in laps, or ended by the game.
+useCases:
+    - timed round
+    - win and lose conditions
+    - race with laps
+    - countdown timer
+    - collect coins before time runs out
+    - score target
+    - time limit
+    - round end screen
+sidebar:
+    order: 7
+---
+
+Round times a round of play: "collect 8 mushrooms before 60 seconds run out", or "two laps, then the finish". The score is the coins that [`addCoins`](/engine/behaviours/pickup/#coins-a-game-pays) credits while the round plays, a [Pickup](/engine/behaviours/pickup/)'s among them. The round is won the step the score reaches the target or the last lap is in, and lost the step the time runs out first. A rule you leave out is off: a round with no `seconds` never runs out.
+
+Unity's Karting Microgame splits this between an objective and a time manager, and Unreal between a racing GameMode and its GameState. Here one Round carries both, so a game configures a race rather than writing one.
+
+Its props are in [`RoundProps`](https://wiki.spawnite.com/reference/round/roundprops/).
+
+Round is the `rounds()` plugin: list `rounds()` in the game's [plugins](/engine/structure/plugins/), and import every name on this page from `@spawnite/engine/rounds`. Its source ships readable in the package, as [Read its source](#read-its-source) says.
+
+The round counts simulated seconds, the fixed steps the world takes, not the wall clock. A modal that pauses, the devtools' pause, and a headless world that nobody steps all hold its clock. Once it is won or lost, the round keeps its clock and its score.
+
+A timer of the game's own, such as a wave of enemies every 30 seconds, is a [`states()`](/engine/structure/states/#waiting) wait or a system on the step, as the round's countdown is. A view that counts with `useTime` keeps its count on one page alone: a room, a dump and a save never see it, and a player who joins late counts from zero.
+
+The round is a [machine](/engine/structure/states/), `RoundMachine`: its states are the `RoundState` values, the step sends it `WIN` and `LOSE`, and its countdown is a wait. Each state is a tag, so `world.queryFirst(RoundMachine.is.playing)` finds a round in play. `RoundMachine.read(entity).secondsLeft` reads the countdown left, as `useRound()` does.
+
+Put Round inside the [scene](/engine/structure/scene/) it times. It starts when the scene opens and goes when the scene closes. In a room, it starts when the first player opens the scene, as [In a room](#in-a-room) says.
+
+## A race
+
+A race starts on a signal, counts down, and ends when the player crosses the line, or when the game says it failed. Round covers each part:
+
+- `ready`: the round waits in `RoundState.Ready`, its clock held, until `start()`. A sling's release or a Start button calls it.
+- `countdown`: seconds in `RoundState.Countdown` before it plays. Without `ready`, the countdown starts when the round mounts.
+- `laps`: the laps that win it. Each entry into a [TrackTrigger](/engine/behaviours/track-trigger/) marked `lap` counts one while the round plays. Start the mover past the line, or its first crossing counts.
+- `finish()` wins a round in play, and `fail(reason)` loses one that has not ended. The round keeps the reason, a crash, a fall, a false start, and `useRound()` reads it back, so a screen can say why. `<RoundScreen>` titles every loss "Out of time" unless the game passes its own `lostTitle`. A round that runs out of time has the reason `"time"`.
+
+A system calls `startRound(world)`, `finishRound(world)` and `failRound(world, reason)` from `@spawnite/engine/rounds`; a component calls the same verbs from `useRound()`. In a game played alone, either one ends the round. In a game with a room, the room decides the round, as [In a room](#in-a-room) says: a system ends it there, since a system runs on the room unless it says otherwise. [The exit gate on the Trigger page](/engine/behaviours/trigger/#decide-an-outcome-in-a-system) wins the round from a system when a player walks in with the keys, rather than from `onEnter`.
+
+## In a room
+
+The room plays the round. The scene's `<Round>` spawns it on the room, the room's steps count it down, score it and end it, and its stream brings it to each page. On a page in a room, the same `<Round>` spawns nothing, so `useRound()` reads the round the room streams. A room runs one scene, so put the `<Round>` in the scene the room runs, the one `package.json` names under `spawnite.room.scene`. A page in a room whose `<Round>` finds no round the room streams throws in development, naming that fix, and logs it in a published game.
+
+The room decides the round, as a Roblox server script, a Unity Netcode `ServerRpc` and a Godot `rpc` to the server leave an outcome to the server. On the room, such as in a system with no `runsOn`, `startRound`, `finishRound` and `failRound` start, win and lose the round every page shows. On a page in a room, `useRound()`'s verbs work as follows:
+
+- `start()` sends the room the `rounds.start` message, and the room starts its round where the round is ready.
+- `restart()` sends the room the `rounds.restart` message, and once the room's round is won or lost, the room starts its scene again, so every page gets the new round. "Play again" on [the round's screen](#its-screen) works in a room this way. The players keep their characters where they stand. The room steps no more while its scene mounts again, as Unreal's level load and Unity Netcode's scene load hold the game: a message, a join or a leave that lands meanwhile waits, and the room takes it once the scene has mounted, before its next step. Two restarts in one step start the scene once.
+- The room refuses a start or a restart at any other time, logs the [`RoundRefusal`](https://wiki.spawnite.com/reference/round/roundrefusal/), and plays on: `not-ready` for a start where no round is ready, `not-ended` for a restart where no round is won or lost, and `no-scene` for a restart on a room whose scene is a spawn function, as a test's.
+- `finish()` and `fail(reason)` throw in development, naming the fix, and do nothing in a published game.
+
+The room mounts its scene as it opens, before any player has the scene open, such as while every page still shows a lobby. So the room's round waits in `RoundState.Ready` until the first page opens the scene: that page's `<Round>` finds the round the room streams ready and sends `rounds.start` for it. A restart's new round waits the same way, and a page that has the scene open starts it. A page that opens the scene once the round plays or has ended sends nothing. Where two pages open the scene in the same moment, both send `rounds.start`: the room starts the round on the first and takes the second as nothing to do, with no refusal logged, since only a start from `start()` is refused while the round counts down or plays. A round with `ready` waits for `start()` instead. Unreal's game mode waits the same way, starting its match once the first player is in. In a game played alone, the round starts when the scene opens.
+
+To win or lose the round from a button, send the room a [message](https://wiki.spawnite.com/platform/room-messages/#send-the-room-a-message), and call `finishRound(world)` or `failRound(world, reason)` in a system that runs on the room and reads it. The following plugin loses the round for every page when one player gives up:
+
+```ts title="packages/room/test/outside/forfeit.ts"
+import type { World } from "koota";
+import { definePlugin, readMessages } from "@spawnite/engine/core";
+import { failRound } from "@spawnite/engine/rounds";
+
+//  A Give up button for a round in a room, built as a creator's plugin is,
+//  from the engine's public entry alone: a page sends the message, and a
+//  rule on the room alone loses the round every page shows.
+
+/** The reason the round keeps, which the round's screen reads back. */
+export const forfeitReason = "gave-up";
+
+/** Loses the round where a player gave up since the last step. */
+function takeForfeits(world: World) {
+    //  No `runsOn`, so it runs on the room alone, which decides the round.
+    if (readMessages(world, forfeit.messages.giveUp).length > 0)
+        failRound(world, forfeitReason);
+}
+
+export const forfeit = definePlugin({
+    name: "forfeit",
+    messages: { giveUp: {} },
+    systems: { rules: { takeForfeits } },
+});
+```
+
+List `forfeit` among the game's `plugins`, beside `rounds()`. The Give up button calls `sendMessage(world, forfeit.messages.giveUp, {})`, with `sendMessage` from `@spawnite/engine` and the world from koota's `useWorld`. Each page then reads `reason` from `useRound()` as `"gave-up"`.
+
+In a game played alone, each verb changes the round on the page's own world, as the sections above say.
+
+## Won on a boss's death
+
+A round that a boss's death wins needs one system, which reads [`DiedEvent`](/engine/behaviours/health/#when-it-dies). The reap, `behaviours.reapDead`, emits it on the boss once its health is zero: in the same step for a hit dealt before the reap, and in the next step for one dealt after it, such as a projectile's. The boss still holds every trait it had, so the system knows it by its own mark and calls `finishRound`. The step after that reap, the engine removes the boss. The engine's tests run this plugin:
+
+```ts title="packages/engine/test/outside/bossWin.ts"
+import type { World } from "koota";
+import {
+    definePlugin,
+    defineTrait,
+    DiedEvent,
+    readEvents,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+import { finishRound } from "@spawnite/engine/rounds";
+
+/** Marks the boss whose death wins the round. */
+export const BossTrait = defineTrait("outsideBoss");
+
+export const bossWin = definePlugin({
+    name: "boss-win",
+    //  No runsOn: the room alone wins a round, and a game played alone is
+    //  its own room.
+    systems: { rules: { win: { system: winOnBossDeath } } },
+});
+
+/** Wins the round in the step the boss dies. */
+function winOnBossDeath(world: World, step: AuthoritativeStep) {
+    for (const { entity } of readEvents(step, DiedEvent))
+        if (entity?.has(BossTrait)) finishRound(world);
+}
+```
+
+List it after `rounds()` among the game's plugins, and give the boss `BossTrait` where it spawns.
+
+## Reading it
+
+`useRound()` returns a [`RoundStatus`](https://wiki.spawnite.com/reference/round/roundstatus/): the seconds left and played, the countdown left, the score and its target, the laps done and wanted, the [`RoundState`](https://wiki.spawnite.com/reference/round/roundstate/), the reason it was lost, the verbs above, and `restart()`, which starts the round's scene again.
+
+The score counts only what `addCoins` credits while the round is in `RoundState.Playing`:
+
+- A coin credited while the round is ready or counting down adds nothing. The one exception: a coin a system credits between the round's step and the machines' step, in the step a countdown ends, counts toward the round that starts there.
+- A wallet a [save](/engine/structure/saves/) restores, or a game sets on the trait itself, adds nothing, so coins carried in from an earlier run never win a round on its first step.
+- A spend, such as a shop's `spendCoins`, never lowers the score.
+- Every wallet's credits count toward the one round: in a room, each player's coins add to the room's round.
+
+The round scores in its step, and `startRound`, `finishRound` and `failRound` score before they change a round, so a coin a game's system credited earlier in the step counts toward the round it ends and never toward one it starts. A round scores first as it spawns too, from `<Round>` or bare, so it counts only the coins credited after it.
+
+What the round scores is the rise in `readCreditedCoins(world)`, from `@spawnite/engine/core`: every coin `addCoins` has credited on the world, a count that only rises. A game reads the same count for a scoreboard or a quest of its own.
+
+The wallet `useWallet()` shows is the player's character's. In a game whose player has no character, such as a rider on a track, it is the wallet on the entity under the client's authority.
+
+Before a round mounts, `useRound()` reads a fresh one from the machine's defaults: 60 seconds and a target of one coin.
+
+In a game that lists its [levels](/engine/structure/levels/), a won round finishes the level being played and keeps its best.
+
+## Its screen
+
+`<RoundScreen>` opens a [Modal](/engine/ui/modal/) the step the round is won or lost. Its pane holds a title, a line of text, the score where the round has a target, and anything you pass as children. Below the pane stands a "Play again" button that calls `restart()`, and beside it any buttons of the game's own that you pass as `actions`, such as one that plays the next level. The screen draws nothing until the round ends.
+
+In a game with [levels](/engine/structure/levels/), a small line above the title names the level and the count, such as "Level 2 of 4". Pass `noun` to call the levels something else, such as `"Track"`. A game with no levels shows no line.
+
+Its props are in [`RoundScreenProps`](https://wiki.spawnite.com/reference/round/roundscreenprops/).
+
+Mount one `<RoundScreen>` beside the round it screens; a game replaces its title and text with its own, but keeps the score and the button.
+
+The screen pauses the world while it is open. Pass `pause={false}` to let the world step on behind it, as a racer coasts past the line under the finish screen; the menu's own pause still freezes it.
+
+To shoot the screen, step the playtest until the round ends: `spawnite play screenshot --keys <start> --until false --budget 120`, where `<start>` is the input that starts the game's round, such as Space. The screen's modal pauses the world, so the step stops on the step it opens and the shot shows it. A screen with `pause={false}` stops no step: step on with `spawnite play step --seconds <s>` past the end, then shoot. A second `spawnite play screenshot --size 390x844`, with no `--until`, shoots the same screen at another size. When the budget runs out with the round still `ready`, the command says so: nothing in the steps started the round.
+
+## Where it runs
+
+Room and page. The round has a consequence: it decides the game's outcome, so the room's copy is the one that counts, and the room streams it to every page. `rounds.advance` runs on each page too, as its `runsOn` says, but leaves each round the room streams to the room: a page's clock moves as the room's sends arrive.
+
+The step runs the round after the behaviours, so a coin picked up in a step counts in that step. The [headless harness](/engine/structure/systems/) runs it too: spawn the `RoundTrait` entity in the scene, which takes the machine's defaults of 60 seconds and one coin for each field you leave out, step the world, and read the round back from the dump under `round`, its state under `state` and its countdown's seconds so far under `waited`, and its state's tag beside it, such as `"round.playing": true`.
+
+The following scene's `Clock` draws the score with a [Counter](/engine/ui/counter/), which bumps as each mushroom lands. A count the game adds beside it, such as the keys the player holds, takes a Counter of its own. The engine's tests mount the `Clock` beside a round and check that the Counter shows each new score:
+
+```tsx title="packages/engine/test/outside/Meadow.tsx"
+import {
+    CharacterSpawn,
+    Counter,
+    Hud,
+    Panel,
+    Slot,
+    Text,
+    World,
+} from "@spawnite/engine";
+import {
+    Round,
+    RoundScreen,
+    RoundState,
+    useRound,
+} from "@spawnite/engine/rounds";
+
+export function Clock() {
+    const { secondsLeft, score, target, state } = useRound();
+    return (
+        <Hud>
+            <Panel slot={Slot.TopLeft}>
+                <Text>
+                    {state === RoundState.Playing
+                        ? `${Math.ceil(secondsLeft)} s`
+                        : state}
+                </Text>
+                <Counter
+                    icon="coins"
+                    label="Mushrooms"
+                    value={`${score} / ${target}`}
+                />
+            </Panel>
+        </Hud>
+    );
+}
+
+export function Meadow() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <Round seconds={60} target={8} />
+            <Clock />
+            <RoundScreen wonText="Every mushroom, with time to spare." />
+        </World>
+    );
+}
+```
+
+## Read its source
+
+The round is a readable plugin: the engine's package ships its TypeScript source, with its comments, under `node_modules/@spawnite/engine/readable/rounds/`, and the code a game runs is built from those files. The folder holds the following:
+
+- `rounds.ts`: the plugin, one system in the `rules` phase, and the room's answer to a page's start and restart.
+- `rules.ts`: the system that scores and times each round, the messages a page sends, and the verbs that start, win and lose one.
+- `traits.ts`: the round's machine and its states.
+- `index.ts`: the names `@spawnite/engine/rounds` exports.
+- `Round.tsx`, `RoundScreen.tsx` and `LevelBanner.tsx`: the components.
+
+Each file reaches the engine through its public entries alone, `@spawnite/engine` and `@spawnite/engine/core`, as a game's own plugin does, so every call it makes is one a game can make. Read it to see how a plugin is built, or copy it into the game as the start of a round with rules of its own:
+
+1. Copy the folder into the game, such as `src/plugins/race/`, keeping the licence lines at the top of each file, as [the licence](https://wiki.spawnite.com/platform/license/) says. Its imports of the engine work unchanged.
+2. Give the copy a plugin name of its own, in `definePlugin` and in each `requirePlugin` call, and rename its machine's `id`, so the copy and the engine's round can never meet under one name.
+3. List the copy in the game's plugins in place of `rounds()`, beside `machines()`, which it requires. Move every import of the round's names to the copy's folder, its traits, its verbs and its handles among them, such as an anchor to `rounds.systems.advance`: a query of the engine's `RoundTrait` finds none of the copy's rounds, and an anchor to the engine's system names a plugin the game no longer lists.

package/dist/wiki/engine/structure/saves.md

@@ -0,0 +1,251 @@
+---
+title: Stores and saves
+description: The stores every hook reads, and the save that keeps a player's progress between visits.
+useCases:
+    - save progress between sessions
+    - keep coins after a reload
+    - read the player's name
+    - store my game's own state
+    - save in a multiplayer room
+    - change what the save keeps
+    - read the wallet in the UI
+sidebar:
+    order: 2.1
+---
+
+`useWallet`, `useScenes`, `useInput`, `useTime` and `useLoading` read stores the engine owns. `usePlayer` queries the world for the player's character instead, and [`useRound`](/engine/structure/round/) queries it for the round. `usePlayer` also says who plays: the `name` the player shows in the player app and an `id` that is theirs in this game alone, which the app hands the page when the game runs in its frame, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#what-a-game-and-the-app-say-to-each-other) says. In a game with rooms the app hands them with the seat, once the room opens, so both read `undefined` while the page loads during a room's start. Both are `undefined` outside the app, as on the game's dev server, so a game falls back to its own, such as a name the player types. A game's own state comes from the engine's `createStore`, and a game reads it the same way; wrapped in the engine's `persist`, it is kept in the player's save, as [Save a game's own store](#save-a-games-own-store) says.
+
+The stores' shapes are [`WalletState`](https://wiki.spawnite.com/reference/game/walletstate/), [`InputState`](https://wiki.spawnite.com/reference/game/inputstate/), [`TimeState`](https://wiki.spawnite.com/reference/game/timestate/) and [`LoadingState`](https://wiki.spawnite.com/reference/game/loadingstate/); `usePlayer` returns a [`PlayerState`](https://wiki.spawnite.com/reference/game/playerstate/) and `useRound` a [`RoundStatus`](https://wiki.spawnite.com/reference/round/roundstatus/).
+
+Game builds the quality store, and keeps it in the browser's storage under its `name`: `sled-quality` for [Game's sample](/engine/structure/game/#sample), so two games on one origin keep separate settings. Anything under Game reads it with `useQualityStore()`, which returns the store for `useStore` from zustand. A camera that remembers its framing keeps it beside it, as [the camera page](/engine/entities/camera/) says. The player's progress is the save, which [Saving progress](https://wiki.spawnite.com/learn/saving-progress/) describes. The quality store holds what the player set in the Graphics rows and the level Automatic picked for the device; `useQualitySettings()` reads the values the engine draws with, and Game's `quality` prop changes what each level means and the level each kind of device starts at, as [Graphics quality](/engine/ui/graphics-quality/) describes. A scene [mounted headless](/engine/testing/headless/#sample) reads stores of its own that start empty and write to no storage. A game that renames itself loses its players' settings on each device, so a game keeps its `name`.
+
+An address with `?quality=<level>`, one of `auto`, `minimum`, `low`, `medium` or `high`, opens the game at that level for the visit. The quality store keeps the saved level in storage, and saves a level the player picks after the game opens. The boot checks open every game at `?quality=minimum`, so the software GPU they run on never decides a level's values. A page opened with `?profile` also takes `?qualityLevels=`, level values over the game's own for the visit, as [Frame](/engine/testing/frame/) shows.
+
+A save is plain data, as it is stored. The character's `position` reads back as three numbers, `{ x, y, z }`, the `StoredVector` type from `@spawnite/schema`, not a three.js `Vector3`, so code that reads a save and draws nothing loads no three.js. A game that needs a vector builds one where it reads the save, `new Vector3(x, y, z)`; the engine's `spawnCharacter` does so itself. Unity, Unreal and Godot store a vector as three numbers the same way.
+
+## Declare what the save keeps
+
+A game declares its save once, with `defineSave` in `src/save.ts`, and passes it to `<Game save={save}>`. The declaration names the engine saves the game wants in `include`, and holds one `schema`, `read` and `restore` for the game's own state:
+
+```ts
+// src/save.ts
+import { defineSave } from "@spawnite/engine";
+import { z } from "@spawnite/schema";
+import { GoldTrait } from "./traits";
+
+export const save = defineSave({
+    include: ["character", "inventory", "random"],
+    version: 2,
+    schema: z.object({ gold: z.int(), quests: z.array(z.string()) }),
+    read: ({ character }) => ({
+        gold: character.get(GoldTrait)?.amount ?? 0,
+        quests: [],
+    }),
+    restore: ({ character }, saved) =>
+        character.set(GoldTrait, { amount: saved.gold }),
+    migrations: { 2: (v1) => ({ ...v1, quests: [] }) },
+});
+```
+
+`defineSave` takes the following fields. The first six describe the game's own state, under the record's `game` key. `schema`, `read`, `restore` and `version` come together, or not at all:
+
+- **`version`**: a whole number from 1 that counts the shape of the state. Any change to the shape raises it, an added optional field included, and adds a step.
+- **`schema`**: required with the game's own state. It types what `restore` receives, and it checks every state that loads.
+- **`read`**: returns the state to keep, as plain JSON. It is synchronous and changes nothing. At every read, in development and when published, the engine checks that what it returns passes the schema and survives JSON. A read that throws, returns `undefined`, or holds a `Set`, a symbol, an `undefined` field, a number that is not finite or a value inside itself is refused, and so is the whole record that read: the last save stays, and play goes on.
+- **`restore`**: puts a loaded state back, after her spawn has set her up and after the engine saves are restored. A restore that throws refuses the load, as a record that fails to load does, so nothing is written over the save.
+- **`migrations`**: one step per version. Step 2 turns a version 1 state into version 2, so a version 1 state that a version 4 game loads runs steps 2, 3 and 4. A step is a pure function from old JSON to new JSON. A step that throws or returns `undefined` refuses the load.
+- **`scope`**: `"player"`, the default, where `read` and `restore` receive `{ world, character, player }`, or `"world"` for a game with no character, such as a puzzle with a board, where they receive `{ world, player }`. `world` is the koota `World`, `character` the `Entity` the Player spawned, which `restore` receives as a `PredictedEntity`, so it may write her predicted traits as she appears, and `player` is `{ id }`, the platform's id for the player in this game.
+- **`include`**: the engine saves the game wants, listed below.
+
+A game sets no interval: the platform writes the save on its own schedule, as [When the save is written](#when-the-save-is-written) and [Saves in a room](#saves-in-a-room) say.
+
+A game that keeps no state of its own, only the engine saves it names and its kits' saves, gives none of the first six fields, and its record has no `game` key:
+
+```ts
+export const save = defineSave({ include: ["levels", "random"] });
+```
+
+Giving some of `schema`, `read`, `restore` and `version` without the rest fails to typecheck, and `defineSave` throws naming the missing fields. `defineSave` also throws for a version that is no whole number from 1, a step missing between 2 and the version, a name in `include` that the engine has no save for, and `resources` without `stats`.
+
+The engine owns the saved form of its own traits, so a game never stores the engine's shapes itself, and an engine release that changes one converts the saves already stored. A game names each engine save it wants in `include`:
+
+| Name        | What it keeps                                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `character` | Her scene, position, facing and health. A position saved in another scene is dropped, and her body moves with it |
+| `stats`     | Each stat's base and its lasting modifiers. Timed modifiers are left out                                         |
+| `inventory` | The bag and what she wears                                                                                       |
+| `resources` | What she has of each resource, such as mana. Needs `stats`, which sets each maximum                              |
+| `wallet`    | The coins in her wallet. A restored wallet adds nothing to a round's score                                       |
+| `levels`    | The levels finished. A page game's alone                                                                         |
+| `loot`      | The loot already taken. A page game's alone                                                                      |
+| `random`    | The world's random stream, so a continued game draws what it would have drawn. A page game's alone               |
+
+The camera is not saved: its framing is a view setting, not progress. A game with rooms may not declare a world scope, `levels`, `loot` and `random`, since a room's world is shared and it seeds its own random stream. Game raises each one when it mounts in development, and `spawnite build` refuses them.
+
+A room mounts a scene and not `<Game>`, so a game with rooms exports its save from the room's scene file too, beside `plugins`: `export { save } from "../save"`. `spawnite build` fails where `src/save.ts` declares a save and the room's scene file does not export it, and where any module of either half calls `defineSave` while the room's scene exports no `save`, so a room never saves nothing by mistake.
+
+A saved state that is empty is saved as empty: an emptied bag writes an empty bag, never the bag the save held before.
+
+## The saved record
+
+The save is one JSON record. The game, each kit and each engine save keep their own key, each with its own version, so one owner's change never touches another's:
+
+```json
+{
+    "game": { "version": 2, "state": { "gold": 140, "quests": ["intro"] } },
+    "stores": {
+        "career": { "version": 1, "state": { "kills": 9, "runs": 2 } }
+    },
+    "kits": { "shop": { "version": 3, "state": { "stock": [] } } },
+    "engine": {
+        "inventory": {
+            "version": 1,
+            "state": { "slots": [], "equipment": {} }
+        },
+        "random": { "version": 1, "state": [1, 2, 3, 4] }
+    }
+}
+```
+
+Every owner's key loads the same way, the engine's, a kit's and the game's own alike, in three steps:
+
+1. **The version is compared.** A stored version above the owner's refuses the load.
+2. **The steps run.** A stored version below the owner's goes through each numbered step in order, up to the current one.
+3. **The schema reads the result**, and it is the only judge. A field the schema does not name is dropped. A missing field that has a default gets it. A missing required field or a value of the wrong type fails the schema. A strict schema, such as `z.strictObject`, refuses a field it does not name.
+
+A key that fails any step, or a step that throws or is missing, refuses the whole record: the engine restores nothing and writes nothing over it, and the result names the owner, the key and the reason. A key no owner in this version claims, such as one a removed kit wrote, is kept as it is and written back.
+
+A kit's key is its plugin's name, `kits.<name>`. Two kits of one name share a key, so a kit that takes the name of one the game removed reads that kit's saved data, and refuses the load where the data does not fit its schema or is at a higher version. A kit's factory takes a `save: false` option and passes `save: false` to `definePlugin`: the kit then saves nothing, and its stored key is kept untouched.
+
+Every change to a saved shape raises its owner's `version` and adds a step, an added optional field included. The engine holds its own saves to that in its tests, which also allow only added fields inside one compatibility line of engine releases: the major from 1.0.0 on, and the major and minor below it. `spawnite build` writes, for each owner, its version and a fingerprint of its schema into the bundle's manifest, under `save`:
+
+```json
+{
+    "game": {
+        "version": 2,
+        "fingerprint": { "format": 1, "hash": "9f3a0c2be1d47f60" }
+    },
+    "engine.inventory": { "version": 1, "fingerprint": null }
+}
+```
+
+The fingerprint hashes the schema as JSON Schema, so the order of its fields, its descriptions, its titles and its examples do not change it. A codec's tagged value counts by the codec's name. A schema JSON Schema cannot say whole has a fingerprint of `null`: one with a refinement, a transform, a pipe, a check that rewrites the value, or a default or fallback that a function computes. `compareSaveManifestEntries(published, next)` from `@spawnite/schema` takes the save entry of every version the game published, and says how each owner changed since the highest version any of them gave it, since a player may hold a save from any of them: `same`, `changed-without-version`, `version-lowered`, `version-raised`, `added`, or `unchecked` where a fingerprint is missing or in another format, or a published entry cannot be read.
+
+The owners restore in a fixed order: the engine saves in the order of the table above, then each kit's in the order of the list, then the game's own. The world's saves restore as the record loads, and the player's onto her character once her spawn has set her up. Before the Player's character is destroyed, such as at a change of scene, the engine reads her into the record, so the next scene's character restores what she had.
+
+Game loads the record before anything inside it mounts, and writes it while the game plays, as [Where the save goes](#where-the-save-goes) says. `createSaveSession(world, { save, player, onRefuse })` holds one player's record while a game plays:
+
+- `load(record)` loads one, or `null` for a new game, and returns what it found. A record that fails, or a restore that throws, refuses the load, and `onRefuse` receives the refusal, at the load or at a later `attachCharacter`.
+- `attachCharacter` and `detachCharacter` restore her and read her.
+- `read()` returns `{ ok: true, record }` with the record as it stands, or `{ ok: false, problem }` where one owner's read failed, with the owner, its key, the reason and a message: nothing is written for that read, the status reads `unsaved` with the problem, and the next read tries again. The record holds what each `read` returned, not a copy, so turn it into JSON before the game changes again. It returns `null` before a load and after a refused one, since nothing may be written then. `versionsOf(record)` names each owner's version in a record by its key, such as `engine.inventory`, and `isOlderReader` says whether a reader is older than a record for any owner.
+
+A kit or a game that keeps an engine value inside its own key keeps it through the engine's codec, which tags it with its form and converts an older form wherever it sits: a shop keeps `itemStack.toSave(stack)` and reads `itemStack.fromSave(saved)`. `defineSaveCodec` makes the same for a value of a kit's own.
+
+## Save a game's own store
+
+To keep a store's state in the player's save, wrap its creator in the engine's `persist`. It takes zustand's `persist` options, so only the import differs from the zustand middleware you know:
+
+```ts
+// src/store/progress.ts
+import { createStore, persist } from "@spawnite/engine";
+
+interface Progress {
+    kills: number;
+    addKill: () => void;
+}
+
+export const useProgress = createStore<Progress>()(
+    persist(
+        (set) => ({
+            kills: 0,
+            addKill: () => set((state) => ({ kills: state.kills + 1 })),
+        }),
+        {
+            name: "progress",
+            version: 1,
+            partialize: ({ kills }) => ({ kills }),
+        },
+    ),
+);
+```
+
+The store keeps its entry under `stores` in the record, by its `name`, with its `version`. It differs from zustand's own in three ways:
+
+- It loads when the Game's save has loaded, never when it is created. Game mounts nothing inside it until the record and every persisted store have loaded, so no component reads a default in place of a saved value.
+- A change writes nothing by itself. Each record the engine writes reads the store as `partialize` keeps it, as [When the save is written](#when-the-save-is-written) says.
+- An entry the store cannot read refuses the whole save, as a game's own key does: one a newer version wrote, an older one with no `migrate`, and one whose `migrate` or `merge` throws. Every store is checked before anything restores, so the game stops on the load-failure screen with no store loaded, and nothing is written over the save. zustand's own throws that state away and plays on. A store with no entry in the save starts on its defaults, and its `merge` is not called.
+
+A store that a lazily loaded module makes after the save has loaded reads its entry as it is made. An entry it cannot read refuses the save as a load does: the game stops on the load-failure screen, the app is told, the entry stays as it is, and the page writes nothing more that session.
+
+`useProgress.persist` keeps zustand's API: `getOptions`, `rehydrate` and `hasHydrated` read as they do there. Two persisted stores with one name throw, except under hot reload, where the store the edited module makes replaces the old one and keeps its live state. Stores live once per page, so the first Game on the page loads and saves them; a second Game, as on a Storybook page, saves nothing. A test that renders its Game calls `resetPersistedStores()` and awaits `resetPageSave()` from `@spawnite/engine/testing` after each case: the first puts every store back to its defaults, unloaded, and the second waits for the write the last Game's unmount sent to reach the host, then ends the page's save, so the next Game loads its host's record. A test that unmounts its Game and then reads what was saved awaits `resetPageSave()` first.
+
+A persisted store is for a game with no rooms. In a game whose package.json gives it a room, a `spawnite.room`, the room writes every player's save, so a persisted store is an error: when the game mounts in development and in `spawnite simulate`, each naming the store, and at `spawnite build`, naming each module that takes `persist` from `@spawnite/engine`. The build reads the modules the bundler parses in both halves, so a re-export through a file of the game's own, a file outside `src` and a lazily imported module all count. A module that takes `@spawnite/engine` or `@spawnite/engine/core` whole, as a namespace, an `export *` or a dynamic import, fails the build too, because the build cannot tell whether it uses `persist` or `defineSave`: import each name by name. `spawnite build --server` checks the server half the same way. Save that value from the server half with a plugin's `save` instead. The game lint refuses `persist` from `zustand/middleware`, which writes to one browser and bypasses the save. A setting that belongs to the device, as the engine's quality and volume do, keeps the browser's storage.
+
+## When the save is written
+
+A game never writes its save. It changes its state, and the platform writes the newest state on its own schedule, the same for every game. The engine reads the record every 5 seconds, or every 30 seconds while its JSON is over 256 KiB, and each time it changed, it numbers it, gzips it and hands it to the page's host for the journal on the device, which a reload on the same device picks up. It sends the record to the cloud at the following moments, each only when the record changed since the last one sent:
+
+- Every 2 minutes.
+- When the tab is hidden, but no sooner than 30 seconds after the last write.
+- When the Game unmounts, and when another tab or device asks for the save.
+
+`save()` marks the record as changed at a moment that matters, such as a level's end: the status reads `unsaved` from the call, and the next write carries the newest state. It never forces a write, so a game can call it as often as it likes. A new game reads `unsaved` until its first record is stored. Nothing is written until the save has loaded. A read of the record that throws, as a game's `read` can, writes nothing: the status reads `unsaved`, the development console names the error, and the next read tries again.
+
+A record must fit two limits: 16 MiB as JSON and 4 MiB gzipped. One that passes either while she plays goes to the cloud at once, and nothing newer is read after it: the status reads `refused`, the development console names the limit and the measured size, and once the host stores it the game stops with the load-failure screen. A write of it that fails is sent again at the next window, a hidden page's flush, or a hand-over's ask. As it opens, the page reads the record once as a trial, after the migration steps and the restore of a world-scope save, measures that record as JSON and gzipped, and refuses a record past either limit the same way. The body it loaded is not measured, so a version whose migration step trims the record opens it. A record past twice either limit, the platform's ceiling, is never stored: the status reads `refused`, the last save that fit stays, and play goes on. Where the cloud lacks the last record that fit, as after its write failed, the engine sends that record again. A body that unpacks past 32 MiB, the platform's ceiling, is not read. The console warns once a record passes three quarters of either limit, with both sizes.
+
+`useSaveStatus()` answers the state of the save and where it goes, so a game can draw its own indicator; the engine draws none. It returns the following fields:
+
+- **`status`**: `saved`, `unsaved`, `saving` or `refused`, as the table below says.
+- **`destination`**: `platform`, `browser` or `nowhere`, as [Where the save goes](#where-the-save-goes) says.
+- **`size`**: the newest record's `unpackedBytes` as JSON and `compressedBytes` gzipped; `null` before the first.
+- **`problem`**: a size limit the newest record is past, with the `limit`, the `bytes`, the `maxBytes` and `ceiling`, true where it is past the platform's ceiling and so never stored, while `status` reads `refused`; or an owner's read that failed, with its `key`, `owner` and `reason`, while `status` reads `unsaved`. `null` while neither holds.
+
+| Status    | Means                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------ |
+| `saved`   | The platform, or the browser on the dev server, holds the newest state                                       |
+| `unsaved` | A change waits for its write, the last write or read failed, or nothing was ever stored                      |
+| `saving`  | A write is on its way                                                                                        |
+| `refused` | The newest record is past a size limit: stored once and the game stops, or past the ceiling and never stored |
+
+## Where the save goes
+
+The page's save goes to one of three places, which `destination` names:
+
+- **`platform`**: in the player app's frame, for a game with no rooms. The app hands the page the newest body in its `init`, and the page hands each record back over the same channel, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#what-a-game-and-the-app-say-to-each-other) lists. The page holds no credential and reaches no network for its save. Once the app has answered the page's hello, the page waits for its `init`, however long it takes.
+- **`browser`**: on the dev server, and on any page with no app around it, a frame that leaves the page's hello unanswered for 2 seconds included. Every record is kept in the browser's storage under `<name>-record`, so a reload restores the newest, and a record sent to the cloud reads `saved` once written.
+- **`nowhere`**: in a game with rooms, where the room writes each player's save; on a `spawnite play profile` run, which starts clean and seeds the world's random stream with a fixed seed so runs compare; and in a second Game on one page, as on a Storybook page.
+
+The page's host is read once a page. A Game that mounts again, or another Game of the same name, loads the record the last one left, and the page's records keep one rising number. Game opens its save once for its world, so a `save` object made anew on each render, as one written inline, changes nothing.
+
+A record that will not load stops the game: a key that fails, a restore that throws, or a body that cannot be read. Game restores nothing and mounts nothing, writes nothing over the save, tells the app, and shows "We couldn't load your progress" with the reason, in development as a player sees it.
+
+## Saves in a room
+
+A room mounts a scene and not `<Game>`, so a game with rooms exports the same declaration from each scene's file, beside `plugins`: `export { save } from "../save";`. The room is the only writer of its players' saves, and the page holds none.
+
+The room saves everyone in it together, by a checkpoint: it reads every player's record at one tick, uploads each record that changed, and commits them all at once. Either every player's save moves to that tick, or none does. So whatever the game moved between two players, such as an item one hands the other, is in both saves or in neither, whatever fails. The room takes a checkpoint at the following moments:
+
+- Every 60 seconds while any record changed, and every 2 minutes while the room holds one player.
+- Within 5 seconds of `requestSave(world)`, which a game's server half calls at a moment that matters, such as a run's end. The call names no player, since the checkpoint saves everyone. Calling it often costs nothing: the room starts 12 checkpoints a minute at most.
+- When a player leaves the room, as her page closes or another tab or room asks for her seat, or as the last player leaves. Her leave is read in the tick she leaves, after each plugin's `onPlayerLeave`, so what a hook hands on as she goes is in the other player's save and not hers, and the checkpoint that holds it frees her seat.
+- As the room stops, for every player still in it.
+
+```ts
+requestSave(world);
+```
+
+A player's join enters whole or not at all. The room loads her save before her player is made, restores it after each plugin's `onPlayerJoin`, where the `characters` plugin spawns her character, so each `onPlayerReady` reads what she saved, and once every `onPlayerReady` has run, reads her record once more as a trial and measures it as JSON and gzipped, as this version reads it after its migration steps, so a version whose step trims it lets her in. A save the room cannot load, a restore that throws, a trial read that fails, or a record past the size limit refuses her join, takes out what her join and ready hooks spawned, takes back their events, and writes nothing over her save: the room closes her socket with `saveNotLoadedCloseCode`, or with `saveNewerCloseCode` where a newer version of the game wrote the save. Each reason reads with `readSaveRefusalReason`, and the loading screen says her progress did not load. The room's other players are not touched.
+
+Where a seated player's save stands is on her player entity, as `readTrait(player, PlayerSaveTrait)?.status`: `saved`, `unsaved`, `saving` or `refused`.
+
+A development room keeps each save as a JSON file in `.spawnite/saves` in the game's folder, by the name the page sends, and commits it through the same checkpoints, so a restart or a rejoin restores progress. A room the cli starts for `spawnite play`, a playtest or a profile keeps none unless `--room-env ROOM_SAVES=1` asks, as a check of a save across a rejoin does, and `spawnite simulate` runs no room, so each starts every player afresh.
+
+## What stops a save
+
+Three things stop a save, in a page and in a room alike. Each is the game's to avoid:
+
+- **A record past the size limit.** A record must fit 16 MiB as JSON and 4 MiB gzipped. In a page, a record over either is stored once, then the game stops with the load-failure screen, and each later open measures the save again and refuses it while it is still past the limit; a record past twice the limit is never stored, and the last save that fit stays. In a room, the checkpoint still saves it with everyone's, up to twice the limit, and then removes her from the room; she takes no seat in that game for 10 minutes, and after that her join is measured again and refused while her save is still past the limit. Keep the record small: save what outlives a session, such as a level or a count, never a log that grows each time she plays. The development console warns once a record passes three quarters of either limit.
+- **Save code that throws.** A `read`, a `restore` or a migration step that throws. In a page, a read that throws writes nothing and the next read tries again. In a room, a read that throws at a checkpoint is tried once more on the next tick, and a second failure ends the room: every player in it goes back to the last checkpoint, and the player whose record failed takes no seat in that game for 10 minutes. At a join, a restore or a trial read that throws refuses her join. Keep `read` a plain copy of state into JSON, and test a restore with `spawnite save check`.
+- **A value that is not JSON.** A `read` that returns `undefined`, or holds a `Set`, a symbol, an `undefined` field, a number that is not finite such as `NaN`, or a value inside itself, is refused as a read that throws is. So is a value the schema refuses. Copy a `Set` into an array, and keep numbers finite before they reach the trait the save reads.
+
+`spawnite save check` plays a scene, reads its save, restores it into a fresh world and compares the two, so it catches a read or a restore that fails before a player does.

package/dist/wiki/engine/structure/scene.md

@@ -0,0 +1,69 @@
+---
+title: Scene
+description: A world and its UI, active one at a time.
+useCases:
+    - switch scenes
+    - go to the next level scene
+    - reload the scene
+    - main menu and game scene
+    - multiple scenes in one game
+    - restart a level
+    - scene transition
+sidebar:
+    order: 3
+---
+
+`<Scene name component>` inside [Game](/engine/structure/game/) registers a scene by name, and Game's `start` names the first one. `useScenes().go(name)` switches, and `useScenes().reload()` starts the active scene again from the beginning. Code outside a component, such as a store's action, calls the same functions on what `useScenes()` returned to the component that calls it. In a room, a system starts the room's scene again with `reloadScene(step)` from `@spawnite/engine/core`: once the step ends, every entity the scene spawned spawns anew on the room and on every page, and the players keep their characters. It returns false, and changes nothing, in a game played alone, which starts its scene again with `useScenes().reload()` from a component, and on a room whose scene is a spawn function rather than a component. Each Game keeps its own scenes, so two Games on one page never draw each other's. Only the active scene is mounted, so leaving one unmounts its world and everything in it. An entity that holds something beyond the frame, a GPU asset or a subscription, tracks it on itself with `trackResource`; destroying the entity runs what it tracked, so a switch leaves nothing behind.
+
+```mermaid
+sequenceDiagram
+    participant UI as scene UI
+    participant Game
+    participant Lobby as Scene lobby
+    participant Run as Scene run
+    UI->>Game: useScenes().go("run")
+    Game->>Lobby: unmount
+    Note over Lobby: world, entities and scene UI go with it
+    Game->>Run: mount
+    Note over Run: world loads, entities spawn
+```
+
+A scene renders a [World](/engine/structure/world/) and any UI that belongs to that scene alone. UI inside a Scene reads the scene's state and lives as long as the scene is active.
+
+Shared UI is a component in the game's folder, included in every scene that needs it, not lifted to Game.
+
+## Sample
+
+```tsx
+// src/scenes/Lobby.tsx
+import {
+    World,
+    Entity,
+    Camera,
+    Hud,
+    Panel,
+    Slot,
+    Button,
+    useScenes,
+} from "@spawnite/engine";
+
+export function Lobby() {
+    const scenes = useScenes();
+
+    return (
+        <World map="hilltop">
+            <Entity model="sled" />
+            <Camera follow={null} />
+            <Hud>
+                <Panel slot={Slot.Bottom}>
+                    <Button onPress={() => scenes.go("run")}>Play</Button>
+                </Panel>
+            </Hud>
+        </World>
+    );
+}
+```
+
+The Play button is scene UI: it unmounts with the lobby when the run starts.
+
+A scene holds no state of its own.