@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/testing/dev-server.md

@@ -0,0 +1,101 @@
+---
+title: Dev server
+description: The routes a game's Vite dev server answers under /__ for the devtools page and the agent's tools, the .spawnite folder they write, how a message sent from the devtools reaches the agent, and how the agent's tools reach the creator's own tab.
+useCases:
+    - how devtools save changes to a game
+    - development server routes
+    - save map edits to a file
+    - capture a screenshot in development
+    - message from devtools to agent
+    - agent tools reach my browser tab
+    - where the spawnite folder is
+    - add a dev route
+sidebar:
+    order: 15
+---
+
+A game's Vite dev server answers a few routes of its own beside the page, under `/__`, from `@spawnite/dev-server`: one [Hono](https://hono.dev) app that a game's Vite config adds as a plugin beside the engine's. The page posts to them. Everything they save lands in the game's `.spawnite/` folder, which is git-ignored, where the agent's tools and hooks read it, except `/__map`, which writes the map editor's strokes into the game's own map file.
+
+Roblox Studio, Unity and Unreal keep the editor and the game in one process, so a panel that wants a file writes it, and Godot's editor talks to a running game over its own debugger protocol. A Spawnite game runs in a browser with no editor, and its agent runs in a terminal, so the dev server is the one process both can reach: the page over HTTP, the agent over the folder.
+
+## Mounting the routes
+
+A game's Vite config mounts the routes with `devServer()`, beside the engine's `spawnite()`:
+
+```ts
+// vite.config.mts
+import { defineConfig } from "vite";
+import { spawnite } from "@spawnite/engine/vite";
+import { devServer } from "@spawnite/dev-server/vite";
+
+export default defineConfig({ plugins: [spawnite(), devServer()] });
+```
+
+`spawnite create` writes both into a new game's config and installs `@spawnite/dev-server`. A game under the repository's `games/` imports the plugin by its source path, `../../packages/dev-server/src/vite.ts`, and resolves the server's modules through the `@spawnite/source` condition under `ssr.resolve.conditions`, as `games/example` does. Without the plugin, Vite answers each `/__` request with the game's page or an empty 404: the devtools' map editor says the server has no map endpoint and keeps its edits, and the agent's tools find no server.
+
+## Routes
+
+| Route                    | Body                                                                                                                                                   | Reply                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /__shots`          | `{ png }`: a PNG data URL, up to 16 MB                                                                                                                 | `{ file }`: its path under `.spawnite/shots/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `POST /__chat`           | `{ text, shots, attachments }`: markdown, the files `/__shots` answered, and the rows `{ id, label }` it carries                                       | `{ file }`: its path under `.spawnite/chat/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `GET /__tab`             | none, with the server's token                                                                                                                          | `{ tabs }`: each open tab of the game                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `POST /__tab`            | `{ expression, timeoutMilliseconds }`, with the server's token                                                                                         | `{ tab, value }`: the value, awaited                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `GET /__clips`           | none, from the dev server's own page                                                                                                                   | `{ clips, maxSeconds, refusal }`: each clip the game keeps, newest first, as `{ name, folder, meta }`, `meta` being its `clip.json`; the clip limit in seconds; and why a new clip would be refused, once the game keeps its `keep` clips                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `POST /__clips`          | a form, from the dev server's own page: `meta`, the measured clip as JSON; `video`, the MP4; `sheet`; and `frames`, the stills                         | the clip's `clip.json`, named for the local time it started, with the replay window's events and its saved name, or a 409 once the game keeps its `keep` clips                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `DELETE /__clips/<name>` | none, from the dev server's own page                                                                                                                   | `{ removed }`: the clip's folder and its saved replay window gone                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `GET /__map?map=<name>`  | none, from the dev server's own page                                                                                                                   | `{ terrain, revision }`: the map file's `terrain` block, null where no brush edited it, and the map's `revision`, 0 before its first write, which every POST is made against                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `POST /__map`            | `{ map, revision }` with one of `stroke`, `fill`, `restore`, `settle`, `material`, `restoreMaterial`, `props` or `sea`, from the dev server's own page | `{ file, revision, change, terrain }`, `revision` being the map's after the write: the stroke, the fill, the undo or the settled base written under `terrain` in `src/maps/<map>.json`; for `material`, one entry of the map's `materials` written over the file's field by field, and for `restoreMaterial` an undo's entry written back whole, null taking it out, each answering `{ file, revision, materials }`; for `props`, each named prop written into the map's `props` and each null one taken out, answering `{ file, revision, removed }` with the names it took out; for `sea`, the map's `sea` height in metres written, answering `{ file, revision, sea }` |
+
+A refused body answers `{ error }` with a 400 that names the field, and an unknown `/__` route a 404. `/__clips` and `/__map` answer only a request whose `Sec-Fetch-Site` is `same-origin`, which a browser sends from the page itself and no other site can forge, and a 409 to any write made against another `revision` than the map's, which every write counts; the [map editor](https://wiki.spawnite.com/design/map-editor/#saving) page describes the writer. `/__chat` takes a shot only from the game's own `.spawnite/shots/`, since the agent reads each one back as an image. Vite's own routes start with `/@`, so nothing overlaps.
+
+## The folder
+
+```text
+<game>/.spawnite/
+  shots/    every screenshot any tool saved: the page's, the playtest's
+  chat/     one JSON file a message, unread
+  chat/read/  the same file once an agent has read it
+  servers/  <port>.json for each dev server that listens: { url, token, pid }
+  clips/<name>/  a recorded video clip, named by the local time it started
+    clip.mp4     H.264, written once the clip stops
+    sheet.webp   the stills as one contact sheet, 6 to a row, each labelled
+    frames/      up to 30 stills, 768 px wide, evenly spaced: 00.webp, 01.webp
+    clip.json    the clip's size and length, each still's moment, the replay's
+                 events in its window, the saved replay window and warnings
+```
+
+A clip's video is served by Vite as any file under the game's folder, `/.spawnite/clips/<name>/clip.mp4`, with range requests, so the Clips section plays it with no route of its own. The page holds a clip in memory and saves it whole as it stops, writing `clip.json` last, so a folder without one is no clip, and a page closed mid-clip saves nothing. Every time in `clip.json` is milliseconds from the clip's first frame.
+
+A file is written under a temporary name and renamed into place, so a reader never sees half of one. A file's name is the moment it was written, so a listing sorts oldest first, and a message and its screenshot carry names a few milliseconds apart.
+
+## The message
+
+A message on disk is an MCP tool result, the shape every MCP client already reads, validated with the SDK's own schema: a text block holding the markdown, a `resource_link` block per screenshot with a `file://` URI and `image/png`, and `structuredContent` with the game's folder name, when it was sent and the rows it carries. The agent's `read_chat` returns it almost as it is, with each linked screenshot read into an image block.
+
+## How a message reaches the agent
+
+Four ways, from the cheapest up:
+
+- **Hooks**, with no setup. In this repository, `.claude/settings.json` runs `spawnite chat pending` on three Claude Code events; the Spawnite plugin's own hooks do the same in any game folder. On `Stop`, when the agent finishes a turn, an unread message blocks the stop and becomes what the agent works on next. On `UserPromptSubmit` it rides beside what the person typed. On `PostToolUse` it rides beside a tool's result, so a message sent mid-task lands within seconds. With nothing unread the hook prints nothing and costs a shell glob. The hook reads the games under the session's own folder, so each worktree's dev server talks to its own session, and it skips a subagent's call, so a worker never takes a message meant for the session.
+- **`read_chat`**, for an agent without the plugin: the unread messages of every game in the session, marked read, and `wait: true` holds the call until one lands, up to 110 seconds or the `timeoutSeconds` given. An agent told to listen calls it that way over and over, so a message sent while it would otherwise sit idle lands at once.
+- **`spawnite chat list`**, for a person: what is pending, with `--all` for what was read.
+- **A channel push**, the moment a message lands, for a Claude Code session started with `--dangerously-load-development-channels server:spawnite`. The flag is Claude Code's own gate on every custom channel; without it the message waits for the hooks.
+
+Unread and read share one cursor, the folder a file sits in, so the hooks, `read_chat` and the channel never hand the agent the same message twice.
+
+## The creator's own tab
+
+`start_playtest` attaches the agent's playtest tools to the tab the creator already has open, so the agent sees and plays what the creator sees, and starts a headless page of its own only when no tab is open. Roblox Studio's MCP, and the MCP bridges for Unity and Godot, each act on the editor that is already open in the same way, through a plugin in it that talks to a local server; here the plugin is a client the dev server writes into each page it serves.
+
+The client joins over Vite's own hot-reload socket and says the tab is there, where it points, whether it shows, and whether an automation drives it, and says so again on a focus, a change of visibility and a reconnect. Each tab has an id of its own, which a reload keeps, so an attached agent stays on its tab through an edit's reload; a tab the browser duplicates gets a new one. `POST /__tab` runs a JavaScript expression in the tab the creator looked at last, a shown one before a hidden one, and answers its value, awaited; the playtest tools send the same functions they run in the headless page. A page an automation drives, such as the headless playtest's, is never picked.
+
+The creator plays live, so a call that steps the world pauses it for its steps and hands it back running, and a world the creator paused stays paused. A hidden tab draws no frames, so a call that steps or shoots refuses one and asks for it to be brought to the front; a read, such as the tree or the dump, reaches it anyway. A shot of a tab is its canvas, without the page's HTML, and a tab keeps its size and its page, so a shot there takes no `size` and no `map`.
+
+The creator sees the agent at work: the devtools' Spawnite toggle, top left, lights green while it is attached, its tooltip names each call it runs, and the console keeps a line for each call that acts, as [the devtools page](/engine/testing/devtools/#the-agent-on-this-tab) says.
+
+Any page the browser opens can reach localhost, so `/__tab` answers only a caller that sends the token the server wrote to `.spawnite/servers/<port>.json`, which only its owner can read, in `x-spawnite-token`. The file goes when the server closes, and a reader removes one whose process is gone.
+
+## Adding a route
+
+A route module is a function of the server's context, the game's root folder and a way to warn, that returns a Hono app, with its own body limit and its own validator. The app in `src/app.ts` mounts each module under its path in one line, and the tests under `test/routes/` run each module against a temp folder with no server. The engine's replay routes still live in its own plugin and move here next.

