@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,301 @@
+---
+title: Game
+description: The root component, its loading and respawn screens, and the Vite plugin.
+useCases:
+    - loading screen
+    - loading progress bar
+    - game start up
+    - respawn screen
+    - game root component
+    - show loading tips
+    - starting volume setting
+    - custom loading screen design
+sidebar:
+    order: 2
+---
+
+`<Game name start>` is the root of a game. It holds the [scene](/engine/structure/scene/) registry, the modal stack, the screen layer and the stores. UI inside Game but outside any scene is global and lives as long as the game. [Stores and saves](/engine/structure/saves/) describes the stores and the save. [Plugins](/engine/structure/plugins/) and [Systems](/engine/structure/systems/) describe what each step runs.
+
+Game draws one canvas. The engine's frame loop and the active scene render inside it; Game's children render as DOM after it. The canvas fills Game's parent, so a game's page gives its root the whole screen, as every template's `styles.css` does:
+
+```css
+/* src/styles.css */
+#root {
+    height: 100dvh;
+}
+```
+
+Game, not [`<CharacterSpawn>`](/engine/entities/player/), listens to the movement keys for as long as it is mounted, whether or not the loop has loaded its physics yet, so a key held across a scene switch or a remount keeps walking the new character. While its world has a player's character, Game also keeps the arrow keys and Space from the page, so they walk rather than scroll it; with no character, they stay the page's.
+
+Each Game keeps its own scene registry, a zustand store among its stores, so two Games on one page each draw their own scene. `useScenes()` reads it from anywhere under Game.
+
+## Loading screen
+
+Game covers the canvas and the HUD with the engine's loading screen from the page's first paint until the first playable frame. A game needs no code for it. The screen lifts once, with a half-second fade, and a later scene's load does not bring it back.
+
+The screen shows one progress, as a line the width of the screen with its percent riding the end. The number and the line are one value: it never moves back, and it reads 100% only once the first playable frame has drawn, or 10 s after the other stages are in if the shaders never report done. Under the line, the screen names the stage the load waits on.
+
+| Stage                                 | The load waits on                                                                                                                                                                          |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `page`, Loading the game              | The page, its scripts and its stylesheet, until Game mounts.                                                                                                                               |
+| `assets`, Loading models and textures | The start scene's files and the engine's own, the physics and navmesh wasm and the scatter shapes table, which load side by side; every scene boundary drawn; and the start scene mounted. |
+| `room`, Joining the room              | The room's welcome, which brings her character. A game played alone has no such stage.                                                                                                     |
+| `world`, Building the world           | Her own character and the World's ground drawn, each only where the scene has one.                                                                                                         |
+| `shaders`, Preparing shaders          | The scene's shaders compiled, and then one whole frame drawn that compiled no new program.                                                                                                 |
+
+A stage passes once its own wait is over and every stage before it has passed. Each stage takes the share of the line that its time took on the last load of the page on this device, and a first visit uses the times of a cold load of Holdfast. Within a stage, the line fills by what it can count, the files and the engine's chunks loaded, and otherwise by its time against the time expected, and it never reaches the stage's end before the stage passes. Games generally weigh their stages this way, by the time each took rather than by their count, so the line moves at an even pace.
+
+The engine's Vite plugin writes the screen into the page itself, so it shows while the scripts download, before any script runs. It carries no script, as the store's pages run none inline, so a CSS animation moves its line toward a fifth. If the scripts have not arrived after 20 s, it says the game is taking longer than usual, with a link that reloads the page. Game takes it over where its line stands.
+
+### What waits for the screen
+
+Nothing shows over the screen, and nothing plays under it:
+
+- The screen layer, with every Hud and slot Panel, stays hidden until the screen lifts, and shows as it fades.
+- The frame counter, the Performance stats row, waits for the lift.
+- The devtools draw nothing until the lift. Their store is on the page from their mount, so `spawnite play stats`, `eval` and `dump` read a game that is still loading.
+- The game's sound holds: a running audio context suspends, and the player's input starts it only once the screen has lifted.
+- The menu waits too, and Escape opens nothing.
+
+### When a load stalls or fails
+
+A load that has passed no stage, landed no chunk and loaded no file for 20 s says it is taking longer than usual, with a Reload button, and a development page names what it waits on. The load goes on underneath, and the notice goes as soon as it moves. A room that closes before its welcome, or turns her away as full, says she could not join the game and why, with the same button, and the screen stays up. In the player app's frame, a room game's page loads while the app holds its room for her seat, and the screen waits at its room stage, without reading the held room as a failed join, until the app's `init` hands the seat over. A game that throws shows the same screen with what went wrong, in place of the game; a development page rethrows, so the dev server's overlay shows the error. A page the site published also sends the error to the platform's error tracker, with the game, the version, the engine release, the scene, the tick, the system that threw and React's component stack, and from the engine's first load sends any error nothing caught, at most 10 a page; a page the site did not serve, such as a dev server's or `spawnite play`'s, sends none, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#network) says. In the player app's frame, Reload loads the page a second time, which the app answers by removing the frame and saying the game stopped, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#network) says.
+
+### Shaders compile under the screen
+
+Three compiles a material's shader in the frame that first draws it, which can hold that frame for a tenth of a second or more. Game compiles the shaders of everything in the scene, drawn or hidden, in view or not, before the screen lifts, so an object the camera turns to later draws without a stall. Under the screen it starts a compile on every draw, so the shaders of what the screen hides build side by side rather than one after another. Once the other stages are in, it compiles the whole scene and uses each program once, then watches the frames: the first whole frame that compiles no new program is the first playable frame. A frame that does compile one, from something that mounted late, starts the compile again. The screen lifts after 10 s with a warning in the console if the compile never finishes. After the lift, Game compiles again after each later load and whenever post-processing is switched on or off. A light the game adds after the stages are in, with no file loading, changes the key of every lit shader, so each compiles again in the frame that next draws it: add a scene's lights before its first draw. Unity and Unreal warm their shader variants at load for the same reason, and Godot 4 compiles its pipelines while the scene loads.
+
+Three reads a program's link status, uniforms and attributes in the first draw that uses it, and each read waits on the GPU process: a burst's glow compiled ahead but never drawn held Holdfast's first spawn for 71 to 79 ms on a production build, so Game makes those reads under the screen. Three also uploads a texture in the first draw that uses it, so Game uploads every texture a material in the scene holds, drawn or hidden, before the screen lifts: in about half of Holdfast's runs, what the screen had not drawn uploaded 285 to 581 ms of textures in the first second of play. Something the game spawns later, with materials the scene does not hold yet, is compiled too when the game keeps one hidden in the scene. The hidden one also keeps those shaders when the last one drawn goes, as three drops a shader no material uses. The compile leaves out the shadow pass's shaders, so a caster spawned later compiles its shadow's shader in the frame that first draws it, unless the game draws the hidden one once, too small to see, after `useLoading`'s [`settled`](https://wiki.spawnite.com/reference/game/loadingstate/) turns true, which is under the screen, or after its `shadersCompiled` does, in a game with no screen. Holdfast keeps a rig of each monster model there and draws each once.
+
+### Effects build under the screen
+
+Chrome builds a GPU program the first time each kind of effect in the page's HTML and CSS draws, which holds the game's next frames on a player's first visit. Game draws the HUD and one of each of the engine's own effects out of sight while the screen covers the game, and a game puts a copy of what its HUD shows later in a `<WarmHud>`, as [the Hud page](/engine/ui/hud/#effects-build-under-the-loading-screen) says. The engine's effects go first, then each WarmHud in the order it mounted, for at most `warmUpMilliseconds` on Game, 6000 by default; 0 turns the warm-up off.
+
+### Dress the screen
+
+To dress the engine's screen, pass `loadingScreen` its options. Each is optional:
+
+- `title`: the game's name, large, over the line.
+- `line`: one line under the name.
+- `tips`: lines shown one at a time over the line, each for seven seconds.
+- `art`: the address of an image drawn behind the screen, filling it, such as a file in the game's `public` folder. The screen darkens it toward the line, so the words stay readable.
+
+The colors are the `--color-loading-*` variables, set on `:root` in the game's stylesheet as the rest of the palette is. The page's own screen reads them too, from its first paint. Its field and text colors are written into the page itself, with the house palette as the fallback, so the first paint is the dark field even before the stylesheet lands, as on the dev server, where it arrives with the scripts; the words show once it has:
+
+| Variable                     | Colors                                 |
+| ---------------------------- | -------------------------------------- |
+| `--color-loading-background` | The field, and the shade over the art. |
+| `--color-loading-bar`        | The line's fill.                       |
+| `--color-loading-track`      | The line behind the fill.              |
+| `--color-loading-text`       | The name, the line and the percent.    |
+| `--color-loading-label`      | The stage, the tips and the notice.    |
+
+Holdfast dresses its screen this way, shown here on the lobby:
+
+```tsx
+// src/AppWithDressedScreen.tsx
+import { Game, Scene, type LoadingScreenOptions } from "@spawnite/engine";
+import { Lobby } from "./scenes/Lobby";
+
+const loadingScreen: LoadingScreenOptions = {
+    title: "Holdfast",
+    art: `${import.meta.env.BASE_URL}loading.jpg`,
+    line: "Hold the circle till dawn",
+    tips: ["Two elements that meet on one monster set off a reaction."],
+};
+
+export function App() {
+    return (
+        <Game name="holdfast" start="lobby" loadingScreen={loadingScreen}>
+            <Scene name="lobby" component={Lobby} />
+        </Game>
+    );
+}
+```
+
+```css
+/* src/styles.css */
+:root {
+    --color-loading-background: #020617;
+    --color-loading-bar: #fcd34d;
+    --color-loading-text: #fef3c7;
+}
+```
+
+### Draw your own screen
+
+To replace the screen, pass a component as `loadingScreen`. Game hands it [`GameLoadingScreenProps`](https://wiki.spawnite.com/reference/game/gameloadingscreenprops/): `value`, from 0 to 1, the stage and its `label`, a `problem` to show or null, and `retry`, which reloads the page. The Made with Spawnite notice stays at the foot of the page over it. Give it `role="progressbar"`, as the engine's screen has, so `spawnite play profile` waits for it to go. Your screen owns its exit: Game unmounts it inside Motion's `AnimatePresence` the moment the game is ready, so to fade it, draw its root as a `motion` element with an `exit`, as the engine's screen fades over half a second. To build on the engine's own, draw `LoadingScreen` inside yours with the props it takes. To draw no screen, pass `loadingScreen={false}`: the page's own screen then goes as Game mounts.
+
+```tsx
+// src/AppWithLoadingScreen.tsx
+import { Game, Scene, type GameLoadingScreenProps } from "@spawnite/engine";
+import { Lobby } from "./scenes/Lobby";
+
+function Countdown({ value, label }: GameLoadingScreenProps) {
+    const percent = Math.floor(value * 100);
+    return (
+        <p role="progressbar" aria-valuenow={percent}>
+            {label} {percent}%
+        </p>
+    );
+}
+
+export default function App() {
+    return (
+        <Game name="sled" start="lobby" loadingScreen={Countdown}>
+            <Scene name="lobby" component={Lobby} />
+        </Game>
+    );
+}
+```
+
+### How the other engines do it
+
+Unity's web template draws one bar from the download alone, and it sits near 90% while the build decompresses and starts. Godot's web export draws its boot splash in the page's own markup from the project settings, before the engine runs. Roblox shows its own screen until the game's first assets replicate, and a game replaces it from `ReplicatedFirst`. Unreal's loading screen module keeps a movie or a widget up until the world is ready. The engine takes Godot's first paint and Roblox's replaceable screen, and differs from all four in reaching 100% only at the first playable frame, bar a shader compile that never reports done, so a player never waits on a full bar.
+
+## Respawn screen
+
+While the player's character waits to [respawn](/engine/behaviours/health/#when-a-character-runs-out-of-health), Game draws the engine's `RespawnScreen` where the loading screen stands: the game dimmed under "Back in 3" and a line that empties as the wait runs out, in the loading screen's colours. It shows only her own wait, never another player's, and goes the step she comes back. A game whose respawn is off never shows it.
+
+To replace it, pass a component as `respawnScreen`. Game hands it [`RespawnScreenProps`](https://wiki.spawnite.com/reference/game/respawnscreenprops/): `seconds`, the whole wait, and `secondsLeft`, counting down to 0. To build on the engine's own, draw `RespawnScreen` inside yours. To draw none, such as a game whose HUD shows the wait itself, pass `respawnScreen={false}`.
+
+```tsx
+// src/AppWithRespawnScreen.tsx
+import { Game, Scene, type RespawnScreenProps } from "@spawnite/engine";
+import { Lobby } from "./scenes/Lobby";
+
+function Knockout({ secondsLeft }: RespawnScreenProps) {
+    return <p role="timer">Knocked out: {Math.ceil(secondsLeft)}</p>;
+}
+
+export default function App() {
+    return (
+        <Game name="sled" start="lobby" respawnScreen={Knockout}>
+            <Scene name="lobby" component={Lobby} />
+        </Game>
+    );
+}
+```
+
+## Starting volumes
+
+The volume sliders in Settings start at 100, the game's own mix, except music, which starts at 60, 20 dB under the effects. To start them elsewhere, pass `defaultVolumes`, such as `defaultVolumes={{ musicVolume: 100 }}` for a game whose music file is mixed under its effects already. Reset audio returns to these volumes, and a volume the player saved on this device keeps its value. [Settings](/engine/ui/settings/#a-games-own-mix) lists the volumes and where the top games start them.
+
+## Voice
+
+A game that joins a room has voice, and the engine draws its microphone button in the top-left corner. Players start on open mic; `defaultVoiceMode={VoiceMode.PushToTalk}` starts them on push to talk, and a mode the player saved keeps its value. `voice: false` on the room, such as `room={{ url, playerName, voice: false }}`, turns voice off for the game: no microphone, no voice rows and no button. [Voice](/engine/audio/voice/) covers the rest.
+
+## Renderer
+
+Game draws with three's `WebGLRenderer`, made as React Three Fiber makes it, with percentage-filtered shadows. Its `gl` prop takes the settings the renderer is made with, such as `{ stencil: true }`, or a factory that makes the renderer; `shadows` picks the shadow filter; and `onCreated` runs once the canvas has made its renderer. Game reads the three once, when it mounts. [Your renderer and your own three.js](/engine/graphics/renderer/) describes them, and [WebGPU (experimental)](/engine/graphics/webgpu/) mounts a game on three's `WebGPURenderer`.
+
+## A page that is not a game
+
+A page can mount the engine to draw something that is not a game, such as the model viewer on the tools app. Four settings leave out what a game's page has and such a page does not want:
+
+- `menu={false}` on Game mounts no Play menu. Escape and leaving fullscreen then open nothing, and Escape reaches the page's own handlers.
+- `loadingScreen={false}` on Game draws no loading screen over the canvas.
+- `spawnite({ loadingScreen: false })` in the page's Vite config writes no loading screen into the page.
+- A Game with no player's character in its world leaves the arrow keys and Space to the page, so a page that scrolls still scrolls.
+
+`<ModelFile url>` draws a GLB or VRM file with no entity and no [World](/engine/structure/world/) around it: stood on its lowest point with its origin across the ground, a VRM 0 avatar turned to face +z as a VRM 1 avatar faces, casting and receiving shadows, and a VRM's springs updated each frame. `animation` names the clip it plays, from the file's own clips or from `clips`, such as clips made from VRMA files for an avatar; `loop={false}` plays the clip once and holds its last frame. `onPlay` hands over the playing action, for a page that pauses or scrubs it, and `onLoad` hands over the model's bounds as it stands, for a camera that frames it. It draws the loaded file itself rather than a copy, since a VRM's springs belong to the file's own bones, so two on one page take two URLs. The props are [`ModelFileProps`](https://wiki.spawnite.com/reference/entity/modelfileprops/).
+
+```tsx
+// src/ModelPreview.tsx
+import { Game, ModelFile, Scene } from "@spawnite/engine";
+
+function Stage() {
+    return <ModelFile url="/models/duck.glb" animation="walk" />;
+}
+
+export function ModelPreview() {
+    return (
+        <div style={{ height: 400 }}>
+            <Game
+                name="preview"
+                start="stage"
+                menu={false}
+                loadingScreen={false}
+            >
+                <Scene name="stage" component={Stage} />
+            </Game>
+        </div>
+    );
+}
+```
+
+The engine's components import their stylesheet, `@spawnite/ui/styles.css`, from their code. A page with a Tailwind stylesheet of its own imports that sheet first, then its own, from its entry module, so that where both hold a utility, such as `flex-col`, the page's variants of it, such as `sm:flex-row`, win. The engine's own import is the same module, so the sheet loads once:
+
+```ts
+// src/main.tsx
+import "@spawnite/ui/styles.css";
+import "./styles.css";
+```
+
+Unity, Unreal and Godot each draw a model in an editor's preview, outside any scene a game plays, with a renderer that assumes nothing of the page around it. Roblox and PlayCanvas have no such preview outside their editors. The settings above are that same preview for a web page.
+
+## The Vite plugin
+
+A game builds with [Vite](https://vite.dev), and its `vite.config.mts` loads the engine's plugin, `spawnite()`, once. A game made from a template already loads it. To add it to a Vite config of your own:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { spawnite } from "@spawnite/engine/vite";
+
+export default defineConfig({
+    plugins: [react(), spawnite()],
+});
+```
+
+The plugin does the following for every game, whatever the game uses:
+
+- Tells the engine whether the game runs in development, so the engine's [dev warnings](/engine/testing/devtools/#the-console) print in development and not in a build a player opens.
+- Inlines each [LYGIA include](/engine/graphics/shader/#include-a-lygia-function) in a shader fragment when the game builds.
+- Writes each sound as a file of its own, rather than into the first chunk the page loads.
+- Points three's Draco decoder at the one the engine loads, so the build ships one decoder.
+- Ships the game's own copy of a model the engine also bundles, where `public/assets` holds the same bytes, as [the frame page](/engine/testing/frame/#what-loads-before-the-first-frame) describes.
+- Warns when a built stylesheet still holds an `@theme` block, which the browser drops.
+- Writes the [loading screen](#loading-screen) into the page, so it shows from the first paint while the scripts download. A page that is not a game leaves it out with `spawnite({ loadingScreen: false })`.
+- Names the game's build in a built page, which the page sends as it joins a room, so a room of another build logs both and the page shows a note naming them, as [Multiplayer](https://wiki.spawnite.com/platform/connections/#a-page-and-a-room-of-another-build) says.
+- On the dev server, keeps each playtest as a [replay](/engine/testing/replay/). `spawnite({ replay: { … } })` sets its budget and its screenshots, as [Settings](/engine/testing/replay-storage/#settings) lists.
+- On the dev server, throttles the errors the page forwards to the terminal: uncaught errors and `console.error` lines. Vite forwards them when an agent runs the server, or when `server.forwardConsole` asks for it, and a frame that throws sends sixty a second: printed each time, they keep the server too busy to send the page the edit that fixes the frame. The terminal prints a repeated error once a second and at most ten distinct errors a second, then one line counting the ones it left out. Warnings and every other console level print as Vite forwards them.
+
+The same config builds a published version of the game, its page and its server half, with the engine left for an engine release, as [Publishing](https://wiki.spawnite.com/platform/publishing/) says.
+
+Vite's frameworks name their plugin for themselves, as `react()`, `vue()` and `sveltekit()` do, and the engine's follows them.
+
+## Sample
+
+```tsx
+// src/App.tsx
+import {
+    Game,
+    Scene,
+    Hud,
+    Panel,
+    Slot,
+    Text,
+    useWallet,
+} from "@spawnite/engine";
+import { Lobby } from "./scenes/Lobby";
+import { Run } from "./scenes/Run";
+
+export default function App() {
+    const wallet = useWallet();
+
+    return (
+        <Game name="sled" start="lobby">
+            <Scene name="lobby" component={Lobby} />
+            <Scene name="run" component={Run} />
+            <Hud>
+                <Panel slot={Slot.TopRight}>
+                    <Text>Coins {wallet.coins}</Text>
+                </Panel>
+            </Hud>
+        </Game>
+    );
+}
+```
+
+The coin count is global UI: it sits inside Game and outside any Scene, so it shows in the lobby and on the run.

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

@@ -0,0 +1,239 @@
+---
+title: Levels
+description: A game's levels in order, and the player's progress through them, kept in the player's save.
+useCases:
+    - level progression
+    - unlock the next level
+    - best score per level
+    - level select screen
+    - level completion tracking
+    - save which levels are finished
+    - list of levels in order
+    - level select in a lobby
+    - next level button after a win
+sidebar:
+    order: 8
+---
+
+A game lists its levels in order with `defineLevels`, and passes the list to Game's `levels`. The engine keeps the player's progress through them: the levels the player has finished, each one's best, and the levels the player can play. A won [round](/engine/structure/round/) records itself against the level being played. The game writes the list and nothing else, and a reload keeps the progress.
+
+Roblox, Unity, Unreal and Godot leave this to the game. A Roblox game invents its own DataStore keys, Unity's `PlayerPrefs` and Unreal's `USaveGame` are empty containers that the game fills, and Godot has nothing built in. Level-based games such as Candy Crush, Angry Birds and Mario Kart keep the same three facts for each level: finished, the best result, and unlocked. The engine keeps those three, so no game writes the bookkeeping again.
+
+## Listing the levels
+
+`defineLevels({ One: "level-1", Two: "level-2" })` names each level and gives its id. The order of the keys is the order of play. The object it returns reads like an enum, `Track.Two` is `"level-2"`, and each id keeps its literal type. It throws for an empty list, and for an id listed twice.
+
+## Unlocking and the best
+
+- The first level is always unlocked. Each level after it unlocks once the level before it is finished.
+- A won round finishes the level being played. A lost round records nothing.
+- A game whose win is no round, such as a puzzle solved, finishes the level itself with `finishLevel(world, { score, seconds })` from a system. The round calls the same function as it is won.
+- A level's best is the highest score and the fewest seconds of any round that won it, each kept on its own. The score is the coins the round counted while it played, and the seconds are the simulated seconds it played. A race shows the seconds, and a game of collecting shows the score.
+
+## Playing a level
+
+`useLevels()` returns a [`LevelsStatus`](https://wiki.spawnite.com/reference/levels/levelsstatus/):
+
+- `levels`: each level in order, as a [`LevelStatus`](https://wiki.spawnite.com/reference/levels/levelstatus/) with its id, whether it is finished and unlocked, and its best.
+- `current`: the id of the level being played. It is never empty: the first level until the save says otherwise.
+- `next`: the id of the level after `current`, or null after the last.
+- `play(id)`: makes an unlocked level the current one and starts the active scene again, as the round's `restart()` does. It returns false, and changes nothing, for a locked level, and throws for an id the game does not list.
+
+The scene builds the level that `current` names. A game opens on the first level not finished, or on the first level once every one is. `useLevels()` throws in a game whose Game has no `levels`.
+
+## A level select in another scene
+
+`play(id)` starts the active scene again, so it suits a button inside the level's own scene. A level select in another scene, such as a lobby, sets the level with `playLevel(world, id)` and then opens the level's scene with `useScenes().go(name)`, as [Scene](/engine/structure/scene/) says. `playLevel` returns false, and changes nothing, for a locked level, as `play` does.
+
+The round's screen leads on with a "Next level" button among its `actions`, shown once the round is won and while `next` names a level. Its `play(next)` makes the next level the current one and starts the race scene again on it; a won round has unlocked it.
+
+The engine's tests open the race from the lobby on level 1, win it, and press Next level:
+
+```tsx title="packages/engine/test/outside/LevelSelect.tsx"
+import { useWorld } from "koota/react";
+import {
+    Button,
+    defineLevels,
+    Hud,
+    Panel,
+    playLevel,
+    Slot,
+    Text,
+    useLevels,
+    useScenes,
+} from "@spawnite/engine";
+import {
+    Round,
+    RoundScreen,
+    RoundState,
+    useRound,
+} from "@spawnite/engine/rounds";
+
+export const Track = defineLevels({
+    One: "level-1",
+    Two: "level-2",
+    Three: "level-3",
+});
+
+/** The lobby scene: a button for each unlocked level, which opens the race
+ *  scene on it. */
+export function Lobby() {
+    const world = useWorld();
+    const scenes = useScenes();
+    const { levels } = useLevels();
+    return (
+        <Hud>
+            <Panel slot={Slot.Center}>
+                {levels.map(({ id, unlocked }) =>
+                    unlocked ? (
+                        <Button
+                            key={id}
+                            onPress={() => {
+                                playLevel(world, id);
+                                scenes.go("race");
+                            }}
+                        >
+                            {id}
+                        </Button>
+                    ) : (
+                        <Text key={id}>{`${id}, locked`}</Text>
+                    ),
+                )}
+            </Panel>
+        </Hud>
+    );
+}
+
+/** The race scene: its round, and a Next level button on the round's
+ *  screen once it is won, while a level is left. */
+export function Race() {
+    const { next, play } = useLevels();
+    const { state } = useRound();
+    const nextLevel =
+        state === RoundState.Won && next !== null ? (
+            <Button onPress={() => play(next)}>Next level</Button>
+        ) : null;
+    return (
+        <>
+            <Round seconds={60} target={8} />
+            <RoundScreen actions={nextLevel} />
+        </>
+    );
+}
+```
+
+Register the levels' type beside `defineLevels`, as [Typing the ids](#typing-the-ids) says, so `playLevel` and `play` take only the game's ids.
+
+## Showing the level
+
+`<LevelBanner>`, from `@spawnite/engine/rounds`, names the level being played and the count, "Level 2" over "of 4", in the centre slot while the round is ready. It hides once the round starts, and it draws nothing in a game with no levels. Two short lines fit the centre of a phone, which is about 114 px wide between the other slots. Pass `noun` to call the levels something else: sled passes `"Track"`. The [round screen](/engine/structure/round/#its-screen) names the level too, on one line above its title.
+
+Its props are in [`LevelBannerProps`](https://wiki.spawnite.com/reference/levels/levelbannerprops/).
+
+A screen of the game's own reads the same count with `useLevelPlace()`: `{ number, count }`, with `number` counted from 1, or `null` in a game with no levels.
+
+Roblox, Unity, Unreal, Godot and Phaser leave a level card to the game. Mario Kart names the course before the race and shows nothing about it during the race, and the banner does the same: the player reads it on the start line, not while steering.
+
+## Typing the ids
+
+A game registers its levels once, beside `defineLevels`:
+
+```ts
+declare module "@spawnite/engine" {
+    interface Register {
+        levels: typeof Track;
+    }
+}
+```
+
+The engine exports an empty `Register` interface, and this line adds the game's levels to it. From then on `current`, `next`, each level's `id` and the argument of `play` take only the game's ids, as the `LevelId` type, so `play("lvl-2")` fails to compile where the game lists `"level-2"`. Without the line, each of them is any string. TanStack Router types its routes the same way, through its own `Register`. Roblox, Unity, Unreal and Godot name a level by a plain string or an asset reference, so a misspelled level name fails only when the game runs.
+
+A game that forgets the line still compiles, so it keeps a test that fails without it:
+
+```ts
+// test/levels.test.ts
+import type { LevelId } from "@spawnite/engine";
+import { expectTypeOf, it } from "vitest";
+import type { Track } from "../src/levels";
+
+it("registers its levels, so useLevels types each id", () => {
+    expectTypeOf<LevelId>().toEqualTypeOf<(typeof Track)[keyof typeof Track]>();
+});
+```
+
+The test fails the typecheck, not the test run: without the line, `LevelId` is `string`.
+
+## The save
+
+The engine saves the finished levels only where the game's save names `levels` in `include`, as [Saving progress](https://wiki.spawnite.com/learn/saving-progress/) says: by id, each with its best `score` and `seconds`, under `engine.levels`. The save restores them as it loads, and a won round that changes them asks for a write within 2 seconds, so a game writes no code for either. A game that does not include `levels` starts on the first level at each load. A game with rooms keeps none: its levels are the room's.
+
+The save finds a level by its id, so a game keeps each id once players hold a save. A level's name, the key in `defineLevels`, can change.
+
+## Where it runs
+
+Client, and headless on the first level. The progress is the player's own and lives in the browser's save, so Game spawns the levels in the player's world, and a room keeps no progress. A room mounts its scene headless, and the mount spawns the levels the last `defineLevels` call made, so a scene that calls `useLevels()` mounts in a room too. The headless mount plays the first level whatever the page's save holds, so a game with levels plays level 1 in a room. The room's stream carries none of them. A won round records the level in the step that decides it, or in `finishRound`. Game spawns the levels on an entity of their own before anything mounts, outside every scene, so a scene's reload keeps the level being played. A system reads them with `listLevels(world)` and `nextLevel(world)`, and changes the level with `playLevel(world, id)`, all from `@spawnite/engine/core`. `createHeadlessGame` takes the same `levels` as Game, so a headless test reads `current` as `spawnite play` does in the browser.
+
+```tsx
+import {
+    Button,
+    defineLevels,
+    Game,
+    Hud,
+    Panel,
+    Scene,
+    Slot,
+    Text,
+    useLevels,
+} from "@spawnite/engine";
+import { Round, RoundScreen, rounds } from "@spawnite/engine/rounds";
+
+export const Track = defineLevels({
+    One: "level-1",
+    Two: "level-2",
+    Three: "level-3",
+});
+
+declare module "@spawnite/engine" {
+    interface Register {
+        levels: typeof Track;
+    }
+}
+
+function LevelSelect() {
+    const { levels, current, next, play } = useLevels();
+    return (
+        <Hud>
+            <Panel slot={Slot.TopLeft}>
+                <Text>{`Playing ${current}, then ${next ?? "the end"}`}</Text>
+                {levels.map(({ id, unlocked, best }) =>
+                    unlocked ? (
+                        <Button key={id} onPress={() => play(id)}>
+                            {best ? `${id}, ${best.seconds.toFixed(1)} s` : id}
+                        </Button>
+                    ) : (
+                        <Text key={id}>{`${id}, locked`}</Text>
+                    ),
+                )}
+            </Panel>
+        </Hud>
+    );
+}
+
+function Race() {
+    return (
+        <>
+            <Round seconds={60} target={8} />
+            <LevelSelect />
+            <RoundScreen />
+        </>
+    );
+}
+
+export default function App() {
+    return (
+        <Game name="racer" start="race" levels={Track} plugins={[rounds()]}>
+            <Scene name="race" component={Race} />
+        </Game>
+    );
+}
+```