@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,129 @@
+---
+title: Joining a room
+description: "How an agent joins players' pages to any room from one command, a room it started or one it did not, and reads what each page saw: welcomed, refused and why, or no answer."
+useCases:
+    - test that a second player can join
+    - room is full and refuses a player
+    - what a player sees when joining
+    - test multiplayer connection
+    - join a deployed room
+    - automated player join test
+    - check the welcome message
+    - measure join speed
+sidebar:
+    order: 18
+---
+
+A multiplayer game raises the same questions each time it changes: does a second player get in, what does a player see when the room turns them away, and does the game reach the room it is deployed beside. `spawnite play join` answers them with one command. It opens players' pages headless against a room, one after another, and prints what each saw of its join. The room can be one the command did not start, such as a room a teammate runs or a deployed one, or the game's own room, started fresh.
+
+This page says how to join pages to a room, how to read each page's outcome, and how to play the pages on once they are in. [Multiplayer](https://wiki.spawnite.com/platform/multiplayer/) says how a room runs, and [Measuring runs](/engine/testing/runs/) how to play a room with bots and no page.
+
+## Join pages to a room
+
+Give the room's WebSocket address, `ws://` or `wss://`, from the game's folder:
+
+```sh
+pnpm spawnite play join ws://localhost:4371 --pages 2
+```
+
+```text
+Joined 2 built pages to ws://localhost:4371:
+  Page 1: welcomed as character 18 in 9.2 s; build 95005bcc4f62. Now joined, 2 players; round trip 54.7 ms, 1,207 B/s, the room's step 0.32 ms.
+  Page 2: welcomed as character 19 in 5.8 s; build 95005bcc4f62. Now joined, 2 players; round trip 271.5 ms, 2,247 B/s, the room's step 0.72 ms.
+```
+
+Without an address, the command starts the game's own room on a free port, with the environment its `spawnite.room` sets, and ends it when it ends. That room logs a heartbeat each second and does not restart when a file changes, which would drop every page. `--room-env NAME=VALUE` sets its environment over those, such as `--room-env MAX_PLAYERS=2`. For its own room, the output also names the room's build, its last heartbeat, its peak memory and its [timeline](/engine/testing/runs/#declare-what-a-run-records) as it stood last.
+
+The command takes the following flags:
+
+- `--pages <n>` opens that many players' pages, 1 to 12, one by default. Each opens in a browser context of its own, so it keeps its own storage and joins as a player of its own. A page opens once the page before it was welcomed or refused, so the pages join in their numbered order.
+- `--join-seconds <n>` is how long each page has to be welcomed or refused: 90 by default, long enough for a dev server's first start.
+- `--dev` serves the game's dev server in place of its build, and `--url <url>` opens a page that is already served, such as the deployed game. [Choose the pages](#choose-the-pages) says which to use.
+- `--screenshot [file]` shoots every page as the command ends: to the file with each page's number after its name, such as `joined-1.png`, or under the game's `.spawnite/shots` without one.
+
+`--json` carries every page's outcome and its whole room, as the [engine's state](/engine/testing/agent-state/#the-engines-state) reads it.
+
+An agent without a shell calls the `spawnite` MCP's `join_room` tool, which runs the same join and returns the same lines. It takes the flags by their names in camel case, such as `pages`, `joinSeconds` and `roomEnv`, the room's address as `room`, each press as `{ key, at, until }` in `presses`, and `screenshot: true` for `--screenshot` with no file.
+
+## Read what each page saw
+
+Each page reads its own room through the engine, as a player's page records it, and the command prints one of three outcomes:
+
+- **Welcomed**: the room's welcome arrived and the page holds a character, named by the id the room's dump keys it under. A room of another build admits the page, and the line names the room's build beside the page's. The line adds what reaches the page as the command ends: the players it sees, the round trip, the bytes it receives a second and the room's step. The command waits up to three seconds after the pages play for each page's first round trip and rates, since a page publishes its rates once a second.
+- **Refused**: the room closed the page's socket with its word on why, and the line names the close code and reads its reason out. A full room closes with 4004 and says how full it is. A room from before the build warning closes a page of another build with 4006 and names both builds. Any other code prints its reason as the room sent it.
+- **No answer**: neither within `--join-seconds`. The line says where the page stood, such as still connecting, and the errors it threw or logged, such as a socket the room's address refused.
+
+Three Holdfast pages against the game's own room, capped at two players, where the two welcomed press ready:
+
+```sh
+pnpm spawnite play join --pages 3 --room-env MAX_PLAYERS=2 --press KeyR@0 --seconds 15 --screenshot .work/ready.png
+```
+
+```text
+Joined 3 built pages to ws://localhost:50486, the game's own room on build 95005bcc4f62:
+  Page 1: welcomed as character 18 in 7.0 s; build 95005bcc4f62. Now joined, 2 players; round trip 10.1 ms, 759 B/s, the room's step 0.31 ms. Shot to …/.work/ready-1.png.
+  Page 2: welcomed as character 19 in 3.6 s; build 95005bcc4f62. Now joined, 2 players; round trip 3.2 ms, 904 B/s, the room's step 0.35 ms. Shot to …/.work/ready-2.png.
+  Page 3: refused with close 4004 in 3.5 s: the room is full, 2 of 2 players. Shot to …/.work/ready-3.png.
+Pressed KeyR at 0 s on each welcomed page, playing 15.0 s after the joins.
+The room's last heartbeat: 2 players, 389 MB, a step 0.87 ms on average and 1.66 ms at the longest; 391 MB at its peak.
+Its timeline: wave 1, phase fight, kills 0, downs 0, coins 0, monsters 2, earned 0, spent 0, rerolls 0, guns 0, upgrades 0, cards 0, fed 0, fire 0, chainShocks 0, blasts 0, steamClouds 0, ownReactions 0, linePoints 0, capstones 0.
+```
+
+The two wardens pressed ready, and the timeline shows the first wave's fight; the third page's shot shows the loading screen's "The room is full: 2 of 2 players."
+
+A player who drops keeps her character, and her seat, for 60 seconds, as [When a player drops](https://wiki.spawnite.com/platform/connections/#when-a-player-drops) says. So a second command against a room that stays up counts the first command's players until their minute is over.
+
+## Choose the pages
+
+A built page names its build as it joins, and a room of another build admits it with a note naming both, as [A page and a room of another build](https://wiki.spawnite.com/platform/connections/#a-page-and-a-room-of-another-build) says. The command serves the game's build by default, with its own Vite's `vite preview`, so it shows what a player's page does. It serves the build as it stands: build the game first with its own build script, such as `pnpm nx build <game>` or `npm run build`. A build from before an edit reads as another build to a room started after it:
+
+```text
+Joined 2 built pages to ws://localhost:4371:
+  Page 1: welcomed as character 20 in 5.9 s; build 7c635a71e8e2, and the room runs another build, 95005bcc4f62. Now joined, 4 players; round trip 113.2 ms, 1,511 B/s, the room's step 0.41 ms.
+  Page 2: welcomed as character 21 in 5.2 s; build 7c635a71e8e2, and the room runs another build, 95005bcc4f62. Now joined, 4 players; round trip 282.4 ms, 3,443 B/s, the room's step 0.82 ms.
+```
+
+Against the game's own room, the output adds that the build served is not the tree the room runs.
+
+`--dev` serves the dev server's page, which names no build, so a room of any build admits it. Use it to check a change without a build, and not to check the build. `--url` opens a page that is already served, such as the deployed game at its own address, with the room's address in its `room` parameter; the page must be one whose engine exposes its room, as every engine from this one on does.
+
+## Play the joined pages
+
+Once every page has its outcome, the command can play the welcomed pages on and read them again:
+
+- `--press <control@seconds>` presses a control on each welcomed page, in seconds from the last page's outcome: `control@seconds` taps it and `control@from-to` holds it, such as `KeyR@0` or `MouseLeft@1-2`. The controls are the ones [Name a control](/engine/testing/director/#name-a-control) lists.
+- `--seconds <s>` plays the pages that long before the command reads them.
+- `--until <expression>` plays until the expression holds on each welcomed page, within `--until-seconds`, 120 by default, and the command exits 1 when it did not. The expression reads the page's globals, `document` among them, and the engine's `camera`, `loop`, `cursor` and `room`, such as `room.players === 2`.
+
+The pages play live: nothing holds the room, as [`spawnite play start`](/engine/testing/directing/) holds its own. [Read what each page saw](#read-what-each-page-saw) shows the two Holdfast wardens readying up with `--press KeyR@0` and the first wave starting.
+
+## Join a room the backend runs
+
+A room the backend runs, such as a production room on a machine, seats only a player the platform sends: the app takes a seat through the backend's `rooms.join` and hands the page its ticket, and the room checks the ticket with the backend. A page opened on its own sends no ticket, and the room refuses it with 4007, "This room seats players the platform sends." `--seat [game]` takes the seat the way the app does, so the command checks such a room end to end. The game is its id, a link to its page, or, with no value, the one the game folder's `package.json` names by its id, which `spawnite games create` writes:
+
+```sh
+SPAWNITE_CONVEX_URL=https://api.spawnite.com pnpm spawnite play join --seat 22699540 --url "https://22699540.$PLAY_DOMAIN/"
+```
+
+`PLAY_DOMAIN` is the play domain that [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#where-a-game-runs) names.
+
+The first line names the seat, and the game version and engine release its room runs. An Arena room on this machine that checks its tickets with a backend, joined from the game's folder with `--seat --dev`, reads:
+
+```text
+Took a seat in a room of game 48201973 through the backend's join, as player 0f3a9c2b: the room runs version 0.
+Joined 1 dev server page to ws://localhost:47401; a dev server's page names no build, so a room admits it whatever build it runs:
+  Page 1: welcomed as character 19 in 3.3 s; no build, as a dev server's page. Now joined, 1 player; round trip 2.1 ms, 1,098 B/s, the room's step 0.21 ms.
+```
+
+The same page without `--seat` reads `refused with close 4007, "This room seats players the platform sends. Open the game from its page."`
+
+The command signs in as `spawnite login` signed this machine in, calls `rooms.join` with the game's id, and waits for a room that is starting to open. It joins the room at the address join answered, and adds the ticket to the page's join message as it leaves the browser, as the app's `init` hands it to the engine. The ticket goes to that address alone, so the command takes no room address beside `--seat`: a ticket sent to another host could be replayed at the seat's room. The room seats the page under the account's name and its id in the game, and `--json` carries the seat as `seat`.
+
+- `SPAWNITE_CONVEX_URL` names the backend, production's API address here; without it, a run from this repository's checkout uses the dev deployment, and a cli installed from npm uses production. A login belongs to one backend's sign-in, so sign in against production first, with the same variable on `spawnite login`, and keep that login apart with `SPAWNITE_CONFIG_DIR`.
+- The page is the one `--url` opens, such as the game's own address, which serves the published version, the one Play seats new players on; or, from a game's folder, its build or dev server. A room of another build admits a built page with a note naming both.
+- One page: an account holds one seat in a game, so a second page would move the first page's seat, and its room would close the first page with 4008.
+- Join is a real player's join. It counts toward the account's seats and room starts, and it starts a room when none has a seat.
+
+## What the other engines do
+
+Roblox Studio's local server test starts a server and a number of player clients from one button. Unity's Multiplayer Play Mode runs up to four virtual players beside the editor. Unreal's Play In Editor takes a number of players and a net mode, and a client can connect to a server it did not start. Godot runs several instances of the game at once. Each opens windows for a person to watch. `spawnite play join` takes the same shape, a number of clients against a server started here or elsewhere, and reports each client's join as text and JSON, so an agent reads the answer rather than a window.

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

@@ -0,0 +1,97 @@
+---
+title: Measuring a frame
+description: The frame bench, the devtools' frame split, a profile of the built game in the browser, and checking a game's counts.
+useCases:
+    - measure game performance
+    - profile the built game
+    - frame time per system
+    - check how many entities spawn
+    - benchmark the frame loop
+    - compare performance before and after a change
+sidebar:
+    order: 13.1
+---
+
+[Frame](/engine/testing/frame/) describes what one frame runs and what each line cost when it was measured. This page describes how to measure it again.
+
+`pnpm nx bench @spawnite/engine` runs the frame bench in `packages/engine/test/components/bench.test.ts` beside the physics bench and prints the Node table. The bench lists the loop's lines by hand, in the loop's order: add a line to the loop, add it to the bench, and it shows as a number on the next run.
+
+In the browser, the devtools overlay splits every frame while it is mounted: the step, the pose and animation, the transforms and camera, the render and the rest on the CPU, and the GPU's time where the browser has a timer query, each by its mean and its worst over the last 60 frames. The top bar shows the CPU's and the GPU's means, the Frame tab every line, and an agent reads `frameSplit` off the store; [the devtools page](/engine/testing/devtools/#the-frame-split) says what each line holds.
+
+Inside the step, the profile times each system with no bench to write. `spawnite simulate --profile` prints each system's mean and worst milliseconds per step over the last 60 steps, slowest first, with `recordPreviousTransforms` among them; `--json` carries them as `profile`. The MCP's `simulate` tool takes `profile` and replies with the same lines under the hash. In the browser, the devtools store's `setProfiling(true)` times the running world, and `readProfile()` reads the same lines. A page opened with `?profile` times its step from the start, a production build too, and `spawnite play profile` opens the build that way and prints the same lines after the frame's, as `profile` under `--json`. The page's clock reads in steps of 0.1 ms, so a system under that reads as a mean of a few hundredths and a worst of 0.1 or 0. Headless, a world with the `StepProfileTrait` trait is timed, and `readStepProfile(world)` reads it. While profiling is off, the step reads no clock.
+
+The browser numbers come from a CPU profile of the built app. Build the game without minification and with a source map, so the profile's function names and positions map back to the engine's files, then profile it:
+
+```sh
+pnpm nx build @spawnite/mmorpg --minify=false --sourcemap=true
+pnpm spawnite play profile --project mmorpg --seconds 20
+```
+
+The command serves the build with `vite preview` and opens it in a headless Chromium at 1920x1080, so nothing shows on the desktop; `--headed` plays it fullscreen on the screen at the display's own rate instead, and `--window` places a visible window. With either, `--person` hands the page to a person at the window: nothing drives it, the page takes the pointer as a player's browser does, and the recording starts as the loading screen lifts, as a capture of a person's own play, as [Capturing your own play](/engine/testing/hitches/#capturing-your-own-play) says. The result's renderer names the GPU the run got. Once the loading screen has gone, it plays 20 s as a player does: it walks, jumps, strafes and drags the camera round. The first 7 s of the same walk run before the recording, so every clip's shader has compiled by then. V8 samples the main thread every 100 µs while it plays. The table sums each sample into its function and every function above it, counting a function once per stack, and divides by the frames `requestAnimationFrame` counted over the same span. Each function is named by the source file and line its source map gives, so an anonymous one, such as the Frameloop's callback, still has a name. `--url` profiles a page that is already served, and `--json` prints the same numbers as fields. The MCP's `profile_game` tool takes the same options, `functions` for each `--function` and `queries` for each `--query`, apart from `--probe`, `--check` and the visible windows of `--headed` and `--window`, and returns the same fields as JSON; with `repeat` or several queries it runs the sweep, at most 10 rounds of 5 queries, and returns its JSON, and a run that fails names the folder that holds the runs before it. A game that throws while it plays fails the run, and the command prints the page's errors in place of numbers that would time a stopped game.
+
+Adding two lines that nest counts the inner one twice: `measureEscape` calls `closestPointToPoint`, and three-mesh-bvh's `closestPointToPoint` and Rapier's `computeColliderMovement` each wrap a function of the same name.
+
+The command also times each frame and counts what it draws. The following options change what it reads:
+
+- `--budget <ms>`, 7.5 by default, is the frame's budget, and `framesOver` counts the frames that took longer. `frameMs` spreads each frame's time, from one `requestAnimationFrame` to the next, as p50, p95, p99, worst and mean; `mainThreadMs` spreads the main thread's, from the frame's first callback to the end of its task.
+- `--no-vsync` launches Chromium with `--disable-frame-rate-limit --disable-gpu-vsync`, so a frame's time is its cost rather than the display's period.
+- `--fps <n>` paces the page's frame callbacks to a rate, each at the first display tick past its 1/n s, as the check's pinned run does. Beside `--no-vsync` the ticks come as fast as the machine allows, so `--no-vsync --fps 120` gives a frame that fits in 8.33 ms the rest of its period, as a 120 Hz display does. A frame that does not fit runs late rather than waiting for the next tick, as a display would make it, so a slow page reads a higher rate than a display would show. The output says `paced to 120 fps`. Every frame of a paced run takes about 8.33 ms, so `--budget 12.5`, one and a half periods as the check's pinned run takes, counts the long frames. It undercounts the ticks a display would miss: a page that takes 10 ms every frame paces to 100 fps with no frame over 12.5 ms, where a display would show 60. A headless Chromium with vsync on runs at the machine's own display's rate where it has one, 120 Hz on a 120 Hz screen, and a frame that misses a tick there reads 16.7 ms as on the screen, so on such a machine vsync on with no `--fps` reads a 120 Hz frame closest. `--trace` refuses `--no-vsync --fps`: the pacing waits through hundreds of native frames a second, each of which the trace records, and the page slows to about half its rate.
+- `--gpu` times each frame's GL work with `EXT_disjoint_timer_query_webgl2` into `gpuMs`. With vsync on, the query spans the wait for the display, so the command reads GPU time only with `--no-vsync` and says so otherwise.
+- `--gpu-passes` times each pass of the GPU's frame into `gpuPasses`: the sun's shadow map, the scene, its resolve out of the multisampled buffer, ambient occlusion with its transparency targets and composite, bloom, the merged effects and the copy to the canvas, each by its own time and its share of the frame, the costliest first. A page opened with `?profile` names its passes, since only the engine knows which pass is which; a pass inside another, such as the shadow map inside the scene's render, reads apart from it, as `scene › shadow map`, and each frame's passes sum to its time. The timer query runs one at a time, so the recorder ends one at every pass's start and end and begins the next, as Chromium's own GPU timing does. It does this on every other frame, and times the frames between as one query into `gpuMs`, as `--gpu` does. Where the GPU is the limit the two agree: Holdfast with four wardens at 3440x1440 read 4.84 ms a frame either way. Where the CPU is, they part, since a query measures the GPU's clock from its start to its end, idle time while the CPU feeds it included, and on Chrome's Direct3D backend each query's end sends the commands queued so far, which keeps the GPU fed: the same game at 1920x1080 read 3.30 ms split against 3.98 whole. Read the passes for where the time goes, and `gpuMs` against an older run's. Another timer on the page, such as the devtools overlay's, takes the context from the split; on a page opened with `?profile` the engine's overlay leaves it to the profile. The browser's resolve of the canvas's own samples and its compositing of the canvas run outside the page's queries. The MCP's `profile_game` takes it as `gpuPasses`.
+- `--scene <name>` opens the game on one of its registered scenes in place of its start scene, such as the bench page's `dusk`, through the address's `?scene=`, which the engine reads on a page opened with `?profile` alone. The MCP's `profile_game` takes it as `scene`.
+- `--render` counts each frame's WebGL2 calls into `gl`, each counter's mean, min and max: the draws, triangles and instances to the screen and into render targets such as the shadow map, the program switches and links, the programs the frame used, and the texture uploads and the buffer uploads apart. A `WEBGL_multi_draw` call, as a `BatchedMesh` makes, counts as one draw of all its ranges. The multi-draw calls and the ranges they hold, their sub-draws, are also counted apart, per pass, because ANGLE's Direct3D 11 backend likely runs each sub-draw as a draw of its own. Only the game's context is counted: the first WebGL2 context the page makes, which the GPU timer times too.
+- `--skip <class>` drops one class of draw: `rt`, `rtinstanced`, `instanced`, `skinned`, `rtskinned` or `sky`. What those draws cost is the frame time's difference from a run that draws them.
+- `--probe` lists the first recorded frame's draws into `probe`, in the order the frame drew them, folded by pass, program, what the program draws, vertex count and instances, with how many draws each holds. A program is numbered in the order the page first used it, and it draws `skinned` or `sky` where its uniforms say so. A multi-draw call is one entry, with its ranges' vertices summed and its sub-draws. Each entry names the three.js objects it folds, each once, by the path of named ancestors down to the object, or by its type where nothing on the path has a name, and their materials by name, or by type where the name is empty. An `Entity` names its group after its `name` and an `InstancedModel` after its model, so a draw reads as `Rider`, `sling-post` or `Rock/tripo_node_…`. A draw three.js did not issue carries no name. The names come from three.js's devtools hook, which the page defines only under `--probe`, so a run without it draws as it would anyway.
+- `--alloc` samples the heap's allocations into `allocations`, the objects a collection freed too, since those are the frame's garbage. `allocations.top` lists the bytes a frame by call site, a function and up to three callers, each named through the source map. The recorder's own allocations are left out. V8's sampler never sees the backing store of a typed array or an `ArrayBuffer`, which lives outside its heap, so the recorder counts the bytes of each one the page makes while recording and lists them as the site `typed arrays' backing stores`. A view on a buffer that already exists makes no backing store and counts nothing.
+- `--trace` records a Chromium trace and reads it between the marks it sets as the recording starts and stops, into `trace`: the page's minor and major collections, its paints and its raster tasks, and each task past 4 ms on the GPU process's main thread as `gpuStalls`, by what it ran, WebGL commands, the page's raster or the compositor's paint, and whether it ran on the CPU or waited. A worker's collection holds no frame up, so it is not counted. The output prints the paints and the raster a second, and the timeline names each GPU-process task on the hitch it held back, as [Finding hitches](/engine/testing/hitches/) says. A trace too long for one string, past about a minute with these categories, is read a line at a time.
+- `--quality <level>`, one of `auto`, `minimum`, `low`, `medium` or `high`, plays at that quality level in place of the one the game picks, through the address's [`?quality=`](/engine/structure/saves/).
+- `--scale <n>` sets the headless page's device scale, so its drawing buffer is `n` times the page's size on each side. A retina laptop draws at 2, and a frame bound by its pixels costs more than twice as much there. A visible window draws at its screen's own scale, so `--headed` and `--window` refuse it.
+- `--viewport <width>x<height>` sets the headless page's size in CSS pixels, 1920x1080 when left out, such as `3440x1440` for an ultrawide screen at its own size. The MCP's `profile_game` takes it as `viewport: { width, height }`. A visible window takes its screen's size, so `--headed` and `--window` refuse it.
+- `--no-jump` plays the walk without its Space, for a game where Space does more than jump. In the sled, Space fires the sling, so a run without it measures the rider held on the sling.
+- `--until <expression>` keeps playing the walk after its first 7 s until a JavaScript expression holds in the page, then records, so a run measures a point later in the game, such as `document.body.innerText.includes('Finish!')`. The build mounts no devtools, so the expression reads what the page shows or exposes on `window`, and the engine's own [`camera`, `loop`, `cursor` and `room`](/engine/testing/agent-state/#the-engines-state), such as `camera.turned > 90` once the walk has turned the camera a quarter. It fails when the expression does not hold within two minutes.
+- `--map-camera <zoom>` records under the map editor's top-down camera, flown out over the map to that zoom of the whole map's frame, as a screenshot's `--zoom` reads one: 3 is where the map camera's own flight lands, the far stop a creator reaches, and 6 stands twice as close. It serves the dev page, since the map camera is the devtools' and the build mounts none, turns edit mode on and records once the flight has landed. Nobody plays unless `--drive` says so, since the walk's keys pan the map. The MCP's `profile_game` takes it as `mapCamera`. `--map-camera 3 --drive idle --render --gpu --no-vsync --no-cpu` prices what a creator's view of the whole map costs, such as the scatter's far fade.
+- `--function <name>` times one function a call, and takes another `--function` for each more. A path on the page's `window`, such as `createImageBitmap` or `Worker.prototype.postMessage`, is wrapped before the page's own scripts run, or as the recording starts where the page defines it later, and each call's synchronous part is timed while the recording runs: the calls, the milliseconds a frame, and a call's p50, p95, worst and mean, into `timedFunctions`. Any other name, such as a function inside the game's bundle, is read from V8's sampler over the whole profile, not only the table's top 40, one entry for each script that holds a function of that name, with its calls counted by V8's precise coverage, which slows the page's JavaScript a little: the milliseconds a frame and a call's mean. A name that neither reaches is named in the notes.
+- `--keep-profile [folder]` keeps the browser's profile between runs, in the folder given or in one for the game under the temp folder's `spawnite/profile/browsers`; the MCP's `profile_game` takes it as `keepProfile`. Without it every run plays on a fresh profile, a first visit, and the first line says which it was. The two differ by Chrome's disk caches of compiled shader programs: Skia's for the page's HTML and CSS, and ANGLE's for its WebGL. A first visit compiles each program the first time its effect or material appears, on the GPU process's thread, which holds the next frames back; a return visit, a second run on the same kept profile, loads them from the cache. A returning player's browser is a return visit, and every new player's first session is a first visit, so a number states which it came from, beside the machine's load and the frame clock: on Holdfast, a first visit created 7 of Skia's programs after the loading screen lifted, each a GPU-process task of 10 ms or more, and the same profile's return visit created none.
+- `--no-cpu` leaves the sampler off. The sampler slows every frame, so a run that reads the frame times against the budget passes it.
+
+The machine's other work moves every number. Run one configuration three times and read the spread before reading a difference.
+
+`--repeat <n>` runs that for you. Give `--query` once for each configuration of the page, and the command runs each in turn, round after round, so the machine's drift over the sweep falls on every configuration alike. Each configuration keeps its runs in a folder of its own under `--out`, named for its parameters, such as `replay=off/1.json`, and an empty `--query ""` adds none and keeps its runs in `no-query`. Without `--out`, the sweep goes to a new folder under the temp folder's `spawnite/profile/sweeps`, which keeps the newest 20. The command then sets each configuration beside the first, as `profile compare` sets two folders, or prints one configuration's runs as a series. Each run prints its phases on stderr as it goes, such as `Profile run 3 of 4, replay=off, round 2: recording 20 s`, and a line as it ends. A setting that a query parameter reaches is then priced with no source edited between runs:
+
+```sh
+pnpm spawnite play profile --project holdfast --dev --drive bot --invulnerable --seconds 60 --query "" --query replay=off --repeat 3 --out runs/replay
+```
+
+[Performance on main](/engine/testing/performance/) says where each game's frame time on `main` is recorded.
+
+## Checking a game's counts
+
+The machine's other work moves the timings by about 20%, but it does not move the counts, so the check fails on counts and only prints timings. Each game commits the counts its frame makes in `test/profile-baseline.json`. `pnpm nx run-many -t perf -p @spawnite/<game>` builds each game and runs `spawnite play profile --check` in its folder, and `pnpm nx run-many -t perf --parallel=1` checks every game. One check profiles at a time on a machine: a check holds `check.lock`, which names its pid, in the profile folder under the system's temp folder, while it runs. A second check prints once that it waits and for which pid, and gives up after ten minutes, naming the pid. A lock whose pid is gone is removed. An app whose game is one of its routes names that route as `spawnite.page` in its `package.json`, as the tools app names `/bench`, and the check, `play profile` and `play start` open it there. A game whose `spawnite.room` has the mode `always`, such as the arena, plays in a fresh room of its own: the profile starts the game's room on a free port and names it in the page's `room` parameter, so the frame never depends on whatever else answers on the target's port. The check profiles the build three times in one configuration, at the `high` quality level with the sampler off:
+
+1. Vsync on, with `--render` and `--alloc`: the counts and the garbage, at the display's rate, or at the rate the baseline pins. The run is traced too and reads the page's HTML counts, `paintsPerSecond` and `rasterTasksPerSecond`: a HUD that changes every frame paints every frame, and its raster runs on the GPU process's thread beside the page's WebGL, as [Frame pacing](/engine/testing/frame/#frame-pacing) says.
+2. Vsync off, with `--gpu`: the GPU's time.
+3. A still camera, with `--drive idle --render` for 5 s: the uploads a frame makes while nothing moves.
+
+It prints the runs' timings and each count beside its baseline, and exits 1 when a count rose past it. When a count rose, it also prints the first-parent merges since the previous row on the same machine in `test/profile-history.jsonl` that touch the game's folder, `packages/engine` or `packages/assets`, one line each as `git log --first-parent --oneline` prints them, or says that the history holds no row for this machine or that git cannot read the row's commit, as in a shallow clone. A count is its highest frame over the walk, because the walk's timing moves a count's mean between runs and not its highest frame. The check reads the programs a frame uses rather than its program switches: the order a page's models load in sets the order three.js draws their materials, which moves the switches from one run of a build to the next, 13 or 16 in the example's, and not the programs. Four kinds of count may rise a little. The garbage a frame makes may rise by a tenth, because V8 samples it and runs of one build spread by up to 4%. The triangles and the instances of each pass may rise by 3%, because the scatter culls each instance, so the busiest frame's view moves with the walk's timing. The HTML counts may rise by a fifth, two a second at least, because a panel that changes on an event, such as a wave's banner, lands in the walk's seconds as its timing moves, where a panel that changes every frame adds a paint a frame. A count that only one side holds fails too.
+
+The walk moves the camera every frame, so work a frame redoes while nothing moves, such as the scatter culling and uploading its instances again, hides under the walk's own. The still camera's counts are each upload counter's busiest frame, `stillBufferUploads` and `stillTextureUploads`, so an upload that fires only now and then while nothing moves, such as once a second, still counts. The check always records the still camera, so a baseline without these counts fails until `--update-baseline` writes it again. When a walk's count rises, the check walks once more and keeps each count's lower reading, so a one-off frame, such as a model compiled late, does not fail it and a rise that repeats does. The still camera records once, after the page loads and its loading screen lifts, with no warm-up, so an upload in any of its frames counts.
+
+The check also keeps the timings, one row per run of the check in `test/profile-history.jsonl` beside the baseline, and [Performance on main](/engine/testing/performance/) says what a row holds. Other sessions' load moves the timings, so the check times a fixed spin of arithmetic before and after its runs and prints both, as `Spin: 232 ms before the runs, 240 ms after.` The median of the spins already in the history on the same CPU is the machine's floor, so one lucky spin moves nothing. A spin more than 15% over the floor, before or after, prints `Under load` and appends no row. No timing is corrected by the spin. The check also prints each run's timings beside the previous row's on the same machine, for information only. Every run counts a frame over 6.94 ms, the platform's frame budget, except a run pinned to 60 fps: its frames all take a sixtieth of a second, so it prints the frames that missed the pin and its main-thread milliseconds instead. When the pinned run held under 95% of its rate, the garbage per frame reads high for the rate's sake, so the check prints `garbageBytesPerFrame` as inconclusive and leaves it out of the comparison.
+
+When a change adds draws on purpose, `spawnite play profile --update-baseline` writes the baseline, and the pull request says why. `--update-baseline=stillBufferUploads,stillTextureUploads` rewrites only the counts it names and leaves the rest of the file as it is; a name the baseline does not hold is an error that lists the names it does. A baseline written with no `fps` gets `"fps": 60`, and its runs are pinned to that rate. It takes each count's highest over three runs of the counts, because a camera that follows a steered character, as the sled's does, reaches its busiest view at a different moment each run. The check and `--update-baseline` both draw a headless page at 1920 by 1080, whatever the machine's display, so every machine sees the same view of the world.
+
+To find the commit that raised a count, check out each commit in turn and build it with `--skip-nx-cache`, as `pnpm nx run-many -t perf -p @spawnite/<game> --skip-nx-cache` does. A cached build can keep another commit's `dist`: when the cache index every worktree shares names an entry whose stored files are gone, Nx reports a hit and restores nothing, then reports `existing outputs match the cache, left as is` on every later run, so two commits read the same counts.
+
+A frame's garbage is part per frame and part per second, so it depends on the display's rate: the sled makes 37,000 bytes a frame at 144 Hz and 57,000 at 60 Hz. A baseline that sets `"fps": 60` pins the counts run to 60 frames a second on any display at least that fast, each frame at the first vsync tick past its sixtieth of a second, so a 120 Hz machine reads the counts a 144 Hz one wrote. The arena, the example, the mmorpg and the sled set it. A display slower than the pinned rate runs at its own, and a machine too loaded to hold the rate drops frames: either way the garbage reads high, and the check prints a warning, and the garbage as inconclusive, when the counts run held under 95% of the pinned rate.
+
+A baseline sets `"jump": false` for a game whose check walks without jumps, and `--update-baseline` writes it back. The sled sets it: with Space, its walk fires the sling, runs out of steam, plays again and fires again, about every 10 s, and a run that reaches the finish loads the next track inside the recording. Without Space, the rider stays on the sling, the level's busiest view, for the whole run.
+
+A baseline can also cap a count under `caps`: a value the count may never read past, whatever the baseline beside it says. The tenth the garbage may rise lets it creep, because each rewrite of the baseline raises the next check's allowance with it. A cap does not move. The check fails a count past its cap, and `--update-baseline` writes no baseline while a count reads past one, so a cap moves only by hand, with the reason in the pull request. A cap on a count neither side holds fails, as a count only one side holds does. The arena caps the garbage its frame makes in a room:
+
+```json
+{
+    "garbageBytesPerFrame": 119915,
+    "fps": 60,
+    "caps": { "garbageBytesPerFrame": 132000 }
+}
+```

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

@@ -0,0 +1,48 @@
+---
+title: Performance on main
+description: Where each game's frame time on main is recorded, and what the record holds.
+useCases:
+    - measure game frame time
+    - hit 144 fps
+    - game too slow
+    - performance history of a game
+    - frame time regression
+    - frame budget
+    - profile game speed
+    - check performance on main
+sidebar:
+    order: 15
+---
+
+Each game records its performance in `test/profile-history.jsonl`, beside its [count baseline](/engine/testing/measuring/#checking-a-games-counts). Each line is one head measured on one machine, so `cat` shows the record and `git log -p` shows it over time. The history file is the record. The Main Performance dashboard that charted the same numbers was paused on 2026-09-25 and is retired.
+
+The number of record is the platform's frame budget: every game holds 144 fps, so no more than 1% of its frames take longer than 6.94 ms. 144 fps is the floor every shipped game holds on the reference machine. The engine's own frame, the stock scene with one character and no game systems, costs at most half of the 6.94 ms budget, 3.47 ms, and [the bench page](/engine/testing/frame/#the-engines-own-frame) measures it. A row holds the following:
+
+- The head's SHA and commit date.
+- The machine's CPU, the renderer string that names its GPU, Chromium's version and the page's viewport.
+- The spins before and after the runs, in milliseconds, and how many other node and chrome processes were running.
+- The steps and frames the loop took over the vsync-off run.
+- Each run's timings: the p50 and p99 frame, the share of frames over its budget, and the main-thread and GPU p50.
+- The counts the check compares with the baseline.
+
+`spawnite play profile --check` appends the row, so a row lands whenever a session runs a game's `perf` target, such as after a merge to `main`. A check whose spin reads the machine as loaded appends no row, as [the frame page](/engine/testing/measuring/#checking-a-games-counts) describes. Compare rows only on the same machine: another CPU or GPU reads different timings for the same head. One row is one sample, and load moves a timing by about 20%, so read a change across several rows rather than from one.
+
+`pnpm nx run-many -t perf --parallel=1` checks every game in turn, and `pnpm check:release` checks each game with a baseline before a release. A check holds a lock while it profiles, so a second check, from this session or another, waits for it rather than sharing the machine. When a count rose, the check names the merges since this machine's previous row that touch the game, `packages/engine` or `packages/assets`. `--update-baseline=<count>,<count>` rewrites only the counts it names. [The frame page](/engine/testing/measuring/#checking-a-games-counts) says how each works.
+
+## Check what a game looks like
+
+To check that a change to a material, a shader, a look or an asset kept a game's colour and quality, run `spawnite play compare` in a running playtest. It shoots each shot the game's `test/shots.json` names and compares it with the accepted image in `test/shots`. Like the perf check, it gates nothing: run it on request, and file a difference as a follow-up.
+
+Each entry of `test/shots.json` names a shot:
+
+- `name`: the accepted image's file name, `test/shots/<name>.webp`.
+- `scene`: the registered scene to shoot, which the command opens before it steps; the game's start scene without it. A room game's shots take none.
+- `steps`: the step to shoot on, counted from the page's load, or from the scene's opening where the shot names one. In a room game, the room runs before its page joins, so the steps count from where the room stands, and a second run needs a fresh `play start --replace`.
+- `size`: the page's size, such as `960x540`; `1280x720` without it.
+- The camera, as the screenshot command's flags name it: `view`, `camera`, `eye` with `target`, or `framing` with `around`. Without one, the shot is one render of the player's camera.
+- `hud`: `true` to shoot the page as it shows, with its HUD.
+- `share`: the share of pixels that may differ, `0.01` without it.
+
+For each shot, the command prints the share of pixels whose any channel differs by more than 8 of 255, and pass or fail. It writes a difference image, with the changed pixels red, to the temp folder, and exits 1 when a shot fails. `--accept` writes the shots as the accepted set.
+
+The accepted images are the GPU's. Two runs of one build on one GPU differed in at most 0.09% of pixels in the five games measured, and 2.9% to 4.8% in arena, whose spawn pads animate on the room's clock, so its shot allows 6%. Software rendering differs from the GPU in about 3% of pixels, close to the 5.7% a faint tint changes, so the 1% share that catches the tint also fails software rendering. On a machine with another GPU or none, run `--accept` on your branch's base first and compare your change against that set, as you compare perf rows only on the same machine.

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

@@ -0,0 +1,87 @@
+---
+title: Processes
+description: What each spawnite command starts, when each of those processes ends, and how a script of your own ends the browser and servers it starts.
+useCases:
+    - stop a test server
+    - clean up the browser after a test
+    - end background processes
+    - browser left running after playtest
+    - server keeps running after my script
+    - kill a game server safely
+    - process cleanup in a script
+sidebar:
+    order: 17
+---
+
+A `spawnite` command that starts a game's Vite, its room, its bots or a browser ends every one of them when its work ends. That holds when the command finishes, when it fails, and when whatever ran it kills it, as a harness does to a command past its time. It holds on Windows, macOS and Linux alike, with one exception: on macOS and Linux, a `kill -9` of the command may leave the browser it launched, [below](#what-each-command-ends).
+
+This page says when each process the cli starts ends, and what a script you write yourself has to do to end its own.
+
+## What each command ends
+
+A command that runs to an end, such as `spawnite play profile`, `spawnite play room` or the playtest, starts its Vite, room and bots as its own children and ends them with itself:
+
+- On Windows, Node puts each child in a job object that ends it, with every process it started, when the command's process ends in any way.
+- On macOS and Linux, each child leads a process group of its own, and a small guard process ends each group once the command's process ends in any way, a `kill -9` included.
+
+On Windows, the browser such a command launches ends with it the same way. On macOS and Linux, Playwright closes it when the command takes a signal it can handle, such as Ctrl+C or a plain `kill`.
+
+A `spawnite play start` session is meant to outlive the command that starts it, so its browser, Vite, room and bots run detached. A second `spawnite play start` of the game refuses while the session runs. Three things end them:
+
+| What                            | When                                                                          |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `spawnite play stop`            | At once.                                                                      |
+| `spawnite play start --replace` | At once, before the new session starts.                                       |
+| The session's keeper            | Once the session goes `--idle` minutes, 60 by default, with no command on it. |
+
+Every command on the session, such as `step`, `screenshot` or `dump`, counts as a use, and so does the dashboard while it shows the session. `--idle 0` keeps the session until `spawnite play stop`.
+
+## Ending what a script of yours starts
+
+A Playwright script, or any script that starts a browser or a server, ends them itself. Close the browser in a `finally` block, and bound the script's wait with a timeout of its own rather than an outer `timeout` command:
+
+```ts
+import { chromium } from "playwright";
+
+const browser = await chromium.launch({ headless: true, channel: "chromium" });
+try {
+    const page = await browser.newPage();
+    await page.goto("http://localhost:9240/");
+    //  The script's own bound: it throws, and the finally still runs.
+    await page.waitForFunction(() => window.__GAME_DEVTOOLS__ !== undefined, {
+        timeout: 60_000,
+    });
+} finally {
+    await browser.close();
+}
+```
+
+An outer `timeout` kills the script before its `finally` runs. On Windows the browser still ends with the Node process that launched it, but a server the script started detached keeps running, and on macOS and Linux any server it started does.
+
+A server you start in the background from a shell, such as `npx vite &` or a room, is yours to end: stop it before the session ends, or run it through the command that ends it for you, `spawnite play start`.
+
+## A child process in a test
+
+A vitest test that runs a command, such as the cli or `git`, runs it through `@spawnite/testing/process`, with `@spawnite/testing` as a dev dependency:
+
+```ts
+import { runProcess, spawnProcess } from "@spawnite/testing/process";
+
+//  Resolves once the command ends, and rejects on a failed exit with its stderr.
+const { stdout } = await runProcess("git", ["rev-parse", "HEAD"], {
+    cwd: game,
+});
+
+//  Resolves on a failed exit too, for a test that checks the refusal.
+const { status, stderr } = await runProcess(process.execPath, [script], {
+    input: "{}",
+    reject: false,
+});
+
+//  Node's spawn, for a process the test keeps running beside it.
+const server = spawnProcess(process.execPath, ["server.js"], {
+    stdio: "ignore",
+});
+```
+
+Each child opens no console window on Windows. A child still running when its test ends is ended then, so a test that fails or times out leaves nothing behind. A child started outside a test, or in a concurrent test, is the test's to end, because vitest cannot tell which of several concurrent tests is running; `runProcess` takes a `timeout` in milliseconds for those. `createDeadPid()` returns the id of a process that has ended, for a test of code that reads a recorded process that is gone.

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

@@ -0,0 +1,156 @@
+---
+title: What a replay keeps
+description: Where a replay is kept and how much, its settings, why only dev builds keep one, what it costs a frame and a disk, and what the other engines keep.
+useCases:
+    - where replays are stored
+    - limit how many replays are kept
+    - turn off replays
+    - replay cost on frame time
+    - replay file size
+    - replays in a published game
+sidebar:
+    order: 14.2
+---
+
+A development build keeps each page's play as a [replay](/engine/testing/replay/). This page says what it keeps and what that costs.
+
+## What it keeps, and where
+
+The dev server and the dev room write each game's replays under its `.replays` folder, which the game's `.gitignore` leaves out, a session a folder:
+
+```text
+.replays/
+  20260927-183940-19mw/            a session: one run of the room, named as the run
+    session.json                   when it began and ended, its room's port and process
+    20260927-183945-hqxe/          a page that played in it
+      replay.json                  how it began, its marks, each piece's bytes, its clock's slips
+      released.json                the marks an agent released
+      pieces/000003/               the session's fourth minute
+        records.bin.zst            the room's frames, what the page sent, each
+                                   frame's length, the input and the keyframes;
+                                   records.bin while the page still writes to it
+        events.jsonl               its log, an event a line
+        shots.bin                  its screenshots, one file for the minute
+        start.json                 the stream's world as it begins, where the
+                                   minute before was deleted
+    rooms/20260927-183940-19mw/    the room's own recording
+      room.json                    the scene, when it began, its port and process, and its settings
+      checkpoint-base.json.zst     its first checkpoint, and its physics then:
+      physics-base.bin.zst         what each later one is compressed against
+      pieces/000003/               the same minute of the wall, opening on a checkpoint
+        actions.jsonl.zst          every action, a line each; actions.jsonl while open
+        checkpoint-10800.json.zst  the whole world before step 10801, and one
+        physics-10800.bin.zst      each 600 steps after it, with Rapier's snapshot
+  20260927-190210-qq4w/            a page that played with no room: its own session
+  saved/boss-fight/                a saved clip, in a session's shape
+```
+
+A session is one run of the room, from its start to a restart, with every page that played in it. The dev server files each page under the session of the room its address names, and moves it to the new session when the room restarts, so a page that played across a restart is in both, on its one clock. A game that plays alone, or a page whose room keeps no recording, has a session for each page load.
+
+The session's clock is split into pieces of a minute of the wall: a page's piece of a minute and the room's piece of the same minute share a number, and the trim deletes them together. The room checkpoints as each minute begins and every 600 steps, ten seconds, inside it, so a continue catches up at most ten seconds. Its steps may fall behind the wall, where the machine slept with the room running; its minutes do not, and a reader finds a step by the checkpoints each minute opens on. A page's clock stops while the machine sleeps in Chromium on macOS, Linux and Android, and runs on in Chromium on Windows. Where it stopped, the page writes a line to its log that says how far the wall ran ahead, and the dev server files its later records by the wall's minute, so they still go with the room's minute of the same time. A room that restarts in its process on a change to the scene closes its run first, and the run's `session.json` says when.
+
+The whole folder but the saved clips, every session's pages, room and shots, fits one budget by size alone, 300 MB unless the game sets another. There is no age limit: a creator back from a week away finds everything. As a page plays, at most every five seconds, the dev server measures the sessions, and while they pass the budget it deletes the oldest minute of any session that no mark protects, oldest first on the wall's clock; with no page open, nothing trims. A long session shrinks from its start a minute at a time, and the short session a quick restart leaves costs almost nothing and stays. Before a page's minute goes, its world is folded into the `start.json` of the minute that follows it on the page's own clock, the next minute or the first after the minutes a sleep skipped, so what remains still plays back and continues. The minute a session is writing now stays, and a session the trim leaves with nothing, whose room and page have stopped, goes whole. A 31-minute Holdfast session played by the bot took 56.2 MB, about 1.8 MB a minute: 1.7 MB of it the page's and 0.15 MB the room's. A person's play takes about 1.3 MB a minute, so 300 MB holds about three to four hours.
+
+What is binary, and so read by no search anyway, is compressed with zstd: a page's records once the page is into the next minute, a room's actions once the room is past their minute, and each checkpoint as it is written. The minute a page or a room stopped in is compressed by the next trim, once the page has posted nothing for two minutes or the room has stopped. The log and each file an agent edits stay plain text. Most of a checkpoint is what the scene built and rarely changes, the ground's scatter and the physics world's heightfield and obstacles, so each is compressed with the run's first as zstd's dictionary: on Holdfast a checkpoint takes about 8 kB where alone it takes about 360 kB.
+
+A page with no input for two minutes keeps nothing until the next one, a dev server with no page open keeps nothing, a room records only while a player is in it, and `?replay=off` in the address keeps nothing for that page. Each page's recording and each room's run names the shape it was recorded in, and one another version of the engine recorded refuses to play, continue or re-run, in one sentence: record the moment again.
+
+Playback and a continue need a room: a game that plays alone keeps its log, its shots and its input, and `play` and `rerun` refuse it.
+
+## Settings
+
+Every limit is a setting of the game's config, through the engine's [Vite plugin](/engine/structure/game/#the-vite-plugin), `spawnite()`:
+
+```ts
+plugins: [
+    spawnite({
+        replay: {
+            budgetMegabytes: 300,
+            markShare: 0.5,
+            savedWarningMegabytes: 200,
+            shotIntervalSeconds: 2,
+            shotWidth: 854,
+        },
+    }),
+],
+```
+
+| Setting                 | Default | What it sets                                                                                  |
+| ----------------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `budgetMegabytes`       | 300     | The megabytes every session takes together, pages, rooms and shots; past it the trim runs.    |
+| `markShare`             | 0.5     | The share of the budget the minutes marks protect may fill; past it a new mark protects none. |
+| `savedWarningMegabytes` | 200     | The megabytes of saved clips past which the tools warn.                                       |
+| `shotIntervalSeconds`   | 2       | The seconds between the rolling shots; 0 takes none.                                          |
+| `shotWidth`             | 854     | The rolling shot's width in pixels, at the canvas's shape.                                    |
+
+A recorded video clip, from the dev tools' Record button, saves its window of the replay as `saved/clip-<name>`, and its own two limits sit beside `replay`, as [the devtools page](/engine/testing/editing/#recording-a-clip) says:
+
+| Setting            | Default | What it sets                                                               |
+| ------------------ | ------- | -------------------------------------------------------------------------- |
+| `clips.maxSeconds` | 30      | The seconds after which a recording stops by itself.                       |
+| `clips.keep`       | 50      | The clips the game keeps; past it, Record is refused, and none is deleted. |
+
+A setting the plugin does not know, or a value out of its range, fails the config's load and names it. The cli reads the same settings from the game's config, so `spawnite replay list` measures against the game's own budget. For one page load, the address changes the shots alone, as `?replay=off` turns the page's replay off, so a profile prices a value without an edit:
+
+| Parameter                | Sets                  | Example                   |
+| ------------------------ | --------------------- | ------------------------- |
+| `?replay-shot-interval=` | `shotIntervalSeconds` | `?replay-shot-interval=0` |
+| `?replay-shot-width=`    | `shotWidth`           | `?replay-shot-width=640`  |
+
+A value that does not read is a warning in the page's log, and the game's setting stands. `spawnite play profile --query replay-shot-width=640` passes one.
+
+## Dev builds only
+
+The engine's Vite plugin defines `__GAME_ENGINE_DEV__` as true in development alone, and every piece of the replay, the recorder, F8, the menu's line and the Settings row, sits behind it, so a production build never has the chunk. The shots' settings, `__GAME_ENGINE_REPLAY__`, are defined in development alone. `games/holdfast/test/build.test.ts` builds Holdfast for production and fails on any module of the replay's, or its words, in the output. A room records only where `ROOM_REPLAY=1` says so, which a game's `spawnite.room` sets and a production room's image never does; the replication protocol between the page and the room is the same either way.
+
+## What it costs
+
+Measured on Holdfast's dev page at 1920 by 1080 with vsync at 100 Hz, played by `spawnite play profile --drive bot` for 60 s in a fresh room, three runs with the replay on and three with `?replay=off`, alternately, on a Ryzen 9800X3D and an RTX 4070 SUPER. Frames are counted from a second after the loading screen lifted:
+
+| Each run's reading                    | Replay on, three runs | Replay off, three runs |
+| ------------------------------------- | --------------------- | ---------------------- |
+| Mean frame                            | 9.61, 9.56, 9.63 ms   | 9.57, 9.55, 9.53 ms    |
+| p99 frame                             | 10.1 ms each          | 10.1 ms each           |
+| Frames over 20 ms                     | 7, 6, 5               | 5, 4, 5                |
+| Frames over 50 ms                     | 2, 1, 0               | 0, 0, 0                |
+| Main thread's p99                     | 6.5, 6.3, 6.4 ms      | 6.5, 6.2, 6.3 ms       |
+| Shader programs linked after the lift | 70 each               | 70 each                |
+
+The three frames over 50 ms, of 56, 70 and 56 ms, came in the second after the lift, where the voice's first connection runs, and the profile's sampler named no function of the replay's in them. A screenshot costs the main thread about 0.1 ms, and at most 0.4 ms, at any width: the shrink is the GPU's and a worker reads it back, compares it and encodes it, where the same read on the main thread held it 3 ms. The replay kept 2.2 MB a minute of that play, 1.4 MB of records and 0.8 MB of shots, and about 1.3 MB a minute of a person's, before its records were compressed; they now take about 0.2 MB a minute of it.
+
+### The shots' size
+
+The rolling shot's width is a trade between what an agent can tell from it, the image tokens it spends to look, the bytes the replay keeps and the frame. Measured on Holdfast's dev page at 1920 by 1080 with the display at 115 Hz, played by the bot for 60 s with F8 at 30 s, three runs at each width and three with no rolling shots, alternately, on the machine above. The bytes are the rolling shots' own, with every shot kept; the frame's readings are the medians `spawnite play profile compare` gives after the lift, and the main thread's time a shot is read round the page's calls at the page's 0.1 ms resolution:
+
+| Rolling shot | Image tokens | A shot | Shots a minute | Main thread a shot | Frame mean, p99 after the lift |
+| ------------ | ------------ | ------ | -------------- | ------------------ | ------------------------------ |
+| 640 by 360   | about 300    | 27 kB  | 0.84 MB        | 0.1 ms, 0.2 ms max | 8.7 ms, 8.5 ms                 |
+| 854 by 480   | about 550    | 36 kB  | 1.08 MB        | 0.1 ms, 0.4 ms max | 8.7 ms, 8.5 ms                 |
+| 1280 by 720  | about 1,230  | 62 kB  | 1.90 MB        | 0.1 ms, 0.2 ms max | 8.7 ms, 8.5 ms                 |
+| none         | none         | none   | none           | none               | 8.7 ms, 8.5 ms                 |
+
+`compare` found nothing worse past the machine's noise at 640 or 1280; at 854 it marked the frame in the half second after the lift, 75 to 83 ms against 0 to 67 ms, which the timeline puts on the voice's first connection, not the replay. A mark's shot at 1920 by 1080 takes 190 to 225 kB.
+
+The same moment read at each width: at 640, an agent names the character, her pose and her weapon, the rune stones and the coins, but not the rune on a stone or what a small thing far down the path is; at 854 both read; 1280 adds detail no question about the moment needed. So the rolling shot is 854 by 480, a quarter more bytes than 640 for a view an agent can read far into, and the mark, the moment a person chose, keeps every pixel. None of the five engines keeps shots in a replay: Unreal's and CS2's replays are the stream alone, and Unity's Recorder writes a video at a size you pick. A crash reporter such as Sentry's attaches one screenshot at the screen's size at an error, as a mark does here.
+
+The room's recording costs the page nothing it can measure. Three runs of the same profile with the room's recording on and three with it off read a frame mean of 8.6 ms each, a p99 of 8.5 ms each, and 2 or 3 hitches over 50 ms after the lift either way; `spawnite play profile compare` found nothing worse past the machine's noise.
+
+The room pays for each checkpoint on its own thread, in the step that takes it, once each 600 steps and as each minute begins. Measured on Holdfast's room played for 62 s by a Node client that runs, shoots and takes the monsters' blows, three runs with `ROOM_REPLAY=1` and three with `0`, alternately; `spawnite play room --seconds 62`, with `--room-env ROOM_REPLAY=0` for the runs with it off and `--room-env ROOM_HEARTBEAT_SECONDS=15` for the same windows, now plays and reads such a run:
+
+| Each 15 s heartbeat's reading, from the second on | Recording on                | Recording off   |
+| ------------------------------------------------- | --------------------------- | --------------- |
+| Mean step                                         | 0.78 to 0.95 ms             | 0.80 to 0.87 ms |
+| Longest step                                      | 5.5 to 7.1 ms, once 10.4 ms | 1.5 to 2.6 ms   |
+| Longest checkpoint                                | 5.4 to 6.7 ms, once 8.9 ms  | none            |
+
+A checkpoint takes the world, about 2 ms, the room's own state, and its JSON, about 1.5 ms, most of both the ground's scatter; the zstd and the write run off the room's thread. Writing the physics world back from its snapshot, as the room does with each checkpoint so a continue from it comes back exactly, adds a restore of that snapshot to the step that takes it. Two bots played each game for 40 s with `spawnite play room --bots 2`: the longest checkpoint read 8.0 to 10.3 ms on Holdfast over three runs, against 8.8 ms in one without it, and 9.6 to 18.3 ms on the arena over four runs, against 9.2 and 10.9 ms in two without it. A step's budget is 16.7 ms, and the room's clock runs a late step's time on the next. Compressing a closed ten seconds of the page's records took the dev server about 0.5 ms, and made them 8 times smaller; a closed minute takes about six times that.
+
+A continue runs as fast as the room steps: Holdfast's 69 s run took 0.7 s to check, and an 8 s moment 0.3 s, past the 5 s the command takes to load the game's room.
+
+Opening a moment with `spawnite replay play` or `shot --render` took 12 to 14 s from the command to its first shot: the command's own dev server answers in 0.6 s, and the page loads the game and stands on its keyframe 6.7 to 8.3 s after it opens. Each later shot takes 0.5 to 2 s, most of it the frames played to reach it.
+
+## Other engines
+
+CS2's demos, Fortnite's replays and Unreal's demo recording keep the server's replication stream, not a video, and play it through the client, as playback does; Unreal also keeps a checkpoint every 30 seconds to jump to. None continues one: a stream recorded on the client cannot hold the server's own state. Unreal's in-memory replay keeps a rolling buffer by time, and NVIDIA's instant replay and OBS's replay buffer keep the newest minutes by time or by size; each drops a recording whole or from its oldest end, and none keeps a moment the player marked apart from the rest. Here one size budget covers every session, a mark protects its window without a copy, and a clip an agent saves is the one copy. StarCraft 2 and Factorio replay the players' actions into a lockstep simulation from its start, and Factorio proves its saves whole by loading one and setting what it steps beside the game, which is what `check` does. Unity and Godot keep nothing, and Roblox has no replay for a place's developer. This keeps a replay of every dev playtest without a line of the game's code, and the room's own checkpoints and actions beside it, so an agent continues any moment of it exactly with the code as it stands, and the room's record, not a tolerance, says it came back.
+
+Unreal's replays pause, change speed and scrub, jump back through their checkpoints, and fly a spectator camera or follow any actor; a live replay lets a spectator rewind a match still running and jump back to live, as a room session's `seek` and `seek live` do. Fortnite's and Rocket League's replay theaters give players the same controls. Godot's game view suspends a running game, steps it a frame at a time and swaps in the editor's free camera, and Roblox Studio pauses a playtest and frees its camera. Unity's Recorder shoots from any camera over a play mode paused in the editor. Each is a person's panel. Here the same controls are commands, so an agent holds a moment, moves its camera and shoots it with no script of its own.