@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,285 @@
+---
+title: Playing a held session
+description: "How an agent plays a session `spawnite play start` holds as a player does, with keys, the mouse, a pad and a finger, reads what the camera sees and where a shot lands, samples a value over time, and runs a script of its own against the page."
+useCases:
+    - automate player input
+    - press keys in a playtest
+    - test on a phone sized screen
+    - simulate a gamepad
+    - check what the camera sees
+    - check where a shot lands
+    - sample a value over time
+    - record a video clip of play
+    - run my own script against the page
+    - test a game mechanic by playing
+sidebar:
+    order: 14
+---
+
+A session that `spawnite play start` holds, a game's page, a room's page or a replay played back, takes a player's input from a command: any key, each mouse button, the mouse's motion and its wheel, a pad, and a finger on a phone-sized page. Three reads answer what a player would check by eye: what the camera sees of an entity, where a shot lands against the crosshair, and how a value moves frame by frame. When no command answers a question, `spawnite play eval` runs a few lines of your own against the page with the engine's world, scene, input and time in reach.
+
+`spawnite play list`, or the MCP's `list_playtests`, names each playtest that runs for the games under the folder, with its address and what started it: `spawnite play start`, which `spawnite play stop` ends, or an MCP server's `start_playtest`, which its `stop_playtest` ends. Read it before a start, to reuse a session that runs or stop one left behind. `spawnite play start` refuses while a session of the game that it began runs, and names that session; `spawnite play start --replace` stops it and starts a new one.
+
+This page covers the input, the reads and the scripts. [Directing a moment](/engine/testing/directing/) covers opening, holding, stepping and shooting a session.
+
+## Name a control
+
+Every input command names the control a player touches. The names are the following:
+
+| Control                                    | Names                                                                                                                                                             |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A key                                      | Its `KeyboardEvent.code`, such as `KeyW`, `Digit1` or `ShiftLeft`, or Playwright's name for it, such as `Space`, `Shift` or `r`                                   |
+| A mouse button                             | `MouseLeft`, `MouseRight`, `MouseMiddle`                                                                                                                          |
+| The mouse's motion and its wheel           | `Mouse`, `Wheel`                                                                                                                                                  |
+| A standard pad's buttons, in its own order | `PadA`, `PadB`, `PadX`, `PadY`, `PadLB`, `PadRB`, `PadLT`, `PadRT`, `PadBack`, `PadStart`, `PadLS`, `PadRS`, `PadUp`, `PadDown`, `PadLeft`, `PadRight`, `PadHome` |
+| A pad's sticks                             | `PadLeftStick`, `PadRightStick`                                                                                                                                   |
+| A finger                                   | `Touch1` to `Touch10`                                                                                                                                             |
+
+Controls joined by `+` are a chord, such as `Shift+KeyW`: pressed in order and let go in reverse.
+
+## Press, hold, release and move
+
+A control stays held between commands until you let it go, and the session's time moves only when it steps or runs, as Unity's InputTestFixture and Godot's GUT hold input until the next update. So a key held across a step walks the player's character for that step:
+
+```sh
+spawnite play hold KeyW
+spawnite play step --seconds 1
+spawnite play release KeyW
+```
+
+The four commands are the following:
+
+- `spawnite play press <controls...>` presses each control and lets it go, in order. `spawnite play press Digit1` takes a card where a game binds 1 to one. Without `--hold`, the control goes down and up at once, which a game that listens for the press takes and one that reads the control held each frame, such as a trigger, misses: `--hold 0.3` keeps it down 0.3 s of the game's time, which a held session steps and a running one runs.
+- `spawnite play hold <controls...>` holds each control down until `release` lets it go.
+- `spawnite play release [controls...]` lets each control go, or with none everything held, the last held first.
+- `spawnite play move <control>` moves what moves. `Mouse --by 400,0` moves the mouse 400 pixels to the right, which turns the camera while the cursor is captured, and `--to x,y` takes a free cursor to a point on the page. `Wheel --by 100` turns the wheel a notch down. `PadLeftStick --to 0,-1` stands a stick, each axis from -1 to 1, where it stays until it moves again. `PadRT --to 0.5` pulls a trigger halfway. A finger held with `hold` slides with `--to` or `--by`.
+
+Each command prints what is held after it, and `spawnite play state` prints the same under the engine's state. `--at x,y` on `press` and `hold` presses a mouse button at a point of the page, in its pixels from the top-left corner, and says where a finger lands. `--on <subject>` on `press` presses on an entity instead: where it shows nearest the middle of what shows, the point `spawnite play see` reads, as Playwright's `locator.click()` clicks an element's middle. The subject picks one entity, and one that picks several fails naming them, as Playwright's strict locator does; so does one that shows nothing, naming why. `--page 2` sends the input to the second player's page.
+
+The MCP's `send_input` also clicks a control by its name, such as a menu's Play button, and a name that matches nothing fails naming the visible controls. A name reaches the game's own controls only: the devtools' controls, such as the Spawnite toggle at the top left, are neither clicked by name nor named in that list, so a test of the game never opens the editor by accident and what it reads is about the game. A point reaches them, `--at x,y` here or a point for `send_input`, and so does their shortcut, such as `⌘E` for edit mode. Playwright's and Testing Library's role queries see the whole page and leave the app to scope them to a region; Unity's and Unreal's UI automation address the game's own interface apart from the editor's, and this click does the same.
+
+On the MMORPG, a click on Mira walks the player's character to her and opens the talk:
+
+```text
+$ spawnite play press MouseLeft --on '[npc.name=Mira]'
+Pressed MouseLeft.
+Nothing is held. The cursor is free at (412, 301).
+```
+
+On Holdfast, a burst from her gun and a turn of the camera:
+
+```text
+$ spawnite play press MouseLeft --hold 0.3
+Pressed MouseLeft, each held 0.3 s of the game's time.
+Nothing is held. The cursor is captured: the mouse turns the camera, and a button presses at the crosshair.
+$ spawnite play move Mouse --by 400,0
+Nothing is held. The cursor is captured: the mouse turns the camera, and a button presses at the crosshair.
+$ spawnite play state
+Camera: position 4.68, 2.17, 2.32; yaw 160.0°, pitch -10.0°, fov 70°; turned 160° since the loop mounted; lock on, third person.
+```
+
+### Press what a game declares
+
+A key reaches only what the game binds to it. A press with no key, such as an ability's cast, or one that carries fields, has no key to press. Name it instead: `press`, `hold` and `release` take a name the game declares, `plugin.key`, in place of a control, and the page presses it as its key would. A press goes out through `sendPress`, as a key bound to it sends it, so a page in a room sends it to the room, which runs it on the tick her page runs it, and the corrections `play state` counts mean something. Each kind of declaration takes the following:
+
+- **A press or a plain message:** `play press` sends it once, with `--payload` as its fields, a JSON object, and `{}` where `--payload` is left out. A payload of another shape fails with the page's refusal and exit code 1.
+- **A held button:** `play press` taps it for the next step, `--hold 0.5` holds it half a second of the game's time, and `play hold` holds it until `play release`.
+- **An axis:** `play hold <name> --value -0.5` holds it at a value inside its range, and `play release` lets it back to its rest.
+- **A page action:** `play hold` runs its listeners' press and `play release` their release, as holding its key does.
+
+One command takes controls or declared names, never both. Where a message and a page action share a name, as Holdfast's `siege.ready` does, `press` sends the message and `hold` holds the action. `play release` with no argument also lets go of every declared input a `hold` holds. A name the world does not declare fails, naming every input, press, message and page action it does declare. Unreal's Enhanced Input injects an input for an action by its name the same way, rather than by its key.
+
+On the MMORPG, played alone, the mage casts Frost Nova, which costs 25 mana and cools down for 5 s:
+
+```text
+$ spawnite play press abilities.cast --payload '{"ability":"frost-nova","target":null,"request":1}'
+Sent the press abilities.cast to the player's next step: on a page in a room, the room runs it on the tick her page does.
+The tools hold no declared input.
+$ spawnite play step --seconds 2
+Stepped 120 steps.
+$ spawnite play eval "JSON.stringify(player().mana)"
+{"current":78,"maximum":100,"reserved":0}
+```
+
+### How the input reaches the page
+
+Each control reaches the page as the browser hands a player's input over:
+
+- **Keys, and the mouse over a free cursor**, go through Chromium's own input, as Playwright's keyboard and mouse send it. The events are trusted, so a focused button presses on Enter, a text box types, and a click lands on whatever stands under the cursor.
+- **The mouse while the cursor is captured** reaches the canvas as a pointer lock delivers it: every event to the canvas, at its middle where the crosshair is, with the mouse's motion in `movementX` and `movementY`. An automated browser gets no pointer lock, since one would hold the cursor of whoever runs the session, so the engine grants the capture itself, as [the engine's state](/engine/testing/agent-state/#the-engines-state) reads it in `cursor.captured`, and the input layer delivers the mouse as the lock would. A game reads the capture with `isCursorCaptured(canvas)`, not `document.pointerLockElement`, which stays empty. Replay playback delivers a recorded move the same way.
+- **A finger** goes through Chromium's touch input, every finger on the screen in each event, as a touch screen reports them. A finger stays on the screen: one moved past the page's edge stands at the edge.
+- **A pad** is a standard pad the page's `navigator.getGamepads()` returns, connected on its first use with a `gamepadconnected` event. No browser takes a pad's input from a tool yet, so the pad lives in the page, as Unity's `InputSystem.AddDevice<Gamepad>()` adds a virtual one. The engine itself reads no pad; a game that reads one does.
+
+### Inputs at moments of a step
+
+`--press` on `spawnite play step` lands inputs on moments of the step, in seconds of its game time: `control@seconds` presses a control there, and `control@from-to` holds it between the two. A press on the step's last moment or past its end fails the step, naming it, since no step is left to take it; a hold may end with the step. The session holds between the moments, so each lands on its step exactly. `--keys` holds controls down for the whole step. On Holdfast, walk forward for a second, jump at 0.3 s and fire from 0.5 s to 0.9 s:
+
+```sh
+spawnite play step --seconds 1 --press "KeyW@0-1,Space@0.3,MouseLeft@0.5-0.9"
+```
+
+A replay played on takes the input too, on top of the input it recorded, which it plays as it goes. What the page would send a room goes nowhere, so the input changes only what the page computes: its camera, its HUD and its own prediction.
+
+### A phone-sized page
+
+`spawnite play start --device <name>` opens the session's pages as a device Playwright names, such as `"Pixel 7"` or `"iPhone 15"`: its screen's size and pixel ratio, a touch screen, and a phone's coarse pointer, so the game lays itself out and picks its controls as it does on a phone. On Holdfast as a Pixel 7, the page is 412 by 839 at a pixel ratio of 2.625, `(pointer: coarse)` matches, and the camera starts unlocked. A finger dragged across the sky turns the camera:
+
+```sh
+spawnite play start --device "Pixel 7"
+spawnite play hold Touch1 --at 150,250
+spawnite play move Touch1 --by 120,0
+spawnite play release Touch1
+```
+
+## Read what the camera sees
+
+`spawnite play see [subject]` prints what the player's camera sees of each entity a subject picks, or of every entity it draws, most showing first: the share of it that shows with the rest of the scene in front, its pixels, the box they fill on the page, and its share of the screen. `--part <name>` narrows each entity to the objects inside its drawn object whose name holds the text, such as the gun in a character's hand. A part that matches nothing fails with the names the entity's meshes carry.
+
+On Holdfast, her gun from the player's camera over her shoulder:
+
+```text
+$ spawnite play see 18 --part blaster
+What the player's camera sees of 18:
+  18 (blaster-d): 97% of it shows, 3,849 of the 3,963 pixels it covers in view, in a 45 by 171 box at (313, 308); 0.7% of the screen.
+```
+
+The camera draws each entity once in a flat colour of its own, with the scene in front, and once alone, at most 960 pixels wide, as three.js's GPU picking draws. What a player sees through, glass, a flame or a glow, hides nothing behind it. A vertex shader's own motion, such as grass that sways, is left out, since the flat colour draws the mesh as it stands. Roblox's `WorldToViewportPoint` says whether a point is on screen and `GetPartsObscuringTarget` what stands in front of one; none of the engines counts the share of an object that shows.
+
+## Check a shot against the crosshair
+
+`spawnite play aim` prints where the crosshair points and each shot the page sent its room, the newest twenty, beside where the crosshair pointed as the shot left. The engine's Weapon records each shot with `recordSentShot` and each refusal with `recordRefusedShot`; a game's own weapon component calls the same two to appear here. The crosshair's point is the first thing the camera's ray through the canvas's middle meets by the engine's own reads: the targets as the page draws them and the cover a shot meets, so grass and a model's render mesh, which no shot meets, are not it. For each shot, the command prints how far its line passed that point, in metres and degrees. A shot that lands on what the crosshair shows passes a few centimetres from it at most. Where the room refused a shot, the line says under which rule and why, since a shot on the crosshair's point that the room refused dealt nothing.
+
+On Holdfast, after a burst at the ground:
+
+```text
+$ spawnite play aim
+The cursor is captured, so the crosshair is the canvas's middle: from (8.15, 2.14, 11.71) it meets cover at (8.15, 0.35, 1.52), 10.35 m from the eye.
+The shots the page sent its room, oldest first, beside where the crosshair pointed as each left:
+  Shot 0 of blaster, at the room's step 423, from (7.57, 1.08, 10.19): it passed 0.000 m from the crosshair's point, 0.00° off; the crosshair met cover at (8.15, 0.35, 1.52), 10.35 m from the eye.
+```
+
+The page keeps each shot as it sends it, in a development build alone.
+
+## Sample a value over time
+
+`--sample <expression>` on `spawnite play step` reads the expression on each frame the page draws while the step runs, as `eval` reads one, and prints each frame's value beside the world's step and the canvas's clock. A room session runs with its page at real time for it, so each frame is one a player would see; a frame that repeats the one before it, its step, its clock and its value, is left out. `--json` carries every frame as `samples`. A recoil's curve is `--sample camera.pitch` over the burst, and a hit's knockback is the monster's `transform` over the half second after it.
+
+On Holdfast, her character walking and jumping:
+
+```text
+$ spawnite play step --seconds 0.5 --sample "player()?.transform"
+Stepped 30 steps.
+Sampled player()?.transform on 143 frames, the world's step and the canvas's clock beside each:
+  frame  step    clock  value
+   3889    69  1.987 s  [7.3708,1.2729,9.3992]
+   3913    74  2.083 s  [7.4541,1.0237,9.5435]
+   3929    82  2.218 s  [7.4541,0.4835,9.5435]
+   3945    90  2.346 s  [7.4541,0.385,9.5435]
+```
+
+## A timeline after a press
+
+`spawnite play timeline <control>` presses the control, then shoots the page every `--every` seconds of the game's time, 0.1 by default, for `--seconds`, 2 by default, and tiles the frames into one PNG, each under its time. It answers the question a clip's numbers do not: which frame an effect should land on. A person reads the sheet, picks the frame where the hands are highest or the wand points, and the label under it is the second to write as the clip's `release` mark in `registerClip`, which is the ability's cast time, as [the abilities page](/engine/behaviours/abilities/#casting) says. Each frame is cropped round the player's character, where the page shows her on the first frame, so the sheet stays small; `--crop '[monster.kind=wolf]'` crops round another entity, and `--crop none` keeps the whole page, shrunk to the cell. The session is held for the sheet, so each frame is exact to its step, and a session that ran runs on after. The gap snaps to whole steps, 60 a second, and the labels count the gap stepped.
+
+`--clip <name>` plays a clip the game registered on the player's character in place of a press, so a clip with no ability yet shows its frames too, and the output ends with the `registerClip` line to write the second into, as its `release` mark. `spawnite model check` on the clip's `.vrma` prints its motion in numbers first, where the arms peak, which a mark starts from; the sheet settles it. The MCP's `timeline` tool is the same for an agent, with `keys` or `clip`. For a person to pick the frame by eye, [the model viewer](https://wiki.spawnite.com/design/model-viewer/#clips-on-an-avatar) scrubs a bundled clip with its marks drawn on the track: `tools.spawnite.com/model?avatar=chifa&clip=charged-spell-cast&marks=release:1.4`, and the time under the track is the second to write.
+
+On the mmorpg, her mage's third spell from beside a wolf:
+
+```text
+$ spawnite play timeline Digit3 --every 0.1 --seconds 2 --out timeline.png
+Saved to /…/timeline.png: 21 frames, one every 6 steps, 0.1 s of the game's time, from the press of Digit3, cropped round [controlled].
+```
+
+## Record a video clip
+
+`spawnite play record start` starts a video clip of the session's page, `spawnite play record stop` saves it, and any play command between them moves the world. The clip is the one the dev tools' Record button writes, as [the devtools page](/engine/testing/editing/#recording-a-clip) describes it: an H.264 MP4 in the game's `.spawnite/clips`, with its stills, contact sheet and `clip.json`. It runs on the world's steps, one frame a step at 1/60 s, so the video shows the game's time, with no pause while a command waits and no frame dropped: a held world waits for the encoder. Its time is not the replay's, so it keeps no replay window. Holding the world pauses the clip, so there is no pause command: a held session records nothing between commands, and `spawnite play pause` stops a running one's clip until the next `step` or `resume`. A `look`, a `set` or a `from-here` while held shows on the next step's frame, as a cut. A step that fails, such as a press past its end, drops the clip, and a pausing modal that ends the steps early ends the clip there, which the output says. A step that holds a press records the press. `--shape 9:16` letterboxes the page to a tall clip. `spawnite play record --seconds <s>` records that much of the game's time in one go, with `--press` as `play step` takes it. The stop prints the clip as `spawnite clip show` does. The MCP's `record_clip` does the same for an agent: `action` start and stop around other playtest calls, or `seconds` with `keys` held, and the reply carries the contact sheet.
+
+```text
+$ spawnite play record start --shape 9:16
+Recording 9:16 on the world's steps: each step is one frame at 1/60 s. spawnite play record stop saves it.
+$ spawnite play step --seconds 3 --press Space@0.2
+Stepped 180 steps.
+$ spawnite play record stop
+Clip 20261003-041307: 3.0 s, 1080x1920 at 60 fps, 3.7 MB.
+Sheet: …/games/sled/.spawnite/clips/20261003-041307/sheet.webp
+```
+
+Godot's Movie Maker and Unity's Recorder in its Constant mode record the same way, on the game's own fixed step rather than the wall's clock. Roblox and PlayCanvas have no recording a script starts.
+
+## Run a check of your own
+
+When no command answers a question, `spawnite play eval` runs your own lines on the page. An expression reads the engine's scope, the names below, before the page's own globals, as a browser's console does. A function is called with the scope and a promise is awaited, for 30 s at most unless `--timeout` says otherwise.
+
+| Name                                 | What it is                                                                                                                                                             |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities`, `count`, `has`, `player` | The world as `spawnite play dump` files it, as a step's `--until` reads it.                                                                                            |
+| `camera`, `loop`, `cursor`           | The engine's state, as `spawnite play state` prints it.                                                                                                                |
+| `views`                              | What each view exposes through `useInspect`.                                                                                                                           |
+| `steps`, `at`                        | The steps a step's condition has taken, and the moment a replay stands on in seconds.                                                                                  |
+| `world`, `find(subject)`             | The Koota world the page runs, and the entities a subject picks, as `dump --where` reads one.                                                                          |
+| `three`                              | React Three Fiber's state: the scene, the camera, the renderer and the canvas's size.                                                                                  |
+| `engine()`, `load(path)`             | The engine's module, and a promise of one of the game's modules by its path from the game's folder, as the game runs them: `find('[npc]')[0].get(engine().Transform)`. |
+| `see(subject, { part })`, `aim()`    | What `spawnite play see` and `aim` read.                                                                                                                               |
+| `input`                              | `press`, `hold`, `release` and `move`, as the commands above take them.                                                                                                |
+| `time`                               | `step({ steps, seconds, until })`, `frames(count)` to wait for drawn frames, and `sample(read, { steps, seconds })`.                                                   |
+
+`input` and `time` reach the director through the page, so they work on a session `spawnite play start` opened. A step from a script runs from the session's own page, not from `--page 2`.
+
+To try a camera setting with no edit and no restart, write it on the camera's own entity:
+
+```sh
+spawnite play eval "() => { const { CameraTrait } = engine(); const rig = world.queryFirst(CameraTrait); rig.set(CameraTrait, { fov: 55, shoulderOffset: 0.7, pivotRise: 0.15 }); rig.get(CameraTrait).orbit.dollyTo(2.2, false); }"
+```
+
+`--file <path>` runs a script's default export with the scope in place of an expression. The game's dev server compiles the script, TypeScript or JavaScript, and resolves its imports to the modules the game runs, so a script in the game's folder imports the game's own traits as its code does. `PlayScope` from `@spawnite/engine/devtools` types the scope. On Holdfast, this script turns to the nearest monster, fires a half-second burst and reads where the monster stands on each frame:
+
+```ts
+import type { PlayScope } from "@spawnite/engine/devtools";
+
+export default async function knockback({
+    entities,
+    camera,
+    input,
+    time,
+    world,
+    engine,
+}: PlayScope) {
+    const [x, , z] = camera?.position ?? [0, 0, 0];
+    const [key, monster] = Object.entries(entities)
+        .filter(([, traits]) => traits.monster !== undefined)
+        .map(([key, traits]) => {
+            const [mx, , mz] = traits.transform as number[];
+            return [key, { mx, mz, far: Math.hypot(mx - x, mz - z) }] as const;
+        })
+        .sort(([, a], [, b]) => a.far - b.far)[0];
+    //  Yaw 0 looks down -Z and 90 down -X, as the engine's state reads it.
+    const yaw =
+        (Math.atan2(-(monster.mx - x), -(monster.mz - z)) * 180) / Math.PI;
+    const turn = ((yaw - (camera?.yaw ?? 0) + 540) % 360) - 180;
+    //  The lock turns the camera lookSpeed radians a pixel, the other way.
+    const { CameraTrait } = engine();
+    const rig = world.queryFirst(CameraTrait)?.get(CameraTrait);
+    const pixels = -((turn * Math.PI) / 180) / (rig?.lookSpeed ?? 1);
+    await input.move("Mouse", { by: [pixels, 0] });
+    await input.hold("MouseLeft");
+    const frames = await time.sample(
+        ({ entities }) => entities[key]?.transform,
+        { seconds: 0.5 },
+    );
+    await input.release("MouseLeft");
+    return { key, frames };
+}
+```
+
+```sh
+spawnite play eval --file checks/knockback.ts
+```
+
+## What the other engines do
+
+- **Playwright** gives a page a keyboard and a mouse with `down`, `up`, `press`, `move` and `wheel`, device descriptors such as `devices["Pixel 7"]`, and a tap on a touch screen. It has no relative mouse motion under a lock, no pad, and no multi-finger touch; Chromium's DevTools protocol has the touch.
+- **Unity's InputTestFixture** presses, releases, moves and sets any control by its path, such as `<Gamepad>/leftStick`, begins, moves and ends a touch by its number, and adds virtual devices. Input waits for the next `InputSystem.Update()`.
+- **Unreal** drives its UI with the Automation Driver's sequences of presses, clicks and waits, injects gameplay input into Enhanced Input for one frame or every frame, and runs whole sessions with bots under Gauntlet. Its CSV profiler records a stat each frame.
+- **Roblox's** VirtualInputManager sends keys, buttons, mouse motion, touches and a pad's input, but only Roblox's own scripts may call it. Studio's device and controller emulators give a creator a phone and a pad, and `RunService.Heartbeat` reads a value each frame.
+
+The director takes Unity's model: named controls held between commands, virtual devices where the browser has none, and time that moves only when the session steps. It takes Playwright's names for keys and devices, which an agent already knows, and Unreal's per-frame sampling. It differs from all four in two ways. The input reaches the page as the browser would hand a player's input over, with the engine's own capture standing in for a lock. And a check that needs more than a command is a few lines against the engine's own scope, run from the command line, with no test project to build.

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

@@ -0,0 +1,71 @@
+---
+title: Editing while playing
+description: "The devtools' edit mode: the last ten seconds recorded, the free and map cameras, play-mode edits and presets, the context menu, a map preview and video clips."
+useCases:
+    - rewind the last seconds of play
+    - fly the camera freely
+    - tweak props while playing
+    - save a preset of an entity's props
+    - preview a map alone
+    - record a video clip of play
+    - delete an entity while playing
+sidebar:
+    order: 12.2
+---
+
+The devtools edit the running world, as Unity's play mode does. Each call on this page acts on `useDevtools`, the store that [the Devtools API](/engine/testing/devtools/) describes.
+
+## The recording
+
+The overlay's Spawnite toggle sets `editing`, and the overlay turns it off when it unmounts. While `editing` is on, the loop records every frame as a dump of the world, keeping the last ten seconds. `recordedFrames` counts them, and `seek(frame)` reads one, where 0 is the oldest kept. `setEditing(false)` drops the recording. Seeking reads a frame; it does not move the world. Rewind, resuming from a scrubbed frame, is a later issue.
+
+`setFreeCamera(true)` puts `FreeCamera` over whatever camera the scene mounts, the engine's or the game's own, and the character stands still while the movement keys fly it, as Unreal's eject does. Game mounts it inside the canvas, so a scene with no camera gets one too. The scene's camera stays mounted with its controls turned off, and the free camera's view is what draws, whatever the scene's camera writes to the canvas camera each frame. The free camera takes every other camera's entity out of the world until it goes, one a scene mounts meanwhile included, so the world reads the free camera alone. `setFreeCamera(false)` gives the scene's camera back, and so does leaving edit mode.
+
+`setMapCamera(true)` puts `MapCamera` over the scene's camera the same way, the city builder's camera over the map, and turns the free camera off, as `setFreeCamera(true)` turns the map camera off; either way the character stands still. It sets `mapFlight` too, which the map camera reads once its orbit stands: one eased camera-controls move from where the eye is to the pose `readMapFlight(eye, aspect)` gives, the whole map from 80° above on the side of the map the eye stands, framed by `frameShot` from the active map or, with none, from the bounds the view draws, at `mapCameraSettings.flightZoom` so it lands closer than the frame that fits every corner; `setMapCamera(true, zoom)` lands at a zoom of its own, as `spawnite play profile --map-camera <zoom>` asks for one. The camera calls `endMapFlight()` when the move settles, or at once where nothing is mounted to frame or the eye already stands there. `setMapCamera(false)` and leaving edit mode clear the flight too. The map camera pans by `mapCameraSettings.panShare` of the eye's distance a second, turns at `turnRate`, and tilts `tiltPerDoubling` for each doubling of the distance the wheel or a pinch makes. The free camera flies at `freeCameraSettings.metresPerSecond`, and `isBoostHeld()`, either Shift, multiplies that by `freeCameraSettings.boostFactor`.
+
+`readPalette()` is the Assets section's content: `models`, every registered model with its url, its height from the manifest's capsule and how many entities carry a `ModelTrait` trait naming it; `avatars`, every registered avatar and every name an `AvatarTrait` trait carries, with how many characters wear each; `scatter`, the six kinds with the file each draws and how many placements every ground stands of it; and `shapes`, the four prop shapes. `selectPlaceable(placeable, adding)` selects the rows of every entity drawing the model or wearing the avatar, or the scatter kind's counted row under every ground that stands it; `adding` adds them to the selection without removing any; a shape or a placeable nothing draws changes nothing. A press on a model's, a scatter kind's or a shape's card also calls the terrain editor's `holdCard(placeable)`, which the next paragraph covers. `readModelThumbnail(url, options)`, exported from the engine's root as well, renders the model or avatar file once on a shared offscreen renderer with a transparent background, two renders a frame at most, and keeps the PNG data URL for the page's life; its options are `size` in pixels, `framing`, the whole model or its face, `yaw` to turn a file whose front is not +z, and `clip`, a VRMA to pose an avatar in, where a model poses in its file's idle clip; `readModelSilhouette(name)` is the manifest hull's outline from the front, for the card to show before the picture lands.
+
+`useTerrainEditor` is the store of the Map section's Terrain section, apart from `useDevtools` and exported beside it. `readMapChoices()` lists every registered map, each marked `mounted` where a World shows it, and `openMap(name)` shows that map alone as `?map=` does, writes it in the address and starts the undo list again. `holdTool("sculpt" | "smooth" | "flatten" | "paint" | "fill" | "scatter" | null)` picks a tool up, which turns the map camera on unless the map or the free camera is on already, and turning the last of them off, or leaving edit mode, puts it down. `mode` is the cursor's mode, `"select"`, `"terrain"` or `"look"`, which no control picks yet, which decides whether a click in the game selects: a tool in hand is `"terrain"`, putting it down turns `"terrain"` to `"select"`, and `setMode(mode)` sets it, `"select"` and `"look"` putting the tool down. `setBrush({ radius, strength, shape })` keeps the brush within `terrainBrushLimits`, and the browser keeps it for the next session, as it keeps `lower`, which `setLower(true)` sets so Sculpt lowers the ground and a stroke begun with Ctrl held flips. `readSea(map)` is the map's sea as the page shows it: the map's `sea`, else 1 m below the lowest point of its base. `previewSea(map, height)` shows a drag of the Sea field's label in `seaPreview`, which the sea's plane follows at once, and `setSea(map, height)` keeps it as one undo step that `save()` writes as one `sea` post to `/__map`. With no tool in hand, Alt and a click on the ground sets the sea to the height there. `readPaintMaterials(map)` lists the materials Paint can lay, each with its family, the row the editor shows it in, its colour texture in the game's set, null in the flat set, its swatch colour and its tint, `setMaterial(name)` picks one and holds Paint unless Fill is in hand, and `pickMaterial(surface, [x, z])` picks the one under a point, as Alt and a click does. `beginStroke`, `extendStroke` and `endStroke()` are what the brush in the canvas calls: each move applies only the dabs it adds, with the engine's `beginTerrainStroke` or `beginPaintStroke`, which leaves the preview equal to the whole stroke painted at once, and a point that repeats the last, as a held brush sends, dabs again; the end registers the page's terrain with the stroke in it and keeps its change as one step of `undoSteps`; every write is made against the map's revision the page stands on, which `readMapRevision(map)` answers. `undo()` and `redo()` show the step's exact values again. Every edit sets `unsaved`; `save()` writes the points, cells and materials the edits since the last save touched, as one `restore` to `/__map` and one `restoreMaterial` for each material, `revert()` shows the file again as one undo step, and `resetToBase(map)` writes the map's base at once as one undo step. A `spawnite:terrain` window event from the dev server for a revision the page did not write goes to `followOutsideWrite(map)`: with nothing unsaved it reloads the file, clears both lists and sets `notice`, which the section shows, and over unsaved edits it sets `changedOnDisk`, as a Save refused as older does; `save({ anyway: true })` lays the edits over the file as it now stands and writes them. A Save refused over a moved base sets `baseMoved`, and `settleBase("keep-heights" | "move-with-ground")` settles it and saves again. With Fill, `beginStroke` and `extendStroke` take the rectangle's two corners and `endStroke()` keeps it as a fill; `fillRegion(map, region)` fills one of `readMapRegions(map)`. `setScatter({ families, action })` picks the families Scatter paints and whether it grows them toward double, which grows back what was erased, thins them toward half or erases each instance under the brush by its spot, `"more"`, `"thin"` or `"erase"`, holds Scatter, and the browser keeps it. `makeEditable(instance)` takes a scattered instance's `placement` from `describe`, writes a prop of its kind where it stands, named such as `tree1`, and erases the seeded one, as one undo step, and answers the name; `removeScattered(instance)` erases one instance, as the ground menu's Remove this does, as one step; `moveProp(map, name, [x, z])` and `removeProp(map, name)` move and delete a prop, each one step. `findScatterPropRow(map, name)` is the row of the instance a prop stands as, once the ground stands it. `setClear(true)` makes Paint and Fill hand cells back to the rules, `setLevel(height)` sets Flatten's level until `setLevel(null)` returns to auto, leaving it as it is for a number that is not finite, as a field's bad text parses to, `pickLevel(surface, [x, z])` sets it to the ground's height under a point, as Alt and a click with Flatten does, and a height stroke's preview names in `level` the height it levels to, and `resetHere(map, surface, [x, z])` hands the points and cells under the brush back to the base as one undo step. `previewMaterial(map, name, look)` shows a change to a material's look while a slider drags, `refineMaterial` keeps it as one step of `undoSteps` back to the look before the first preview, `duplicateMaterial(map, name)` makes a new material from it and holds it as one step, whose undo takes it out and holds `name` again, and `readMaterialLook(map, name)` reads its tint, `tintAmount`, tile, bumps and wet. `preloadCard(placeable)` starts loading a model card's model, as a mouse resting on the card or focus reaching it does, and `holdCard(placeable)` picks an Assets card up, as a press on it does, and loads its model too: it puts the tool down, sets `mode` to `"select"` and turns the map camera on as a tool does, and `card` holds it until `holdCard(null)`, Escape, leaving Assets or the last camera going off puts it down; a tool picked up puts it down too. `placeCard(map, [x, z])` stands the card in hand there as a prop of the map, `{ model }` for a model, `{ kind }` for a scatter kind or a shape, at the spot rounded to the centimetre, named after the card, `villager`, then `villager-2` where that name stands, and keeps it as one step of `undoSteps`, shown at once through `registerMapProps` and unsaved; it returns the name, or null with no card in hand or an avatar's. `save()` writes every prop placed, made editable, moved or taken out since the last save as one `props` post to `/__map`, which writes through `writeMapProps`, the writer `spawnite map place` uses, and `revert()` takes them back with the rest. In the canvas, the card in hand draws its footprint in the brush cursor's look under the pointer, a metre's square for a shape and a model's measured radius otherwise, and a still click places it, then selects its row once the World draws it; a drag still moves the map camera, and the click selects nothing else. `pickGroundSpot(x, y)` reads the ground under a canvas point as `pickRow` takes one, with the map, its surface, `cellMaterial`, the cell's own material that the menu's Duplicate and Wet act on, and `scattered`, the seeded instance in front of the ground there, which the menu's Remove this erases, and `readGroundSpot(surface, [x, z])` reads a point's height, slope in degrees and material as `spawnite map query` answers it: the ground's right-click menu reads both.
+
+## Play-mode edits
+
+Everything below that changes the world, an edited prop, a hidden or deleted entity, an added behaviour, acts on the running world and is gone on reload, as an edit in Unity's play mode is. The scene's code stays the source of truth, and two paths turn an edit into code. Send to agent puts the edit in the bundle. Copy as prop, on a card whose row names the prop its component takes, copies the changed fields as that prop, `movement={{ speed: 7 }}`, for you to paste. An edited card reads "Tried, not saved" until then. Unity's play mode discards its edits on exit, and Unreal keeps them only through Keep Simulation Changes; the copy is the same step for a component written in code. Duplicate takes that path too: it opens Send to agent with the intent "Add another beside this one", because a copy made in the world would have no component to draw it and no row.
+
+## Editing a behaviour's props
+
+`setProp({ id, name, value })` writes one prop of a behaviour row onto its trait through `set`, so every subscriber hears it. A row that adds two traits, as Chase does, writes the one whose schema has the field. The row records the write under `edits`, so the inspector marks the behaviour changed and shows the edited value, and `resetProps(id)` drops the edits and puts the component's own props back on the trait. A prop that holds a function cannot be set, and a prop is set only to a value of its own type, so a typed-over array or number never reaches a trait as text. A number is clamped to the row's declared range.
+
+On a room's replica, an entity the room streams is the room's. Where the room's welcome says it takes edits, `setProp` also sends the room an `edit` message: the entity's dump key, the trait's dump name, the prop and the value. The room writes it, clamped to the range the trait's behaviour declares, and the write streams back to every client. The devtools' hour and day length fields, and Jump to, go to the room the same way, as edits of its streamed clock's `dayClock` trait: the room wraps the hour into the day, as `setTimeOfDay` does, and refuses a length the clock cannot run on. Where the room refuses, every row of a streamed entity over a trait with a dump name is read-only, greyed with "The room keeps its settings", and so are the World card's hour and day length and Jump to. A row over only traits with no dump name stays editable: the room never streams them, so nothing overwrites the edit. A room takes edits only when started with `allowEdits` or `ROOM_EDITS=1`, a development room: Roblox lets a client write its own `WalkSpeed`, the classic speed hack, and Unreal keeps movement on the server.
+
+When the component renders again with the same props, the edit stays: the behaviour hook sets the trait only when the props' fields differ from the ones it last wrote. A changed prop wins and the edit goes, which is React DevTools' rule for an overridden prop. Headless, no component has mounted, so there are no rows to edit; a test sets the trait itself. Cost per frame: none; a shallow compare per render of the behaviour.
+
+## Presets
+
+A preset is a named set of the props one entity's behaviours hold, saved under the entity's component name, so a preset saved on one Coin applies to every Coin. `presets` lists the names for the selected row's component. `savePreset(name)` takes the selected entity's props as they stand, and `applyPreset(name)` writes them through `setProp`. Each behaviour's props are kept under its name, as a list in the entity's order where it has two of one kind, so each applies to its own row; a read-only row is left as it is, and so is a field a stat sets, so a preset saved before the stat existed still applies the rest. The Stats component's row is neither saved nor applied, since its stats are not props. `preset` names the last applied on the selected row. Presets persist in the browser's storage under the game's name, as the save does, and a test builds the store over a map. Unity's Preset assets are the shape; the other engines have none. Cost per frame: none.
+
+## The context menu's actions
+
+The overlay's menu offers actions the store carries out. `readDisabledActions(id)` says why an action is off for a row, by action, and the menu shows the reason; an action called while off throws it. The actions are the following:
+
+- `focusCamera(id)` flies the mounted orbit to the entity, at the distance that fits its model's bounds, with a transition, and sets the camera's `follow` to null so the frame's aim stops pulling the eye back to the player. Leaving edit mode puts the follow back. Off with "No camera is mounted" or "Nothing draws it". In Unity, Unreal, Godot and Roblox Studio, F moves an editor camera; the game has one camera, so it stops following instead.
+- `hide(id)` and `show(id)` flip the entity's object's `visible`, and `hiddenIds` lists the hidden rows. The frame loop applies it again after the transforms sync, so a model that loads later stays hidden, and `pickEntity` skips a hidden object. Physics and behaviours run on, as under Unity's scene visibility and Unreal's H key: the view is hidden, not the entity. Off with "Nothing draws it".
+- `deleteEntity(id)` destroys the entity. `Entity` and `Player` see their entity go and take its children and its row down. Off with "The world" and "The camera's rig", whose components do not watch for that.
+- `addBehaviour(id, name)` adds a registered behaviour's trait with its defaults and registers a row for it under the entity, which goes when the entity does. `behaviourOptions(id)` lists what the entity can take: each behaviour `defineBehaviour` made that it lacks, with the `description` it declares as its summary. The engine defines Spin, Bob, Pickup and Health. A behaviour whose component does more than add the trait, as Interact draws its prompt and listens for E, Trigger fires its callbacks and Chase adds a body, is not offered, because its trait alone would run half of it; it puts its trait in the dump with `defineTrait`. Off with "Has every registered behaviour".
+- `playFromHere([x, y, z])` is the ground's menu's Play from here: it stands the player's character at the point, at rest, facing the way the camera the page draws with looks, turns the scene's orbit to the same yaw, so a camera that follows the character starts behind them, moves the character out of any prop the point stands inside, then leaves edit mode and resumes. In a map preview, which has no character, it sets `previewPlayer` to the point and the yaw instead, and the preview mounts `<PlayFromHere position facing>` there: the game's own component that rendered its last mounted `<CharacterSpawn>`, such as a `Spirit` that wraps it, with its props and what it draws beside the Player, or, where the scene wrote the `<CharacterSpawn>` in its World directly, a `<CharacterSpawn>` with the props it took, its children among them; under the last `<Camera>`, `<SideCamera>` or `<ChaseCamera>` that followed one, with its props; or the engine's defaults where the Game has mounted none. Its `<CharacterSpawn>` spawns at the point and the yaw whatever the game's component hands it, which takes them too as `position` and `facing` unless its own `position` is another shape than `[x, y, z]`, such as a `Vector3`, and with the default respawn comes back there when it falls; once the character's body is built, it is moved out of any prop it spawned in. A component that mounts a camera of its own beside the `<CharacterSpawn>` keeps it, and no other is added. `readPlayFromHereReason()` says why it is off, which is also what it throws: "No player in this scene" in a game scene with no character, such as a lobby, or "The room places the player" on a room's replica. An agent makes the same move with `spawnite play from-here --at 4,-2`, which reads the ground's height under the point and calls it, and `--map <name>` opens another map in its preview first, as the terrain editor's `openMap` does; the session stays held. A room places its players, and there `spawnite play set '[controlled]' transform.position '[x,y,z]'` has the room move her. Unreal's Play From Here and Roblox Studio's Play Here start play with the character at the clicked point; Unity and Godot have none.
+- Duplicate goes through Send to agent, as above. Copy id, Inspect, Select parent and Send to agent are the overlay's own.
+
+Every action is a call on the store, so an agent's what-if is the same call: delete a coin, add Spin, `stepUntil`, then screenshot. Headless, focus and hide report their reason. Cost per frame: none for focus and delete; one visibility write per hidden entity.
+
+## Previewing a map
+
+In development, `?map=<name>` in the URL shows that registered map alone: the overlay registers a `map-preview` scene holding a `<World map={name}>` and a camera the page drags, and goes to it. No player spawns until `playFromHere` asks for one, and every `<Hud>` draws nothing while `mapPreviewScene` is the active scene, so a readout the game mounts outside its scenes stays off the map. The game's start scene mounts first, because the overlay loads after it, and then gives way. The terrain editor's `openMap(name)` shows another map the same way, with no reload. The overlay exposes both through [`useInspect`](/engine/testing/agent-state/#a-views-own-state) as the page's `map preview` view, `maps` from `readMapChoices()` and `open` as `openMap`, which is how `spawnite play from-here --map` reads the game's maps and opens one: `spawnite play eval "views.page['map preview'].maps"` lists them. `frameView("map")` then frames the whole preview from above.
+
+## Recording a clip
+
+The top bar's Record button, or F9, records what the canvas draws as a clip, a short video for marketing a mechanic, a move or a fly-over, and a second press stops it. A clip stops by itself after `maxSeconds`, and the dev server keeps up to `keep` clips, refusing a new one past that rather than deleting one; the game's `vite.config.ts` changes either through the engine's plugin:
+
+```ts
+spawnite({ clips: { maxSeconds: 10, keep: 20 } });
+```
+
+The defaults are 30 seconds and 50 clips. The page hands the canvas to [Mediabunny](https://mediabunny.dev/), which encodes it as H.264 through the browser's WebCodecs and keeps the MP4 in memory until the clip stops, at 1920 by 1080, or 1080 by 1920 for the Clips section's 9:16, about 15 Mbps and 60 frames a second, with a keyframe every half second and no audio. The canvas letterboxes to the chosen shape while it records. The video holds the canvas alone, so the devtools and the HUD stay out, and so does what the editor draws into the canvas, such as the brush's cursor, the ability rings, the hit zones and the navmesh: each draws inside `EditorDrawing`, a group from `@spawnite/engine/devtools` that hides while a clip records, and a game's own debug drawing wraps itself in it to stay out too. At the stop the page decodes up to 30 stills from the finished video, draws the contact sheet, and posts it all to the dev server once. The dev tools close while a clip records and Record waits beside the Spawnite toggle. A clip also saves the replay's window as `.replays/saved/clip-<name>`, on a page whose replay records a room's play, so a later tool can play the moment back. [The dev server page](/engine/testing/dev-server/#the-folder) says what a clip's folder holds, and `spawnite clip show <name>` and the MCP's `read_clip` read it. An agent records the same clip from a held session with `spawnite play record`, or the MCP's `record_clip`, on the world's steps, as [the director page](/engine/testing/director/#record-a-video-clip) says.

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

@@ -0,0 +1,146 @@
+---
+title: Errors and bug reports
+description: How to read an error the engine makes, look its code up offline, name the engine's frames in a stack, and write a bug bundle when the engine itself fails.
+useCases:
+    - an error from the engine
+    - what does this error code mean
+    - error code SP
+    - the engine crashed
+    - report a bug in the engine
+    - stack trace with minified frames
+    - symbolicate a stack
+sidebar:
+    order: 2
+---
+
+The engine's core ships minified, so its own function names are gone from a stack. To make up for them, every failure the engine sees carries what you can act on: a code for each error the engine makes, a line that names where the failure happened, and two `spawnite` commands that name the engine's frames and write a bug report. This page shows how to read each of them, and what to do when the engine itself is at fault.
+
+## Read an error the engine makes
+
+Every error the engine makes ends its first line with a stable code, such as `[SP0077]`, and carries the same code as `error.code`. A code keeps its meaning in every version: a message whose words change takes a new code. The message itself says what was asked, what was wrong and what to change.
+
+The engine labels a failure at four boundaries, where it leaves your code or the engine's work and reaches the engine: a system's run in the step, a render of one of the engine's components, a frame callback, and the connection to the room. When an error crosses one, a second line follows the message. It starts with `Spawnite:` and names what the engine knew of the failure:
+
+- **system**: the system that ran, by its `plugin.system` name, such as `dashes.coolDashes`.
+- **component**: the engine's component whose render threw, such as `<Entity>`.
+- **frame**: the frame callback that threw, by the component or hook that owns it.
+- **room**: what the connection to the room was doing, such as `message from ws://localhost:5174`.
+- **tick**: the tick the step ran.
+- **call**: the engine call that threw: a public export your code called, such as `startCooldown`. Only an error the engine makes, with a code, names it.
+- **entity**: the entity the call was given, by the key the dump files it under and the name a player reads for it. `describe_entity` takes the key. Only an error the engine makes names it.
+- **page**: the code's page in the engine you installed.
+
+The following plugin passes the cooldown it is given to `startCooldown`:
+
+```ts title="packages/engine/test/outside/dashes.ts"
+import type { World } from "koota";
+import {
+    createQuery,
+    defineCooldown,
+    definePlugin,
+    defineTrait,
+    readEach,
+    startCooldown,
+} from "@spawnite/engine/core";
+
+/** An entity that dashes: each step it dashes, the dash cools down. */
+export const DasherTrait = defineTrait("dasher", { dashing: false });
+
+const dashers = createQuery(DasherTrait);
+const dash = defineCooldown("dash");
+
+/** Dashes that each cool down for `cooldownSeconds`: list it after
+ *  `cooldowns()`, which counts the cooldowns down. */
+export function dashes(cooldownSeconds: number) {
+    function coolDashes(world: World) {
+        readEach(world, dashers, ([dasher], entity) => {
+            if (dasher.dashing)
+                startCooldown(entity, {
+                    key: dash,
+                    seconds: cooldownSeconds,
+                });
+        });
+    }
+    return definePlugin({ name: "dashes", systems: { rules: { coolDashes } } });
+}
+```
+
+With `plugins: [cooldowns(), dashes(0)]` and a dasher named Ada, the first step throws this error:
+
+```text
+startCooldown: the cooldown "dash" has 0 seconds; pass seconds above 0, or start none [SP0077]
+Spawnite: system dashes.coolDashes, tick 0, call startCooldown, entity 3 "Ada", page @spawnite/engine/dist/wiki/engine/errors/SP0077.md
+```
+
+A test asserts the refusal by its code, which stays the same when the message's words change: `expect(thrown).toMatchObject({ code: "SP0077" })`.
+
+A development world stops at the throw. A room the platform hosts keeps running, undoes the rest of that system's tick, and logs each throw with its system, its tick, its code, its call and its entity.
+
+## Read an error with no code
+
+An error with no code, such as a `TypeError`, is one the engine did not plan for. Its `Spawnite:` line names the boundary, such as `system characters.movement, tick 412`, but never a call or an entity: the engine names those only for the errors it makes. Its own message says only what JavaScript saw. Name its engine frames with `spawnite symbolicate`, below, to find the engine call it ran in.
+
+## Look up a code offline
+
+Each code has a page that ships in the engine's package, matched to the version you installed. Open it from the game's folder:
+
+```text
+node_modules/@spawnite/engine/dist/wiki/engine/errors/SP0077.md
+```
+
+`node_modules/@spawnite/engine/dist/wiki/engine/errors/index.md` lists every code with the engine call it is thrown in. Each page holds the message, with `%s` for each value it names, and the call's entry, whose declaration says what the call requires.
+
+## Name the engine's frames in a stack
+
+A stack through the engine's core shows mangled frames, such as `at Oe (.../@spawnite/engine/dist/BMUQtXzM.js:1:2051)`. To name them, save the stack to a file and run `spawnite symbolicate`:
+
+```sh
+spawnite symbolicate stack.txt
+```
+
+The command sends each engine frame, and nothing else of the stack, to the platform. The platform resolves each frame to the public engine call it ran in, never to a source line, and the command prints the stack with those frames named:
+
+```text
+The game called startCooldown, which failed inside the engine, from: at cool (src/systems/dash.ts:12:9)
+
+    at [engine, in startCooldown]
+    at cool (src/systems/dash.ts:12:9)
+    at [engine, its own work]
+    at [engine, in stepWorld]
+```
+
+Each engine frame prints as one of the following:
+
+- `[engine, in startCooldown]`: a frame inside that public export, whoever called it. The summary line above the stack is the one that names the call your game made.
+- `[engine, its own work]`: a frame no game calls by name.
+- `[engine 0.1.0, a file its index does not hold: ...]`: a file the platform's index for that version lacks, such as a build from somewhere other than a release.
+
+When no engine frame sits next to one of your own, the summary says that none of the engine's frames is a call the game made by name.
+
+Your game's own frames stay as they are, since they map to your own source. Of each engine frame, the command sends the engine's version, the file's name inside the engine's package, and the line and column; nothing else of the stack leaves the machine. It reads frames of the engine's package, of a published page's engine release, and of the dev server's prebundled engine. `--json` answers the same as fields. It needs `spawnite login`, and resolves up to 60 stacks an hour.
+
+## Decide whether the engine is at fault
+
+Most errors name a mistake in the game, and the message says the fix. Suspect the engine when one of the following holds:
+
+- The error has no code, and its frames are all the engine's, such as a `TypeError` whose frames are all `[engine, its own work]`.
+- The system that failed belongs to one of the engine's plugins, one your game imports from `@spawnite/engine`, such as `characters()`, rather than one in your game's `src/`.
+- The call's declaration says your use is allowed, and the error says otherwise.
+- The same input gives a different result on the room and on the page, which `spawnite replay check` shows.
+
+## Write a bug bundle
+
+When the engine is at fault, write a bug bundle from the replay of the failure. A bundle comes from a replay, which a game's dev page and dev room keep as it plays: a failure a test found is played once on the dev page first, so a replay holds it. `--from` and `--to` take moments as the replay reads them, seconds into it or a mark such as `m1`, not ticks.
+
+```sh
+spawnite bugreport latest --stack stack.txt --note "The dash froze the room."
+```
+
+The bundle is a folder that holds the following files:
+
+- `clip/`: the replay, or the window `--from` and `--to` name, with the room's checkpoints, so the platform's team plays it back and continues it against the engine's source. It holds each player's name and input, what each page showed, and the world and the saves the game kept.
+- `log.json`: the replay's log in that window.
+- `bundle.json`: the engine's and the cli's versions, the plugins `src/game.ts` lists, the step the room composed where the replay kept one, the Node version and the operating system, and your note.
+- `error.txt`: the stack you passed with `--stack`.
+
+Nothing leaves the machine, and the cli has no step that sends a bundle. The command prints what each file holds: show the creator that list, and attach the folder to their report to Spawnite only once they agree. [Replay](/engine/testing/replay/) says how a game keeps its replays.