package/dist/wiki/engine/testing/devtools-wiki.md

@@ -0,0 +1,80 @@
+---
+title: Devtools wiki
+description: How the devtools' Wiki tab lists every part of a game, its entries, kinds and links, and how a game writes its own pages.
+useCases:
+    - see how my game is put together
+    - list every system and trait in my game
+    - write a wiki page for my game
+    - document my own behaviour
+    - find what uses an entity
+    - read the game's wiki from an agent
+sidebar:
+    order: 12.1
+---
+
+`wiki()` lists every part of the bound world's game as an entry, grouped by kind, and returns `{ kinds, entries }`. Each kind carries its `name`, which heads its entries, a `description` and a wiki `page`. Each entry carries its `kind` and `name`, an optional `description`, `page` and `source` file, the `parent` it belongs to, a system's `phase`, its `properties`, the `links` it refers to, and `usedBy`, the entities that carry it by the key the dump, the entity tree and `describe` use. An entry is made of the entries whose `parent` it is, and its `links` are its other references, never its parent or one of the entries made part of it: a behaviour's trait is under it and not linked, and `KeyE`, under `climbUp`, is linked from `interact`. Nobody writes an entry by hand: each kind reads a registry the engine already keeps.
+
+An entry's `properties` hold its own data as its registration holds it, in plain JSON, with a function as the string `"function"`. A kind with nothing to say leaves them out, and they never hold a timing or a place in the step. A link carries a `relation` where a word says how it connects, such as `changes` from an item to the trait its use changes; a link with none only refers to its entry. The engine's kinds are the following:
+
+- `behaviour`: each declared behaviour, with its description, page and file, and the entities that carry its trait. Its properties are `props`, its trait's fields and their defaults, and `ranges`, the slider bounds it declares. It links to each event its [`handles`](/engine/entities/entity/#events) names, with the relation `handles`.
+- `trait`: each trait the dump names, under the behaviour whose trait it is, or the event it is, and the entities that carry it. Its properties are its fields and their defaults; a trait whose whole value one function makes, such as `transform`'s vector, has none.
+- `stat`: each stat that sets a trait's field, under the first such trait and linked to the rest, and the entities whose stats hold it. Its properties hold its `base`: the default of the field it sets on that first trait.
+- `system`: each system in the world's step, under the plugin it belongs to, with the `phase` of the step it runs in, which the Wiki tab shows under its description. Each system carries the line on what it does that its plugin gave it. Each plugin is a system too, with the plugin's description and the systems the game's list omits, and the core and the engine's plugins are marked as the engine's; a system that replaces another names it. A system links to each trait its queries name, with the relation `reads`: `core.move` reads `transform` and `velocity`. On a world in development, attaching the devtools has each step note the traits a system's queries name, whether it queries through `world.query` or through the engine's passes, so a system links to nothing until the world has stepped, and a trait it reads with `get` or `has` alone is not among them. A system links to no trait it writes: in koota a system writes a class trait, such as `transform`'s vector, in place, which no call or subscription reports, and a change seen in a step shows only the writes that step happened to make.
+- `machine`: each machine [`states()`](/engine/structure/states/) made, such as the engine's `round`, with its states as properties, and the entities that hold it. A machine on the world adds its state and the seconds its wait has left as the property `world`. It links to its trait, with the relation `stored in`.
+- `event`: each event `defineEvent` made: the engine's, such as `damaged`, `gaveUp`, `itemAccepted`, `taken`, `triggerEntered` and `triggerExited`, and each of a game's. Its properties are its record's fields and their defaults. It links to each behaviour whose `handles` names it, with the relation `handled by`. It links to nothing that sends it: an event is raised by an `emitEvent` call anywhere, such as the one in `dealDamage` from the Weapon's click, the projectile system or the room's judgement of a shot, and a game's behaviour names no system.
+- `input`: each action the player takes on the keyboard, the engine's such as `jump` and the game's inputs, presses and page actions such as `sprint.sprint`, with one line on what it does, and a link to each of its keys that another action binds first.
+- `key`: each key the page binds, by its `KeyboardEvent.code`, such as `Space`, under the first action that binds it and linked to the rest: `KeyE` climbs the free camera and interacts.
+- `scene`: each registered scene, by name. The running scene links to the map its World lays out, with the relation `lays out`, since only the running scene has a World mounted.
+- `model`: each registered model, with its `url`, and the `size` and `bounds` its manifest measured, as properties, and the entities drawn with it.
+- `avatar`: each registered avatar, with its VRM body's data as properties.
+- `map`: each registered map, with the whole map as properties, linked to each registered model of a scatter kind that stands on it, with the relation `scatters`. A model matches a kind by its file: the example's `tree-tall` and `tree` both name `tree-tall.glb`, which the meadow's `treeTall` kind draws.
+- `item`: each registered item, with its definition as properties, and the entities whose bag holds it, who wear it or whose loot gives it. It links to each trait its use effects change, and to each stat a `modify` effect names that the wiki lists, with the relation `changes`: Potion's `heal` changes `health`. It also links to the behaviours that hold it, with the relation `held by`: `inventory`, and `equipment` where it has an `equip` slot.
+
+`registerWikiKind(kind)` adds a game's own kind, such as a quest or a card, with a `list(world)` that finds its entries. A kind registered again under the same name replaces the first, since a hot reload runs the module again, and the return forgets it and puts back the engine's kind of that name. Each `kind:name` names one entry: a repeat keeps the first and warns in the console, and a kind whose `list` throws lists nothing and warns, so the other kinds still show. The wiki explains structure and holds no timings of the step or the frame: the Frame tab shows those.
+
+`spawnite play wiki [query] [--kind <kind>]` prints the running playtest's wiki as JSON, and the MCP's `read_game_wiki` replies with it. A query keeps the entries whose name, kind or description holds it, ignoring case, and a kind keeps that kind alone. Both add the paths of the pages that exist, each from the game's folder: `pagePath` on each entry, and `overviewPath` beside the kinds. A game's entry gets [its own page](#a-games-own-pages), and an engine entry gets [the engine's page](#the-engines-pages) that the Wiki tab shows for it, such as `node_modules/@spawnite/engine/dist/wiki/engine/behaviours/stats.md`.
+
+The overlay's Wiki tab shows `wiki()` in one pane: a map at the top, which stays in view, and the page under it. The map centres on the page that shows. At its default of 2 steps, its left side holds the 2 steps of the chain up to the game nearest the centre, such as Health Behaviour then Health Trait for Max Health, and its right side holds what the centre is made of, refers to and is used by; the home's map is made of each kind with an entry. A link with a `relation` goes in a group of its own, titled by the word as the data writes it with a capital first letter, one group for each word, after Refers to, and a link with none stays under Refers to: Potion's map shows Health under Changes and Inventory under Held by. A relation's group draws as Refers to does and follows the same tiers and folds. The links that point at the centre follow, as Obsidian shows a note's backlinks, in a group for each word they read back as, which `reverseWikiRelation` in `@spawnite/schema` gives: Inventory's map shows Potion under Holds, and Health's shows it under Changed by. A link with no relation reads back as Referred to by, and a link the centre already makes back, or one from a part of it, shows once, where the centre says it. Each column of entries lists them in three tiers, by name within each: the game's entries, then the engine's entries the game uses, then the rest of the engine's. The home's kinds come in the same tiers: the kinds that hold a game entry, then the kinds that hold an engine entry in use, then the rest. Used by and Holds keep their own order. The game's entries, and each kind that holds one, draw bright with an accent outline, one column further out too, and the engine's draw muted. A column folds past 8 into "N more", and each node's parts one column further out fold past 3 into "+N", but a fold hides only the engine's entries and the entity rows, the last tier first: every one of the game's is drawn. The running scene's map holds the rows under its row in the tree, and a scene that is not running has none to show. [The debugger page](https://wiki.spawnite.com/design/debugger/) holds the rest of the tab's design.
+
+The map's box takes at most 40% of the pane and scrolls like any other box, with the wheel, a two-finger scroll or one finger on a phone; the page under it scrolls on its own. The drawing is as wide as the box and never zooms. You move around the map by pressing a node, and it draws again only after that or an unfolded group:
+
+- A press on a node moves into it: the node becomes the centre, the page under the map changes to its page, and the box scrolls the new centre to its middle, as far as it scrolls.
+- The map reaches two steps out from the centre: the centre and its neighbours, with 1 step of the chain, then each neighbour's own parts one column further out, 3 at most. Every ring keeps the tiers and never folds the game's entries. There is no control to reach further: a press on a node centres it instead. An unfolded group keeps the box's scroll.
+
+The page under the map is built of folding sections, and a press on a section's header folds or opens it. A section's items sit in under its header, and a section inside another sits one step further in. The home holds Your game, a section with a section inside it for each kind, in the map's tiers, then the overview. Each kind lists the game's entries by name, then, muted, the entries that carry `engine: true` and that the game uses, by name. The game uses an engine entry when an entity carries it, or when a game entry names it in `links` or as its `parent`. The engine's entries that nothing uses fold into one "N more from the engine" section at the end of their kind. A kind's header shows its count and an arrow that opens the kind's page. Every section starts open except the overview, an entry's Page and each "N more from the engine" section, and the tab keeps which are folded while another tab shows.
+
+A kind's page and an entry's page open with the same header: the name in words and what it is, with icons at the right, each named in a tooltip. A copy icon's tooltip shows the code name, such as `maxHealth`, and a press copies it. A book opens the page on the wiki site, and a file opens the entry's source in the developer's editor, where it has one. The description sits under the header, and a scene that is not running says there that it holds nothing until it runs. A kind's entries follow, listed as the home lists them. An entry with `properties` shows them next, in a Properties section, and its Page section follows. An entry with none goes straight to its Page section.
+
+The Properties section folds like any other and takes no edit: it draws the inspector's read-only card, which says whether the game's code or the engine's holds the values. Each key reads as its data writes it, such as `cooldownSeconds`, and each value keeps its field: a number in its box, a string in its box, `true` or `false` as a switch, and a function as the word `function`, muted. A nested object sits indented under its key, and each object of an array, such as each of Potion's `use.effects`, sits under the array's key as a group of its own.
+
+A behaviour or a trait that entities carry shows a Used by section after Properties, with the count of its `usedBy` in the header. It lists each entity by its row in the tree, such as Player #1, or by its dump key where it has no row, with the value the dump holds under the entry's name, in the same read-only card: Player's Health shows `current` and `max`. The section reads one `dump()` as it opens and nothing while it is folded, as the inspector reads a selection once; folding it and opening it again reads the values afresh.
+
+Godot builds its class reference from the running `ClassDB`, and a script's doc comments put a game's own classes beside the engine's; the wiki matches it, with a game's kinds beside the engine's. Unity's Inspector shows a ScriptableObject's serialized fields, Unreal's Details panel a Data Asset's properties, Godot's Inspector a Resource's, and Roblox's Properties panel an instance's; an entry's `properties` hold the same data, read-only, since it lives in the game's code. Unity's Systems window lists the systems by group, as the `system` kind lists them by place, and each system's queries, the components it reads and writes, which a system declares there; the `system` kind links the traits a system reads from the queries it runs, since a koota system declares none. Godot's Node dock lists a node's signals and the methods connected to them, as the `event` kind links each event to the behaviours that handle it. Godot's Input Map and Unity's Input System list each action with the keys bound to it, as the `input` kind does. Cost per frame: none for the entries, which are found when read. While the devtools are attached to a world in development, each query a system runs adds its traits to that system's set.
+
+## A game's own pages
+
+A game explains how it works in markdown pages in its own folder, one for each entry at `wiki/<kind>/<name>.md` and an overview at `wiki/index.md`. The entry's kind and name are the path, so no field in code names a page: `wikiPagePath(ref)` in `@spawnite/schema` gives it, such as `wiki/item/sword.md`, and `wikiOverviewPath` gives the overview's. A page is markdown as the wiki site reads it, tables included, and a `mermaid` fence draws as a diagram in the theme of the Wiki tab's map. The Wiki tab leaves out a page's frontmatter, the `---` block a site page opens with. The game's agent writes each page with the MCP's `write_wiki_page` tool, by the entry's kind and name, and the overview with neither.
+
+The engine's Vite plugin `wikiPages()` serves the pages on the dev server alone, so a published build carries none of them. It answers `/__spawnite/` and a page's path with the file's markdown, read on each request, or 204, no content, where the game has no such page. When a file under `wiki/` is added, changed or removed, the page fires `spawnite:wiki` on its window with the file's path. Every game's config loads the plugin, and so does the config `spawnite create` writes.
+
+The Wiki tab reads a page the first time its entry opens, and reads nothing for an entry that never opens:
+
+- An entry with a page shows the page's opening paragraph under its description. Read more shows the whole page in the entry's Page section, with its file's path under the title, and Show less at the section's top returns to the opening. A press on the path opens the file in the developer's editor.
+- An entry without a page shows, muted, the path its page would take. A press on the path opens Send to agent with a line that asks the agent to write the page.
+- A relative link from one page to another, such as `[Sword](sword.md)` in `wiki/item/potion.md`, opens that entry in the panel. A link to `wiki/index.md` opens the tab's home, a link to any other file in the game's folder opens the file in the developer's editor, and a path from the game's folder written as code, such as `src/models.ts`, opens as a link to that file does. On an entry's page, a site route opens in the panel too where it names an entry's page or a kind's, whole or without its anchor: `/engine/behaviours/inventory/#items` opens the item kind, and `/engine/behaviours/stats/#the-formula` the Stats behaviour. Any other link opens in a new tab, and any other site route opens on the wiki site.
+- The tab's home shows the overview below the kinds, folded until a press, and hides it during a search.
+- A saved page shows on the open entry without a reload.
+- Until a page, the overview, a diagram on a page or the map arrives, its place holds a loading ring at a set height, so nothing under it moves. The ring's frame is a `progressbar` with `aria-busy`, so a script driving the page can wait until none is left. A page or a diagram read before shows at once, the map shows its last drawing at once when the tab opens again, and it keeps that drawing while the next one draws. Where nothing arrives, such as a page the game lacks, the ring gives way to what that case shows.
+
+An engine entry, one the engine registered, carries `engine: true`. It shows [the engine's page](#the-engines-pages) rather than a game page, and never a game path. A game's registration under one of the engine's names is the game's. Godot builds a help page in the editor from the `##` doc comments on a class and updates it on save; a game's pages are files instead, because an overview, an item, a system and an input action have no declaration to carry a comment, and a page holds diagrams. Unity and Unreal show tooltips from a user's attributes and comments, and Roblox, PlayCanvas and Phaser show no pages for a user's own code. Cost per frame: none; a page is read when it shows.
+
+## The engine's pages
+
+The engine ships the wiki site's pages under `/engine/` in its package, at `dist/wiki/`, so the Wiki tab shows an engine entry's page offline and matched to the engine version the game runs. An engine entry's page is the one at its route: its own, such as a behaviour's `wiki`, or its kind's where it has none, as a system has none. The route `/engine/behaviours/stats/` names `engine/behaviours/stats.md`, `.mdx`, or the index in that folder. `wikiPages()` answers `/__spawnite/` and the route, such as `/__spawnite/engine/behaviours/stats/`, with that page's markdown, or 204 where the engine has none. In this repository, where the games run the engine's source, it reads the wiki's own source instead of a build.
+
+The Wiki tab shows an engine page as it shows a game's, with two differences:
+
+- Where the route names a section, such as `#systems`, the entry shows that section, its heading and everything under it, in place of the opening paragraph. Where no heading has the anchor, the entry shows the opening paragraph.
+- Read more shows the route under the title, and a press on it opens the page on the wiki site. The book in the header opens the same page there.
+
+An engine entry that neither it nor its kind gives a route, such as a key, shows no page. A route with no page shows nothing either, and asks no agent to write one. Unity installs an offline copy of its manual matched to the editor's version, and Godot and Unreal ship theirs with the editor; the engine ships its pages with the package for the same reason.

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

@@ -0,0 +1,143 @@
+---
+title: Devtools API
+description: What the engine exposes for the debugger and for an agent, with no UI.
+useCases:
+    - pause and step the game
+    - inspect entities while playing
+    - slow the game down to debug
+    - select an object by clicking
+    - frame rate and timing
+    - read the console from an agent
+    - entity tree of a scene
+sidebar:
+    order: 12
+---
+
+The engine exposes everything [the debugger](https://wiki.spawnite.com/design/debugger/) draws, and everything an agent that cannot look needs, on one store: `useDevtools`. Nothing here draws. `@spawnite/devtools` reads the store for its overlay, and an MCP tool or a test reads it outside React through `useDevtools.getState()`, as every engine store is read. The following pages continue this one:
+
+- [Devtools wiki](/engine/testing/devtools-wiki/)
+- [Editing while playing](/engine/testing/editing/)
+- [State for an agent](/engine/testing/agent-state/)
+- [Headless tests](/engine/testing/headless/)
+
+The world the store acts on is bound by whoever runs it. Inside [Game](/engine/structure/game/), the frame loop binds the running world. A test or an agent binds a headless game from the harness with `attachDevtools(game)`, and the return unbinds it.
+
+## The tree
+
+`tree` is the scene as the developer wrote it: the scene by its name, then each game component by the name it was written under, with its entity id beside it, and its behaviours as leaves with the props they were given. A `Coin` that renders an Entity with Spin, Bob and Pickup reads as `Coin #12` with three leaves under it. An Entity written straight into the scene reads as `Entity`. World, CharacterSpawn and Camera have rows of their own. There are no invented groups.
+
+A scene's HUD sits in the same tree, as Unity lists UI under its Canvas, Godot lists Control nodes in the Scene dock and Roblox lists GuiObjects under a ScreenGui. A `Hud` has a row where it sits in the JSX: under the scene's row, or under the entity whose render holds it. Each `Panel` inside it has a row under the Hud's, and each `Button` a row under the Panel or Hud it stands in, named by its text, as `Button: Play`, or by its `label` where it shows one icon. A game's own component inside a Hud adds no row. These rows are of kind `hud`, with an id such as `hud:3`, and no entity. Headless, a Hud mounts nothing, so its own row stands with no rows under it. The Entities tab draws them under ▭. A press on one selects it, as a press on an entity's row does, from the keyboard and on a phone's sheet too. While a Panel's or a Button's row is hovered or selected, [the outline](#the-outline) frames its element on the screen, as Unity draws a UI element's rect, Godot a Control's and Roblox a GuiObject's selection box. The inspector shows the row's name, its kind and the props the game wrote on the component, such as a Panel's `slot` and `variant` or a Button's `label`, on a card that takes no edit, with a function as `function` and no Send to agent. `useHudRows` holds each such row's element and props by row id, beside the tree, so the tree stays plain data that `spawnite play` prints. A Hud's own row has no element and no props, so it frames nothing, as a Roblox ScreenGui and a Godot CanvasLayer draw no selection box.
+
+Each node carries `id`, `name`, `kind`, an optional `entityId` and `props`, and `children`. The name comes from the React component tree, so it is the developer's own name for the thing and needs no registration. Only the scene that runs has a row, whose id `sceneRowId(name)` gives, such as `scene:lobby`.
+
+The World's scatter reads as one Scatter group under the World's row, with a row per kind in it, `Tree Round ×212`, with the kind's `count`. The Scatter row's id starts with the World's own, so two Worlds mounted at once each keep their own: under the World whose ground is entity 3 it is `3:scatter`, and a kind's row is `3:scatter:treeRound`. A tree, a bush, a rock or a tuft has no row until something asks for one: `3:scatter:treeRound:12` is the round tree at index 12 in its kind's batch, and `findNode` makes its row on the lookup, named as its kind's row is, with its `index` and the reason it takes no edit. A meadow of two thousand tufts adds nothing to the tree. An `InstancedModel` or a `TrackScatter` registers one such counted row for its model under its parent's row, named for the model, with an id of the model's name and a React id so two of one model stay apart; its copies' rows are made the same way by index. The kinds' rows and the models' come with the drawn batches, so headless there are none. Unreal selects foliage one instance at a time the same way; Unity's terrain trees and Godot's MultiMesh select only the whole batch.
+
+## Selection and pick
+
+`selectedIds` holds every selected node in the order picked, and `selectedId` is the last of them, the one the inspector shows. `select(id)` makes that node the whole selection, and `toggleSelect(id)` adds it or takes it out. `pickEntity(world, raycaster)` finds the entity under a ray, walking the hit up to the entity whose object it belongs to, and passing through a hidden one. `pickRow(x, y)` casts that ray from a point of the canvas, given from -1 to 1 across and up, through the camera the game draws with, and returns the row of the entity it meets, or of the instanced model's copy it meets. That camera is the one the outline projects through, so a camera with no orbit picks too, as a track's `ChaseCamera` does; a headless game, which draws nothing, picks through the mounted orbit's camera. `pickRowHit(x, y)` returns that row with the world point where the ray meets it. Where the ray meets an instanced mesh, the pick names the mesh and the instance's index, and the row is that instance's when a row under the entity's counts the mesh's instances, as the scatter's kinds do. The scatter's batches answer the ray through the ground entity, which holds them on `ScatterRefTrait` beside its own mesh; an instanced model's answer it through the group its row holds, which no entity owns. The overlay passes the row to `hover` as the pointer moves over the game and to `select` on a click, or to `toggleSelect` on a ⇧ or ⌘ click. On a right-click, it opens the context menu with the point beneath the entity's name.
+
+## The outline
+
+`hoveredId` and `hover(id)` hold the row under the pointer, beside the selection. While `editing` is on, the frame loop writes `screenRects`, keyed by row id, for the hovered entity and every selected one: where each stands on screen, in pixels from the canvas's corner, which is its model's bounds projected through the camera after the camera has moved for the frame. An instance's rect is its kind's geometry bounds moved by its instance's matrix. An entity with nothing drawn has no rect, a row that is no entity's, a behaviour's or a group's, has none, and headless no entity has one. A Panel's or a Button's HUD row has its element's box on the page, read each frame, so the frame follows the element as it moves or resizes. The loop writes the store only when a rect changed, so a still scene wakes nobody. `describe(id)` carries the rect too, so a playtest driving the page knows where to click the entity.
+
+Unity projects a renderer's bounds to the screen the same way; Roblox, Unreal and Godot adorn the selection in 3D, which an overlay in the DOM cannot. Cost per frame: nothing with edit mode off; with it on, two bounding boxes and sixteen projections at most, a bounding box for an instance being its kind's moved by one matrix read, and one layout read for each hovered or selected HUD row.
+
+## Pause, step and speed
+
+`pause()` holds the world still and `resume()` lets it run. A page opened with `?hold` in its address starts paused, before the world's first step, and the playtest opens its page that way, so two fresh playtests stepped alike show the same frame. `stepFrame()` advances exactly one fixed step, pausing the world first when it runs, which is the period key on the top bar. `setSpeed(speed)` scales each frame's time, 0.25, 1 or 2 on the top bar: the steps and every view's `useFrame` alike, so a game's own animations and particles slow with the world. The map's own motion runs on the effects' clock instead: the grass's wind, the sea's waves and foam, the [water material](/engine/graphics/water-material/)'s waves, the ground's flowing materials and wet ripples, and the sky's drifting clouds. A game's own [Shader](/engine/graphics/shader/) keeps the world's clock, since it may show gameplay time. The pause holds it as it holds the world's clock, and the speed leaves it at the wall clock's pace, as [the World page](/engine/structure/world/#grass) says. A modal's pause is separate: it belongs to the modal stack, and [holds the steps and every view's clock](/engine/ui/modal/#pausing). The devtools' pause holds the steps, the day clock that moves with them, and the canvas's clock. A view's `useFrame` gets no time while the world is held and one step's time, 1/60 s, in the frame that steps it, and the clock's elapsed time holds with it, so a game's own animations and effects stand still with the world and move with each step, as Unity's zero time scale holds them. The camera's controls, the free camera and any view on `useUnscaledFrame` keep the wall clock, so a drag still turns the view of a held or slowed world and the free camera flies at its own speed. On a room's replica the pause, the step and the speed do nothing, since the room runs on, and every view keeps the wall clock. `spawnite play pause` holds the room itself and then writes the store's hold on the page: the page's own steps and every view's clock then follow the store's `paused`, owed steps and `speed` as a world without a room does, while the room's stream still lands. A frame takes the steps owed, as many as a frame's longest time holds, 0.1 s: the overlay owes one at a time, and a tool that owes a room's hundred steps at once runs six a frame.
+
+A paused world with edit mode off draws only when something changes, so an idle playtest leaves the GPU alone: a step, a change to the store, a file that finishes loading and a capture each draw one frame, and one frame a second catches the rest, such as a hot edit. Edit mode and a room's world draw every frame. Roblox, Unity and Godot keep drawing while the game is paused. Unreal's editor viewport with Realtime off, Godot's low processor mode and PlayCanvas's `autoRender = false` draw only on a change, as this does.
+
+`stepUntil({ until, steps })` pauses the world and takes one fixed step at a time until the expression holds or the steps run out, and returns `held`, the `steps` taken and the value the expression `last` returned. The expression reads the world's `entities` as the dump holds them, `count(trait)`, `has(id, trait)`, `player()` and the `steps` taken, and the [engine's state](/engine/testing/agent-state/#the-engines-state) as `camera`, `loop`, `cursor` and `room`, which a headless world leaves undefined. `walkTo({ destination, steps })` sends the player's character walking along the navmesh and steps until the character reaches the route's end, and returns `arrived`, the `steps` taken and where the character stands, `at`. Both stop on the step on which a pausing modal opens, such as a round's end, because the loop takes no step while it is open, and name that modal by its title in `modal`. The step owed when the modal opened is dropped, so closing the modal takes no step. A loop that takes no owed step within one second, with no modal open, is not running, and the call fails saying so.
+
+## The frame split
+
+`setFrameTiming(true)` has the loop time each frame, and `frameSplit` holds where the last 60 frames went, written twice a second: each part of the CPU's frame, then the CPU's whole, the GPU's and the frame's, each by its mean and its worst, so a hitch shows as a worst rather than vanishing into the mean. The overlay turns it on while it is mounted, edit mode or not, so an agent driving the page reads `frameSplit` without the recording's cost in the numbers. The MCP's `read_frame_split` prints the split as the last playtest call that stepped the world left it. The top bar shows the CPU's and the GPU's means beside the frame's, and the Frame tab lists every line, with the last frame's draw calls and triangles beside the means and, in a room, the room's own work per step, the server tick, which the room sends with each answer to a ping.
+
+The parts are the loop's own, as [the frame page](/engine/testing/frame/) lists them:
+
+- `step`: every fixed step the frame bought, and in a room the moves sent with them.
+- `pose and animation`: the character's pose off the step, then her clips, her springs and their colliders.
+- `transforms and camera`: the transforms drawn between the last two steps, then the camera.
+- `render`: the time inside the renderer's render calls, which is the shadow map, the scene and each of a composer's passes, on the JavaScript side.
+- `other`: the rest of the CPU's frame, which is the loop's input and stores, the other `useFrame` subscribers, a composer's work between its passes and React Three Fiber itself.
+
+The CPU's frame runs from React Three Fiber's before-effect to its after-effect, so React's scheduled work, layout and paint fall outside it. The GPU's time comes from `EXT_disjoint_timer_query_webgl2`, from the frame's first render call to its end, which Chrome on the desktop has and Safari and most phones have not; there, the line reads `inferred gpu` and holds each frame less its CPU, which is the wait on the GPU or on vsync together with any main-thread work outside the loop. On a page opened with `?profile` the line reads `inferred gpu` too: `spawnite play profile` times the GPU itself there, and two timers on one context end each other's queries. With vsync on the timer takes in the wait for the swap too, so read the GPU's cost with it off. The CPU and the GPU work at once, so the two do not add up to the frame. Each line keeps its own last 60 samples, and a GPU result lands a few frames after its frame. A frame spent in a hidden tab reads as one long frame and ages out.
+
+Unity's profiler shows CPU and GPU time as bars against the target frame time, Unreal's `stat unit` shows game, draw and GPU, Godot's monitors split CPU and GPU time, Roblox's MicroProfiler shows each engine task per frame, and PlayCanvas's MiniStats shows CPU, GPU and frame time; this is the same split over the loop's own parts. Cost per frame, while mounted: a dozen clock reads and one timer query.
+
+## Panels
+
+`registerPanel({ id, title, icon, order, component })` adds a game's own inspector as one section of the rail, and the return removes it. `id` defaults to the title, `icon` takes a component such as one of lucide's, and `order` places it among the game's sections, lowest first. `panels` lists them. `useLayout` from `@spawnite/devtools` holds where the sidebar stands, which the browser keeps: `openSection(id)` opens a section, a `SectionId` or a panel's `panel:` and its id, as a test or a story does before it reads one.
+
+## Playtest actions
+
+A game's playtest panel runs steps a tester wants on demand: a quick start past the title, damage off, a wave now. `<Devtools playtestActions={actions} />` names those same steps for an agent, each a `PlaytestAction` from `@spawnite/devtools`, `{ name, run }`, so `spawnite play actions` lists them and `spawnite play action <name>` runs one by name, whatever its case, without a chain of `set` and `step` calls. `run` returns a line the cli prints, such as `No damage on.`, and throws to refuse, with why, where the panel's button would be disabled. The panel's buttons call the same functions, so the two never drift apart: Depthfield's are the example. Unreal runs a cheat by name from its console, the functions a `CheatManager` marks `Exec`; Unity, Godot and Roblox leave it to each game's own debug menu. An agent drives the game by commands, so a name it can list beats a button it cannot press. Cost per frame: none.
+
+A panel the game opens on before play, such as a character creator, gets an action that closes it as its button does, so an agent leaves it with `spawnite play action` rather than a click found by its text: Hack and Slash's `Done` is the example.
+
+A game that mounts `<Devtools />` only behind a parameter of its address, such as `?debug`, shows the session no scene until the page carries it: `spawnite play start --query debug` adds the parameters to the address of each page the session opens, and `--query 'map=town&debug'` adds several. The session's own parameters, such as `room` and `hold`, are set over them.
+
+## Pins
+
+`pinnedIds` holds the rows whose panel stands over their entity in the world, in the order pinned. `pin(id)` adds a row once, `unpin(id)` takes it out, and a row that leaves the tree drops its pin. The pins last through a hot reload, which runs a game's modules again but not the store's, and go on a page load. `worldPanels`, off to start, is the World panels switch on the World row's inspector, and `setWorldPanels(on)` sets it: off, the pins stay and nothing draws them. `RowPanel` stands the overlay's pane over a row's entity from beside the canvas, at a width in metres, which the world panels draw through. [The debugger page](https://wiki.spawnite.com/design/debugger/) has the rules, and [Devtools panel](/engine/ui/devtools-panel/) says what a component declares for the panel.
+
+## Abilities
+
+An entity that holds [`AbilitiesTrait`](/engine/behaviours/abilities/) shows an Abilities section in the overlay's Inspector, after its behaviours. It shows the numbers that decide a cast, live, and draws the selected ability's range on the ground.
+
+The section holds the following:
+
+- **Target.** The caster's `TargetTrait`, its reach in metres, whether it is in range of the selected ability, and whether it is in sight. With no target, the section says so.
+- **Last refusal.** The line a page shows for the last `CastRefusedEvent`, such as "Out of range", or "None yet". The store keeps it after every system has read the event.
+- **One button per ability.** Each shows its kind, its range in metres (its radius for an area ability), its cost, the seconds its cooldown has left, and its cast state: `ready`, `pending` while the caster walks into range, or `casting` with the seconds of wind-up left. The cooldown is the longer of the ability's own and the global one, since both hold a cast back. A press selects the ability.
+- **Range rings.** A switch that draws, round the caster, a ring at the selected ability's range and a fainter one at `approachShare` of it, where she stops when she walks into range. A line runs from her to her target, green while the target is in range and red while it is out. The inner ring appears only for an ability that approaches: an area ability gets its radius ring and no line, and a projectile or chain registered with `approach: false` gets its range ring alone.
+
+The rings are the engine's `GroundMark.Ring` and a line, drawn in the game's canvas by `AbilityRings` from `@spawnite/engine/devtools`, and left out of a view capture as the other gizmos are. They last while the Inspector shows the row and the switch is on.
+
+The store reads the same numbers for an agent:
+
+- `readAbilityInspection(world, caster)` returns `{ target, abilities, refused }` for a caster, or `undefined` where it holds no abilities.
+- `useRowAbilities(id)` is the hook the section reads: it renders again on each frame a number changes, since the reach and the cooldowns move with no write a subscriber hears.
+- While the overlay is mounted, every caster files the same record under `useInspect("abilities")`, so `spawnite play eval views` and a dump read it without a selection. The last refusal is kept only while a world is attached to the devtools, which `watchCastRefusals` does.
+
+Unreal's `showdebug abilitysystem` prints an actor's abilities, cooldowns and effects on the screen, and its debug draw puts a sphere at a radius. Unity and Godot leave a range to an editor gizmo, `OnDrawGizmosSelected` and `_draw`, and read values in the inspector while the game runs. Roblox and PlayCanvas have neither. This section matches Unreal's page and the gizmo ring, and differs in that it is part of the Inspector that exists, and its numbers reach an agent through `useInspect`, since an agent debugs a skill as often as a person does.
+
+## The chat
+
+The overlay mounts no chat, and the store keeps its state for the chat components. `chatAttachments` holds the ids of the rows put on the next chat message; `attachToChat(id)` adds one once, `detachFromChat(id)` removes it, and `clearChatAttachments()` empties it when the message goes. `sentMessages` keeps every message the page sent, oldest first: the line the creator typed, or the entity's name where they typed none, how it went, sent to the dev server, copied to the clipboard with no dev server, or neither, the file the dev server wrote, and the rows it carried. `recordSent(message)` appends one. The store holds no message body: the dev server keeps those, and an agent reads them with `read_chat` or the hooks, as [the dev server page](/engine/testing/dev-server/) says. Cost per frame: none.
+
+## The console
+
+`log` holds the last two hundred lines the page's console received, and `clearLog()` empties it. `captureLog()` wraps `console.log`, `info`, `warn` and `error`, and listens for uncaught errors and unhandled rejections on the window; the return restores the console. Each line carries its level, the simulated `seconds` it arrived at, the message as the console prints it, and its `source`: the file name of the first stack frame outside the wrapper. The overlay installs the capture while it is mounted, so a published bundle wraps nothing, and a test installs it itself. The engine's own warnings go through `console.warn` and arrive the same way, so gameplay, which imports no store, has nothing new to import. A warning meant for the agent building the game, such as a walker's `CharacterCapsuleTrait` cut to fit, prints only on a dev world, one marked with `DevWorldTrait`. Four hosts mark their world a dev world:
+
+- The page in development mode, which the engine's Vite plugin reports.
+- The headless harness.
+- A room that allows edits.
+- A game's own tests under vitest in jsdom or node, on the engine's source or its published package.
+
+A built game a player opens marks none, so it prints nothing.
+
+Unity's `Application.logMessageReceived` and Roblox's `LogService.MessageOut` read the native log rather than keep a second one, and so does this. The MCP's `read_console` on its headless page stays on the browser protocol, and `spawnite play console` reads its session's page from Playwright's own list of console messages and page errors, keeping the errors and warnings, which also catches an error raised before the store exists; on the creator's own tab it reads the lines the page logged since the agent attached, with no file for each, since no protocol reaches that browser. Cost per frame: none; one stack read per console call.
+
+## The agent on this tab
+
+While an agent's playtest is attached to this tab, as [the dev server page](/engine/testing/dev-server/#the-creators-own-tab) describes, the Spawnite toggle, top left, lights green: its pane takes a green edge and glows in that green, as the gem that dots the i of its wordmark, or that stands alone on a phone, does, with no control of its own, and the two glows breathe together while a call runs. Its tooltip says "Agent connected" between calls, and the call the agent runs, such as "Agent: walk to (9.0, 0.0, 9.0)", while it runs. The console keeps a line for each call that acts, a step, a walk, a click or a shot, and for the attach and the let-go; a read, such as the tree or the dump, keeps none. The agent's calls fire `spawnite:agent` on the window with an `AgentActivity`, `{ state, action }` from `@spawnite/schema`, and `useAgentActivity()` follows it. The agent fires its state again every `agentHeartbeatMilliseconds` between calls, and the toggle goes back to grey after three missed beats, so an agent whose process ended without `stop_playtest` is not shown attached until the page reloads. Roblox Studio shows a plugin's work in its output window, and Unity marks play mode by tinting the editor; the green toggle does both in the corner a creator already watches for the frame rate. Cost per frame: none.
+
+## Stats
+
+An entity's [stats](/engine/behaviours/stats/) have one card in the inspector, the Stats card, whatever declared them: the Stats component, Health's `maxHealth`, or `<CharacterSpawn>`. The card has a slider on each stat's base, and under the sliders the value each stat resolves to where its modifiers or bounds move it, with each modifier's source and a timed one's seconds left. The Stats component's own row carries `stats: true`, and the card takes its place; an entity with no such row shows the card after its behaviours' cards.
+
+`setStatBase({ id, name, base })` sets the base of a stat of the entity the row `id` stands for, as the engine's `setStatBase` does, so every modifier still applies over it, and records it under the row's `statEdits` until the component that declared the stat declares it anew: Health on a changed `maximum`, and the Stats component on any changed prop, since it declares all its stats at once. An edited base reads "Tried, not saved" on the card, and Copy as prop copies each edited stat the Stats component declared as its prop, `side={{ base: 4, min: 0 }}`; a stat another component or a system declared offers no copy. It throws on a stat the entity has not got and on a base that is not finite. A slider's ends are read off the base as the selection found it: from zero to the stat's `max`, or to the base where the base is past it, or else to the power of ten above the base, so 3.5 slides to 10 and 100 to 1000. The number box beside a slider takes any finite base, past the slider's ends, as Godot's `or_greater` range hint lets a typed value pass its slider; a behaviour's own number box still refuses a value outside its declared range. On a room's replica an entity the room streams keeps the room's stats: the card is greyed with "The room keeps its stats", and `setStatBase` throws it, because the room's edit sets one field of a trait and a base sits inside the stats record.
+
+A field that a stat sets every step has no slider on its behaviour's card, since the next step would overwrite an edit: Health's `maximum` where the entity has `maxHealth`, and on sled's rider the track mover's `sideSpeed` and `drag`. `registerStatField(stat, trait, field)` declares one, and the step then sets it, and `readStatFields(id)` returns a behaviour row's fields that its entity's stats set, each by its stat. The engine declares Health's; a game declares its own. `setProp` throws on such a field, naming the stat that sets it and `setStatBase` as the way to change its base.
+
+`useRowStats(id)` returns the stats of the entity the row `id` stands for and why they take no edit, and renders its caller again on each write of them, as the step writes them every step while a timed modifier counts down. An agent reads the same stats from `dump()`, under `stats`. Cost per frame: none while no stat changes; one render of the inspector for each write of the selected entity's stats.
+
+Unity's inspector edits a stat's serialized base, and its layout groups grey out the fields they drive, "Some values driven by" the group. Roblox's Attributes panel edits the value itself, which has no modifiers to keep. Unreal's GAS debugger shows attributes read-only. The Stats card edits the base as Unity does, so a buff or an upgrade stays on top of the edit, and hides the driven field where Unity greys it, so each number has one slider.
+
+## Systems and relations
+
+`describe(id)` lists `systems`: the blocks of the step and the frame that touch the entity, read off its traits and never by instrumenting a step. `input` for a player's character, `motion` for a transform with a velocity, `rules` naming the registered behaviours it has, `physics` for a collider or a walker, which is a transform with a velocity and no collider, then the frame's `render` for a drawn object and `camera` for the character the camera follows. Unity's Entities inspector lists the systems whose query matches the entity; this is the same list from a table rather than a query log. A game's own systems are plain functions that declare no traits, so they are left out until `System` carries the traits it reads.
+
+`relations` holds the parent and the children from the tree, follows and followed by from the camera's `follow`, and chases from the nearest player's character at the moment of the read. Koota's relations carry a behaviour that targets one entity, once one exists. Cost per frame: none; both are computed when read.

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

@@ -0,0 +1,125 @@
+---
+title: Directing a moment
+description: Hold a replay's moment open and move its time, its players, its world and its camera with a command each, to shoot it as a director does.
+useCases:
+    - shoot a recorded moment from another angle
+    - scrub a replay's time
+    - move the camera in a replay
+    - change the world at a moment
+    - film a multiplayer moment
+    - make a trailer shot from play
+sidebar:
+    order: 14.1
+---
+
+A moment of a [replay](/engine/testing/replay/) opens on the game's dev page and holds there while each command moves it.
+
+To look at a moment the way a director does, open it once and hold it, then move its time and its camera with a command each. `spawnite play start` opens the session and every command after it acts on the page it holds, in about a second:
+
+- `spawnite play start --replay <replay> --at <moment>` plays a replay back on the game's dev page, with the code as it stands, and stands on the moment.
+- `spawnite play start` on a room game holds the game's own room and the page in it once the page has joined. `--bots <n>` adds the room's bots, which play until the session stops, and `--invulnerable` spares every character, so a live fight runs as long as you need it. The page is a player too, so a game that waits on every player waits on it: `--page-bot` has the page's own character play the part the scene's `bot` plays for a room bot, the words a player's keys and menus send, such as ready, while its walk and its aim stay yours. `--pages 2` opens a second player's page beside it, [below](#more-than-one-player), and `--page-bot` has each page's character play the bot's part.
+
+Every session opens held. The following commands move it:
+
+| Command                                                    | What it does                                                                                                                                                                                                                                                                                                                          |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spawnite play pause`                                      | Holds the session where it stands: the replay's playback, or the room with its page.                                                                                                                                                                                                                                                  |
+| `spawnite play resume --speed 0.25`                        | Runs it on at a speed, 1 by default, until `pause` or the replay's end.                                                                                                                                                                                                                                                               |
+| `spawnite play step --steps 30`                            | Runs 30 fixed steps, half a second, and holds again. `--seconds` counts in seconds, and `--until <condition>` runs until a condition over the world holds, as a playtest's step does. `--press` lands inputs on moments of the step, and `--sample` reads a value on each frame, [Playing a held session](/engine/testing/director/). |
+| `spawnite play seek m1`                                    | Stands on a moment: seconds, a mark, a mark and seconds such as `m1-2`, or `now` and seconds from where the page stands, such as `now-5`. It goes back as well as on.                                                                                                                                                                 |
+| `spawnite play mark`                                       | Marks the moment on a room page's own replay, as F8 does, so a later `seek` finds it.                                                                                                                                                                                                                                                 |
+| `spawnite play screenshot`                                 | Shoots what the player sees, the HUD among it, or the world from a camera of its own.                                                                                                                                                                                                                                                 |
+| `spawnite play dump`, `state`, `ai` and `stats`            | Read the page as it stands, as they read a playtest. `dump --where '[monster.kind=colossus]'` prints only the entities a selector picks, and `--where '[round.playing]'` those in a machine's state.                                                                                                                                  |
+| `spawnite play eval '<expression>'`                        | Reads a value on the page as it stands, as a browser's console does, such as a HUD's width after a seek, over the engine's scope; `--file` runs a script of your own, [Playing a held session](/engine/testing/director/#run-a-check-of-your-own).                                                                                    |
+| `spawnite play console`                                    | Prints the page's console errors and warnings and its uncaught errors since the session started, or since the last `console`.                                                                                                                                                                                                         |
+| `spawnite play actions`, `action '<name>'`                 | List the game's playtest actions, the steps its devtools panels run, and run one by name, [Playtest actions](/engine/testing/devtools/#playtest-actions).                                                                                                                                                                             |
+| `spawnite play set '[controlled]' warden.health 0`         | Writes a trait's value onto the entities a subject names, [below](#setting-the-world).                                                                                                                                                                                                                                                |
+| `spawnite play look --yaw 90 --pitch -10`                  | Turns the page's own camera to a yaw and a pitch, as `state` reads them, or by `--turn` degrees from where it looks.                                                                                                                                                                                                                  |
+| `spawnite play press Digit1`, `hold`, `release` and `move` | Play the page as a player does: any key, each mouse button, the mouse's motion and its wheel, a pad and a finger, [Playing a held session](/engine/testing/director/). What the page sends a held room lands on its next step.                                                                                                        |
+| `spawnite play see` and `aim`                              | Read what the camera sees of an entity, and where each shot the page sent passed the crosshair's point.                                                                                                                                                                                                                               |
+| `spawnite play stop`                                       | Closes the page, the dev server, the room and its bots. An unused session stops itself after `--idle` minutes, [60 by default](/engine/testing/processes/).                                                                                                                                                                           |
+
+A replay's page plays on to a moment up to 3 s ahead, and opens afresh on the keyframe before any other, a second at most before it, in place, without loading the game again: a seek back takes about as long as one ahead. It stands her character where the keyframe had her, and when her character stands more than a centimetre from where the recording's keyframes had her since, the line each command prints says how far, because a shot of her then shows a place she never stood. A room's page keeps a replay of its own, with no idle stop while the session holds it, so `seek` in a room session holds the room where it stands and opens that replay in a second page beside the live one, which stays in the room and keeps recording. `spawnite play seek live` goes back to the room. While the page shows the past, `pause`, `resume`, `step` and `screenshot` act on the past.
+
+A replay's `seek`, and its `step` of fixed steps, play the last half second before the moment a frame for each frame the browser draws, so what the page animates in its DOM, which runs on the browser's frames, stands as it stood then: a health bar drains a hit that landed just before the moment. Every animation the DOM runs keeps the replay's clock, whichever the browser runs it on: motion's own reads the page's clock, which is the replay's, and a CSS animation, a transition, or one motion hands the browser, such as an opacity's fade, is held at its age on the replay's clock from the frame it began at, and finished once past its end. So a moment reads the same after any seek or step that lands on it, however fast the browser drew: on Holdfast, the wave bar's lost piece read a width of 3.21 % and an opacity of 0.67 in three seeks to one frame. A seek that opens afresh first runs the page's clock a second on, with the world held, so what the jump itself starts in the DOM, as a bar draining all the health the seek skipped, is over by the moment. In a replay, a condition also reads `at`, the moment the page stands on in seconds, as a seek names one, so `step --until 'at >= 58.55 || count("monster") === 0'` stops at a moment or sooner. `step --until` plays as fast as it can, then, where it played a frame, opens afresh on the keyframe before the frame it stopped on and plays its last half second settled, as a seek does, so what the fast play started in the DOM stands as it stood then too. That costs the step about a second more. `resume` plays at the pace the game ran, not the page's clock's: a stretch a tool stepped, 3 s of the game in the 0.7 s of the page's clock its steps took, plays at speed 1 in 3 s, and a stretch the room ran at speed 4 plays at 1 as the game ran it. A `step` counts the game's steps the same way, and so does `step --until`: its condition's `steps`, its `--budget` and the step it says the condition held on count the game's steps the frames it played ran, so a frame the room ran at speed 4 counts about four, as a room session's step does. Over frames that ran none of the game's time, as while a tool held the room, the budget runs out on the page's clock instead. The page keeps each frame's own seconds of the game where they differ from its clock's, and `spawnite replay export` writes them as `gameSeconds`.
+
+Holding a room holds its clock: the room runs no step, its time stands still, and its players stay joined. Each player's budgets, of moves, shots, walks and the game's messages, fill on the room's time, so a bot that fires at a held colossus spends its burst and is refused after that, rather than landing a minute of shots as the room runs again. A step runs the page's own steps and then the room's, so the moves the page sends, as `--keys` walks its character, wait in its queue for the room's steps, and the page's views, a monster's walk and the fire's flames, move with the room and stand still with it. `step --until` lets the room run on its own clock, at the speed it last ran at, and holds it again on the first frame the page sees the condition hold, or once the budget's steps have run. The page draws the stream a send or two behind the room, so the room stands up to a fifth of a second past that frame. The page steps at the room's speed and sends its moves as fast, and the room's bots send a move for each of the room's moves, so a room's bots fight on at speed 4 as they do at 1, four times as fast, and stand while it is held. The room tells each page its pace in the answer to each ping, and again at once as a tool pauses, resumes or steps it, so a shot the page fires names the room's step it drew at any speed, from the moment the speed changes, and stands on the room's step while it is held.
+
+## More than one player
+
+`spawnite play start --pages 2` opens a second player's page in the session's browser, in a tab of its own, so it joins the room as a player of its own before the bots do. Every page holds, steps and runs with the room, and each keeps a replay of its own. `--page 2` on `screenshot`, `dump`, `eval`, `state` and `look` reads or shoots the second page; the rest act on the room, or on the session's own page. So what one player sees and another does not, such as the screen each warden reads at dawn, is read on that player's page with no script of your own:
+
+```sh
+spawnite play start --bots 2 --pages 2 --page-bot --invulnerable
+spawnite play step --until "Object.values(entities).some((e) => e['phase.dawn'])" --budget 1800
+spawnite play eval --page 2 "[...document.querySelectorAll('dialog')].map((dialog) => [dialog.getAttribute('aria-label'), dialog.open])"
+spawnite play screenshot --page 2
+```
+
+Unreal's play-in-editor opens more clients beside the listen server, each in a window of its own, and Roblox Studio's local server test opens a window for each player; here each is a page a command names.
+
+## Setting the world
+
+`spawnite play set <subject> <path> <value>` writes a trait's value onto the entities a subject names, so a check starts from the state it needs rather than from play that reaches it, as Unreal's `set` console command and its cheat manager write a property, and Roblox Studio's command bar runs a line on the server. The subject is a dump key or a selector such as `'[monster.kind=colossus]'`; the path names the trait as `spawnite play dump` files it, such as `warden`, or a field of it, such as `warden.health` or `transform.position`; the value is JSON, such as `true`, `5` or `[4.5,2.1,-12]`, `null` takes the trait off, and anything else is text.
+
+A room takes the write between two steps, the room's own traits among them, which no page receives, and a recording room records it, so `spawnite replay rerun` and `check` take it again on its step and still come back exactly. A held room then steps one move, three steps, so its page draws the write. A walker whose transform it writes stands there at once, her body built where the transform says, so give the ground's height there, which `spawnite map query --at x,z` reads, with its slope. A game with no room takes the write on its page, where a subject may also be a row's name. A replay plays what it recorded and refuses one: continue its moment in a room with `rerun`.
+
+```sh
+spawnite play set '[controlled]' transform.position '[-18.4,3.2,21.7]'
+spawnite play set '[controlled]' warden.health 0
+spawnite play step --seconds 1
+spawnite play screenshot --framing shoulder
+```
+
+Holdfast's warden at no health goes down on the room's next step, and the dump files her as `life.down`.
+
+A trait no dump shows, such as the state a room keeps for itself and draws its streamed traits from, takes a write by the name its module exports it under. Holdfast's room rewrites the `siege` trait from its own `SiegeStateTrait` on every step, so a write to `siege` does not hold; a write to `SiegeStateTrait` does. Its night reaches dawn once the last wave's monsters are gone:
+
+```sh
+spawnite play set '[siege]' SiegeStateTrait.wave 15
+spawnite play set '[siege]' SiegeStateTrait.toSpawn 0
+spawnite play set '[monster]' monster null
+spawnite play step --steps 30
+```
+
+## Cameras
+
+Without a camera flag, `screenshot` shoots what the player sees, the page's panels among it, and `--no-hud` shoots one render of the game's camera without them. Each other camera renders the world from where it stands, at the page's shape, with no panel, and the command names the eye and the target it resolved to:
+
+- `--eye 0,14,10 --target 0,0,0` places a free camera anywhere.
+- `--around <subject> --angle <azimuth,elevation> --zoom <factor>` frames a subject from an angle. The subject is anything a map shot frames, or an entity: by the key `spawnite play dump` files it under; by a selector of what it is, as CSS's attribute selectors pick an element, such as `'[monster.kind=colossus]'` for the entity whose `monster` trait's `kind` is `colossus`, `'[controlled]'` for one that holds the `character` trait, or several groups for all of them; or by its row's name in `spawnite play start`'s tree, such as `hearth`. A subject that picks more than one entity fails, naming each one's key. The shot frames what the page draws of the entity where it stands at that moment, its model as posed then, so the same flags after a step follow it.
+- `--orbit 4` with `--around` takes four shots round the subject, a quarter turn apart, from `--angle`'s azimuth.
+- `--framing shoulder` stands behind and over the right shoulder of the player's character, or of the entity `--around` names, and looks where it faces. `--framing top` looks straight down, and `--framing wide` is an establishing shot from high to one side; both frame every entity in play where no `--around` names a subject.
+
+A shot from any camera but the player's own leaves out the screen overlays her view draws in the canvas, such as Holdfast's red hurt vignette, which would cover what the camera frames; so does `--no-hud`, and `--overlays` keeps them. The page as it shows, the shot with no camera flag, keeps them, since they are what she sees. `spawnite play look --yaw 90 --pitch -10` turns the page's own camera instead, to a yaw and a pitch as `spawnite play state` reads them, or `--turn 30` by degrees from where it looks, so the player's own shot looks where a check needs it to; a character that faces where the camera looks turns with the room's next step.
+
+`--size 1920x1080` sets the page's size for the shot, and `--width 1280` writes each file at most that wide, since an image costs an agent about its width times its height over 750 of its tokens. A list, `--size 1920x1080,1280x720,960x540`, shoots at each size in turn in one call, with the world held between them; a HUD that animates on the page's own clock moves on a few hundred milliseconds from one size to the next. `--out after/offer.png` writes the shot there rather than under `.spawnite/shots`, and several shots add their size to the name, such as `after/offer-1280x720.png`.
+
+On Holdfast, a live fight with three bots, run four times as fast until its colossus rises, then shot from the player, round the colossus, picked by what it is, and from over the fire, and then back at the moment it rose, from the page's own past. Holdfast starts a run once every warden is ready, the session's page among them, so `--page-bot` has the page say it is ready as the bots do:
+
+```text
+$ spawnite play start --bots 3 --invulnerable --page-bot
+The room is held at step 306; its page keeps replay 20260928-025215-8z5t, at 5.35 s.
+$ spawnite play resume --speed 4
+The room is running at speed 4 at step 453; its page keeps replay 20260928-025215-8z5t, at 7.01 s.
+$ spawnite play step --until "Object.values(entities).some((e) => e.monster?.kind === 'colossus')" --budget 30000
+The condition held on step 14317; it returned true.
+The room is held at step 15040; its page keeps replay 20260928-025215-8z5t, at 68.14 s.
+$ spawnite play mark
+Marked m1 of 20260928-025215-8z5t at 69.25 s: `spawnite play seek m1` comes back to it.
+$ spawnite play step --seconds 6
+Stepped 360 steps.
+$ spawnite play screenshot --size 1280x720
+$ spawnite play screenshot --size 1280x720 --around '[monster.kind=colossus]' --orbit 4
+azimuth 90°, elevation 25°, around [monster.kind=colossus]: perspective fov 50, eye (14.2, 8.1, -9.8) → target (1.9, 2.4, -9.8); screen up = +y, right = -z (north).
+$ spawnite play screenshot --size 1280x720 --eye 0,16,12 --target 0,0,0
+Camera: perspective fov 50, eye (0.0, 16.0, 12.0) → target (0.0, 0.0, 0.0); screen up = +y -z (north), right = +x (east).
+$ spawnite play seek m1
+The room's page shows its own past: 20260928-025215-8z5t held at 69.24 s. `spawnite play seek live` goes back to the room.
+$ spawnite play seek live
+The room is held at step 15400; its page keeps replay 20260928-025215-8z5t, at 85.90 s.
+```
+
+The wait for the colossus, 14,317 of the room's steps, took 61 s at speed 4. A condition waits for any moment the same way: `step --until` runs the room at its own pace until the page's world holds one.
+
+On Holdfast on a Ryzen 9800X3D with an RTX 4070 SUPER, `spawnite play start --bots 3` opened in 9 to 10 s, a room with no bots in 7 to 8 s, and `spawnite play start --replay` in 7 to 8 s. The room, the dev server, the browser and the bots start side by side, the page loads while the room starts, and the browser keeps the shaders it compiled for the last session, which saves about 5 s of a replay's first frames. Most of what is left is the game's own load: its modules, its models and its shaders, 3 to 4 s, and the room's start, about 4 s beside it. After that, `pause`, `resume`, `mark` and a shot of the player's camera each took 0.4 to 1.1 s, and `step --steps 30` 0.8 to 1.1 s. A seek in a replay took 0.9 to 1.6 s back or on, and 2.4 s to play 2 s on. A room session's first `seek` took 6 to 9 s, since it loads the game in a second page, and each after 1 to 1.6 s. A free camera's first shot took about 5 s, as the page compiled the shaders the camera's view needed, and each after under a second, or 1.4 to 1.6 s for four orbit shots together.