@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/testing/replay.md

@@ -0,0 +1,230 @@
+---
+title: Replay
+description: Every playtest in a dev build kept as a replay, with its marked moments, to read, shoot, play back, and continue exactly with the code as it stands.
+useCases:
+    - replay a playtest
+    - reproduce a bug from a recording
+    - mark a moment in play
+    - continue play from a saved moment
+    - screenshot a recorded moment
+    - play back what a player did
+    - review a multiplayer session
+    - debug a crash with a replay
+sidebar:
+    order: 14
+---
+
+A development build keeps each page's play as a replay, with no code in the game: what its room sent it, what it sent the room, each frame's length, the player's input, the page's own state each second, a log of what happened and a screenshot every two seconds where the view changed. Its dev room keeps a recording of its own beside it while a player is in it: every action the room took, from every player, and a checkpoint of its whole world as the first player comes in, as each minute begins, every ten seconds, and as the last one leaves. The two are kept together as a session, one for each run of the room, under one size budget for the whole game, 300 MB unless the game sets another: a long session shrinks from its oldest minute, and a marked moment stays until an agent releases it. When a player says "the monsters stopped hitting me just before I pressed F8", an agent finds that moment in the replay's log, looks at what the screen showed, continues the moment in a fresh room exactly as it was, fixes the code, and continues it again to prove the fix.
+
+Two pages continue this one: [Directing a moment](/engine/testing/directing/) and [What a replay keeps](/engine/testing/replay-storage/).
+
+A replay is not a video. What the room sent is the world, so playback draws it again on the game's own page, from any angle the game's code picks. What the room kept is the whole world, the state no page ever receives among it, so a continue is the room again, step for step.
+
+The replay keeps three layers of what happened, and each tool plays one of them again:
+
+| Layer        | What it is                             | Made by                  | Played again by                                                                |
+| ------------ | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------------ |
+| Device input | Keys, the mouse and the wheel          | The player               | [Playback](#seeing-it), into the page: controls, camera, HUD, prediction       |
+| Actions      | Moves, shots, walks, each at its step  | The page, from its input | [A continue](#continuing-a-moment), into the room: rules, AI, damage           |
+| Results      | Where everything stands, what it holds | The room                 | Nothing: [reading the world](#reading-the-rooms-world-at-a-moment) is watching |
+
+## What a player sees
+
+In a dev build, the Escape menu reads "Replay is on · F8 marks this moment", with a Mark this moment button, and Settings, Graphics has a Keep a replay switch, on until the player turns it off. F8 or the button marks the moment: a notice shows its number, `m1`, `m2` and on, the log gets a line, and the page keeps a shot of the canvas at its own size, as the player saw it. Where marks already protect their share of the budget, the notice says the new one protects nothing. A production build has none of this: the replay's code is a chunk only a development build loads, and [a build test](/engine/testing/replay-storage/#dev-builds-only) holds every game to it.
+
+## Finding a moment
+
+`spawnite replay list` names each session of the game, newest first: the room's run and every page that played in it, or a page that played with no room, with the minutes each keeps, their marks and their bytes, then the saved clips, and how much of each budget they take:
+
+```text
+Replays in .replays: 13.5 MB of the 15.0 MB budget; marks protect 9.7 MB of their 7.5 MB; saved clips 5.7 MB, a warning past 200.0 MB.
+Sessions, newest first:
+  20260927-185312-diw4  the room's run of ./src/scenes/Holdfast.tsx, started 2026-09-28T00:53:12.458Z, minutes 2 to 3  3.5 MB  being written
+    20260927-185317-25ny  Iron Lantern  kept 115.00 s to 194.09 s  m1 68.39 s protects nothing  2.9 MB
+  20260927-183940-19mw  the room's run of ./src/scenes/Holdfast.tsx, started 2026-09-28T00:39:41.009Z, minutes 3 to 6  10.0 MB
+    20260927-183945-hqxe  Frost Keeper  kept 175.26 s to 415.26 s  m1 308.05 s, m2 314.03 s, m3 320.01 s, m4 326.00 s, m5 332.00 s, m6 338.00 s, m7 344.00 s, m8 350.01 s, m9 356.01 s, m10 362.00 s  9.2 MB
+Saved clips:
+  minute-10  20260927-183945-hqxe of 20260927-183940-19mw, 475.26 s to 655.26 s  5.7 MB
+Marks protect 9.7 MB of their 7.5 MB: a new mark protects nothing until one is released with `spawnite replay release`.
+```
+
+That list is Holdfast's under a budget set to 15 MB: a 12-minute session whose ten marks in one minute protect minutes 3 to 6, trimmed to them by a later session, whose own mark came once marks filled their share. A command names a page by its name, the date and time it opened, such as `20260927-183945-hqxe`, by the start of one, by its session's name, by a saved clip's name, or `latest`, the newest page. A moment is seconds into the page, a mark such as `m1`, or a mark and seconds, such as `m1-10`.
+
+`spawnite replay log latest` prints the lines that say what happened, and counts the engine's events:
+
+```text
+20260927-060206-sgqv, holdfast, Ash Warden, started 2026-09-27T12:02:06.877Z:
+      3.95 s  room joined
+      5.44 s  long frame 1352 ms under the loading screen
+      7.49 s  long frame 1837 ms
+      8.50 s  2 corrections of her character, up to 0.12 m
+     11.68 s  marked m1
+Engine events, counted: load ×37, scene ×1, spawn ×9, loading screen lifted ×1, shot ×124, destroy ×4.
+The shot at m1, 11.69 s, 1920 by 1080: `spawnite replay shot 20260927-060206-sgqv --at m1`.
+```
+
+With `--around m1`, the 20 s before a moment and the 5 s after it, or `--from` and `--to`, it prints every line in the window. The lines are the engine's events, the ones [Finding hitches](/engine/testing/hitches/) reads, a game's own `performance.mark` calls, frames over 50 ms, the console's errors and warnings, the room's joins and drops, the room's corrections of the player's character, the marks, where the page sat idle, and where the page's clock fell behind the wall. The log also reads the room's changes from the stream, each a `room:` line: what came in and went, such as `room: spawn monster 17`, who joined and left, and each hit on her character, such as `room: her character took 5 damage, 65 left`. Without a window it shows the joins and leaves, and counts the rest. A window's log ends by summing its frames: how many, the seconds of the page's clock they took, and the seconds of the game's time their steps ran, which part where a tool stepped the game or ran it at another speed, as `292 frames in the window: 2.96 s of the page's clock, 3.00 s of the game's time.` A continue's log is its room's changes alone.
+
+## Seeing it
+
+`spawnite replay shot latest --at m1-2` writes the screenshot the page kept nearest the moment and names the file: an 854 by 480 WebP every 2 s, about 550 of an agent's image tokens, and one at each mark at the canvas's own size, 1920 by 1080 on a full HD screen. A shot comes out at most 1280 px wide, never wider than it was kept, and the command says the whole size it shrank from; `--width full` writes it whole, and `--width 640`, or any width, writes it that wide at most, at its own shape. An image costs about its width times its height over 750, so 640 by 360 is about 300 tokens, 1280 by 720 about 1,230 and a full HD mark about 2,760, where the model does not scale it down first:
+
+```text
+The shot at 36.93 s, at m1, 0.01 s from the moment asked, 1280 by 720 of its 1920 by 1080: /tmp/spawnite/replay/20260927-175414-moe8-36934-m1-1280w.webp. `--width full` writes it whole.
+```
+
+It shows the canvas alone, not the page's own panels, so a HUD drawn in the page's DOM, as Holdfast's is, is not in it; `--render` shoots the whole page, at most 1280 px wide the same way. Without `--out`, shots and exports go to `spawnite/replay` in the system's temp folder, which keeps the newest 20.
+
+The page leaves a rolling shot out when it barely differs from the last one it kept, so a character standing still, or a menu open over a quiet scene, keeps one shot every 10 s rather than five: the first of each ten seconds is always kept, so every ten seconds have one. The encoding worker compares the two on a grid of 32 by 18 cells, each cell's mean brightness, and keeps the shot where 16 cells or more moved by more than 5 % of the range from black to white. On Holdfast, shots 2 s apart differed in 1 to 12 cells while her character stood still and in 37 or more while she fought. A skipped moment reads from the kept shot before it, which showed the same view; the command says how far that shot is from the moment asked.
+
+`spawnite replay play latest --from m1-3 --to m1+2 --every 1` plays the window back on the game's dev page, headless, and shoots the whole page at each end and each second. `spawnite replay shot latest --at m1 --render` plays back to one moment and shoots it. The page opens on its state at the last second before the window, then runs each recorded frame with the room's messages and the player's input that came before it, on a clock that reads the recording's time. What the page computes is the page's code as it stands, so a fix to the camera shows in the shot. The command prints how far the player's character strayed from where the recording had her, which on Holdfast is 0.000 m, what the page drew before it stood on its keyframe, and what the page logged as it played:
+
+```text
+Played 20260927-060206-sgqv to 13.68 s in 553 recorded frames on the game's dev page, with the code as it stands now.
+The dev server answered in 0.6 s; the page stood on its keyframe 8.3 s after it opened.
+Before it stood on its keyframe, the page drew 0 frames of the loading world that the loading screen did not cover, and showed a frame the recording never had for 10 ms. It drew the keyframe on 2 frames of no time until what it mounted had loaded; the first waited on 0 shader programs.
+Her character stood at most 0.000 m from where the recording's keyframes had her.
+```
+
+With `--json`, the numbers on the second line are in `status.opening`, counted from the page's last open on a keyframe, a seek's included:
+
+- `staleFrames`: frames of the loading world that the loading screen did not cover.
+- `staleMilliseconds`: the time from the loading screen's lift to the end of the keyframe's first frame, while the page showed a frame the recording never had.
+- `keyframeFrames`: frames of no time drawn on the keyframe until what it mounted had loaded.
+- `keyframePrograms`: shader programs the first of those frames waited on: those it compiled, and those still linking as it began. A nonzero count means the loading frames left out a material the keyframe mounted.
+
+A person opens the same moment in a browser at the dev server's address with `?replay=<name>&at=<seconds>`, and it plays at the display's pace; `&session=<session>`, or `&session=saved/<clip>`, reads it from that session or saved clip, where the page is in more than one. Before it plays, the page draws the keyframe's world on frames of no time until every model it began loading has landed. The first of those frames compiles the shaders of anything the keyframe added that the loading frames had not drawn, and the page shows its last loading frame until it ends. The loading screen stays up until a frame compiles nothing new, so on Holdfast that frame compiles none: the page draws one frame of the loading world after the screen lifts, and the keyframe shows about 20 ms after that frame.
+
+`spawnite replay shot --render` takes the same camera flags as [a held session's `screenshot`](/engine/testing/directing/#cameras), and `spawnite replay play --camera <json>` shoots each moment from one camera; `--no-hud` on either shoots the player's camera without the page's panels. Their other cameras, and `--no-hud`, leave out the screen overlays the player's view draws in the canvas, as a held session's shots do, [below](/engine/testing/directing/#cameras), and `--overlays` keeps them.
+
+## Continuing a moment
+
+`spawnite replay rerun latest --at m1-5 --seconds 8` continues the moment in a fresh room of the game, with the code as it stands:
+
+1. The command finds the room's run the page played in, and the step the room had run when it sent the last delta the page had at the moment, by the hash the delta carries.
+2. A room of the game starts, serving nobody, on the settings the run's `room.json` says its room started with, whatever the continuing room's own environment says: whether it spared every player's character, the most players it held, whether it took devtools edits, and how long it kept a dropped player's character. It writes back the room's checkpoint from before that step: every trait of every entity, the server-only ones among them, each entity under koota's own number, the order every query walks, the physics world as Rapier snapshots it, the navmesh polygon each chaser stood on, the world's random stream, and each player's queued moves and credits.
+3. The room takes every action it recorded from the checkpoint on, from every player, after the same step as it took it then, at the room's time then, as fast as it steps: Holdfast's 8 s take about 0.3 s. Koota defers taking a destroyed entity out of each query until a query next runs, so the room, recording or continuing, commits those removals as each step and each action ends: a mounted scene's React render, which queries the world whenever the room's thread is free, then finds none to commit, and every query walks its entities in the order the continue gives them.
+4. The command keeps what the room sent her as a replay of its own, `<name>-r1`, on the first one's clock, and prints the two side by side.
+
+With the code unchanged the room comes back exactly, and the command says so from the room's own record, not from a tolerance. A room that records hashes its world at each send, puts the hash on the delta, and logs each one, with a hash of the events the delta carried beside it: every send of the continue must hash as the room's did, its world and its events alike. Where the continue passes a later checkpoint, it sets its whole world beside that checkpoint: every trait of every entity, and the physics world byte for byte as Rapier snapshots it, which holds state no trait shows. It then names the first change in the world that parts the two, and where her character stood and what the world held, second by second:
+
+```text
+Continued 20260927-131554-dfbf from 20.00 s to 27.46 s as 20260927-131554-dfbf-r3: a fresh room of the game with the code as it stands now, from the room's checkpoint at step 1200, with the 226 actions it recorded from there taken again, in 0.3 s.
+Exact: every one of the 177 sends hashed as the room's own did.
+Every change in the world, each spawn, removal, join and hit on her, came in the same order in both.
+Second by second, step for step, the continue against the recording:
+     20.46 s  her character where she was; her health 85; monster ×4, 120 health
+     21.46 s  her character where she was; her health 75; monster ×5, 150 health
+```
+
+With a fix in the code, the same command shows what the fix changes from that moment: the send where the stream first parts, the entity and trait each later checkpoint holds otherwise, and the first spawn, removal or hit that differs. `spawnite replay play` plays the continue back on the game's page, and `spawnite replay log` reads its changes. The page times of a recording bunch where its page ran slowly, so the comparison sets the two side by side by the room's step, which each delta's hash gives.
+
+A continue needs the room's recording: a game's `spawnite.room` sets `ROOM_REPLAY=1` in its `env`, which keeps one while a player is in the room. A room that keeps its players' saves records, with each join, the record it loaded for her and her id, or that she had none, and never a pass: a continue restores that record onto her character, with no store, so a session of saved players comes back exactly from her first step. A page played against a room with none, or a moment whose checkpoint the trim deleted, is refused with the reason. A game that plays alone has no room, and nothing to continue.
+
+A [round's restart](/engine/structure/round/#in-a-room) mounts the room's scene again, which gives the scene's entities numbers a fresh room's mount does not, so a continue starts from the last checkpoint taken before the room's first restart and takes each restart again, as the room took it. A continue from a later checkpoint is refused with the reason.
+
+## Checking a continue comes back exactly
+
+A continue from any checkpoint taken before the room's first restart steps as the room stepped from it. Rapier's snapshot leaves out one piece of its state, the queue its broad phase reshapes its tree by a little each step, and a restore starts that queue empty. So the recording room, as it takes each checkpoint, writes its own physics world back from the snapshot it just took, as a continue does, and a continue that passes a later checkpoint does the same. Without it, the room's tree and the continue's grow apart some ten seconds on, and a later cast that meets two colliders at the same distance takes them in the other order.
+
+A checkpoint holds every trait, so a continue parts from the room only where the game keeps state outside the world: a count in a module's variable, a system's own closure, the wall clock, or `Math.random` in a system. [State a continue can carry](/engine/structure/systems/#state-a-continue-can-carry) says where each goes instead. `spawnite replay check latest` proves it for a game: it continues each room run the replay played in from its first checkpoint to its last action, sets every send and every checkpoint beside the room's, and exits 1 where one parts. `--run <session>` checks the room run of a session or a saved clip, by its name.
+
+On Holdfast it passes:
+
+```text
+Room run 20260927-131551-k8d4 of ./src/scenes/Holdfast.tsx: continued from step 213 to 4357, 69.07 s of play, in 0.7 s.
+  Exact: 1381 sends and 7 checkpoints, each as the room had it. A continue of any moment in it comes back as it was.
+```
+
+A system that counted its steps in a variable of its module and wrote the count into the world's `CoinScatter` fails it, and the check names the trait:
+
+```text
+Room run 20260927-132201-p1qz of ./src/scenes/Holdfast.tsx: continued from step 4022 to 5552, 25.50 s of play, in 0.7 s.
+  At the checkpoint at step 4200, the first that parts: entity 0 CoinScatter.seed: 4200 in the room, 178 in the continue.
+  State the checkpoint cannot see parts a continue from the room: a module's variable a system writes, a system's own closure, the wall clock, or Math.random in a system. Keep it in a trait, and draw from random(world).
+```
+
+That advice follows a trait the game owns. Where every difference is the engine's own state, the check points at the engine instead: the physics world as Rapier snapshots it, `blobs.physics`, which no game's code writes directly, a trait the engine registers or exports, such as `transform`, or the state of the engine's own checkpoint codec; a codec a game registers for its own trait, and the bytes it keeps, are the game's. So a codec's blob takes a name of its own: a checkpoint refuses one named as another codec's blob, or as one the engine keeps, such as `physics`, naming both codecs. The likely cause is then in what the engine's checkpoint keeps or a restore writes back, and the check says so. With `--json`, each such difference carries `engine: true`. An entity alive in one world and absent in the other names no owner, so a checkpoint that holds one keeps the game's advice.
+
+A room played with no browser records the same way. [`spawnite play room`](https://wiki.spawnite.com/platform/bots/) plays the game's own room with bots and names the run the room recorded, and `check --run` takes it:
+
+```text
+$ pnpm spawnite play room --project holdfast --seconds 40
+The room recorded run 20260927-174326-l4hl: spawnite replay state --run 20260927-174326-l4hl --at <m:ss> prints its world at a moment of play, and spawnite replay check --run 20260927-174326-l4hl checks that a continue of it comes back exactly.
+$ pnpm spawnite replay check --project holdfast --run 20260927-174326-l4hl
+Room run 20260927-174326-l4hl of ./src/scenes/Holdfast.tsx: continued from step 177 to 2559, 39.70 s of play, in 0.9 s.
+  Exact: 794 sends and 5 checkpoints, each as the room had it. A continue of any moment in it comes back as it was.
+```
+
+`log`, `state` and `export` take `--run` the same way, in place of a page's replay. With no page to name a moment, a moment of a run is its seconds of play, the room's steps over 60, or minutes and seconds as the run's table prints them, such as `14:25`: `spawnite replay state --run <run> --at 14:25 --trait monster` continues the checkpoint before that moment of play to it and prints the world, `spawnite replay log --run <run>` prints who joined and left and what each player said, such as `player 1 said ready`, at its seconds of play, with the moves, shots and sends counted, and `spawnite replay export --run <run> --around 14:25` writes the run's actions and its checkpoints from the one before the window.
+
+A run played with `--invulnerable` or another `--room-env`, by the room bots or by a profile, checks as any other does. The run's `room.json` keeps each setting that changes what the room does with an action: `invulnerable: true` where it spared every player's character, `maxPlayers`, `sendRate`, `allowEdits`, and `rejoinSeconds` where the room held every drop for one length; a room on the platform's two holds records none, and each recorded close notes `broken` where no close frame came. The continue takes each from there, whatever its own environment says, so a run played with `MAX_PLAYERS=1` refuses the second join again, even where the game's `room` settings name 4.
+
+The check runs the same continue as `rerun`, in a fresh process, so a module's state starts as it does there. A game's lint warns of the common cases as they are written: `Math.random` and a module's variable written in a function that takes the world. Factorio finds its own desyncs the same way, by loading a save and setting what it steps beside what the game stepped.
+
+## Reading the room's world at a moment
+
+`spawnite replay state latest --at m1` prints the room's whole world at the moment as JSON: every trait of every entity, filed by the key a dump files it under, with the room's own, such as Holdfast's monsters' `ClawsTrait` cooldowns, among them. `--entity <key...>` and `--trait <name...>` narrow it. The command continues the checkpoint before the moment to the moment, so it runs the game's room, and prints the world as the room held it:
+
+`spawnite replay state latest --at 22 --trait ClawsTrait` on a Holdfast replay, the monsters' cooldowns the stream never carries:
+
+```json
+{
+    "id": "20260927-131554-dfbf",
+    "at": 22000,
+    "step": 1398,
+    "entities": {
+        "17": { "Claws": { "cooldown": 0.2666666666666652 } },
+        "18": { "Claws": { "cooldown": 0.7833333333333327 } },
+        "19": { "Claws": { "cooldown": 0 } }
+    }
+}
+```
+
+A number keeps its full precision. A value JSON cannot hold is tagged with its type, such as `{ "$": "Vector3", "value": [1, 0, 2] }`. A trait no module exports and nothing registers is filed by koota's own number, such as `#75`, and the checkpoint keeps its fields, so a continue under changed code refuses it rather than writing it into another trait.
+
+## Every byte, as files
+
+`spawnite replay export latest --around m1 --out replay-m1` writes a replay, or a window of it, as files any tool reads, and names each:
+
+| File                                 | What it holds                                                                                                   |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `replay.json`                        | How it began, its marks, and what it continued.                                                                 |
+| `log.jsonl`                          | Its log and the room's changes, a line each: the time, the words, and the event's own fields.                   |
+| `records.jsonl`                      | Every record, decoded, a line each: `room` for a frame the room sent, `sent`, `frame`, `input`, `keyframe`.     |
+| `shots/`                             | Its screenshots.                                                                                                |
+| `rooms/<run>/room.json`              | How the room's run began, and the settings a continue of it takes: whether it spared every character, and more. |
+| `rooms/<run>/actions.jsonl`          | Every action the room took, a line each.                                                                        |
+| `rooms/<run>/checkpoint-<step>.json` | The room's whole world and its own state at the step.                                                           |
+| `rooms/<run>/physics-<step>.bin`     | Rapier's snapshot of the physics world then, which `World.restoreSnapshot` reads.                               |
+
+A script reads the same records itself: the engine's `./replay` export is the decoder. `readReplayRecords(folder, id, window)` yields each record decoded, `readRoomActions` a run's actions, `readRoomCheckpoint` a checkpoint with its blobs, and `readWorldLines` the room's changes. Each takes the game's `.replays` folder and a replay's or a run's name:
+
+```ts
+import { readReplayRecords, readRoomActions } from "@spawnite/engine/replay";
+
+for (const record of readReplayRecords(".replays", "20260927-131554-dfbf"))
+    if (record.kind === "sent") console.log(record.at, record.message);
+```
+
+## Marks and saved clips
+
+A mark is a tag, not a copy. It records its time, its name and one shot at the canvas's size, and protects its window, the two minutes before it to the thirty seconds after, from the trim: every minute of the session the window touches stays, the page's and the room's. Marks that overlap protect the same minutes once, so ten presses of F8 in one minute protect one window of four or five minutes and copy nothing.
+
+The minutes marks protect may fill half the budget, 150 MB unless the game sets another share. Past it, a new mark still tags the moment and keeps its shot, but protects nothing: the page's notice says so, the dev server's log warns, `spawnite play profile --dev` prints the warning among its notes, and `spawnite replay list` and `spawnite replay log` name the mark. An agent that investigates a moment names the page and the mark in its issue, and releases the mark when the issue closes:
+
+```sh
+spawnite replay release 20260927-183945-hqxe m1 m2
+spawnite replay release 20260927-183945-hqxe
+```
+
+With no mark named, `release` lets every mark of the page go.
+
+A moment an agent wants to keep for good, past any release and any trim, it saves. `save` copies the whole minutes a window touches into `.replays/saved/<name>`, with the room's checkpoints from the minute before to the minute after and the world as the first minute begins, so the clip plays back and continues after its session is gone:
+
+```sh
+spawnite replay save latest --around m1 --name boss-fight
+spawnite replay save latest --from 1180 --to 1260 --name minute-20
+```
+
+`--around` saves the window a mark protects. A saved clip is named like a session, so `spawnite replay play boss-fight`, `rerun boss-fight` and `log boss-fight` read it. The trim never reads the saved clips; the tools warn once they pass 200 MB together, and `spawnite replay remove saved/boss-fight` removes one. `remove` also removes a session whole, by its name.

package/dist/wiki/engine/testing/runs.md

@@ -0,0 +1,162 @@
+---
+title: Measuring runs
+description: "How an agent measures and tunes a room game with bots over many seeded runs from one command: what the scene's timeline records, what each run's table shows, and where each number comes from."
+useCases:
+    - test a game with bots
+    - balance a wave game
+    - measure economy and kills
+    - test different player counts
+    - tune a game over many seeded runs
+    - how long each wave lasts
+    - bot playtest table
+    - measure room cost and network
+sidebar:
+    order: 16
+---
+
+To tune a room game, you play it with bots over many runs and read what happened in each: the wave the run reached, how long each wave lasted, what the players earned and lost, and what each wave cost the room and the network. `spawnite play room` does this with one command and no page. It runs the game's own room once for each bot count and seed, and prints a table for each run and a table over the runs of each bot count.
+
+This page says how a scene declares what a run records, how to run the runs, how to read the tables, and where each number comes from. [Play the room with bots](https://wiki.spawnite.com/platform/bots/) says how the bots play.
+
+## Declare what a run records
+
+The scene's file exports a `timeline` beside its component, its `plugins` and its `bot`. The room reads each measure before its first step and after every step, and logs each change with the step it landed on. Holdfast's timeline, shortened:
+
+```ts
+import { createQuery } from "koota";
+import {
+    MeasureKind,
+    WalletTrait,
+    type SceneTimeline,
+} from "@spawnite/engine/core";
+import { LifeMachine } from "./life";
+import { PhaseTrait, readPhase } from "./phase";
+import { MonsterTrait, SiegeTrait } from "./traits";
+import { wardens } from "./wardens";
+
+const monsters = createQuery(MonsterTrait);
+
+export const timeline: SceneTimeline = {
+    measures: {
+        wave: {
+            kind: MeasureKind.Gauge,
+            read: (world) =>
+                world.queryFirst(SiegeTrait)?.get(SiegeTrait)?.wave ?? 0,
+        },
+        phase: {
+            kind: MeasureKind.Gauge,
+            read: (world) =>
+                readPhase(world.queryFirst(PhaseTrait)) ?? "waiting",
+        },
+        //  The wardens down now: a counter sums each rise, so each fall.
+        downs: {
+            kind: MeasureKind.Counter,
+            read: (world) =>
+                world
+                    .query(wardens)
+                    .filter((warden) => warden.has(LifeMachine.is.down)).length,
+        },
+        monsters: {
+            kind: MeasureKind.Gauge,
+            read: (world) => world.query(monsters).length,
+        },
+    },
+    parts: ["wave", "phase"],
+    over: (world) => {
+        const phase = readPhase(world.queryFirst(PhaseTrait));
+        return phase === "over" || phase === "dawn";
+    },
+};
+```
+
+A timeline holds the following:
+
+- `measures`: each measure by the name that heads its column. A measure reads the room's world and returns a value.
+    - A **counter** returns a number, such as kills or coins. The table shows how far it rose over each part, summing each rise, so a count that starts again at a new run still counts, and a level such as the wardens down counts each time it rose.
+    - A **gauge** returns a number, a word or a boolean, such as the wave, the phase or the monsters standing. The table shows its highest number, or its last word.
+- `parts`: the measures whose change starts a new part of the run. The table has a row for each part. Holdfast's parts are the wave and the phase, so each wave's fight and each breather are rows of their own. Left out, the run is one part.
+- `over`: whether the run is over, such as every player's character down or the last wave held. A run ends when it holds. Left out, a run lasts its `--seconds`.
+
+The room refuses a timeline of another shape as it loads the scene, naming what is wrong. A read runs after each of the room's steps, so keep it to a query and a sum. A read that throws closes the room, naming the measure, as a system that throws does. The reads change nothing, so a run the room recorded still [continues exactly](/engine/testing/replay/#checking-a-continue-comes-back-exactly).
+
+A measure the game does not keep, such as how long a monster lives, needs state of the game's own that a measure can read: for example a counter of damage dealt to each kind of monster beside a counter of kills of each kind, from which the mean damage to kill each kind follows.
+
+## Run the runs
+
+From the game's folder:
+
+```sh
+pnpm spawnite play room --bots 1-4 --seed 1-3 --speed 8
+```
+
+The command takes the following flags:
+
+- `--bots` takes a count, a list such as `1,2,4`, or a range such as `1-4`, from 1 to 12, and no more than the room holds, as the game's [`maxPlayers`](https://wiki.spawnite.com/platform/multiplayer/#set-the-rooms-players-and-send-rate) or `--room-env MAX_PLAYERS` sets it. Each count plays its own runs.
+- `--seed` takes a seed, a list or a range. Each seed is one run for each bot count, 12 runs above. The room's world draws its random numbers from the seed, so a run on one seed draws the same night each time. The bots' timing still varies from run to run, so two runs on one seed differ in their details. Without `--seed`, each command draws one seed and prints it.
+- `--speed` runs the room's clock that many times faster than the wall's, up to 16. The bots keep the room's time, so the game plays as it would at real time. Each run prints the speed the room kept up: a busy room runs slower than asked, and the numbers stay right, since every time and rate counts the game's own seconds.
+- `--seconds` caps a run's game time: 60 seconds by default, or 30 minutes when the scene's timeline says when a run is over.
+- `--invulnerable` spares every player's character, so a run plays to its last wave.
+- `--room-env NAME=VALUE` sets the room's environment over its `spawnite.room`'s, such as `SEND_RATE=30`.
+- `--room-heap <megabytes>` sets the room's V8 old space, 256 by default, the hosted room's 259 MB heap, so a game that keeps more memory every wave fails here with `JavaScript heap out of memory` as it would in production. A larger number raises it, and `none` lifts it. The run's output names the limit in force.
+- `--out <file>` keeps the runs in that file. Without it, they go to `spawnite/room-runs` in the system's temp folder, which keeps the newest 20. The file is written as each run ends, so a run that fails loses none before it.
+- `--heap-snapshot <when>` has each run's room write a heap snapshot, which Chrome's DevTools Memory panel loads: `exit` as the run ends and the room stops, or a share of the heap limit such as `0.6`, the first time a full collection leaves the heap past it. The snapshots go to `spawnite/heap-snapshots` in the system's temp folder, which keeps the newest 6, and the command prints each one's path. Writing one holds the room for as long as the write takes, 25 s for a 616 MB heap on a desktop, so use it to measure memory, never time.
+
+Each run starts a fresh room on its seed. The room holds its clock until every bot has joined, so the run starts with every player in it, and then runs at `--speed`. The room runs unwatched, so an edit to the game's files during a long pass does not restart it. `spawnite play room report <file>` prints a file of runs again, and `--json` carries every table as numbers.
+
+A room that exits during a run, such as one out of memory, stops the command with its exit code and the last 20 lines it printed, where V8's out-of-memory error sits.
+
+## Read the tables
+
+Each run prints what each bot did, then a row for each part:
+
+```text
+1 bot, seed 1: stopped after its 0:30 of play, at wave 2, phase fight (4.0× real time).
+  Bot 1, character 15: 603 moves, 38 shots, 34 hits for 304 damage, walked 153 m; sent siege.pick ×2, siege.ready ×4.
+  wave  phase     starts  lasts  kills  downs  coins  monsters peak  step ms  longest  B/s a page  peak B/s
+     0  waiting     0:00   0:05      0      0      0              0     0.48     9.63       1,634     3,124
+     0  breather    0:05   0:03      0      0      0              0     0.40     2.40       1,370     1,639
+     1  fight       0:08   0:11      5      0      2              1     0.36     9.99       1,812     2,885
+     1  breather    0:19   0:03      0      0      4              0     0.32     7.17       1,812     2,885
+     2  fight       0:22   0:08      4      0      0              1     0.29     7.73       1,942     2,175
+        run         0:00   0:30     10      0      6              1     0.36     9.99       1,770     3,124
+```
+
+A room whose heartbeat logs its heap and counts adds four columns, and the run's head line names its heap limit. Holdfast's room with two bots, its measure columns cut here:
+
+```text
+2 bots, seed 4: stopped after its 0:30 of play, at wave 1, phase fight (1.0× real time), on a heap limit of 4,288 MB.
+  wave  phase     starts  lasts  step ms  longest  B/s a page  peak B/s  heap MB  kept MB  entities  objects
+     0  waiting     0:00   0:05     0.78     9.96       2,916     9,164      178      111        20       15
+     0  breather    0:05   0:08     0.56     1.99       2,103     2,154      167      115        20       15
+     1  fight       0:13   0:17     0.73     2.89       3,560     4,568      170      115        27       15
+        run         0:00   0:30     0.69     9.96       3,063     9,164      178      115        27       15
+```
+
+Each row has the following columns:
+
+- The part measures' values, then `starts` and `lasts`: when the part started, from the run's start, and how long it lasted, in minutes and seconds of play.
+- Each other measure: a counter's rise over the part, or a gauge's highest, headed `peak`.
+- `step ms` and `longest`: the room's step, on average over the part and at its longest. A step runs 60 times a second, so a room holds real time while its mean stays under 16.7 ms, and a player feels a step past that as a stall. Both leave out the replay checkpoint a recording room takes every 600 steps, which a production room never takes, so they read as the game's own step: the room times each step without its checkpoint, so the longest is the longest step whichever step took the checkpoint.
+- `B/s a page` and `peak B/s`: the bytes each player's page received a second of play, on average and in the second that sent one page the most.
+- `heap MB` and `kept MB`: the most heap the room held in the part, and the most a full collection left it holding, which is what the room keeps. A kept heap that climbs from wave to wave is a leak; one that nears the heap limit on the run's head line is a room about to run out of memory. `--heap-snapshot` takes a snapshot to find what holds it.
+- `entities` and `objects`: the most entities the room's world held in the part, and the most objects in its headless scene, which no frame draws. A count that climbs from wave to wave, such as the objects of a view that adds one on each shot and removes it only on a frame, shows the leak before the heap does.
+
+The last row sums the whole run. To look inside a part, such as a wave that lasted far longer than the rest, read the run the room recorded at a moment of it, with no page: `spawnite replay state --run <run> --at 14:25 --trait monster` prints the room's world at 14:25 of play, and `spawnite replay log --run <run>` what its players did, as [the replay page](/engine/testing/replay/#checking-a-continue-comes-back-exactly) says. Where a bot count ran more than once, a table over its runs follows: how far its runs reached and how long they lasted, then each part's means over the runs that reached it, with a `runs` column that counts them.
+
+## Where the numbers come from
+
+The room logs one JSON line on each change of the timeline, a heartbeat for each second of play, and a heartbeat as each part ends, so no heartbeat spans two parts. The heartbeat names the room's step, the steps since the last heartbeat and their milliseconds, the bytes sent to its players since the last heartbeat, over all of them and the most to one, its heap now, after the last full collection and at its limit, and its entities and scene objects. A recording room also names its longest checkpoint since the last heartbeat, and the steps' milliseconds again with each step's checkpoint taken out, which the command reads in place of the logged ones. A log from a room built before it named them reads as logged, with the checkpoints in. The command prices each part from the heartbeats inside it.
+
+The bytes are the payloads of the frames the room sent: the snapshot on join, each delta, each acknowledgement and each word to one player. WebSocket's own framing, two to fourteen bytes a frame, is left out, as is voice, which does not travel over the socket. A page's rate is the heartbeat's total shared among its players, so the join's snapshot lifts the first part's rate.
+
+A step's time is the room's own, measured in the room's process. The bots run in a process of their own on the same machine, so a pass run beside other work reads slower steps than a room alone would.
+
+## Keep to a range of ports
+
+Every server a command starts, such as the dev server, the build's preview and the room, listens on a free port the system picks. To keep to a range, give `--ports 8960-8979`, and `--room-ports 4360-4379` for the rooms, to any command, or set `GAME_PORTS` and `GAME_ROOM_PORTS`. The command gives each server the first free port of the range that it has not already given another, and says so when every port is taken. A room the cli starts runs no voice, as every development room does, so it takes no UDP port and no media worker's CPU, and a profile measures the game without voice's cost.
+
+Every room the cli starts listens on this machine alone, `127.0.0.1`, the room's own default, so Windows' firewall never asks about it.
+
+## What the other engines do
+
+Unreal's CSV profiler records a game's own stats and events beside the engine's for each frame of a headless or dedicated server, and its report tool splits a run's summary at the events. Unreal's Gauntlet runs automated sessions with bots and collects their metrics. Godot's custom monitors are named functions the engine calls each frame. Unity's profiler counters and Roblox's server stats show the same live. The timeline takes Godot's shape, a named read of the game, and Unreal's split into parts. None of them prints a table of a game's outcomes over many seeded runs from one command, which is what an agent tuning a game reads.

package/dist/wiki/engine/testing/which-tool.md

@@ -0,0 +1,155 @@
+---
+title: Which tool
+description: The tool for each thing an agent checks in a game, in one table, with the page that explains it.
+useCases:
+    - which test tool to use
+    - how to test my game
+    - debug a multiplayer issue
+    - check performance of a game
+    - read view state without globals
+    - wait for a moment in the game
+    - take a screenshot of the game
+    - game testing checklist
+sidebar:
+    order: 1
+---
+
+Find what you want to do in the first column, and use the tool beside it. Each row links the page that explains the tool. Every `play` command runs as `pnpm spawnite play <command> --project <game>` inside this repository, and as `spawnite play <command>` in a creator's game. `pnpm spawnite <command> --help` prints each command's options.
+
+## Signs you are about to hand-roll a tool
+
+Stop and find the row here when you are about to write any of the following:
+
+- A global on `window`, such as `window.__rig = rig`, to read a view's state from outside.
+- A loop of `play step` and `play eval` that waits for a moment.
+- A delay, such as `sleep 3`, before a read or a screenshot.
+- A Playwright script against a game's page.
+- A `play eval` or an `--until` that imports the devtools store to stand the player somewhere or to turn the map camera on.
+- A script that renders or tiles pictures of a model, places a camera or a light round one, or sets a concept beside a render to judge it by eye.
+- A script that pulls a few fields out of a dump's JSON.
+- A click worked out by hand from the box `play see` prints.
+- An `afterEach` that destroys a test's worlds, or a loop of `stepWorld` in a test.
+- A `vi.stubGlobal("fetch", …)` in a test, with a `Response` built by hand.
+- A `mkdtempSync` in a test, with an `rmSync` in a hook to remove it.
+
+Each of these has a tool below. When no row fits, tell your user which check had no tool, so it can be asked for. In the platform's own repository, its tooling rule says where to write it down.
+
+## Run and step the game
+
+| You want to                                       | Use                                                                                                 | Page                                                                  |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Open the game in a browser you drive              | `play start`, and `play stop` when you finish                                                       | [The director](/engine/testing/director/)                             |
+| See which playtests run, and who started each     | `play list`, or the MCP's `list_playtests`                                                          | [The director](/engine/testing/director/)                             |
+| Read an error the engine made, by its code        | The code's page, `node_modules/@spawnite/engine/dist/wiki/engine/errors/<code>.md`                  | [Errors and bug reports](/engine/testing/errors/)                     |
+| Name the engine's minified frames in a stack      | `spawnite symbolicate <file>`                                                                       | [Errors and bug reports](/engine/testing/errors/)                     |
+| Report a failure inside the engine                | `spawnite bugreport [replay]`                                                                       | [Errors and bug reports](/engine/testing/errors/)                     |
+| Run a scene with no browser and no GPU            | `spawnite simulate`, or the MCP's `simulate`                                                        | [Devtools API](/engine/testing/headless/#sample)                      |
+| Step until something holds                        | `play step --until "<condition>"`, or `--seconds` and `--steps`                                     | [The director](/engine/testing/director/)                             |
+| Hold the game still, or let it run                | `play pause`, `play resume`                                                                         | [The director](/engine/testing/director/)                             |
+| Start a run, turn damage off, or call a wave      | `play actions`, then `play action "<name>"`                                                         | [Devtools API](/engine/testing/devtools/#playtest-actions)            |
+| Press, hold or let go of a key, or move the mouse | `play press`, `play hold`, `play release`, `play move`, `step --keys`                               | [The director](/engine/testing/director/#press-hold-release-and-move) |
+| Send a press with no key, or one with a payload   | `play press <plugin.key> --payload '{...}'`, `play hold <plugin.key> --value <n>`                   | [The director](/engine/testing/director/#press-what-a-game-declares)  |
+| Click a game's button or link by its name         | `send_input`'s `click` with its name                                                                | [The director](/engine/testing/director/#press-hold-release-and-move) |
+| Click an entity, such as an NPC to talk to        | `play press MouseLeft --on "<subject>"`, or `send_input`'s `click`                                  | [The director](/engine/testing/director/#press-hold-release-and-move) |
+| Start playing at a point of a map                 | `play from-here --at <x,z>`, `--map <name>` for another map's preview                               | [Devtools API](/engine/testing/editing/#the-context-menus-actions)    |
+| Play the game on a slow connection to its room    | `play start --latency 150 --jitter 20 --stall 500/10`, or the MCP's `start_playtest` with `latency` | [Multiplayer](https://wiki.spawnite.com/platform/multiplayer/#play-it-on-a-slow-connection)    |
+
+## Read the world
+
+| You want to                                                                  | Use                                                           | Page                                                                         |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Read every entity's traits                                                   | `play dump`, `--where` to filter                              | [Devtools API](/engine/testing/agent-state/#for-an-agent)                    |
+| Read only a few traits or fields                                             | `play dump --fields`, `simulate --fields`                     | [Devtools API](/engine/testing/agent-state/#for-an-agent)                    |
+| Change a trait's value, such as coins or where the character stands          | `play set <subject> <path> <value>`, or the MCP's `set_trait` | [Devtools API](/engine/testing/agent-state/#for-an-agent)                    |
+| Read what the player's camera sees                                           | `play see`                                                    | [The director](/engine/testing/director/#read-what-the-camera-sees)          |
+| Read where the crosshair points                                              | `play aim`                                                    | [The director](/engine/testing/director/#check-a-shot-against-the-crosshair) |
+| Read what each entity is and does, in words                                  | `play ai`                                                     | [Metadata](/engine/ai/metadata/)                                             |
+| Read a caster's ability range, cost, cooldown, target reach and last refusal | `play eval "views"`, under `abilities`                        | [Devtools API](/engine/testing/devtools/#abilities)                          |
+
+## Read what a view draws
+
+A view's state lives outside the world: the pose it chose, a fade it keeps in a ref, a clip's weight. Read it through `useInspect` and `play eval`, never through a global.
+
+| You want to                                             | Use                                                                              | Page                                                                                                  |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Read a view's own state                                 | `useInspect(name, read)` in the view, then `play eval "views..."` or `play dump` | [Devtools API](/engine/testing/agent-state/#a-views-own-state)                                        |
+| Read the three.js scene: a bone, a material, the camera | `play eval "three.scene..."`                                                     | [The director](/engine/testing/director/#run-a-check-of-your-own)                                     |
+| Follow a value frame by frame                           | `play step --sample "<expression>"`                                              | [The director](/engine/testing/director/#sample-a-value-over-time)                                    |
+| Run a check of your own on the page                     | `play eval "<expression>"`, or `--file` for a script                             | [The director](/engine/testing/director/#run-a-check-of-your-own)                                     |
+| Read the page's errors and warnings                     | `play console`                                                                   | [Devtools API](/engine/testing/devtools/#the-console)                                                 |
+| Find a prediction mistake on a page in a room           | `play state`, each kind's count and latest line, or `play console`               | [Networking](https://wiki.spawnite.com/platform/networking/debugging/#the-prediction-checks)                                   |
+| Check a predicted mechanic at a player's round trip     | `play start --latency 150 --jitter 20 --stall 500/10`, then `play state`         | [Build a predicted mechanic](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-6-check-it-against-a-room) |
+| Read the room's corrections of her character            | `play state`, on its `Room:` line, the last second's and since the page loaded   | [Networking](https://wiki.spawnite.com/platform/networking/debugging/)                                                         |
+| Read the room's lead, round trip and bytes over a span  | `play state --sample <seconds>`, `--every <ms>`, `--json` for each sample        | [Networking](https://wiki.spawnite.com/platform/networking/debugging/#read-the-reports-with-a-tool)                            |
+
+## See it
+
+| You want to                                                            | Use                                                                                                   | Page                                                                             |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Shoot what the player sees                                             | `play screenshot`, `--width` to keep the file small                                                   | [Devtools API](/engine/testing/agent-state/#for-an-agent)                        |
+| Shoot one entity or place from a chosen side                           | `play screenshot --around "<subject>" --angle <side>`, or `--view`                                    | [Devtools API](/engine/testing/agent-state/#for-an-agent)                        |
+| Shoot the moment something happens                                     | `play screenshot --until "<condition>"`, which reads `views` too                                      | [Devtools API](/engine/testing/agent-state/#a-views-own-state)                   |
+| See what a press does frame by frame, with its second                  | `play timeline <control>`, `--every` and `--seconds`, or the MCP's `timeline`                         | [The director](/engine/testing/director/#a-timeline-after-a-press)               |
+| See a clip's frames on the character, and read its release mark        | `play timeline --clip <name>`, or the MCP's `timeline` with `clip`                                    | [The director](/engine/testing/director/#a-timeline-after-a-press)               |
+| Record a clip of what the game drew, for marketing                     | The dev tools' Record, or F9; from a held session, `spawnite play record`, or the MCP's `record_clip` | [The director](/engine/testing/director/#record-a-video-clip)                    |
+| Read a recorded video clip: its sheet, events and stills               | `spawnite clip show <name>`, `--from` and `--to` in seconds, or the MCP's `read_clip`                 | [Dev server](/engine/testing/dev-server/#the-folder)                             |
+| Have a person scrub a clip to a mark's frame in a browser              | `/model?avatar=<name>&clip=<name>&marks=release:<s>` on the tools app                                 | [The model viewer](https://wiki.spawnite.com/design/model-viewer/#clips-on-an-avatar)                     |
+| Read a clip's motion in numbers: where the arms peak, each bone's turn | `spawnite model check <clip.vrma>`, or the MCP's `check_model`                                        | [Models](https://wiki.spawnite.com/learn/models/#turn-a-meshy-character-into-an-avatar)                   |
+| Check a change kept each shot's colour and quality                     | `play compare`, `--accept` to take a new set                                                          | [Performance on main](/engine/testing/performance/#check-what-a-game-looks-like) |
+| See a model's size, facing, clips and bones                            | `spawnite model check <files...>`, `--angle` once a view, `--clip <name> --at <s>,<s>`                | [Models](https://wiki.spawnite.com/learn/models/)                                                         |
+| Check a model against its concept, with the differences as numbers     | `spawnite model check <file> --reference front=<concept>`, `--style silhouette,outline`               | [Models](https://wiki.spawnite.com/learn/models/#check-a-model-against-its-concept)                       |
+| Find the frames where a clip puts a limb through the head or torso     | `spawnite model check <file> --clip <name>`, or the MCP's `check_model` with `clip`                   | [Models](https://wiki.spawnite.com/learn/models/#check-a-model-against-its-concept)                       |
+| See a model's edges, topology or vertices                              | `spawnite model check <file> --style outline,wireframe,vertices`                                      | [Models](https://wiki.spawnite.com/learn/models/#check-a-model-against-its-concept)                       |
+| Compare several models side by side                                    | `spawnite model check a.glb b.glb c.glb`                                                              | [Models](https://wiki.spawnite.com/learn/models/)                                                         |
+| Turn a Meshy character into a VRM avatar                               | `spawnite model avatar <file>`                                                                        | [Models](https://wiki.spawnite.com/learn/models/#turn-a-meshy-character-into-an-avatar)                   |
+| Turn a Meshy clip into a VRMA every avatar plays                       | `spawnite model clip <file> --clip <name>`                                                            | [Models](https://wiki.spawnite.com/learn/models/#turn-a-meshy-character-into-an-avatar)                   |
+| Check a downloaded sound for a constant hiss                           | `spawnite sound check <files...>`, or the MCP's `check_sound`                                         | [Assets](https://wiki.spawnite.com/platform/assets/#check-a-sound-for-hiss)                               |
+
+## Measure and replay
+
+| You want to                                           | Use                                                                                                | Page                                                                  |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Count draw calls, triangles and textures              | `play stats`                                                                                       | [Devtools API](/engine/testing/agent-state/#for-an-agent)             |
+| Find what a frame spends its time on, and its hitches | `play profile`                                                                                     | [One frame](/engine/testing/measuring/)                               |
+| Measure a frame under the map editor's camera         | `play profile --map-camera <zoom>`                                                                 | [One frame](/engine/testing/measuring/)                               |
+| See which files a page requested                      | `play profile --har <path>`, a HAR of every request, listed by URL                                 | [Finding hitches](/engine/testing/hitches/)                           |
+| Weigh what a page downloads before the game starts    | `spawnite build`, the game's own code and the engine's, gzipped                                    | [One frame](/engine/testing/frame/#what-loads-before-the-first-frame) |
+| Go back to a moment a player hit                      | `spawnite replay list`, then `play start --replay <page> --at <moment>`, and `play seek` within it | [Replay](/engine/testing/replay/#finding-a-moment)                    |
+| Play a room with bots and no browser                  | `play room`                                                                                        | [Runs](/engine/testing/runs/#run-the-runs)                            |
+| Find what a room's heap holds, or what grows in it    | `play room`, its heap columns, and `--heap-snapshot exit` or a share such as `0.6`                 | [Runs](/engine/testing/runs/#read-the-tables)                         |
+| Time one engine call over worlds of several sizes     | Vitest's [`bench`](https://vitest.dev/api/#bench) in a `.bench.ts` file, `vitest bench --run`      | [Testing](/engine/testing/which-tool/#pin-it-in-a-test)               |
+| Join several pages to a room                          | `play join`                                                                                        | [Joins](/engine/testing/joins/)                                       |
+
+## Pin it in a test
+
+A fact that should stay true after the next change goes in a test, not only a playtest. A behaviour test runs under vitest in the project's `test/` folder: the rules step headless, and a scene mounts in Node through the engine's headless mount, as [Devtools API](/engine/testing/headless/#sample) describes. A test of code that fetches stubs `fetch` with `stubFetch` from `@spawnite/testing/fetch`, as [Devtools API](/engine/testing/headless/#a-stubbed-fetch) shows. A test that renders the whole app in jsdom mocks fiber and drei with `fakeFiber` and `fakeDrei` from `@spawnite/testing/fiber`, as [A whole game in jsdom](/engine/testing/headless/#a-whole-game-in-jsdom) shows. A rule that holds for every input, such as a round trip, goes in a [property test](/engine/testing/headless/#property-tests), which draws the inputs for you. A test that writes files makes its folder with `makeTempDir` from `@spawnite/testing/temp`, as [Devtools API](/engine/testing/headless/#a-temp-folder) shows. A test that runs a command, such as the cli or `git`, runs it with `runProcess` from `@spawnite/testing/process`, as [Processes](/engine/testing/processes/#a-child-process-in-a-test) describes.
+
+Import `it` from `@spawnite/engine/testing` rather than from `vitest`, and name the fixture the case needs. Each fixture tears down what it made after the case, so a test writes no `afterEach`:
+
+| You want to                                   | Use                                                     |
+| --------------------------------------------- | ------------------------------------------------------- |
+| A world on the file's `plugins`, and its step | `({ world, step })`, then `step(n)` or `step(n, input)` |
+| A world on your plugins, or a second          | `({ createWorld })`, then `createWorld(plugins)`        |
+| A scene mounted headless                      | `({ scene })`, then `await scene(Arena)`                |
+| A headless game with the map's ground         | `({ createGame })`, then `await createGame({ scene })`  |
+
+The world is a dev world with Rapier loaded, as `createHeadlessGame` makes one, and each step is 1/60 s. A game adds its own fixtures with `it.extend("arena", async ({ world }) => spawnArena(world))`.
+
+### Leave nothing for the next file
+
+The engine's own suite and Holdfast's run without isolation: a worker runs one test file after another on the same modules, the same jsdom window and the same Koota worlds, which roughly halves the CPU a run spends outside the tests. A file therefore undoes what it changed before the next file starts:
+
+- Destroy each Koota world it makes, or take the world from a fixture above, which does. A process holds 16 worlds at most.
+- Unmount a React Three test renderer from `create` before you destroy its world. Testing Library's `render` unmounts on its own after each case.
+- Undo each change outside the file: `vi.unstubAllGlobals()` after `vi.stubGlobal`, `vi.useRealTimers()` after fake timers, the page's address after `history.replaceState`, a store's state after `setState`, and each registration through the disposer it returned.
+- Test a module's first state on a fresh copy: call `vi.resetModules()`, then import the module inside the case.
+
+Vitest restores `vi.spyOn` spies between files on its own. A file that calls `vi.mock`, `vi.doMock` or `vi.hoisted` still runs in a fresh worker of its own, because a module loaded under its mock would keep the mock for every later file; the project's vitest config finds those files by the call. A file that measures the heap or races a time limit goes in the config's quiet list, whose files run one at a time after the rest.
+
+Each run takes the files in a new random order and prints its seed at the top, such as `Running tests with seed "1790788700828"`. A file that fails in one order and passes in another reads what an earlier file left behind. Run the same order again with that seed:
+
+```sh
+pnpm --dir packages/engine exec vitest run --coverage.enabled=false --sequence.seed=1790788700828
+```
+
+One Playwright check per game proves the built bundle boots: `test/e2e/boot.spec.ts` calls `bootSmoke` from `@spawnite/testing/e2e`, which opens the page, waits for the canvas, runs the game's own steps, and fails on any error the page reports. The package's README shows the config and the spec.