@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/structure/world.md

@@ -0,0 +1,371 @@
+---
+title: World
+description: The map, mounted by name.
+useCases:
+    - create a game map
+    - terrain and ground
+    - grass on the ground
+    - scatter trees and rocks
+    - sea level
+    - gravity setting
+    - day and night cycle
+    - navigation mesh for npcs
+    - pick a sky look
+    - vegetation on a map
+sidebar:
+    order: 4
+---
+
+`<World map>` mounts a map by name: its ground, the scatter standing on it, the navmesh baked from both and from the Entities' fixed colliders and resting kinematic ones, and the daylight. All of it lives as long as the World is mounted. The [`<CharacterSpawn>`](/engine/entities/player/) and the [Camera](/engine/entities/camera/) go inside it, as does every entity of the scene.
+
+Every world has one physics scene, which loads the physics, Rapier's WebAssembly, at the first body the world declares: a World's ground, an entity's `collider`, or a body the room streams. A game that declares none, such as one that shows a model under [Lighting](/engine/graphics/looks/#a-scene-without-a-map) or a card game, never downloads it, alone or in a room, and its room's process never loads it either. The navmesh loads recast for the first World. A Game's loading screen starts recast as it mounts, beside the scene's files. While the physics loads, the World and its children wait inside a boundary of their own, so the rest of the scene mounts at once, and a game played alone runs no step until the load lands, so its first step meets the ground and every body however long the download took. A page in a room steps on at the room's pace, and its scene holds each body from the first step after the load. A World mounted after that, a second one or the next scene's, spawns its ground at once. Code that reads the physics before any body, such as a test, awaits `loadRapier()` first, and `loadRecast()` before it bakes a navmesh.
+
+Its props are in [`WorldProps`](https://wiki.spawnite.com/reference/world/worldprops/).
+
+## Look
+
+`look` picks a [look](/engine/graphics/looks/): the sky the models light from, fog, exposure, grading and a post-processing stack, set together.
+
+## Sky, sun and fog
+
+World lights its map with the engine's [Lighting](/engine/graphics/looks/#a-scene-without-a-map), and you can replace any of its parts while keeping the rest:
+
+- `sky` is the sky behind the scene. Left out, the engine draws its scattering sky with clouds, which follows the hour. `{ file, sunU }` draws an equirectangular image in its place, turned so its sun stands on the engine's. `false` draws none, for a cave, a space station or a sky the game draws itself.
+- `sun={false}` leaves out the sun, and the moon after dark: the one directional light, which casts the shadow. The sky's fill light stays.
+- `fog` takes a three.js `Fog`, linear between two distances, or `FogExp2`, which thickens with distance, in place of the look's. `false` sets none. Make the fog once, with `useMemo` or outside the component.
+- `shadowBox` sizes the sun's shadow box in metres, `{ halfWidth, depth }`, 14 by 40 by default, and `focus` is the point it stands over, the player character by default. A top-down or strategy camera that sees farther than her surroundings widens the box and names the point the camera looks at.
+- `lighting={false}` mounts none of it: no sun, sky, fill, exposure, fog or look stack. The game lights the scene itself, with its own `<Lighting>` or its own lights. A look then sets only the hour the World opens on. TypeScript refuses any of the props above beside `lighting={false}`.
+
+A scene under the sea keeps the sun for the light that reaches down, draws no sky, and fills the distance with blue. The engine's tests mount this file:
+
+```tsx title="packages/engine/test/outside/UnderwaterWorld.tsx"
+import { useMemo } from "react";
+import { FogExp2 } from "three";
+import { World } from "@spawnite/engine";
+
+const water = "#1a4a6a";
+
+//  Under the sea: no sky, the sun kept for the light that reaches down,
+//  and a blue fog that thickens with distance into a blue backdrop.
+export function UnderwaterWorld() {
+    const fog = useMemo(() => new FogExp2(water, 0.06), []);
+    return (
+        <World map="meadow" sky={false} fog={fog}>
+            <color attach="background" args={[water]} />
+        </World>
+    );
+}
+```
+
+Unity keeps the skybox material, the sun source and the fog, linear or exponential, as separate entries of its Lighting settings. Unreal places the sky atmosphere, the sky light, the directional light and the height fog as separate actors that a level keeps or deletes. Godot's `WorldEnvironment` holds the background, sky or plain colour, and the fog, beside a `DirectionalLight3D` node. Roblox's `Lighting` service takes a `Sky` and an `Atmosphere` and its own fog values. World takes the same three parts as three props, each replaceable on its own, and keeps the engine's for whatever a game leaves out.
+
+## Scatter
+
+The scatter is what stands on the ground: trees, rocks, bushes and grass, placed from the map's seed. A kind that blocks a walker, a tree or a rock, always stands in full: on every device, and in a room on the server and every client, so all of them stop her at the same trunk. `scatterShare` thins only what decorates, a bush or a tuft of grass, which she walks through. When a scene passes no `scatterShare`, the [quality level](/engine/ui/graphics-quality/) in force sets the share, and a game changes each level's share with Game's `quality` prop; a scene that passes its own keeps it at every level.
+
+Bushes and tufts shrink away into their feet past a distance from the eye that the [quality level](/engine/ui/graphics-quality/) sets, 60 m at High, and a pass draws none past it; trees and rocks draw at every distance, since they are the map's shape. So the map camera's far zoom draws the ground, the trees and the rocks.
+
+Each kind draws as one instanced draw per pass, of only the copies that pass's camera holds: the screen draws what the view sees, and the shadow map what the sun's shadow box holds. The copies stand still, so a tree over them, built once, finds each pass's set without testing every copy. Each pass keeps its set, and finds it again only on a frame when its camera moved, turned or changed shape, or the scatter changed, so a still frame sends the GPU no new list.
+
+## Ground, sea and scatter materials
+
+Three props change what the World draws its map with, each on its own:
+
+- `ground` is the ground's material.
+- `sea` is the water's.
+- `scatter` is the scatter's, each kind's in turn. A bush or a tuft hands over the engine's copy that shrinks it with distance, and a tree or a rock a copy of its file's material, never the loaded file's own.
+
+Each takes a function handed the engine's material, which returns either that material patched, such as with an `onBeforeCompile` of the game's, or a material of the game's in its place. A patched material keeps what the engine's does: the ground's paint of each cell, its detail and the quality level's changes to it, and a bush's shrink with distance. A material of the game's replaces all of it: the engine goes on updating its own material out of sight, and the mesh goes on drawing the game's. Either way, the ground still holds the walkers up and answers a ray, such as a click to walk. The engine's program key carries the hook's text, so a patched ground and a plain one never share a program.
+
+The ground's material is a three.js `MeshStandardMaterial`, so a patch splices the standard material's chunks, such as `#include <emissivemap_fragment>`. Its mesh lies turned a quarter turn about x, so a shader reads world positions, `modelMatrix * vec4(transformed, 1.0)`, rather than the mesh's own `position`. The sea's material is a `ShaderMaterial` of the engine's own.
+
+The function runs once each time a World mounts, and never again while it stands: a quality change patches the engine's material in place. Define it once, outside the component. A material the engine handed over and the function returned patched is still the engine's, which it disposes of with the World. A material of the game's is the game's to dispose: one made at the module's top lives for the page, and one the game makes for each World is disposed in the cleanup of the component that mounts that World.
+
+`false` draws none of it, for a game that draws its own:
+
+- `ground={false}` draws no ground. The engine's ground still holds the walkers up, answers a ray such as a click to walk, and bakes the navmesh, unseen, so the game's own ground draws over the same shape.
+- `sea={false}` draws no water. The sea's height still rules the ground's materials, the scatter and the navmesh.
+- `scatter={false}` draws none of the map's scatter, nor its props of a scatter kind. A tree or a rock still blocks a walker where it stands, and the ground's `ScatterTrait` still lists every placement, for a game that draws them itself.
+- `grass={false}` grows no grass, whatever the materials' covers say. Otherwise `grass` takes the blades' shape, as [Grass](#grass) says.
+
+The meadow under snow keeps the engine's shaders and lays white over their colour before the light, its lake is frozen, and the snow buries its grass. The engine's tests mount this file:
+
+```tsx title="packages/engine/test/outside/Snowfield.tsx"
+import { World, type ModelMaterial } from "@spawnite/engine";
+
+//  The meadow under snow: the ground and the scatter keep the engine's own
+//  shaders, with white laid over their colour before the light, and the
+//  lake is frozen, so the World draws no water. The snow buries the
+//  grass, so none grows.
+
+/** Patches the material the engine hands over and returns it, so the
+ *  ground keeps its paint and the quality level's changes, and a bush
+ *  keeps shrinking with distance. Made once, outside the component. */
+const snow: ModelMaterial = (engine) => {
+    const own = engine.onBeforeCompile.bind(engine);
+    engine.onBeforeCompile = (shader, renderer) => {
+        own(shader, renderer);
+        shader.fragmentShader = shader.fragmentShader.replace(
+            "#include <emissivemap_fragment>",
+            "diffuseColor.rgb = mix(diffuseColor.rgb, vec3(0.92, 0.95, 1.0), 0.7);\n#include <emissivemap_fragment>",
+        );
+    };
+    return engine;
+};
+
+export function Snowfield() {
+    return (
+        <World
+            map="meadow"
+            ground={snow}
+            scatter={snow}
+            sea={false}
+            grass={false}
+        />
+    );
+}
+```
+
+Unity's terrain takes a material of the game's, and its trees and details their prefabs' materials. Unreal's landscape takes a landscape material, and its foliage types their meshes' materials. Godot's terrain add-ons and its `MultiMeshInstance3D` each take a material override, and Roblox's terrain takes a `MaterialVariant` for each of its materials. Each of them hands the game the whole material. World hands over the engine's own as well, so a game can patch it and keep the engine's paint, or replace it.
+
+## Grass
+
+The ground grows grass blades on its own wherever its material grows them, as Unreal's Landscape Grass Type grows from a layer and Roblox's Grass terrain grows its decoration. The built-in `grass` grows green blades and `dry-grass` straw-coloured ones; any material grows them with a `cover` in its entry, in the game's `src/maps/materials.json` or the map's own `materials`, and a `density` of 0 grows none:
+
+```json
+{
+    "materials": {
+        "grass": { "cover": { "density": 1.5, "height": 0.45 } },
+        "moss": {
+            "from": "dirt",
+            "cover": { "height": 0.12, "colour": "#3f5a2a" }
+        }
+    }
+}
+```
+
+- `density`, from 0 to 2, is how thick it grows; the scatter brush's grass multiplier scales it per cell, up to 2, so the brush that thins tufts thins the blades too.
+- `height` is the tallest blade in metres, 0.32 when left out.
+- `colour` is the blades' colour; the material's swatch, tinted as the material is, when left out.
+- `sway: false` holds the blades still; they sway when left out.
+
+The blades shrink where a cell's grass gives way to another material, and grow from the cells a stroke paints, popping in as the scatter does. They draw in square patches of 6 m, only the patches within reach of the eye, each thinning with its distance, as the [quality level](/engine/ui/graphics-quality/) sets: at Low a sparse field out to 12 m, where the ground's texture carries the grass beyond it, and none at Minimum. The blades within 0.45 m of a character bend aside and stand shorter, and stand again once a jump lifts the character off them. They bend in the wind at Medium and High, and stand still at Low, under Reduced motion and on a material whose cover says `sway: false`; the player's [Grass sway](/engine/ui/settings/#the-rows) setting wins over the level and Reduced motion. Still, the shader skips the wind's work. The wind blows on the effects' clock: the devtools' pause and a pausing modal hold it, and the devtools' speed leaves it at the wall clock's pace. A pointer's ray passes through them to the ground.
+
+A game that paints its own ground over the engine's shapes the blades with `grass`, GLSL the blade's vertex shader runs after the engine's own, as three's `onBeforeCompile` splices a chunk. Holdfast gives a cover to every material its map resolves to, dirt and stone included, so the engine grows blades everywhere, and its shape trims them by the layout its paint draws: they give way to its roads, its cobbled ring and its worn earth, and take its paint's colour. `shape` reads `bladeRoot`, `bladeSeed`, `groundUp` and `coverShare`, and changes `bladeHeight` and `bladeColour`; `functions` holds what `shape` calls, and `uniforms` its numbers, colours and textures, each declared for it.
+
+```tsx
+import { World } from "@spawnite/engine";
+
+export function Fort() {
+    return (
+        <World
+            map="holdfast"
+            grass={{
+                shape: "bladeHeight *= 1.0 - smoothstep(30.0, 38.0, length(bladeRoot.xz));",
+            }}
+        />
+    );
+}
+```
+
+## Maps
+
+A map is a value the map schema in `@spawnite/schema` accepts: a seed, a size and a cell, its hills, regions, paths and rim. `registerMap(name, values)` parses it and keeps it under the name; it throws on a value the schema refuses, at registration rather than at mount. `readMap(name)` throws on a name nobody registered, which a `<World map>` with that name does as well, into the game's boundary. The engine registers two maps, each a square centred on the origin:
+
+- `grid`, the map a `<World>` with no `map` mounts: a flat floor 8 m across, from −4 to 4 m on x and z, of the `grid` material, one grey with a darker line every metre. It has no hills, no scatter, no grass and no water, and it loads no texture and no model, so a scene that shows a character or an effect opens fast. Roblox's default place is the same flat Baseplate.
+- `meadow`, the nice map: 100 m across, from −50 to 50 m, with hills, a level clearing in the middle, a textured ground, the scatter and grass. A scene names it with `<World map="meadow">`.
+
+Either is a map like a game's own: `gridMap` and `terrainMap` in `@spawnite/schema` hold their values, and a game's map can copy one.
+
+A game keeps its maps as JSON files under `src/maps/`, one per map, and registers them all from its app file with `registerMaps(import.meta.glob("../maps/*.json", { eager: true }))`, which names each after its file: `src/maps/blockout.json` is `blockout`. A file named `meadow.json` takes the place of the engine's meadow. `add_map` writes a new file, and a tool rewrites one safely, where it could not rewrite a TypeScript module. `spawnite map check`, `spawnite map describe` and `spawnite map query` read `src/maps/<map>.json` when the game has it, and the game's only map file when no `--map` is given; a game with several map files names one.
+
+A map's edits from [the map editor](https://wiki.spawnite.com/design/map-editor/) live in its own file, under a `terrain` key: a grid of height offsets over the map's base, a dot where no brush touched, written by the devtools' Terrain section, `spawnite map terrain` and the MCP's `edit_terrain` through the one writer every map file goes through, which changes only its own key. `registerMaps` loads the block with its map, so a game's code does not change; the first edit of the engine's meadow writes the map into the game as `src/maps/meadow.json`. The ground bakes the base, then adds each edited point's offset, and each scatter family's multiplier per cell, from 0 to 2, scales how thick it grows there; an instance the editor erased, named by its spot, stands nowhere. New terrain, from a stroke's end or an agent's command, stands the ground on a new surface without reloading the page, and the physics, the navmesh, the scatter and the props follow it. A block written for another `size` or `cell` is refused at load, naming `spawnite map terrain resample`.
+
+The rim is a bank an actor climbs, and the map's edge behind it is a wall: nothing walks or jumps off the map, so a game needs no check for a fall. Each wall stands the map's `size` above its highest ground, 100 m on `meadow` and 8 m on `grid`; a `jumpHeight` above that would clear it.
+
+### Sea
+
+A map's `sea` is one height in metres below which the ground is under water, the way Roblox's Sea Level fills water up to a height and Unreal's ocean is a plane at one. Every map has one: left out, it stands 1 m below the lowest point of the map's base, the heights before any terrain offset, so the map is dry until its ground is dug below that, and the World draws no water while all the ground stands above it. The World draws the water across the whole map at that height, with the [water material](/engine/graphics/water-material/)'s waves, lighter in the shallows and broken into foam where the ground rises out of it. The waves and the foam move on the effects' clock, as the grass's wind does: the devtools' pause and a pausing modal hold them, and the devtools' speed leaves them at the wall clock's pace. The scatter thins toward the shore over its last 4 m and stands nothing under water, and the ground's water rules, `deeperThan` and `shallowerThan` under the sea and `shoreWithin` beside it, match by the depth and the distance to the water. The navmesh leaves out every triangle of the ground that dips more than `wadeDepth`, half a metre, under the sea, so a walker that follows it, a chaser or a character sent walking, wades into the shallows and no further; on a coarse grid it stops up to a cell short of that depth. The water has no collider and no swimming: a character the player steers walks on its floor. The ground's surface answers `sea`, the height it stands at, `isUnderWaterAt` and `getShoreDistanceAt`, metres to the nearest water within a cell of the coast. [The map editor](https://wiki.spawnite.com/design/map-editor/)'s Sea field sets it, `spawnite map terrain sea --level 1` and the MCP's `edit_terrain` write it, `spawnite map check` gives its height and names a view, a path or a prop under water, and `spawnite map describe` gives its height, the share of the map under water and the shoreline's length.
+
+### Views
+
+A map's `views` are named cameras: an eye, a target, and a vertical field of view, or an `ortho` span in metres for an orthographic view. A view is a bookmark an agent writes once, at the angle its concept art was drawn from, and shoots again after every edit so the shots compare. `frameView(map, name)` returns the camera for a name: a `views` entry as written, a region, a path or a prop framed from 45° above at two and a half radii, or `map`, which every map answers with the whole ground from straight above. It throws on a name the map has not got, listing the ones it has.
+
+An agent matching the map to concept art works in a loop: it writes a view at the art's angle, edits named entries, checks the map's facts with `spawnite map check`, shoots the top-down `map` view and the concept view, and asks a second agent to score both against the art until they pass or ten rounds are spent.
+
+### Props
+
+A map's `props` are named objects that stand at a written spot, as a level file in Unity, Godot or Unreal keeps its placed instances. Each prop is one of three kinds:
+
+- A shape: `kind` is `box`, `sphere`, `cylinder` or `plane`, with a `size` in metres across, tall and deep, 1 m each by default, and a `color`.
+- A scatter kind: `kind` is one of the scatter's kinds, such as `treeRound` or `rockBoulder`. It stands with the scatter whatever the `scatterShare`, and one that blocks a walker blocks it as the scatter's own do. It stands at the middle of its kind's heights.
+- A model: `model` is a registered model's name, or a path the game serves, such as `assets/statue.glb`, which needs no registration. The engine reads a registered name as that name, and any other value with a `/` as a path. `spawnite map check` cannot see what a game registers, so it reads any value with a `/` as a path and reports a path with no file behind it in the game's `public/` folder. The path reads from the page's own folder, a leading `/` included, because the games site serves each game under its own folder, such as `/arena/`.
+
+Every prop takes a `position`: `[x, z]` stands it on the ground there, and `[x, y, z]` holds it at that height. `yaw` turns it, in degrees, and `scale` multiplies its size, as one number or one per axis; a scatter kind takes one number, because the scatter scales a kind evenly. A model prop draws its file unturned, so at a `yaw` of 0 its front faces +z, where an [`<Entity model>`](/engine/entities/entity/#models) turns it to face -z. A shape or a model is an entity named for its prop in the devtools tree, which draws with the World's other views and not headless.
+
+```json
+"props": {
+    "tower": { "kind": "box", "position": [0, 0], "size": [4, 12, 4], "color": "#8a8f99" },
+    "oak": { "kind": "treeRound", "position": [8, -6], "yaw": 30 },
+    "statue": { "model": "assets/statue.glb", "position": [-6, 4], "scale": 1.5 }
+}
+```
+
+## Gravity
+
+Gravity belongs to the world's physics scene, not to a World: every actor and every dynamic body falls at it, 9.8 m/s² down by default. A game sets it once with `definePhysics({ gravity: [0, -20, 0] })`, exported from `src/game.ts` as `physics` and passed to `<Game physics>`, as [Plugins](/engine/structure/plugins/) says, and a system changes it in play with `setGravity(step, gravity)`, which the room streams to every page. A character falls along its y component. The devtools' gravity card sets the same value in a game played alone.
+
+## Day clock
+
+Each World keeps a day clock, which the sun, the moon and the sky follow. Two props set it:
+
+- `startHour` is the hour the World opens on, from 0 up to 24, with the minutes as a fraction: 18.5 is half past six in the evening. An hour past either end wraps into the day, so 25 opens at 1. When left out, the look's hour is used, or 10 with no look.
+- `dayLengthSeconds` is the real seconds a whole day takes, 1200 by default.
+
+The clock runs in the step, as the first system of the `rules` phase, `core.advanceDayClock`, so a game's rules read the hour of the step they run in. A room, a headless run and `spawnite simulate` all move it; the devtools' pause holds it and their speed scales it. In a room the clock runs on the room alone, and each page draws the room's hour, which the stream brings.
+
+Two functions read and set the hour:
+
+- `findTimeOfDay(world)` returns the hour, from 0 up to but not 24, and a view reads it too. It returns `undefined` where it finds no clock: in a scene with no World, such as a menu, on a page in a room before the room's clock has streamed in, and for a ground with no clock.
+- `setTimeOfDay(authority, hour)` puts the clock at an hour, wrapped into the day, and the clock keeps running from there. A jump in the hour is an outcome, so it takes the step's authority, as [`dealDamage`](/engine/behaviours/health/) does. It throws in a world with no day clock, naming `<World>` as the fix, and on an hour that is not finite.
+
+Where two Worlds each keep a clock, both take `{ ground }`, the ground entity of the World whose clock to use, and throw without it.
+
+The hours of the night are the game's own. This plugin spawns a prowler at each lair as night falls and destroys them at dawn, both through the step, and leaves every other entity alone. It waits while the scene has no World. It keeps whether the last step was night on the world, so the prowlers come once a night however many fall. The engine's tests run it against a real room and alone:
+
+```ts title="packages/room/test/outside/night.ts"
+import { createQuery, type World } from "koota";
+import { Vector3 } from "three";
+import {
+    ChaseTrait,
+    definePlugin,
+    definePrefab,
+    defineTrait,
+    destroy,
+    findEntity,
+    HealthTrait,
+    findTimeOfDay,
+    spawn,
+    TargetableTrait,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  Prowlers that hunt at night, built as a creator's plugin is, from the
+//  engine's public entry alone: as night falls the room spawns one at each
+//  lair, each chasing the nearest player's character, and as day breaks it
+//  removes the ones still standing and no other entity. Their traits
+//  stream, so every page draws them, and a game played alone runs the
+//  same.
+
+/** Marks a prowler, so the dawn removes this plugin's own; the stream
+ *  carries it. */
+export const ProwlerTrait = defineTrait("outsideProwler");
+/** The hour night falls, and the hour day breaks. */
+export const duskHour = 19;
+export const dawnHour = 6;
+export const lairs = [new Vector3(10, 0, 0), new Vector3(-10, 0, 0)];
+/** On the world: whether the last step was night, so the prowlers come
+ *  once a night however many fall, and at once in a game that opens at
+ *  night. Named, so a checkpoint restores it; the room alone keeps it. */
+const NightTrait = defineTrait(
+    "outsideNight",
+    { isNight: false },
+    { serverOnly: true },
+);
+const prowlers = createQuery(ProwlerTrait);
+
+/** One prowler: a model that chases the nearest player's character and
+ *  can be targeted. `visor-bot` is the example template's own model; a
+ *  game draws its prowlers with any model it registers. */
+export const prowler = definePrefab("outsideProwler", {
+    traits: [
+        ProwlerTrait,
+        HealthTrait({ current: 20, maximum: 20 }),
+        ChaseTrait({ speed: 3, reach: 1 }),
+        TargetableTrait,
+    ],
+    model: "visor-bot",
+});
+
+export const night = definePlugin({
+    name: "night",
+    //  No runsOn: the room alone spawns, and a game played alone is its
+    //  own room.
+    systems: { rules: { prowl: { system: prowlAtNight } } },
+});
+
+function prowlAtNight(world: World, step: AuthoritativeStep) {
+    const hour = findTimeOfDay(world);
+    //  No World in the scene, such as a menu, or a page before the room's
+    //  clock streams in.
+    if (hour === undefined) return;
+    const isNight = hour >= duskHour || hour < dawnHour;
+    if (world.get(NightTrait)?.isNight === isNight) return;
+    if (world.has(NightTrait)) world.set(NightTrait, { isNight });
+    else world.add(NightTrait({ isNight }));
+    if (isNight)
+        for (const lair of lairs) spawn(step, prowler, { position: lair });
+    else
+        for (
+            let standing = findEntity(world, prowlers);
+            standing;
+            standing = findEntity(world, prowlers)
+        )
+            destroy(step, standing);
+}
+```
+
+Roblox's `Lighting.ClockTime` holds the same number, from 0 up to 24, and stands still until a script moves it; its `TimeOfDay` is the same hour as a string, such as `"18:30:00"`. Unity, Unreal and Godot keep no clock of their own, and a game or a plugin drives the sun. Here the clock runs on its own, in the step, because the hour decides what spawns and must be the same in a room, on every page and in a headless run.
+
+## Two Worlds
+
+A scene can mount two Worlds at once. Each dresses, draws and bakes only its own ground, and puts its scatter's rows under its own row in the devtools tree. Each ground's terrain is a fixed body in the world's one physics scene, so an actor walks on whichever terrain she stands on, and a character spawned in the second World stands on its ground. The two share the scene's gravity: a game that needs two separate physics spaces runs two Games. The devtools frame the World the player's character is in, or the first World mounted when she is in none: `frameView` and `frameShot` read that World's map. The inspector of a World's row reads and sets the day clock of the World the selected row sits in, or the first World's with no row in a World selected, and titles its card with that World's row label, such as `World #3`.
+
+## The ground entity
+
+The ground is one entity with the ground, scatter, obstacles and navmesh traits on it, and its terrain is one fixed body on that entity, holding the heightfield, the wall along each edge and the scatter's hulls, which a map edit replaces alone, so every other body keeps its pose and velocity; and the day clock is another, which carries `InWorldTrait` naming its ground. `useWorldEntity()` reads the ground from anywhere inside the World, for UI that wants the map.
+
+## Sample
+
+```tsx
+// src/scenes/Run.tsx
+import {
+    Bar,
+    Camera,
+    CameraTarget,
+    CharacterSpawn,
+    Hud,
+    Panel,
+    Slot,
+    usePlayer,
+    World,
+} from "@spawnite/engine";
+import { Coin } from "../components/Coin";
+import { Chest } from "../components/Chest";
+import { Yeti } from "../components/Yeti";
+
+export function Run() {
+    const player = usePlayer();
+
+    return (
+        <World map="slope">
+            <CharacterSpawn />
+            <Camera follow={CameraTarget.ViewTarget} />
+            <Coin position={[3, 0, 5]} />
+            <Chest position={[8, 0, 20]} />
+            <Yeti position={[12, 0, 40]} />
+            <Hud>
+                <Panel slot={Slot.TopLeft}>
+                    <Bar
+                        label="Health"
+                        value={player.health}
+                        maximum={player.maximumHealth}
+                    />
+                </Panel>
+            </Hud>
+        </World>
+    );
+}
+```
+
+Coin, Chest and Yeti are the game's own components, each wrapping an [Entity](/engine/entities/entity/).

package/dist/wiki/engine/testing/agent-state.md

@@ -0,0 +1,131 @@
+---
+title: State for an agent
+description: The calls an agent that cannot look makes to step, read and dump a running game, a view's own state, and the engine's state apart from the world.
+useCases:
+    - step the game from an agent
+    - dump the world's state
+    - read what a view shows
+    - read the camera and frame loop state
+    - check which engine code a page runs
+    - inspect without a screenshot
+sidebar:
+    order: 12.3
+---
+
+An agent reads a running game as data. This page describes the calls an agent makes on `useDevtools`, the store that [the Devtools API](/engine/testing/devtools/) describes, and the state the engine keeps apart from the world.
+
+## For an agent
+
+These calls serve an agent that cannot look:
+
+- `step(seconds)` advances the bound world by that many seconds of fixed steps on its last input, with no clock. It is the harness's `stepSeconds`, and an MCP call: it is never a control in the overlay.
+- `dump()` returns the world as JSON, the harness's `dumpState`: every entity's data traits keyed by id, a hash of them, and `plugins`, the plugins the world was made from, the engine's first, each with its `name`, `description`, `requires`, `options`, `systems`, `isEngine` and `omitted`, and `systems`, every system of the step in its order, each with its `name`, `plugin`, `phase`, `runsOn`, `predicted`, `isEngine` and, for a replacement, `replaces`. The hash covers the entities alone, so two worlds whose entities match hash alike whatever their plugins, and a world on the building blocks alone lists none. `spawnite play dump` prints it, `--where '[npc]'` keeps the entities a selector picks, and `--fields transform,npc.line` keeps only the traits, or fields inside one, that it names, with the entities that hold one, and names each field no entity holds. `spawnite simulate --fields` and the MCP's `simulate` `fields` narrow a headless run's dump the same way. A trait name with dots, such as a state's tag, reads as one key.
+- `capture(view)` returns a PNG of the scene from a bookmarked camera, and `frameView(name)` gives the camera for a name on the map of the World the player's character is in, or of the [first World mounted](/engine/structure/world/#two-worlds): a `views` entry, a region, a path, or `map` for the whole ground from above. The capture leaves out a gizmo, an object drawn for the play camera alone, such as the destination marker; a view marks one by setting `gizmoUserData` as its root object's `userData`. It also leaves out a screen overlay, a quad a view draws in clip space over the whole frame, such as a hurt vignette, which would cover the view it frames: a view marks one with `screenOverlayUserData`, and `capture(view, { overlays: true })` keeps them. The playtest's `screenshot` takes the name as `view`, and a `size` for the viewport, so an agent shoots the same zone after every edit; [the world page](/engine/structure/world/#views) says what a view holds.
+- `captureScreen()` returns a PNG of what the player sees: one render from the camera the game draws with, and nothing the page draws over the canvas, the overlay and the HUD among it. Its screen overlays stay in, and `captureScreen({ overlays: false })` leaves them out. Headless, it returns nothing. The overlay's Screenshot button copies it to the clipboard. Send to agent saves it through the dev server's `/__shots` into the game's `.spawnite/shots/`, where the playtest's screenshots land too; [the dev server page](/engine/testing/dev-server/) has the folder.
+- `readStats()` draws 60 frames and returns what the page costs to draw: three.js's `renderer.info.render` for the last of them (draw calls, triangles, points and lines, summed over every render call in the frame, so a composer's passes count), its `renderer.info.memory` (geometries and textures), and the mean and worst frame time over the 60. A held world draws them without a step. Headless, it returns nothing. `spawnite play stats` prints it, `--json` as an object, and the MCP's `read_render_stats` replies with it. Unity's Stats panel, Unreal's `stat rhi` and Godot's monitors show the same counts.
+- `frameShot(camera, aspect)` gives the camera for a shot with no view written first, from the mounted map's data: an angle, a subject and a zoom, or a raw eye and target. With no map mounted, as in a track game, `all` frames everything the scene draws. A subject the map has no name for may name an entity, by the key its dump files it under, by a selector of what it is such as `[monster.kind=colossus]`, or by its row's one name among the rows whose entity is still in the world: the shot frames what the page draws of it, whether or not the dump names its traits, or its body or its collider where it draws nothing, where it stands now, so the same camera after a step follows it. `findEntities(subject)` answers the keys a subject picks, which `spawnite play dump --where` prints. [The camera page](/engine/entities/camera/#shots-from-any-angle) says what each takes. The playtest's `screenshot` takes it as `camera`, and a `map` to shoot through the `?map=` preview, and names the eye and the target it resolved to.
+- `describe(id)` returns one entity's context bundle: its row in the tree, its behaviours with their props, the wiki page each behaviour declares, the source file a game's own behaviour declares, the systems that touch it and its relations, the `plugins` its world was made from as the dump lists them, under `panel` the values its component declared through [`useDevtoolsPanel`](/engine/ui/devtools-panel/), where it stands on screen, and a PNG screenshot framed on the entity from the running renderer. Headless, there is no screenshot, no screen rect and no `panel`, since the hook does nothing there. A scattered instance's id returns its `placement` in place of traits: its kind, where its foot stands, its height, and its yaw and tilt in degrees, with its `family`, its World's `map` and, where it stands for one of the map's props, the `prop`'s name. Its screenshot is framed on the instance, and the actions that move the camera or change the world, focus, hide, delete and add behaviour, are off for it, because only the map's seed places it. `describe` takes a row's id, its entity's dump key, or its name where one entity row has it. An entity with no row, such as a bolt a system spawns, is found by its dump key and described from its traits, with no row and no behaviours or relations. An id that is one row's id and another row's dump key, as a room game's replica can give, fails naming both rows.
+
+- `setTraits(subject, traits)` writes each trait, by the name the dump files it under and in the shape the dump writes it, onto every entity the subject names, as `findEntities` reads it, and returns their keys: a record's fields over the ones it holds, `null` to take a trait off, `true` to add a tag. A walker whose transform it writes stands there at once, her body built again where the transform says. `spawnite play set` calls it on a game with no room; a room's own write goes through the room, [below](/engine/testing/directing/#setting-the-world).
+- `aimCamera({ yaw, pitch, turn })` turns the player's camera at once, to a yaw and a pitch in the degrees [the engine's state](#the-engines-state) reads, or by `turn` degrees of yaw from where it looks, and returns where it looks. `spawnite play look` calls it.
+- `readViews()` returns what each view exposes of its own state through `useInspect`, [below](#a-views-own-state).
+- `readScope()` returns the scope a read of the page sees, which `PlayScope` types: the world as the dump files it, the engine's state, the live world and scene, the game's modules, `see` and `aim`, and the director's input and time. `compileRead(expression)` reads the scope from an expression, as a browser's console reads one, and `stepUntil` reads its condition that way. `spawnite play eval` runs over it, [Playing a held session](/engine/testing/director/#run-a-check-of-your-own).
+- `startSample(read)` reads an expression, or a function of the scope, after each frame the page draws, and the call it returns stops and answers each frame's value: `spawnite play step --sample`.
+- `see(subject, { part })` returns what the player's camera sees of each entity a subject picks, or of every entity it draws, each with `point`, where it shows on the page nearest the middle of what shows, which `spawnite play press --on` presses, and `readAim()` where the crosshair points beside each shot the page sent its room: `spawnite play see` and `aim`. Headless, both throw.
+
+The dump reads the engine's traits and each trait a game defines. A Koota trait carries no name, so a game makes its own with `defineTrait`, which takes the name first, and the dump and `describe` show it under that name:
+
+```ts
+export const ScoreTrait = defineTrait("score", { points: 0 });
+```
+
+`defineTrait`'s options say [who a room streams the trait to](https://wiki.spawnite.com/platform/room-messages/#choose-who-a-trait-reaches). Make a trait that holds what a dump cannot write with Koota's `trait`: a physics world, a bake, or an object in a scene.
+
+A behaviour declares its description, its page and its file beside its trait, and its row carries all three, so the inspector's card shows the description. A behaviour whose component only adds the trait is made with `defineBehaviour` under a name, which puts the trait in the dump and the behaviour in the context menu's Add behaviour list:
+
+```ts
+export const GlowBehaviour = defineBehaviour({
+    name: "glow",
+    trait: GlowTrait,
+    runsOn: RunContext.Client,
+    description: "Glows brighter as the character nears.",
+    wiki: "/behaviours/glow/",
+    source: "src/behaviours/glow.ts",
+});
+```
+
+## A view's own state
+
+A view keeps state no trait holds: the pose it chose for a character lying on a slope, or the strength of a red it fades in a ref. `useInspect(name, read)` exposes it to the tools. `spawnite play dump` prints what `read` returns under `views`, by the key the dump files the view's entity under, the nearest `Entity`'s or the one passed third, or under `page` for a view that draws none, and `spawnite play eval` reads the same as `views`. The read runs only when a tool asks, so it may read what the last frame wrote:
+
+```tsx
+import { useRef } from "react";
+import { useInspect } from "@spawnite/engine";
+
+export function HurtVignette() {
+    //  The red's strength, which each frame fades.
+    const strength = useRef(0);
+    useInspect("hurt vignette", () => ({ strength: strength.current }));
+    return null;
+}
+```
+
+```sh
+spawnite play eval "views.page['hurt vignette'].strength"
+```
+
+A `--until` condition on `spawnite play step` or `spawnite play screenshot` reads `views` too, so `--until "views.page['hurt vignette'].strength > 0.5"` stops on the frame the red passes half.
+
+A read that throws stands as `{ "error": "..." }` in its place. Unity's inspector shows a component's fields as the game plays, and Godot's remote inspector a node's; here a view names each value it wants a tool to read, since a function component keeps no fields a tool could find.
+
+## The engine's state
+
+The engine keeps its own state apart from the world: where the camera stands and looks, how the frame loop runs, whether the cursor is captured, where the page stands with its room, the plugins its world was made from, and every system of its step. An agent reads it without devtools on a dev build and on a page opened with `?profile`, a production build too, as `window.__GAME_ENGINE_STATE__()`. `spawnite play state` prints it on the running playtest, the MCP's `read_engine_state` replies with the same lines, a `--until` condition reads it as `camera`, `loop`, `cursor` and `room`, `spawnite play profile` reads it as the recording starts and ends, and [`spawnite play join`](/engine/testing/joins/) reads each page's `room`. Godot's remote scene tree and PlayCanvas's `pc.app` hand a tool the same live values.
+
+The read returns the following fields:
+
+| Field                         | What it holds                                                                                                                                                                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `camera.position`             | Where the eye stands, in metres.                                                                                                                                                                                                                                             |
+| `camera.yaw`                  | Degrees about the vertical the camera looks, from -180 to 180: 0 looks down -Z and 90 down -X, as three.js turns an object about Y.                                                                                                                                          |
+| `camera.pitch`                | Degrees above the horizon it looks; below it is negative.                                                                                                                                                                                                                    |
+| `camera.fov`                  | Degrees the lens sees top to bottom; `null` for an orthographic camera.                                                                                                                                                                                                      |
+| `camera.turned`               | Degrees the yaw has swept since the loop mounted, each drawn frame's turn counted whichever way it went.                                                                                                                                                                     |
+| `camera.locked`               | Whether the camera's lock is on: the mouse turns it, and the character faces its way.                                                                                                                                                                                        |
+| `camera.firstPerson`          | Whether the eye stands in the character's head.                                                                                                                                                                                                                              |
+| `camera.shake`                | The [shake](/engine/entities/camera/#shake) the camera holds, from none at 0 to a whole shake at 1: a game's big moments raise it, and it fades on its own.                                                                                                                  |
+| `loop.frameloop`              | How React Three Fiber runs the canvas: `always`, `demand` while the devtools hold the world, or `never` while replay playback drives it.                                                                                                                                     |
+| `loop.held`                   | Whether the devtools hold the world still.                                                                                                                                                                                                                                   |
+| `loop.pausedBy`               | The title of the open modal that pauses the world, or `null`.                                                                                                                                                                                                                |
+| `loop.speed`                  | The devtools' time scale: 1 is real time.                                                                                                                                                                                                                                    |
+| `loop.running`                | False once a frame has thrown and stopped the loop.                                                                                                                                                                                                                          |
+| `loop.steps`                  | Fixed steps of 1/60 s the world has taken since the loop mounted, and `loop.seconds` their seconds.                                                                                                                                                                          |
+| `loop.frames`                 | Frames the page has drawn since the loop mounted.                                                                                                                                                                                                                            |
+| `loop.clock`                  | Seconds on the canvas's clock, which a view animates on: it follows the world's time, so it stands still while the world is held or a modal pauses it, and runs at the devtools' speed.                                                                                      |
+| `cursor.captured`             | Whether the cursor is captured, so the mouse turns the camera. In an automated browser, the engine grants the capture without a lock.                                                                                                                                        |
+| `cursor.pointerLock`          | Whether the browser itself holds a pointer lock on the canvas: always false in an automated browser.                                                                                                                                                                         |
+| `room.status`                 | `connecting` until the room's welcome, `joined` from then, `reconnecting` once a socket that opened closes, and `closed` for good once the room refused her, a minute passed with no socket open, or the game opened no room.                                                |
+| `room.characterId`            | Her character, by the id the room's dump keys it under; `null` until the welcome.                                                                                                                                                                                            |
+| `room.build`                  | The page's build, which each join names; `null` on a dev server's page, which names none.                                                                                                                                                                                    |
+| `room.refusal`                | The close code and reason the room refused her with, as `{ code, reason }`, whatever the reason; `null` until it does.                                                                                                                                                       |
+| `room.full`                   | How full the room was when it refused her for being full, as `{ players, maxPlayers }`; `null` otherwise.                                                                                                                                                                    |
+| `room.buildMismatch`          | The room's build and the page's when it refused her for another build, or its protocol and the page's, as `{ room: "protocol 6", page: "protocol 5" }`, when either refused the other; `null` otherwise.                                                                     |
+| `room.players`                | Players in the room, as its stream shows them to her.                                                                                                                                                                                                                        |
+| `room.roundTripMilliseconds`  | A ping to the room and back, the mean of the last few; 0 before the first answer.                                                                                                                                                                                            |
+| `room.bytesPerSecond`         | What the room's messages to her weighed over the last second.                                                                                                                                                                                                                |
+| `room.sentBytesPerSecond`     | What her page's messages to the room weighed over the last second: her input, a message a frame, her presses, her pings and the rest.                                                                                                                                        |
+| `room.leadTicks`              | Ticks her page's clock runs ahead of the room's, as the room's answers to her pings estimate its tick, read once a second; `null` before the room's first answer.                                                                                                            |
+| `room.stepMilliseconds`       | A step of the room's, on average over the last second, as the room reports it.                                                                                                                                                                                               |
+| `room.replayedSteps`          | The steps the room's corrections of her character had her page replay over the last second.                                                                                                                                                                                  |
+| `room.takenSweeps`            | Of those steps, the ones that took the physics sweep their first run kept rather than sweeping again; none while `sweepRecordSettings.check` sweeps every one to compare.                                                                                                    |
+| `room.tiedSweeps`             | Of those steps, the ones that read what their kept sweep read and swept again, because one of its queries met two colliders at the same distance, which a replay cannot prove it breaks the same way.                                                                        |
+| `room.correctionMilliseconds` | The milliseconds her page spent over the last second receiving the room's messages that corrected her character, the restores and replays among them.                                                                                                                        |
+| `room.link`                   | The [slow link](https://wiki.spawnite.com/platform/multiplayer/#play-it-on-a-slow-connection) a dev page plays the room over, as `{ latencyMilliseconds, jitterMilliseconds, stall }`, the stall `{ milliseconds, everySeconds }` or `null`; all zero on a direct link, and absent from a built game. |
+| `plugins`                     | The plugins the page's world was made from, the engine's first, as the dump lists them; empty for a world made from no list. `spawnite play state` prints each with its description.                                                                                         |
+| `systems`                     | Every system of the page's step, in the order it runs them, the core's among them, each with its `name`, `plugin`, `phase`, `runsOn`, `predicted`, `isEngine` and `replaces`, as the dump lists them. `spawnite play state` prints them one line per phase.                  |
+
+### Which engine code a page runs
+
+A page can run older engine code than its checkout: a tab left open across an edit, or a page from another worktree's dev server. The engine's plugin names the engine build in every page a dev server serves, as a `spawnite-engine` meta tag: a hash of the engine's code and its `package.json`, twelve hex digits, alike for two copies of one engine. A game's dev server answers at `/__spawnite/engine` with the build it serves now and the folder it reads the engine from.
+
+`spawnite play state` and the MCP's `read_engine_state` end with one line that reads both, such as `Engine: build 3f9c02b41e7a, from /work/game-platform/packages/engine/src.` When the server serves another build than the page loaded, the line says so and asks for a reload, since the page runs the older code until it reloads. A built page names its game's build instead, and a page from an engine plugin older than the tag names none, so the line says the page names no engine build.