@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,175 @@
+---
+title: Frame
+description: Everything one frame runs, in order, and what each line costs.
+useCases:
+    - game runs slowly
+    - what runs each frame
+    - frame rate drops
+    - reduce per frame cost
+    - how long a frame takes
+sidebar:
+    order: 13
+---
+
+A frame is one call of React Three Fiber's loop: every `useFrame` subscriber in the order it mounted, then the render. The engine's Frameloop is the first subscriber, and it runs the simulation, the character's animation and the camera in one callback. This page lists what runs, measures each line, and says which lines are worth cutting.
+
+[Measuring a frame](/engine/testing/measuring/) describes how to measure it again, and [Finding hitches](/engine/testing/hitches/) describes how to find the frames that run long.
+
+## What one frame runs
+
+The Frameloop mounts before any scene, so its callback runs first. Every line after the fixed steps runs once per frame, so it scales with the display's rate; the steps do not.
+
+1. Whether drei's loaders have a file in flight, copied into `useLoading` on a change.
+2. The pause checks: a modal that pauses returns before anything is banked; the devtools' pause hands the loop one owed step or none.
+3. The accumulator: how many whole 1/60 s steps this frame's time buys, and the leftover.
+4. The browser's input, read once: every input the game declares, the character's move from its keys and the stick among them, then the camera's azimuth, written into the character's heading.
+5. The pending debit out of `useWallet`, spent on the player's character.
+6. `stepWorld`, once per step bought: the previous transforms, then the world's systems by phase.
+    - `input`: the character's path and steer.
+    - `motion`: the stats, then every velocity applied.
+    - `rules`: the day clock, the cooldowns, the behaviours, the resources and the state machines, with the rules of each plugin the game lists, such as the round.
+    - `physics`: every actor walked by the engine's own character controller, with Rapier as its query tree, which is most of a step, then the physics scene's one Rapier step.
+7. The wallet's copy in `useWallet`, on a change; the step count in `useTime`, on every frame that stepped; while editing, the recording's dump of the world.
+8. The character's pose off the step's steer and turn.
+9. The transforms onto the objects, blended between the last two steps by the leftover.
+10. The devtools' hidden entities hidden again.
+11. The character's animation: a clip switch and its blend, the mixer, the head turn, the humanoid, the world matrices, then `vrm.update`, which runs the spring bones with their colliders and the look-at.
+12. The camera: the aim swept out from her eye line, the orbit moved to it and updated, then the eye swept in from the aim, each as a small sphere against the world's fixed colliders and held off the ground.
+13. While editing, the hovered and selected entities' screen rectangles.
+
+Then the other subscribers, in mount order: drei's camera controls, the daylight rig (the sun and fill from the clock), the VRM view (nothing while the character's animation is bound), drei's `Html` and `PerformanceMonitor`, and the game's own, such as the mmorpg's autosave. Last, `gl.render`: the shadow map, then the scene. A scene that mounts [post-processing](/engine/graphics/post-processing/) draws through its composer instead, which renders the scene and then its passes.
+
+Three stores change during a frame. A component that subscribes re-renders after the frame, in React's scheduler:
+
+| Store        | Written                  | Who reads it at the frame rate                                               |
+| ------------ | ------------------------ | ---------------------------------------------------------------------------- |
+| `useWallet`  | on a change of coins     | a HUD's coin count, on a pickup                                              |
+| `useTime`    | every frame that stepped | the devtools' playback bar while editing; a game's HUD reads `running` alone |
+| `useLoading` | on a change              | a scene or loading screen waiting for its models                             |
+
+## The engine's own frame
+
+The engine's own frame is the stock scene with no game on it: the meadow and its whole scatter, the daylight rig, the camera and one character. `StockScene` mounts it, with the character's body as its `character` prop, and the bench page at `tools.spawnite.com/bench` mounts `StockScene` with the mmorpg's heroine, Fris, under the performance overlay's Full level. Of the overlay's levels, FPS shows the frame rate and, in a room, the ping; Graph adds the 1% low and a small line of the last ten seconds' frame times; and Full adds the CPU's and the GPU's time per frame and, in a room, the ping's jitter beside the ping, such as `58 ms ±4`; [the settings page](/engine/ui/graphics-quality/#the-performance-overlay) says what each number measures. The draw calls and triangles are in the devtools' Frame tab and in `spawnite play stats`. The page is the tools app's, so no game's own work runs beside the engine's. It also registers one scene per engine look, `morning`, `noon`, `dusk` and `overcast`, beside the stock scene, `stock`, which opens first and draws the rig alone.
+
+The goal is half the 6.94 ms budget, 3.47 ms, on the reference machine, so a creator's game keeps the other half. The perf check measures the page as it measures a game: `pnpm nx run @spawnite/tools:perf` profiles `/bench`, checks its counts against `apps/tools/test/profile-baseline.json`, and appends a row to `apps/tools/test/profile-history.jsonl`. On the machine below, with vsync off, the whole frame's p50 is 1.70 ms and its p99 2.50 ms, and no frame passes 6.94 ms; the GPU's p50 is 0.66 ms. With the counts run pinned to 60 fps, the main thread's p50 is 2.50 ms. The frame is under the goal by about half.
+
+A change to the engine's frame is measured on this page, with nothing of a game's in the way. `spawnite play compare`, run in a playtest of `apps/tools`, shoots the stock scene and each look through `apps/tools/test/shots.json`.
+
+## What it costs
+
+Chromium 153 on Windows 11 with an AMD Ryzen 9 3900X and an RTX 3070, the built mmorpg at 1280 by 720, the character running back and forth for 20 s, a CPU profile sampled every 100 µs and read back through the source map, the median of three runs. The display runs at 144 Hz, and the loop kept pace at 144 fps with about 2.8 ms of CPU per frame: on this machine the display, not the CPU, sets the rate. At 60 Hz the same lines cost the same per frame and less than half as much per second. Inclusive milliseconds per frame, in the frame's order:
+
+| Line                                     | ms per frame | Note                                                                              |
+| ---------------------------------------- | ------------ | --------------------------------------------------------------------------------- |
+| The Frameloop's callback                 | 1.64         | everything below through the screen rectangles                                    |
+| Accumulator, input read, `useInput` copy | 0.007        |                                                                                   |
+| `stepWorld`                              | 0.14         | the controller 0.064                                                              |
+| `useWallet` and `useTime` writes         | 0.005        | with no subscriber at the frame rate                                              |
+| Pose                                     | 0.009        |                                                                                   |
+| Transforms                               | 0.009        |                                                                                   |
+| Animation                                | 1.44         | the springs' colliders 0.66, of which the obstacle queries 0.017; head turn 0.011 |
+| Camera                                   | 0.031        | the eye settle 0.005                                                              |
+| Daylight rig                             | 0.008        |                                                                                   |
+| Autosave                                 | 0.001        | saves once every 1,800 frames                                                     |
+| `gl.render`                              | 1.09         | the scene 0.48, the shadow map 0.38, the world matrices 0.13                      |
+
+The animation is the frame's largest line. Its spring bones collide with the model's own spheres, the ground and the baked obstacles. Fris carries 176 spring joints on 54 chains, and the obstacle collider asks the bake once per body before any joint does: one query from the hips, reaching half a metre past the furthest spring tail. A joint queries the bake itself only when the hips' nearest surface stands within half a metre of the joint's own distance from the hips. In the open a frame runs one query, the hips' own. Near a surface, each joint within reach of it queries as well, running or at rest. The hips' query runs only on a frame where the hips moved, and the idle clip moves them, so a body at rest still asks once a frame. Each query walks one tree over the whole bake, so the obstacle queries are a small part of the colliders: most of their time is the joints against the model's own spheres and the ground.
+
+Measured on an M2 Pro with the devtools editing, the frame gains the recording's dump, 0.036 ms, and the playback bar's re-render off `useTime`, 0.38 ms of React work per frame. That is the cost of one subscriber at the frame rate: a HUD clock that subscribed the same way would pay it too.
+
+The Node bench runs the same lines with no render on the bench page's own `StockScene`, mounted headless, the character running in a ring on the meadow with its obstacle bake, over 3,600 frames after 600 of warm-up, the mean of five runs. The character wears the bench page's body, Fris, parsed from the assets with the engine's VRM loader and prepared as the render prep prepares a body, with the run clip on every pose, so its 176 spring joints on 54 chains query the bake as they do on the page. Milliseconds per frame on the same machine:
+
+| Line                   | mean ms | p99 ms | share |
+| ---------------------- | ------- | ------ | ----- |
+| `accumulateSteps`      | 0.0003  | 0.0006 | 0.0%  |
+| `publishInput`         | 0.0007  | 0.0012 | 0.1%  |
+| `takePendingDebit`     | 0.0002  | 0.0004 | 0.0%  |
+| `stepWorld`            | 0.1956  | 0.3334 | 25.4% |
+| `publishWallet`        | 0.0013  | 0.0019 | 0.2%  |
+| `publishInventory`     | 0.0011  | 0.0018 | 0.1%  |
+| `publishSteps`         | 0.0012  | 0.0018 | 0.2%  |
+| `resolveCharacterPose` | 0.0027  | 0.0038 | 0.3%  |
+| `syncTransforms`       | 0.0036  | 0.0051 | 0.5%  |
+| `hideEntities`         | 0.0005  | 0.0008 | 0.1%  |
+| `animateCharacters`    | 0.5227  | 0.7042 | 68.0% |
+| `syncCamera`           | 0.0363  | 0.0648 | 4.7%  |
+| `writeScreenRects`     | 0.0006  | 0.0011 | 0.1%  |
+| whole frame            | 0.7687  |        |       |
+
+`publishSteps` runs with one subscriber on `useTime`, so the number includes waking it. The animation's line and the camera's query the same bake the browser does; the two runtimes price the rest of their work differently.
+
+## What to reduce
+
+In the order the numbers point:
+
+1. **The springs of the character the page steers, 0.66 ms.** Every other character is posed every other frame while small on screen and not at all out of view, so its springs cost nothing there. The page's own character is posed every frame, because a game may aim her shots from her hands.
+2. **The render's JS side, 1.09 ms.** The shadow map is a third of it. Nothing in the engine's own code is here; the levers are the quality tier's shadow map size and how much scatter casts.
+3. **The step's controller, 0.064 ms.** Cheap at one actor; its cost with a crowd is the physics bench's subject, and a room budget question rather than a frame one.
+4. **The eye settle, not yet remeasured.** Two sphere casts a frame in the physics world, one for the aim and one for the eye, and up to about 100 looks at the ground's height along the eye's line at the farthest zoom. It measured 0.005 ms as three rays against the bake before the sweep replaced them.
+5. **The per-frame queries.** koota's `world.query` builds an array of the entities, a closure per method and, for each trait of fields, a record per entity on every call: most of the arena's garbage in a room, 40 KB of its 79 KB a frame. The step's systems and the frame's lines walk their queries through the engine's own walk in the entity folder, which builds none of them. A query that runs on an event rather than on a frame, such as a click's, still calls koota.
+6. **Numbers across a call V8 does not inline.** V8 boxes a fractional number passed into or returned from such a call, 12 bytes each way. three-vrm's spring joints handed each collider the joint's hit radius and read a distance back, through a call that sees four shape classes: 377 KB of the arena's frame with its heroines drawn. The engine's loop in render/springCollision.ts passes them through the fields of one preallocated contact, which the collider writes into and V8 writes in place. A hot call that takes or returns a fractional number takes the same shape: the bake's `measureEscape` writes its depth into the query it is handed rather than returning it.
+7. **A library's walk that builds per call.** three-mesh-bvh's `shapecast` builds three typed-array views of the tree, a callbacks object and a closure on every call, and boxes each node's score on its way out of the score callback; three-vrm's spring manager builds a closure for every object under every joint, every frame. With the heroines beside the arena's rocks, the two made about 31 KB of a frame. maths/escape.ts walks the bake's tree itself over views built once for each tree, and render/springCollision.ts walks the joints' children in a plain loop. Each reads the pinned library's private members, and a test runs the library's own walk beside it.
+
+## Spawns and deaths
+
+A game that spawns and destroys entities many times a second, as a wave shooter does, keeps to three rules:
+
+1. **Measure a spawn on a build, not on the dev server.** React's development build makes every element through `jsxDEV`, which records where each was made, so a list that draws again costs many times what it costs in production. At Holdfast's wave 10 with four wardens, the dev page played at a p99 of 83.3 ms with 289 frames over 50 ms in the run, most of them right after a spawn or a destroy. The production build played the same wave at a p99 of 33.4 ms with 10 such frames, and the frames after its 630 spawns and 618 destroys were no slower than the rest. Profile without `--dev` before you change how a game spawns.
+2. **Memoize the view of one entity in a list.** koota's `useQuery` draws its list again whenever an entity joins or leaves the query, so a view that is not wrapped in `memo` draws its whole tree again for every other entity's spawn and death. `Replicas` memoizes each entity's view; the overlay you hand it keeps that only when it is the same function every render, one declared at module level or held in `useCallback`.
+3. **Draw many spawned things from one pool.** [InstancedModel](/engine/graphics/instanced-model/), the [skinned batch](/engine/graphics/skinned-batch/), [Particles](/engine/graphics/particles/) and [FloatingText](/engine/ui/floating-text/) draw every copy from objects made once, so a spawn adds a copy rather than mounting a tree. A spawned material is compiled under the loading screen only when the scene holds one, so keep one of each hidden in the scene, as [Shaders compile under the screen](/engine/structure/game/#shaders-compile-under-the-screen) says.
+
+Unity games pool spawned objects with `ObjectPool<T>`, Unreal pools actors for projectiles and crowds, and PlayCanvas documents entity pooling; React Three Fiber's own guidance is to reuse objects rather than mount and unmount them in the hot path. The engine's pooled components are that path, and a memoized view keeps the list itself cheap.
+
+## Frame pacing
+
+A game can average a full 120 frames a second and still stutter: the frames a player notices are the slowest few, which the average hides. On a 120 Hz screen a frame that misses its refresh shows for 16.7 ms, and one such frame in ten seconds already pulls the overlay's 1% low from 120 to about 111. Most of those frames in a browser game are not the game's code. The page's own frame can finish in 4 ms and the frame still miss, because what runs after it is the browser's.
+
+Chrome draws a page in two processes. The page's process runs the game's code, React and three.js, and turns the HTML and CSS into paint commands. The GPU process runs everything that touches the graphics card, on one main thread, in turn: every WebGL command the game sends, the raster that draws the HTML and CSS into tiles, and the compositor's paint that lays the tiles and the canvas into the frame. While that thread rasters a HUD panel, the frame's WebGL commands wait behind it, however short the page's own frame was. A HUD that changes every frame, such as a number that counts up or a bar that animates its width, is painted again every frame and rastered again every frame on that same thread: Holdfast's HUD painted about 54 times a second, and half its slow frames were the GPU process busy with the raster and the compositing. `spawnite play profile --trace` names that work on each slow frame, as [Finding hitches](/engine/testing/hitches/) says, and prints the page's paints and raster a second.
+
+What a HUD avoids, beside what does the same without the repaint:
+
+| Avoid                                                                                          | Instead                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A value written every frame through React state, such as a timer's text or a bar's `width`     | Write it only when it changes, or through a ref into `transform` or `opacity`, which the compositor moves without a repaint                                        |
+| A CSS animation of `width`, `height`, `top`, `left`, `color`, `box-shadow` or `filter`         | The same motion as `transform: scale()` or `translate()`, and a fade as `opacity`                                                                                  |
+| A blur or a drop shadow on an element that changes or animates                                 | The effect on a still element, or baked into an image                                                                                                              |
+| `backdrop-filter` over the canvas on a panel that stays up while the game plays                | An opaque or translucent fill: a blur behind a panel is redrawn every frame the canvas changes, which is every frame                                               |
+| A panel that changes every frame outside a slot, where its repaint reaches the page beneath it | A slot `Panel`: the screen layer that holds the slots is contained on a layer of its own, so a panel there rasters alone; a `Hud`'s own children are not inside it |
+
+A model a wave spawns draws for the first time as the wave rises, and Chrome's GPU process builds the draw's vertex layout then: 24 and 44 ms of its time at Holdfast's first wave before the engine drew each [skinned batch](/engine/graphics/skinned-batch/) once under the loading screen. Keep one of each spawned model in the scene from the first frame, as [Shaders compile under the screen](/engine/structure/game/#shaders-compile-under-the-screen) says, and the batch draws it there.
+
+## What loads before the first frame
+
+Before a page draws its first frame, it downloads the page, its entry chunk, what that chunk imports statically and their stylesheets. Each game in this repository guards a standalone build of those files, the engine bundled in, by calling `checkGameBuild` from `@spawnite/engine/vite` in its `test/build.test.ts`. The guard is 1,500,000 bytes gzipped: the engine release's own budget of 1,000,000, which the engine's release test holds, plus the 500 KB of game code past which `spawnite build` warns. The engine is most of a standalone build, so the guard catches a large mistake, such as a WebAssembly module imported statically, rather than tracking the game's size:
+
+```ts
+// @vitest-environment node
+import * as path from "node:path";
+import { checkGameBuild } from "@spawnite/engine/vite";
+import { it } from "vitest";
+
+it("builds for production within the platform's rules", async () => {
+    await checkGameBuild(path.resolve(import.meta.dirname, ".."));
+}, 180_000);
+```
+
+`checkGameBuild` builds the game for production into a temporary folder and throws when those files weigh more than 1,500,000 bytes gzipped, naming the size and the game's own source files' share, or when any chunk holds zod's classic API or a zod locale other than English. It returns every file the build wrote, so a game can assert more about its own bundle. Its `env` option sets environment variables for the build, such as `ROOMS_DOMAIN`, and its `plugins` option adds Vite plugins, such as one that reads a written file in `writeBundle`.
+
+What a creator is told about is the game's own code, not the guard. To weigh what a published page downloads before the game starts, run `spawnite build`: it builds the game's bundle, prints the gzipped size of the game's own code as `Game code`, warns past 500 KB, and lists the heaviest files and the heaviest modules of the game's own code. `--json` gives the same data under `code`, with the engine release's part as `code.engineBytes`. The example's build test also fails when any of the following comes back into them. Each loads where it is first used, and a game keeps it there:
+
+- **motion's drag and layout.** ui renders `m` inside `LazyMotion` with `domAnimation`, and a game's own animated component does the same. The devtools take `motion` from `motion/react-client`: `motion/react` binds `motion` in its entry module, so a use of it from any chunk puts drag and layout in the first load. Lint refuses `motion` from `motion/react` in ui, the devtools and every game.
+- **Sounds.** Vite writes a file under its 4 kB inline limit into the importing chunk as base64. The engine's Vite plugin, which every game loads, keeps an `.mp3` a file, and the view that plays a sound preloads it.
+- **A sky's `EXRLoader`.** A look's image loads through three's `HDRLoader`, and `EXRLoader` is fetched the first time an image names an `.exr`.
+- **The devtools' console capture.** Only the engine's `./devtools` subpath exports `captureLog`, so a game's first load carries neither of its parsers.
+- **Rapier's wasm.** The physics scene loads it at the first body a world declares, through `loadRapier`, and a World waits for it before its ground spawns.
+- **recast's library and the navmesh wireframe's line materials.** They load in one chunk on the first call of `loadRecast`, beside the wasm, which every bake awaits.
+
+Most of a published page's first load is the engine release, which the platform holds to a budget of its own. The release's part is what the engine, `react`, `react/jsx-runtime` and `react-dom/client` import statically, the modules every game's page boots with. The engine's release test builds the release, sums those files gzipped, and fails over the budget the engine's release build sets, listing each file heaviest first with the packages its code comes from. Run it alone with `pnpm --dir packages/engine exec vitest run --coverage.enabled=false test/release.test.ts -t "within its budget"`. The same test file fails when zod's locales other than English or its JSON Schema writer come back into those files: only a page that imports `z` from the schema loads them.
+
+A lazy import alone does not keep a module out while any module the barrel reaches imports it statically. The engine's barrel reaches every engine module, and the engine declares no `sideEffects`, so the bundler keeps any module that runs code at its top level in the entry chunk. The room client stays there for that reason, though a game played alone never calls it.
+
+## What a deploy carries
+
+A game's build copies every file that a module it reaches names, whether or not the page ever fetches it: the bundler drops unused code, not the files that code names. The built-in looks light from the engine's own sky and name no image, so a look adds no file to a deploy. A look whose `environment.image` names an `.hdr` ships that file, about 1.5 MB for a 1K image, as [Looks](/engine/graphics/looks/#lighting-from-an-image) says.
+
+A shared file, from `@spawnite/assets` or one the engine loads itself, such as the scatter's tall tree, ships in no deploy: the engine's build and the package name it by its URL on `https://assets.spawnite.com`, and every game's page fetches it from there. Each URL names the file's bytes, so no deploy carries a copy. In this repository a game's own build reads the kit's files themselves; `spawnite build` names them by URL, as a published game does. Where a game's `public/assets` holds a kit file byte for byte, as `spawnite add asset` puts one there, a build in this repository ships the game's copy alone and points the import at it. A game on the npm engine fetches the engine's copy from the shared site and its own from its deploy, so the page fetches that model twice.

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

@@ -0,0 +1,133 @@
+---
+title: Headless tests
+description: Testing a game in Node with the devtools store and the harness, rendering the whole app in jsdom, and property tests with fast-check.
+useCases:
+    - test my game without a browser
+    - write a unit test for a system
+    - test the whole app in jsdom
+    - stub fetch in a test
+    - property based tests
+    - run a scene headless
+sidebar:
+    order: 12.4
+---
+
+A game's tests run in Node. There, the devtools store and the harness step the world, draw nothing and load no asset.
+
+## Sample
+
+In Node, the store comes from `@spawnite/engine/devtools` and the harness from `@spawnite/engine/core`, so nothing draws and no asset loads. A game with its own systems passes its plugins to `createHeadlessGame` as `plugins`, the same list it gives [Game](/engine/structure/plugins/):
+
+```ts
+import { createHeadlessGame } from "@spawnite/engine/core";
+import { attachDevtools, useDevtools } from "@spawnite/engine/devtools";
+
+const game = await createHeadlessGame({ scene: spawnCoins });
+const detach = attachDevtools(game);
+const { step, dump } = useDevtools.getState();
+
+step(5);
+const { entities, hash } = dump();
+detach();
+```
+
+A scene's own component mounts in Node too, through the engine's headless mount, on a root that draws nothing: the views that load a model, a sound or a VRM, the camera, and Hud, Panel and Modal render nothing headless, and the traits the rest fill are what the steps run on. A game's own component that loads a file or reaches the page reads `useHeadless()` from the engine and renders nothing when it is true, as the engine's do. One that does not fails the mount with an error that names it, such as `Rock failed headless: Failed to parse URL from /@fs/rock.glb`, followed by that fix. `useQualityStore()` works headless too: each mount builds its own stores, which start empty and keep nothing once it ends. A headless mount saves nothing; `spawnite simulate --save <file>` starts the world from a save file. The mount makes a world from no plugins, the core alone, unless it is handed one, so a scene that places a character or a behaviour mounts on a world made from the game's `plugins`. A scene that calls `useLevels()` mounts on the levels the last `defineLevels` call among its imports made, as Game's `levels` gives them, unless the world handed to the mount holds levels already. The components render between the calls that step the world, not between the steps, so a modal that opens on a step, a round screen for one, holds none of them up: read the round's state off the dump. The mount returns once every render and effect it started has run, a first load the scene waits on included: under React's `act` in React's development build, and in its production build, which has no `act`, once fiber's scheduler is idle and no update waits to commit. A room run with `NODE_ENV=production` mounts a scene this way.
+
+```ts
+import { createGameWorld, mountHeadlessScene } from "@spawnite/engine";
+import { attachDevtools, useDevtools } from "@spawnite/engine/devtools";
+import { plugins } from "./game";
+import { Run } from "./scenes/Run";
+
+//  On the game's own plugins: a world made from none runs the core alone.
+const game = await mountHeadlessScene(Run, createGameWorld(plugins));
+const detach = attachDevtools(game);
+useDevtools.getState().step(5);
+const { entities, hash } = useDevtools.getState().dump();
+detach();
+await game.unmount();
+game.world.destroy();
+```
+
+The cli's `spawnite simulate --scene <name>` and the MCP's `simulate` tool mount the component `src/scenes/<Name>.tsx` exports under that name this way, loading it and the engine through the game's own Vite, step the world on the `plugins` list the scene's file exports, else on the one `src/game.ts` exports, else on the core alone, with the levels from the last `defineLevels` call among the scene's imports, where there is one, as Game's `levels` gives them, seconds of game time or until an expression holds with keys held through the game's own key table, as its page reads them, and print this dump with its hash, the plugins the world was made from, each with its description, and the step's systems, one line per phase.
+
+## A whole game in jsdom
+
+A test that renders a game's whole app, `Game` and its DOM together, runs in jsdom, which has no WebGL. With `GAME_ENGINE_VIEWS=off` in the environment, the engine leaves out the views that load a model or draw the world: a World's ground, scatter, props, navmesh and light, a Player's body, footsteps and marker, an Entity's model and an InstancedModel. The screen, every Hud and Panel, the game's own DOM and every trait still mount, so the test can find a button and read the wallet. The test still mocks `@react-three/fiber` and `@react-three/drei` with the fakes `@spawnite/testing/fiber` exports, as the example's `test/app.test.tsx` does:
+
+```ts
+vi.mock("@react-three/fiber", async () =>
+    (await import("@spawnite/testing/fiber")).fakeFiber(),
+);
+vi.mock("@react-three/drei", async (importOriginal) =>
+    (await import("@spawnite/testing/fiber")).fakeDrei(importOriginal),
+);
+```
+
+`fakeFiber()` draws the canvas as a `div` with `data-testid="canvas"` that holds its children, with the `camera` prop as `data-camera`, and its `useThree` reads a detached canvas, a 1280 by 720 size and an always-running loop. `fakeFiber({ state })` puts what `state()` returns behind `useThree`'s `get`, read at each call, so a case can swap the renderer. `fakeDrei(importOriginal, overrides)` keeps drei whole, draws no `CameraControls` or `GradientTexture`, and replaces any export `overrides` names, such as `Html`. `fakeLoader(importOriginal, () => model)` keeps the real fiber and hands every `useLoader` call the loaded value, for a test that draws with the real renderer. The `vi.mock` call stays in each test file, because Vitest hoists it only there.
+
+The engine reads the variable on each render rather than once when its module loads, so a test sets it in `beforeEach`, after its imports have loaded the engine, and the package's bundle reads it the same way as the source does:
+
+```ts
+beforeEach(() => vi.stubEnv("GAME_ENGINE_VIEWS", "off"));
+```
+
+A page has no `process`, so the variable changes nothing in a game's build.
+
+The vitest config names a setup file in `setupFiles`. The setup tells React the tests run under `act`, unmounts what the last test rendered, registers the jest-dom matchers, and stubs the `scrollTo` and `matchMedia` that jsdom lacks, answering `matchMedia` as a desktop. A game names `@spawnite/testing/setup` there, with `@spawnite/testing` as a dev dependency, and adds `@spawnite/testing/setup` to `types` in its test `tsconfig` to type the matchers. A game that needs more keeps a `test/setup.ts`, lists it after the package, and sets `sequence: { setupFiles: "list" }` so vitest runs the two in that order rather than in parallel. A game made by `spawnite create` from a template that declares `@spawnite/testing` comes with all of it; Holdfast's template keeps its own `test/setup.ts` instead.
+
+### A stubbed fetch
+
+A test of code that fetches, such as a panel that reads a page from the dev server, stubs `fetch` with `stubFetch` from `@spawnite/testing/fetch`. It takes one answer for every URL, or an answer per URL, keyed by the URL exactly as the code passes it. An answer is a `Response`, served as a fresh copy on each call, or a function that takes fetch's own arguments. It returns the spy, so the test reads the calls, and it puts the real `fetch` back when the test ends:
+
+```ts
+import { stubFetch } from "@spawnite/testing/fetch";
+
+it("saves the shot through the dev server", async () => {
+    const fetch = stubFetch({
+        "/__shots": Response.json({ file: "shots/1.png" }),
+    });
+    await expect(saveShot(png)).resolves.toBe("shots/1.png");
+    expect(fetch).toHaveBeenCalledWith("/__shots", expect.anything());
+});
+```
+
+A URL that no route names rejects, and fails the test even where the code catches the rejection, so `stubFetch({})` proves the code fetched nothing. A function answer covers the rest: a network failure, `() => Promise.reject(new TypeError("offline"))`, or a request held in flight, `() => new Promise(() => {})`. Call it in the test or in a `beforeEach`.
+
+The mocked canvas hands the engine a renderer that cannot compile shaders ahead, and the engine reads that as a canvas that runs no frames. The loading screen then waits on nothing a frame does, neither the room's welcome nor a drawn frame, and with the views off it waits on no drawn character or ground. It lifts once the physics, navmesh and scatter shapes chunks have landed and the scene has mounted, so the test finds the lobby's Play button and every Hud.
+
+### A temp folder
+
+A test that writes files, such as a save or a generated game, makes its folder with `makeTempDir` from `@spawnite/testing/temp` and never removes it:
+
+```ts
+import { makeTempDir } from "@spawnite/testing/temp";
+
+it("writes the save", () => {
+    const folder = makeTempDir("save-");
+    // ...
+});
+```
+
+Called in a test or a `beforeEach`, the folder goes when that test finishes, passed or failed. Called at a file's or a `describe` block's top level, it goes when that file or block finishes, or with the file when the block is skipped or filtered out. A file whose every test a `-t` filter leaves out runs no hook, so the temp guard names what its top level made. Not in a `beforeAll`, whose folder nothing removes: call it at the block's top level instead. A second argument names a parent folder other than `os.tmpdir()`, for a test whose files must sit inside the workspace.
+
+## Property tests
+
+A property test states what holds for every input, and [fast-check](https://fast-check.dev/) draws the inputs: hundreds of them, biased toward the edges such as `0`, `-0`, the smallest double and a `__proto__` key. When one fails, fast-check shrinks it to the smallest input that still fails and prints it. Write one where a rule is short and the inputs are many: a round trip, such as a decode of an encode or a save read back after a write, or a law, such as a sine that is odd.
+
+Add `fast-check` and `@fast-check/vitest` as dev dependencies, and pass a fixed `seed` and `numRuns`, so every machine draws the same inputs:
+
+```ts
+import { fc, test } from "@fast-check/vitest";
+import { expect } from "vitest";
+import { quaternionToYaw, yawToQuaternion } from "@spawnite/engine";
+
+test.prop([fc.double({ min: -3.14, max: 3.14, noNaN: true })], {
+    seed: 2640,
+    numRuns: 200,
+})("reads back the yaw it wrote", (yaw) => {
+    expect(quaternionToYaw(yawToQuaternion(yaw))).toBeCloseTo(yaw, 12);
+});
+```
+
+A failure prints the counterexample, with the `seed` and `path` that replay it alone. The engine's own property tests sit beside its other tests, such as the codec's in `packages/engine/test/gameplay/replication/codec.test.ts`.

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

@@ -0,0 +1,140 @@
+---
+title: Finding hitches
+description: Find the frames that run long in play, name what each one ran, and capture your own play to read the same way.
+useCases:
+    - find the cause of a hitch
+    - game stutters
+    - frame spikes when enemies spawn
+    - long frames in my game
+    - capture a performance trace of play
+sidebar:
+    order: 13.2
+---
+
+A game that stutters holds one frame far longer than the rest: a shader that compiles as a monster first draws, a script that blocks the page as a room answers. The spreads [Measuring a frame](/engine/testing/measuring/) reads hide a frame like that, so every run of `spawnite play profile` also keeps a timeline from the page's first frame, and prints each frame longer than `--hitch` milliseconds, 50 by default, with what it waited on and the event before it. 50 ms is three frames at 60 Hz, the threshold Chrome's long animation frames use.
+
+For each frame, the timeline keeps the following:
+
+- **compile**: the time WebGL's shader compile and link calls held the page, and the programs it waited on, each named by its material and by the object three.js was drawing, such as `MeshStandardMaterial for brute`.
+- **texture upload**: the time the page's texture uploads took.
+- **draw**: three.js's renders, less the compile and upload waits inside them.
+- **script**: the JavaScript outside the renders that V8's sampler caught, with the three functions it spent most in, named through the source map.
+- **garbage collection**: the collector's samples.
+- **other**: what none of those explains, the browser's own work or a wait on the GPU.
+- **GPU process**, with `--trace`: the longest task on the GPU process's main thread across the frame, such as `GPU process: the page's raster 16 ms, waiting`. That one thread runs the page's WebGL commands, the raster of its HTML and CSS and the compositor's paint in turn, so a long task of any of them holds the next frame back while the page's own frame is short; it names the `other` time. Working means the task ran on the CPU, such as the driver building a draw's vertex layout the first time a model draws; waiting means it sat on the driver or the GPU.
+- **the machine's load**: the share of every core's time busy in the second the frame ended, which a hitch line names past 70%. Other programs then take the cores the browser's threads wait for, and a slow frame there is the machine's, not the game's.
+
+V8's sampler runs from the navigation unless `--no-cpu` turns it off, and without it no frame names its script. The timeline also keeps when each frame's first callback ran, beside the time the browser handed it, and the output reads the 1% low as [the engine's overlay](/engine/ui/graphics-quality/#what-each-number-measures) reads it, over each ten seconds after the lift, on both: the median and the lowest window on the browser's time, which the overlay reads, and the median on the callbacks' own, which reads lower wherever something holds a frame's start back. The timeline's clock is the page's own, in seconds from its navigation, as `performance.now()` counts it.
+
+A frame that ends before the loading screen's fade has ended is listed apart, longest first, since no player sees it as a hitch; the frames after it are listed in the order they ran. The engine marks the lift on a page opened with `?profile`, which the profile opens; a build from before the mark gives it by the page's `[role="progressbar"]` leaving the page.
+
+The engine also marks its own events on the page's performance timeline, under `?profile` alone, so a production page opened without it marks nothing:
+
+| Mark                    | When                                                                                                       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `spawn`, `destroy`      | An entity with a model, health or a character spawns or is destroyed, named by its model where it has one. |
+| `load`                  | three's loaders let a file go, with its address.                                                           |
+| `scene`                 | A scene mounts, with its name.                                                                             |
+| `shot`                  | A weapon fires, sent to the room or fired off one.                                                         |
+| `loading stage`         | A stage of the [loading screen](/engine/structure/game/#loading-screen) passes, with its name.             |
+| `loading screen lifted` | The loading screen's fade has ended.                                                                       |
+
+A game adds its own with the browser's `performance.mark(name, { detail })`, such as `performance.mark("wave", { detail: "3" })`, and nothing else: the profile reads every mark on the page. Each hitch names the last mark in the second before it, and the output ends with the frames in the half second after each kind of mark: how many there were, their p99 and longest frame, and the programs linked there.
+
+`--drive` picks who plays:
+
+- `walk`, the default, plays the walk [Measuring a frame](/engine/testing/measuring/) describes and records after its first 7 s, as the check does.
+- `idle` plays nothing, so the world runs on its own, and records from the lift.
+- `bot` records from the lift, and plays from what the engine tells a profiled page. It turns the camera toward the nearest living entity with health but a character, fires the primary button at the middle of the screen once it looks at one, walks toward a far one and strafes beside a near one. With none in sight, it sweeps the camera and walks a loop. The engine asks an automated browser for no pointer lock and turns its camera only under one, so the bot's page reads its canvas as locked while no real lock is ever asked for.
+
+`--invulnerable` starts the game's own room with `ROOM_INVULNERABLE=1`, which gives every character the `InvulnerableTrait` trait: [`dealDamage`](/engine/behaviours/health/) leaves her be, so the bot plays on through a long run.
+
+A game whose `spawnite.room` has the mode `always` plays in a fresh room of its own, which the command starts with a heartbeat a second, and the output prints the room's steps over the recording under the page's frame times: how many it ran, a step's mean and longest milliseconds as the room timed each step without its replay checkpoint, as [`spawnite play room`'s table](/engine/testing/runs/#read-the-tables) reads them, the longest checkpoint, and its memory. `--json` and the run's file carry them as `room`, each heartbeat with the second of the recording it landed at. `--room-env NAME=VALUE` sets the room's environment over its target's, once for each setting, so a run measures the room's recording on and off with no edit to `package.json`:
+
+```text
+$ pnpm spawnite play profile --project holdfast --dev --drive bot --invulnerable --seconds 20
+Frame ms: p50 8.30, p95 8.40, p99 8.50, worst 66.60, mean 8.47.
+The room ran 1,209 steps over 20 heartbeats in 20.5 s, 59.0 a second: a step took 0.79 ms on average and 6.34 ms at the longest, without its replay checkpoints, the longest of which took 37.97 ms; 221 MB.
+
+$ pnpm spawnite play profile --project holdfast --dev --drive bot --invulnerable --seconds 20 --room-env ROOM_REPLAY=0
+Frame ms: p50 8.30, p95 8.40, p99 8.50, worst 41.70, mean 8.44.
+The room ran 1,204 steps over 20 heartbeats in 20 s, 60.2 a second: a step took 0.66 ms on average and 3.13 ms at the longest; 357 MB.
+```
+
+A heartbeat counts the steps since the one before it, and the output reads each heartbeat that landed from half an interval into the recording to half an interval past it. A run shorter than `ROOM_HEARTBEAT_SECONDS` may read none, or one heartbeat that mostly covers time outside it; set it with `--room-env` for a finer or a coarser reading. [`spawnite play room`](https://wiki.spawnite.com/platform/bots/) reads the same steps from a room its bots play with no page.
+
+`report` of several runs and `compare` set the room's steps beside the page's readings: the room step mean, the longest room step and, where the room recorded, the longest room checkpoint, each over the whole run whatever `--from` and `--to` say. A step takes well under a millisecond, so a step's time moves past a fifth and 0.1 ms rather than 5 ms. A recording room's step times leave its checkpoints out, so a comparison of runs with the recording off and on prices what recording adds to each step, and the recording run's longest room checkpoint, printed in its own output, is the rest. A run's file keeps `checkpointsIn` on its room steps, true where a room built before it timed each step without its checkpoint counted them in; `compare` and a series add a line where their runs differ in it, since the longest room step then differs by a checkpoint's time with no change in the game:
+
+```sh
+pnpm spawnite play profile --project holdfast --dev --drive bot --invulnerable --seconds 20 --room-env ROOM_REPLAY=0 --out off/1.json
+pnpm spawnite play profile --project holdfast --dev --drive bot --invulnerable --seconds 20 --out on/1.json
+pnpm spawnite play profile compare off on
+```
+
+This is what a run from the loading screen of Holdfast printed on `main` at `cdbbe9a9`, before the loading screen waited for the scene's shaders:
+
+```text
+$ pnpm spawnite play profile --project holdfast --drive idle --seconds 15
+Timeline from 0.25 to 22.32 s on the page's clock, from its navigation; the loading screen lifted at 7.16 s.
+Programs linked under the loading screen: 72, 4,754 ms waited on; after it: 26, 174 ms waited on.
+4 hitches over 50 ms after the loading screen lifted, in the order they ran; the p99 10.1 ms:
+  7.29 s  468 ms, 0.12 s after loading screen lifted: draw 6 ms, script 461 ms (getNativeRtpCapabilities mediasoup-client/lib/handlers/Chrome111.js:83 457 ms, ...), garbage collection 3 ms.
+  7.75 s  180 ms, 0.59 s after loading screen lifted: compile 148 ms on 7 programs (Material.001, MeshDepthMaterial for Root_Scene/RootNode/Cube/Cube_1, ...), draw 15 ms, script 13 ms (...).
+```
+
+When the page marked its loading stages, a line after the first names each stage with its time since the stage before it, such as `The loading screen's stages: page 0.49 s, engine 0.44 s, assets 3.12 s, world 0.52 s, shaders 1.20 s.`
+
+The next line says what the page downloaded before the loading screen lifted, which is what a player waits for, and by the end of the run: `Before the loading screen lifted, the page fetched 6,049,280 bytes in 29 requests, the player's wait; 6,049,280 bytes in 29 requests by the end of the run.` The bytes are each response's transfer size, compressed as it was sent, the page's own document among them. A response from another origin that sends no `Timing-Allow-Origin` header counts as a request of 0 bytes. A page that shows no loading screen, such as a model viewer, has no lift to read: with `--until <expression>` the profile notes when the expression held, and the line reads `Before the recording started, the page fetched ...` from that moment. `--json` carries the sums as `timelineSummary.downloads`. A series and a comparison list the same as rows, the bytes and requests before the lift (or before the recording started) and by the end of the run, where every run kept downloads; a change in bytes under 1,024 counts as the same.
+
+The sums say how much the page fetched, not which files. `--har <path>` writes every request the page made to a HAR file, with each request's URL and sizes and no response bodies, so a file the page fetched, or no longer fetches, is read from its URL. A sweep (several `--query` or `--repeat`) ignores the path and writes each run's HAR beside its run file, as `<round>.har` in the configuration's folder. To list the URLs a run requested, in the order the page asked for them:
+
+```sh
+node -e 'for (const { request } of JSON.parse(require("fs").readFileSync(process.argv[1])).log.entries) console.log(request.url)' .work/pr1.har
+```
+
+On the example, `play profile --project example --drive idle --seconds 3 --no-cpu --har .work/pr1.har` printed this, shortened to the files that matter:
+
+```text
+http://localhost:58384/?profile=
+http://localhost:58384/assets/index-DFpzlAV9.js
+...
+http://localhost:58384/assets/rapier-BhH15pMY.js
+...
+http://localhost:58384/assets/visor-bot.glb
+http://localhost:58384/assets/draco_wasm_wrapper-fZCQGLGb.js
+http://localhost:58384/assets/draco_decoder-Z1_iN-Ht.wasm
+```
+
+A change that stops a page requesting a file, such as the Rapier module on a page with no World, is proved by running this command on a HAR from before and after it and finding the URL gone from the second list. The HAR covers the whole run, so a file that only moves to after the loading screen lifts stays in the list; the bytes before the lift, above, show that move.
+
+Where a real GPU compiles a shader faster than the machine that measured it, the milliseconds shrink and the count of programs linked does not, so read the counts first.
+
+Each run writes the whole of itself, every frame and mark, to a JSON file whose path its output names: `spawnite/profile` in the system's temp folder, which keeps the newest 20, or the file `--out` names, which nothing prunes. `--json` prints the result with the timeline read in place of its frames, as `timelineSummary`. Two commands read a file again:
+
+- `spawnite play profile report <file>` prints the run again. Several files, or a folder of them, print as a series: each reading's median, its lowest and highest, and every run's value.
+- `spawnite play profile compare <before> <after>` sets two runs side by side: when the loading screen lifted, the longest frame and the programs linked under it and after it, the hitches, the p99, and each mark's longest frame. It marks each reading better or worse where a time moved by more than a fifth and 5 ms, or a count moved at all, then prints the hitches and the programs behind each reading that got worse. Each side may be a folder of runs.
+
+Both take `--hitch`, and `--from` and `--to` in seconds on the page's clock, so a run reads 78 to 90 s alone; the run itself takes them too. A threshold lower than the run's names no script, since the run kept the samples of the frames over its own.
+
+To check a change for hitches, keep a run from before it, change the game, build it, and compare:
+
+```sh
+pnpm spawnite play profile --project holdfast --drive bot --invulnerable --seconds 90 --out before.json
+pnpm spawnite play profile --project holdfast --drive bot --invulnerable --seconds 90 --out after.json
+pnpm spawnite play profile compare before.json after.json
+```
+
+The other engines answer the same question for a person at a desktop tool. Unreal's CSV profiler writes a row a frame and its report counts hitches past 60 ms a minute, Insights draws bookmarks and regions on a timeline, and Gauntlet runs a bot for either. Unity's Profiler flags frames past a target time, and its Profile Analyzer compares two captures marker by marker. Chrome's own long animation frames name the script a long frame ran, and DevTools draws `performance.mark` on its timings track. This command answers an agent in text, in the game's own terms, from the marks the engine already sets and the browser's own `performance.mark`.
+
+## Capturing your own play
+
+A headless page has no screen of the player's, so the last word on a stutter is a minute of a person's own play on their own screen. One command records it in a game's build and names each slow frame's cause:
+
+```sh
+pnpm nx build @spawnite/<game> --minify=false --sourcemap=true
+pnpm spawnite play profile --project games/<game> --headed --person --trace --hitch 12.5 --budget 12.5 --seconds 60 --out capture.json
+```
+
+The window opens fullscreen at the display's own rate, the loading screen comes up, and the minute starts as it lifts: play as you would, the page takes the mouse as a player's browser does, and Escape gives it back. When the minute is over the window closes and the output lists each frame past 12.5 ms, one and a half refreshes at 120 Hz, with what it waited on: the page's own work by part, the GPU process's task across it, and the machine's load in its second, then the 1% low as the engine's overlay reads it. `capture.json` holds the whole run for `spawnite play profile report` and `compare`, and an agent reads the same file when a player reports a stutter.
+
+`--trace` is what names the GPU process; without it the output still names the page's own parts, and `other` stands for the rest. `--url` takes a page already served in place of `--project`.