@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/entities/entity.mdx

@@ -0,0 +1,1063 @@
+---
+title: Entity
+description: A thing in the world and the behaviours that compose on it.
+useCases:
+    - spawn an object in the world
+    - load a 3d model
+    - play a model's animation
+    - collision on an object
+    - name label over a character
+    - place a model at a position
+    - combine behaviours on one thing
+    - react to events on an entity
+sidebar:
+    order: 1
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+`<Entity model position>` spawns a koota entity on mount and destroys it on unmount, except on a page in a room, where it binds to the room's, as [In a room](#in-a-room) says. It publishes itself through a context, so `useEntity()` inside reads that entity and nothing else. UI inside an Entity lives as long as the entity exists.
+
+The children mount once the entity exists and unmount on the commit after it dies, whether the Entity unmounted or a system destroyed the entity mid-frame. Entity draws one group at its pose and binds it to the entity, so a system that moves or turns the entity's transform moves what the children draw, the model included.
+
+## In a room
+
+A game in a room has one scene, which the room mounts headless and every page mounts to draw it. An Entity takes its identity from its place in the scene: for each element from the scene's root down to it, the `key` the game gave it, or its index among its siblings. The room spawns the entity and streams it under that place. On a page, the Entity spawns nothing: it binds to the entity the room streams at its place, draws its model and its children on it, and leaves its position and its behaviours' traits to the stream. A game with a list of entities gives each a `key`, so an entity keeps its identity when the list changes. `Replicas` draws what no Entity of the scene draws, the other players' characters among it.
+
+## Pose
+
+An entity's pose is where it stands, how it is turned and how large it is: `position`, `rotation` and `scale` on the Entity, and the `TransformTrait` trait's three fields of the same names on the entity. The pose is always the world's, never relative to anything, as Unity's `transform.position` and Roblox's `CFrame` are. Metres, right-handed, y up; at rest an entity faces negative z.
+
+- `position` is `[x, y, z]` in metres.
+- `rotation` is three Euler angles in radians, `[x, y, z]` in three.js's default order, as React Three Fiber's `rotation` prop takes them, or a `Quaternion`. The trait stores it as a quaternion.
+- `scale` is one number for every axis, three, or a `Vector3`, and 1 when left out. It is the entity's own.
+
+The collider turns and scales with the entity, so a box tilted on x is a ramp a walker climbs, and a box of size `[1, 1, 1]` at scale `[4, 1, 8]` is a 4 by 1 by 8 box. A sphere takes one scale for every axis and a capsule the same scale across x and z: any other scale throws when its body is built, naming the shape, since neither shape can stretch. What the children draw turns and scales with the entity too, so a model needs no group of its own to turn it.
+
+```tsx
+<Entity
+    position={[0, 0, 10]}
+    rotation={[-0.3, 0, 0]}
+    scale={[4, 1, 8]}
+    collider={{ shape: box({ size: [1, 1, 1] }) }}
+/>
+```
+
+A system reads and writes the pose through the trait, each field a vector it changes in place: `entity.get(TransformTrait)?.position`. To spawn an entity with a pose, give the trait a whole record, which `createTransform` makes from any of the three fields: `TransformTrait(createTransform({ position: [0, 1, 0] }))`. A record with a field left out is a type error, because koota stores the record it is handed, and the missing field would be gone.
+
+## Prefabs, spawning and destroying
+
+`definePrefab(name, { traits, model, animation, body, collider })` declares one kind of entity, at module scope in a module the room and every page import. A scene places one with `<Entity prefab={wolf} position={[4, 0, 10]} />`, and a system spawns more with `spawn(step, wolf, { position, rotation, scale, traits })`. Both run the same code, so the two carry the same traits, stream alike and dump alike, and each carries `PrefabTrait` with the prefab's name. Each spawn copies the prefab's records and its own, so no two entities share a list, and a spawn's own `traits` go over the prefab's field by field. A copy of a prefab, such as `{ ...wolf }`, spawns as the prefab. A prefab whose collider is its model's hull names its `model`, and a spawn throws where the model's corners wrap no body, as a scene's Entity does. An Entity's own `model`, `animation`, `body` and `collider` go over its prefab's, and so do a spawn's own `body` and `collider`. A prefab with `placed: false` spawns entities with no pose, such as a ledger; any other spawns at the origin unless the spawn gives a pose. Unity's prefab and `Instantiate` are the model.
+
+Who may spawn and destroy is a type, as who may deal damage is:
+
+- `spawn` takes an `Authority`: the room's step, in a system with no `runsOn` or inside `if (step.authoritative)`, or `requireAuthority(world)` outside a step. A step on a page in a room, a predicted step there and a re-run are no authority, and a view holds only a world, so none of them can spawn what the room streams.
+- `destroy(authority, entity)` takes the same, or the one `findAuthority(world, entity)` gives over an entity only this page holds. Every field a trait names under `entities` that held the entity reads null from that moment, and a list drops it, so a system later in the tick never reads a dead entity.
+- `spawnLocal(world, prefab, options)` makes an entity only this world holds, page-only on a page in a room: no stream carries it, such as a placement ghost or a preview. A re-run refuses it, since it would make one for every correction.
+
+A game's source reaches koota's own `world.spawn` and `entity.destroy()` only through these: the engine's lint rule names each call.
+
+The [crate on the body section](#bodies-and-colliders) is one such prefab.
+
+## Attaching one entity to another
+
+`attach(authority, child, parent, { offset, rotation })` makes the child's pose follow its parent's every step, after the physics step, as Roblox's weld holds one part to another and Unreal attaches one actor to another. The child's `TransformTrait` stays its pose in the world; `AttachmentTrait` holds the `offset`, in metres along the parent's axes, and the `rotation` after the parent's. An option left out keeps where the child stands from the parent now, as Unity's `SetParent` keeps the world pose. A chain stands parents first, so a flag on a turret on a tank follows both.
+
+- `detach(authority, child)` lets the child go where it stands, with its parent's speed, so a rider who jumps off a moving kart keeps going. A character stands upright again, since her controller turns her about the vertical alone.
+- Destroying a parent lets each child go where it stood, in the same destroy.
+- An attached entity takes no part in collisions: a walker's capsule and a collider's body leave the physics world until it lets go.
+- Scale is the child's own and never follows the parent's: a scaled kart does not scale its rider, and an offset stays in metres. A system that grows a mount and its rider together sets both scales.
+- `attach` takes the same authority as `destroy`: the room's step, `requireAuthority(world)` outside a step, or `findAuthority(world, child)` for an entity only this page holds. An attachment that would make a loop, or one to an entity that is gone, attaches nothing: `attach` returns the reason, an `AttachRefusal`, and a development world throws, naming both entities.
+- A predicted system may write the child's `AttachmentTrait` `offset` and `rotation`, such as a turret it aims on her kart, and every page streams the attachment.
+- A page draws a rider from her parent's drawn pose, so she never slides against the saddle while the kart blends between sends or eases out of a correction.
+
+```ts title="packages/engine/test/outside/kart.ts"
+import type { Entity } from "koota";
+import { attach, detach, type AuthoritativeStep } from "@spawnite/engine";
+
+/** Seats `rider` on `kart`, 0.6 m up and 0.2 m back from its middle. */
+export function mount(step: AuthoritativeStep, rider: Entity, kart: Entity) {
+    attach(step, rider, kart, { offset: [0, 0.6, 0.2] });
+}
+
+/** Lets `rider` go where she sits, with the kart's speed. */
+export function dismount(step: AuthoritativeStep, rider: Entity) {
+    detach(step, rider);
+}
+```
+
+## Models
+
+A model is a GLTF file. `registerModel(name, model)` keeps a model under the name: its file's entry in the game's model manifest, or a bare url, and `<Entity model>` draws that file's scene inside the entity's group, stood on its lowest point at the entity's feet, each entity with its own copy on the one loaded geometry. The file's front is +z, as glTF puts it, and the engine turns the model half a turn so that its front faces the way the entity does, along -z at rest. Godot names +z a model's front in the same way, while its nodes look along -z. [InstancedModel](/engine/graphics/instanced-model/), a map's [model props](/engine/structure/world/#props) and the [scatter](/engine/structure/world/#scatter) draw the file unturned, with only their own yaw, so at a `turn` or `yaw` of 0 its front faces +z. A file centred on its origin, as the kit's come, is lifted by half its height, and one whose origin is its feet does not move. [`<CharacterSpawn>`](/engine/entities/player/#the-default-body) and [InstancedModel](/engine/graphics/instanced-model/) stand the same file the same way, so a model placed at `y = 0` stands on flat ground whichever draws it. The children stand while it loads. `readModel(name)` throws on a name nobody registered, which an `<Entity model>` with that name does as well, into the game's boundary, as [World](/engine/structure/world/#maps) does for a map. The engine registers no model of its own.
+
+A model with animations plays one of them by name. `animation` names the clip the entity loops, as the file names it: `<Entity model="duck" animation="walk" />` walks the kit's duck, whose other clips are `idle`, `attack` and `dead`. Set `animation` to another name to switch clips. Each entity plays the clip on its own copy of the model's skeleton, so two ducks move apart. Every entity looping a clip of one model draws in that model's [skinned batch](/engine/graphics/skinned-batch/): one draw for each of its meshes, however many stand. A name the file lacks plays nothing, and a dev world warns once with the names the file has. [Models](https://wiki.spawnite.com/learn/models/) says how to name the clips when you make the model.
+
+`playClip(entity, name)` plays one of the file's clips once over the loop, then fades back to the loop. A hit or an attack plays this way: `playClip(wolf, "hit")`. The clip fades in over `fadeSeconds`, 0.15 s by default, and fades out over its last `fadeSeconds`. A second call starts the clip again, the same clip included. `{ hold: true }` holds the last frame instead, as a death does, until `stopClip(entity)` fades it back or the next `playClip` replaces it. On a model that loops nothing, the clip plays at full weight, and a clip that does not hold returns the model to its rest pose at its end. The call writes the `OneShotClipTrait` trait, so call it from a system or an event: a room streams the trait, and every page plays the clip. A page that joins after a clip started plays none of it, except a held clip, which it plays from the start and holds. A name the file lacks plays nothing and stops the clip the layer plays, as `stopClip` does, and a dev world warns once with the names the file has.
+
+`layer: ClipLayer.UpperBody` plays the clip on the bones from the model's spine up, while its loop goes on driving its hips and legs; `start`, `end` and `speed` play part of the clip; and `useAfterPose` leans or turns the posed model each frame, as [the player page](/engine/entities/player/#one-shot-clips) says for her model. The spine is the model's first bone whose name holds `spine`: the kit duck's `Spine` holds its head, so `playClip(duck, "attack", { layer: ClipLayer.UpperBody })` attacks with its head while its legs walk.
+
+Unreal plays a montage over the state machine in the same way, and replicates it, and limits it to the upper body with a layered blend per bone. Unity fires an Animator trigger into a state that exits back, on a layer an `AvatarMask` limits, Godot plays a one-shot node in an `AnimationTree` with bone filters, and Roblox plays a loaded animation track at a priority over the loop, on the joints its keyframes name.
+
+A walker takes its size from its model, and nobody types the numbers. The flow runs as follows:
+
+1. `spawnite add asset <id>` copies a model into the game's `public/assets/` folder and bakes that folder into `src/models.json`. Each file's entry holds its path, its bounds, the capsule that fits inside it, which has the model's height and a radius of half its smallest extent, and the corners of its convex hull.
+2. The game's `src/models.ts` registers every entry under its file's id, and under the game's own names for it, such as the arena's `monster` for `rock-boulder`. The scene imports that module, so the room, which loads no model file, cuts the same capsule every page does. `spawnite add asset` writes the module for a game that has none, and prints the line that imports it into the scene.
+3. A `CharacterCapsuleTrait` whose `radius` or `height` the game leaves out takes the registered capsule. A size the game sets wins, field by field. A radius over half the height would give the capsule a negative length, so the engine cuts the radius to half the height, writes that into the `CharacterCapsuleTrait`, and warns once in a dev world.
+
+A walker whose model has no measured size, one registered by a bare url or not at all, gets a player's character's 0.35 m by 1.4 m, and a dev world warns once for its name. Each game's `models` target bakes the manifest before `dev`, `build`, `test` and `room`, and the dev server rebakes it when a model file appears, changes or goes. The manifest check compares a fresh bake with the manifest as committed, not the working copy that `test`'s own bake has just rewritten, so in a repository a commit that changes a model without its manifest fails the test with the command to run; outside git the check reads the working copy. The bake records what the file draws: the kit's duck and red panda are drawn in centimetres and measure hundreds of metres, and the bake warns about each, as [Models](https://wiki.spawnite.com/learn/models/) says. Unity, Unreal and Godot measure a model when it is imported and store the result beside the asset, where the server reads it; the manifest is that stored measurement.
+
+A model may be Draco-compressed: every GLB the engine loads, a VRM included, decodes Draco with three's glTF decoder. A texture may be KTX2: `useKtx2(url)` loads one inside the Canvas, transcoded by Basis into a format the device's GPU reads, for a material's `map`. It suspends while it loads, and the texture is shared by URL, so its wrapping and repeat change for every material that uses it. The decoder and the transcoder come from the `three` package, and the game's build copies them beside its bundle, so a player's device fetches them from the game's own site, and only once a file needs them. Compress assets before they are committed; the engine decodes and does not compress.
+
+```tsx
+import { Entity, registerModel, useKtx2 } from "@spawnite/engine";
+import rock from "./rock-draco.glb?url";
+import snow from "./snow.ktx2?url";
+
+registerModel("rock", rock);
+
+export function Slope() {
+    const map = useKtx2(snow);
+    return (
+        <>
+            <mesh rotation-x={-Math.PI / 2}>
+                <planeGeometry args={[20, 20]} />
+                <meshStandardMaterial map={map} />
+            </mesh>
+            <Entity model="rock" position={[0, 0, -4]} />
+        </>
+    );
+}
+```
+
+## Materials
+
+`material` changes what an entity's model wears: a function handed each of the file's materials, which returns the one the model wears in its place. A team's colour, a hit's flash, a stone curse or a hologram is a function of this kind. The original is the loaded file's, which every other draw of the file wears, so return a new material, such as a clone, rather than the original changed.
+
+The engine asks the function once for each of the file's materials and keeps what it returns. Every Entity handed the same function wears the same materials, and the animated ones draw in one [skinned batch](/engine/graphics/skinned-batch/): one draw for each mesh, however many stand. A second function draws in a batch of its own, so give each look one function and define it once, outside the component. A function made anew in each render makes new materials in each render.
+
+To change the look of one entity for a while, such as a hit's flash, hand it another function for as long as the look lasts, and `undefined` to go back to the registered material or the file's own. The entity moves to that function's batch and keeps its skeleton, its mixer and its clips. A batch whose last entity leaves waits 30 seconds for the next before it is freed, so a flash that comes back draws in a batch whose first draw is done. Looks do not stack: each function is handed the file's materials, never another function's result, so a red team's flash is a function of its own. A look under the engine's tone mapping reads darker than its colour, so a flash that should read white sets an `emissiveIntensity` above 1. A value that changes for each entity over time, such as a flash that fades out or how far one enemy has dissolved, is not a `material`: draw that entity with a view of the game's own, whose [skinned batch](/engine/graphics/skinned-batch/#batch-a-games-own-view) holds a value for each copy.
+
+The following rules hold for every model the engine draws:
+
+- When the function returns a see-through material, one with `transparent: true`, the entities wearing it leave the batch, and each draws on its own, sorted back to front with the scene's other see-through draws.
+- A mesh drawn with several materials asks the function for each of them.
+- A shader patch, an `onBeforeCompile` on what the function returns, draws in the batch too: the batch never copies the material, since three.js leaves the hook out of a copy, and each hook compiles a program of its own.
+- A new load of the file asks the function again for the new file's materials, and a change of quality level leaves them as they are.
+- What the function returns is the game's to dispose: the engine never disposes it, so one material can dress many models.
+
+`registerModel(name, { path, material })`, or a manifest's entry with `material` beside it, gives the model a material wherever the engine draws it by that name: an `<Entity>` with no `material` of its own, an [InstancedModel](/engine/graphics/instanced-model/), a map's model prop, and an entity a system spawns or a room streams. A function cannot travel to another page, and a name can, so the registration is how every page in a room dresses the entities the room spawns. Every page registers its models from the same module, so each holds the same function. A collider's `material` is unrelated: it is the body's friction and bounce.
+
+These ducks walk in their team's colour, the red team in one draw and the blue team in another. The engine's tests mount this file:
+
+```tsx title="packages/engine/test/outside/TeamDuck.tsx"
+import { Entity, type ModelMaterial, type Position } from "@spawnite/engine";
+import { MeshStandardMaterial } from "three";
+
+//  Ducks in their team's colour: each wears its file's texture tinted red
+//  or blue, and walks on its own skeleton.
+
+export enum Team {
+    Red = "red",
+    Blue = "blue",
+}
+
+/** The file's material tinted `color`, which multiplies the file's
+ *  texture: a copy, since the original is the loaded file's, which every
+ *  other draw of the file wears. */
+function tint(color: string): ModelMaterial {
+    return (original) => {
+        const tinted = original.clone();
+        if (tinted instanceof MeshStandardMaterial) tinted.color.set(color);
+        return tinted;
+    };
+}
+
+//  Made once, outside the component: each function is asked once for each
+//  of the file's materials, so every duck of a team wears the same ones and
+//  the team draws in one draw per mesh.
+const colors: Record<Team, ModelMaterial> = {
+    [Team.Red]: tint("#d04a3a"),
+    [Team.Blue]: tint("#3a6ad0"),
+};
+
+interface TeamDuckProps {
+    team: Team;
+    position: Position;
+}
+
+export function TeamDuck({ team, position }: TeamDuckProps) {
+    return (
+        <Entity
+            model="duck"
+            animation="walk"
+            position={position}
+            material={colors[team]}
+        />
+    );
+}
+```
+
+Unity gives a renderer its own material instance, or a property block for a value per renderer that keeps it in its batch; Unreal makes a dynamic material instance per mesh; Godot sets `material_override` on a mesh instance; Roblox sets a part's material and colour, or a `MaterialVariant`; and PlayCanvas sets a material, or a shader parameter, on each mesh instance. `material` takes Godot's override and Unity's shared material: one function stands for one look, so the engine can draw every entity of a look together, and a game writes no per-instance bookkeeping. `<Entity>` has no equivalent of Unity's property block yet: a value for each entity is a view of the game's own, as the paragraph above says.
+
+## Display name
+
+`<DisplayName name="Wolf" />` inside an Entity gives it the name a player reads: a target frame's title, a plate over its head. It writes `DisplayNameTrait`, which a room streams with the entity. Every plate and frame reads a name through one reader, `useDisplayName(entity)` in a component and `readDisplayName(entity)` elsewhere, which takes the first of: the display name, the name a player joined a room as, an NPC's own name, and the model's name in words, so `red-panda` reads Red panda. Roblox's `DisplayName` stands over a character's name the same way; Unity, Unreal and Godot leave names to each game.
+
+## Authority
+
+Every entity says which end steers it. In a room, the room runs the game and has the final say over every entity, each player's own character included. Her page also runs her character, ahead of the room, so a key press moves her at once on a phone. The room runs the same move from her input, and where the two disagree, her page takes the room's position. [Multiplayer](https://wiki.spawnite.com/platform/multiplayer/#fair-play-built-in) says what that keeps a modified page from doing.
+
+An Entity carries an `AuthorityTrait` trait, `RunContext.Server` unless the `authority` prop says `RunContext.Client`. `Client` means this page steers the entity ahead of the room and keeps its own movement over what the room streams; the room never takes the page's word for where it is. The one entity that says `Client` is the local player's character, and the `<CharacterSpawn>` component sets that itself. A single-player game runs the whole simulation on the page, writes no `authority` prop, and the default costs it nothing. The defaults in a room:
+
+| Entity kind                        | Steered by                  | Note                                                         |
+| ---------------------------------- | --------------------------- | ------------------------------------------------------------ |
+| A player's own character           | Her page, ahead of the room | The room runs each move from her input and corrects her page |
+| Other players' characters          | The room                    | Drawn from the room's stream, smoothed between its snapshots |
+| Pickups, spawners, enemies and AI  | The room                    | The page draws what the room streams                         |
+| Physics props                      | The room                    | Drawn from the stream; the page's own body for it can drift  |
+| Score, wallet, inventory, progress | The room                    | The page reads, never writes                                 |
+| Timers, rounds, match state        | The room                    |                                                              |
+| Cosmetic effects, local UI         | Each page                   | Changes only what that page draws                            |
+
+[The trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#what-a-room-decides) cites this section for the room authority contract.
+
+## Bodies and colliders
+
+An Entity without a `collider` has no body: a coin is walked through, and a ball placed in the air stays there. Two keys give it one, on `<Entity>`, on `definePrefab` and through `spawn` alike:
+
+- `collider` is its shape, one collider or a list of them, each with an `offset` and a `rotation` in the entity's own axes, a `material`, a `trigger` flag and, where one part differs from the rest, its own `collisionLayer` and `collisionMask`. A collider's index in the list names it.
+- `body` is how it moves: `bodyType` is `RigidBodyType.Fixed`, `Kinematic` or `Dynamic`, Rapier's names with one kinematic kind, and each kind takes only the settings that mean something for it, so a kinematic body's `mass` or a dynamic body's `pushes` fails to typecheck. A collider with no body is a fixed body.
+
+The physics world builds the body on the step after the entity spawns and takes it out in the same tick the entity is destroyed, so a cast later in that tick misses it, and what rested on it wakes and falls.
+
+```ts title="packages/engine/test/outside/crate.ts"
+import type { World } from "koota";
+import {
+    box,
+    definePrefab,
+    HealthTrait,
+    RigidBodyType,
+    spawn,
+    type AuthoritativeStep,
+} from "@spawnite/engine";
+
+export const crate = definePrefab("crate", {
+    traits: [HealthTrait({ current: 20, maximum: 20 })],
+    model: "crate",
+    body: { bodyType: RigidBodyType.Dynamic },
+    collider: { shape: box({ size: [1, 1, 1] }) },
+});
+
+export function dropCrates(world: World, step: AuthoritativeStep) {
+    spawn(step, crate, { position: [0, 4, 0] });
+}
+```
+
+### Shapes
+
+A helper makes each shape from named sizes, since Rapier takes half extents where three.js takes full ones:
+
+| Helper                                                     | Size                                                                                                                    | Bodies              |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `box({ size })`                                            | Full extents, `[width, height, depth]`                                                                                  | Any                 |
+| `sphere({ radius })`                                       | Radius                                                                                                                  | Any                 |
+| `capsule({ radius, height })`                              | Height from tip to tip, as Unity's and Godot's capsules take it                                                         | Any                 |
+| `cylinder({ radius, height })`, `cone({ radius, height })` | Full height, centred halfway up                                                                                         | Any                 |
+| `convexHull({ points })`                                   | The points' hull; with no points, the hull of the entity's `model`, which it then names                                 | Any                 |
+| `triangleMesh({ vertices, indices })`                      | A concave mesh, three indices per triangle                                                                              | Fixed and kinematic |
+| `heightfield({ heights, rows, columns, size })`            | `rows` samples along z by `columns` along x, row by row, over `size`, `[width, depth]`, centred on the entity           | Fixed               |
+| `voxels({ size, cells })`                                  | Cubes `size` metres on a side; the cell `[x, y, z]` is the cube from those numbers times `size` to one `size` past them | Fixed               |
+
+The body's type refuses a shape its kind cannot take: a triangle mesh, a heightfield or voxels on a dynamic body has no inside to weigh.
+
+Colliders turn and scale with the entity, offsets included, so a box tilted on x is a ramp a walker climbs, and a box of size `[1, 1, 1]` at scale `[4, 1, 8]` is a 4 by 1 by 8 box. A sphere takes one scale on every axis, and a capsule, a cylinder and a cone the same scale across x and z. A collider turned in its entity takes one scale on every axis, since a turned box would shear. Any other scale throws when the body is built, naming the shape.
+
+A model's hull wraps the corners its manifest entry holds, so its body stands before the model loads, and in a room, which loads no model. A model registered by a bare url, or baked with `hullPoints: false`, has no corners, so the Entity throws into the game's boundary, naming the model. A hull thin in one direction, such as a rug's or a post's, gets a body a centimetre past its points across that direction, and a hull Rapier refuses, such as a slender pole of many sides, falls back to the box around its points, which every world warns about once. Give such a model a box or a capsule collider.
+
+### Layers
+
+A body stands in one `collisionLayer` and meets the layers its `collisionMask` lists. Two bodies touch only when each one's mask holds the other's layer, the rule Rapier and PlayCanvas use; Godot passes a pair when either mask holds the other's. A mask is a list of layers, `{ except: [...] }` for every layer but those, or every layer when left out.
+
+A plugin declares its own layers by name, `definePlugin({ name: "pitch", collisionLayers: ["karts", "ball"] })`, and a body names each by its handle, `pitch.collisionLayers.ball`. The core reserves `CoreLayers.default`, where every body stands that names none, and `CoreLayers.ground`, where the terrain, its edge walls and its scatter stand; `characters()` declares `characters.collisionLayers.players` and `npcs`, which every world numbers. That leaves 12 of Rapier's 16 for a game's plugins, numbered in list order, and a world whose plugins declare more refuses to be made, naming each plugin and its count. A page and its room compare the numbering at the welcome.
+
+- `pushes`, on a kinematic body, lists the dynamic layers it pushes, every layer of its mask when left out. A kart that leaves the ball out still meets it and passes through, so the game's own system decides the kick.
+- `ignore: [entity]` skips the pairs between this body and the entities named, such as a rider and her own dragon, without spending a layer.
+- A `trigger` collider touches nothing and weighs nothing unless its material says so; its entry and exit events arrive with the contacts step.
+
+### Mass, damping and materials
+
+A dynamic body's mass is its colliders' density times their volume, at Rapier's density 1, so a 1 m crate weighs 1 kg. `mass` sets the total in kilograms over the densities, and `centerOfMass`, in the entity's axes, moves the centre, so a kart sits low. `linearDamping`, `angularDamping`, `gravityScale`, `canSleep`, `enabledRotations` and `enabledTranslations` take Rapier's and Unity's meanings. `continuousCollision: true` stops a fast body at a thin wall; without it, a development world warns once for each body that moves farther in one step than its thinnest collider is thick. A collider's `material` takes `friction`, 0.5 by default, `restitution`, 0, `density`, and `frictionCombine` and `restitutionCombine` from `CombineRule`.
+
+### Changing a body while it lives
+
+`BodyTrait` and `ColliderTrait` hold what the entity declared. A game reads them with `readTrait(entity, BodyTrait)`, never koota's `get`, which refuses them by type as it refuses writing them, and changes them through three verbs on its authoritative step, which edit the body in place, so it keeps its velocity, its sleep and the pairs it holds, and each change streams:
+
+- `setBody(step, entity, changes)` changes its kind, layer, mask, `pushes`, `ignore`, mass and the rest: `setBody(step, crate, { bodyType: RigidBodyType.Kinematic })` picks a crate up.
+- `setCollider(step, entity, changes, { index })` changes one collider's shape, place, material, trigger flag, layer or mask: a door turned trigger is walked through, and the crate resting on it falls. `collisionLayer: null` and `collisionMask: null` give a collider's own layer and mask back to its body's.
+- `setVoxel(step, entity, [x, y, z], filled)` fills or empties one cell of a voxels collider, as Rapier's `setVoxel` does, without rebuilding the grid.
+
+A change of an Entity's own `body` or `collider` prop does the same, and a change of its `position` or `rotation` prop places its body there, as a teleport does. A dynamic or kinematic body writes its pose back onto the entity every step, so what the children draw falls, rolls and rides with it. The player's own character has no `collider`: her capsule is `CharacterCapsuleTrait`, which the player page describes.
+
+### Moving a body
+
+A body moves only through the physics: the solver, a force, its next pose or a teleport. Every verb takes the authority first, as `setBody` does, so a view and a page's step, which decide nothing, fail to typecheck, and a predicted system narrows with `if (step.authoritative)` first. Every read takes the world and works anywhere. Vectors are three.js `Vector3`s or anything with `x`, `y` and `z`; a verb copies what it is given.
+
+- `applyImpulse(step, ball, kick, { at })` changes a dynamic body's velocity at once, in newton-seconds; `at`, a point in world space, adds the spin an off-centre kick gives. `applyTorqueImpulse` does the same for its spin.
+- `applyForce(step, boat, thrust, { at })` and `applyTorque(step, wheel, drive)` push for the next physics step alone, as Unity's `AddForce` does, so a system that stops calling them stops pushing.
+- `setLinearVelocity` and `setAngularVelocity` set a dynamic body's velocity and spin, in metres and radians a second.
+- `setNextPose(step, lift, { position, rotation })` sets where a kinematic body stands after the next physics step, as Unity's `MovePosition` does: the step moves it there with the velocity of the move, so a lift carries the crate on it and a door that swings pushes one aside. A query before the step meets it where it stood. A second call in one tick replaces the position or the rotation it names, so a spin and a bob land together. `<Spin>`, `<Bob>`, a `VelocityTrait` and a track mover move a kinematic body this way, each onto where `readNextPose(world, entity, into)` says an earlier system sent it this tick, so their moves add up; a game's own mover does the same.
+- `teleport(step, entity, { position, rotation, keepVelocity? })` places a body of any kind at once, with no sweep, keeping its velocity and waking it, as Unity, Godot and Roblox keep a body's velocity when a script sets its position; `keepVelocity: false` stops it, as a respawn wants. A kinematic body arrives without pushing, and every page draws it there with no glide. It answers `{ isClear }`: false where the body overlaps a fixed or kinematic body there, which marks it `StuckTrait` until its next move recovers it. A dynamic body teleported inside a fixed one is pushed out over the next steps, and a development world warns once, naming both. A character takes the same call, as [the player page](/engine/entities/player/#changing-her-movement-for-a-while) says.
+- `moveAndSlide(step, entity, { velocity, rotation?, floorSnapDistance? })` moves a kinematic body by a velocity for one tick, sliding along what it meets, as Godot's `move_and_slide()` does: it pushes the shape out of anything it starts inside, slides along one surface, follows the crease of two and stops against three, turns in place and is pushed out of what the turned shape overlaps, and snaps down onto a floor within `floorSnapDistance`. It answers what the move did, `slideVelocity`, `isGrounded`, `hits` and the rest, as scratch its next call overwrites. On the room the physics step pushes each dynamic body the tick's move reaches along its net displacement. It refuses a dynamic body and a character, which `moveCharacter` moves.
+- `commitPose(step, entity, { position, rotation })` moves the step's own entity to a pose a game computed, with no recovery, push out or slide, as a continuous move rather than a teleport: what a game's own movement policy commits its result through.
+- `wakeUp(step, crate)` and `sleep(step, crate)` wake a dynamic body or put it to sleep. A force, an impulse, a velocity and a teleport each wake it too.
+- `readLinearVelocity(world, ball)`, `readAngularVelocity(world, ball)` and `isSleeping(world, ball)` read a body anywhere: on a page, a body the room simulates reads the room's velocity and sleep from the stream, which sends each awake body's every send and a sleeping body's once. The two reads write one vector each that the next call reuses, so copy one to keep it.
+
+A force, a velocity and sleep act on a dynamic body, and `setNextPose` on a kinematic one. A prefab's kind refuses the wrong verb by type: `applyImpulse` on a kart `spawn` made from a kinematic prefab fails to typecheck. A plain `Entity`'s kind is read when the verb runs: a development world throws, naming the system and the fix, and a deployed one refuses with a `BodyRefusal`, `"not-dynamic"` or `"not-kinematic"`, which the verb returns, logs once and keeps running. So does a write to a body's transform, which the body does not follow: the next physics step throws in development, naming the entity, and puts the transform back where the body stands deployed (`"use-set-next-pose"`). A verb on a body spawned in the same tick builds the body at once and acts on it, and a force on a body destroyed in the same tick goes with it.
+
+A prefab that declares its body hands its kind to every entity `spawn` makes of it: `spawn(step, crate)` returns a `BodyEntity<RigidBodyType.Dynamic>`, which a verb for one kind of body reads.
+
+In a room, the room simulates every shared body, and a page holds each one it streams as a stand-in: of its declared kind to every filter, placed at the newest streamed pose and never stepped, so it never drifts. A character on a streamed kinematic body is carried by the room's velocity for it. A fixed or kinematic body stops a shot in the room and on the page, and so does a dynamic one.
+
+The following file is a pitch on a map with no terrain: layers its plugin declares, a ball, and two karts of two colliders each, one of which leaves the ball out of what it pushes. `outsidePitch.test.ts`, in the room's tests, runs it in a real room.
+
+```ts title="packages/room/test/outside/pitch.ts"
+import { createQuery, type World } from "koota";
+import { Vector3 } from "three";
+import {
+    box,
+    CoreLayers,
+    definePlugin,
+    definePrefab,
+    defineTrait,
+    fixedStepSeconds,
+    RigidBodyType,
+    setNextPose,
+    spawn,
+    sphere,
+    TransformTrait,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  A pitch on a map with no terrain, built as a creator's plugin is, from
+//  the engine's public entry alone: a fixed floor, two balls on a layer
+//  the plugin declares, and two karts of two colliders each, a chassis and
+//  a trigger at the nose that meets the ball alone. The room drives both
+//  karts up the pitch; one pushes its ball, and the other, whose `pushes`
+//  leaves the ball out, passes through its own, as a ball kit that applies
+//  its own kick would want.
+
+export const pitch = definePlugin({
+    name: "pitch",
+    collisionLayers: ["karts", "ball"],
+    systems: { rules: { drive: { system: driveKarts } } },
+});
+
+/** Metres a second the room drives each kart up the pitch, along +z. */
+export const kartSpeed = 3;
+
+/** Marks a kart, so the drive finds it. */
+export const KartTrait = defineTrait("pitchKart");
+
+/** A ball, by the lane it starts in. */
+export const BallTrait = defineTrait("pitchBall", { lane: 0 });
+
+export const floor = definePrefab("pitchFloor", {
+    collider: { shape: box({ size: [40, 1, 40] }) },
+});
+
+export const ball = definePrefab("pitchBall", {
+    body: {
+        bodyType: RigidBodyType.Dynamic,
+        mass: 0.45,
+        collisionLayer: pitch.collisionLayers.ball,
+        collisionMask: [CoreLayers.default, pitch.collisionLayers.karts],
+        continuousCollision: true,
+    },
+    collider: {
+        shape: sphere({ radius: 0.4 }),
+        material: { friction: 0.6, restitution: 0.3 },
+    },
+});
+
+/** A kart: its chassis, and a trigger at its nose that meets the ball
+ *  alone, its own layer and mask over the body's. */
+function declareKart(name: string, pushesBall: boolean) {
+    return definePrefab(name, {
+        traits: [KartTrait],
+        body: {
+            bodyType: RigidBodyType.Kinematic,
+            collisionLayer: pitch.collisionLayers.karts,
+            pushes: pushesBall ? [pitch.collisionLayers.ball] : [],
+        },
+        collider: [
+            { shape: box({ size: [1.4, 0.5, 2.2] }), offset: [0, 0.35, 0] },
+            {
+                shape: box({ size: [1.6, 0.8, 0.4] }),
+                offset: [0, 0.6, 1.3],
+                trigger: true,
+                collisionMask: [pitch.collisionLayers.ball],
+            },
+        ],
+    });
+}
+
+export const kart = declareKart("pitchKart", true);
+export const ghostKart = declareKart("pitchGhostKart", false);
+
+const karts = createQuery(KartTrait, TransformTrait);
+
+function driveKarts(world: World, step: AuthoritativeStep) {
+    if (step.tick === 1) {
+        spawn(step, floor, { position: [0, -0.5, 0] });
+        spawn(step, ball, {
+            position: [-4, 0.4, 0],
+            traits: [BallTrait({ lane: -4 })],
+        });
+        spawn(step, ball, {
+            position: [4, 0.4, 0],
+            traits: [BallTrait({ lane: 4 })],
+        });
+        spawn(step, kart, { position: [-4, 0, -4] });
+        spawn(step, ghostKart, { position: [4, 0, -4] });
+        return;
+    }
+    for (const each of world.query(karts)) {
+        const at = each.get(TransformTrait)?.position;
+        if (!at) continue;
+        next.set(at.x, at.y, at.z + kartSpeed * fixedStepSeconds);
+        setNextPose(step, each, { position: next });
+    }
+}
+
+//  Where a kart drives to this tick, written in place for each.
+const next = new Vector3();
+```
+
+The following file kicks a ball the room alone simulates, on a press of hers: the room applies the impulse, and her page reads the ball's velocity and its sleep from the stream. `outsideKick.test.ts`, in the room's tests, runs it in a real room.
+
+```ts title="packages/room/test/outside/kick.ts"
+import type { World } from "koota";
+import { Vector3 } from "three";
+import {
+    applyImpulse,
+    box,
+    definePlugin,
+    definePrefab,
+    definePress,
+    defineTrait,
+    readPresses,
+    RigidBodyType,
+    spawn,
+    sphere,
+    type AuthoritativeStep,
+    type PredictedStep,
+} from "@spawnite/engine/core";
+
+//  A ball a player kicks, on a map with no terrain, built as a creator's
+//  plugin is, from the engine's public entry alone: the room spawns a
+//  fixed floor and a ball only it simulates, and a press of hers kicks the
+//  ball up the pitch with an impulse. Her page holds the ball as a
+//  stand-in, and reads its velocity and its sleep from the stream.
+
+/** The kick, in newton-seconds along +z: 2.4 m/s on a 0.45 kg ball. */
+export const kickImpulse = new Vector3(0, 0, 1.08);
+
+/** Marks the ball, so the kick finds it. */
+export const KickBallTrait = defineTrait("kickBall");
+
+export const kicks = definePlugin({
+    name: "kicks",
+    messages: { kick: definePress({}) },
+    systems: {
+        input: { kick: { system: kickBall, predicted: true } },
+        rules: { setUp: { system: setUpPitch } },
+    },
+});
+
+const floor = definePrefab("kickFloor", {
+    collider: { shape: box({ size: [40, 1, 40] }) },
+});
+
+const ball = definePrefab("kickBall", {
+    traits: [KickBallTrait],
+    body: {
+        bodyType: RigidBodyType.Dynamic,
+        mass: 0.45,
+        linearDamping: 1,
+        angularDamping: 1,
+    },
+    collider: { shape: sphere({ radius: 0.4 }) },
+});
+
+/** The room's pitch, on its first tick: a floor at height 0 and the ball
+ *  resting on it, away from where her character stands. */
+function setUpPitch(_world: World, step: AuthoritativeStep) {
+    if (step.tick !== 1) return;
+    spawn(step, floor, { position: [0, -0.5, 0] });
+    spawn(step, ball, { position: [6, 0.4, 0] });
+}
+
+/** Kicks the ball on each of her presses, on the room alone: her page,
+ *  whose step is no authority, reads the press and leaves the ball to the
+ *  stream. */
+function kickBall(world: World, step: PredictedStep) {
+    const presses = readPresses(step, kicks.messages.kick);
+    if (!step.authoritative) return;
+    const [kicked] = world.query(KickBallTrait);
+    if (!kicked) return;
+    for (let count = 0; count < presses.length; count++)
+        applyImpulse(step, kicked, kickImpulse);
+}
+```
+
+### Joints
+
+A joint holds two bodies together on every physics step, or one body to the world, so they move as one machine: a gate on its post, a trailer behind a kart, a fence panel that breaks off. Each joint is an entity of its own, which `createJoint(step, body, options)` makes and returns, and `<Joint>` makes inside an `<Entity>` while it is mounted:
+
+- `type` is `JointType.Fixed`, `Hinge`, `Slider`, `BallAndSocket`, `Spring` or `Rope`, the words Unity, Godot and Roblox use, where Rapier says revolute, prismatic and spherical.
+- `to` names the other body's entity; left out, the joint holds its body to the world.
+- `anchor` is where it holds, in its body's own axes, and `connectedAnchor` where it holds on the other body; left out, it is wherever `anchor` lies on the other body when the joint is made, as Unity's `autoConfigureConnectedAnchor` does. A spring or a rope spans to the other body's origin instead.
+- A hinge turns about its `axis` and a slider moves along it, in its body's axes; `limits: { min, max }` stop it, in radians or metres from the pose the two bodies had when the joint was made, signed by the right-hand rule about the axis; `motor: { targetPosition, targetVelocity, stiffness, damping, maxForce }` drives it, so a gate closes itself.
+- A spring takes `restLength`, `stiffness` and `damping`, and a rope `length`, each the bodies' distance when left out.
+- `breakForce`, in newtons, and `breakTorque`, in newton-metres, break it: the step the force it holds with passes either, the joint goes and `JointBrokenEvent` lands on its entity with the force, the torque and both bodies, and the entity is destroyed the next tick. `readJointReaction(world, joint)` reads the same force and torque for any joint.
+- `collideConnected: true` lets the two bodies collide, which a joint stops by default.
+
+`setJoint(step, joint, changes)` changes a live joint's motor, limits, lengths and break thresholds, each where its type has one, and refuses a motor on a rope, a throw in development and a `JointRefusal` deployed: a crane's arm follows its lever. A joint's anchors move with its bodies' scales, and a body attached to another leaves its joints until it is let go. A joint goes with either body, in the same tick, with no `JointBrokenEvent`, and `destroy(step, joint)` unhitches it. Both bodies must be simulated by the same world: the room's two, or two a page holds alone. In a room the room simulates every shared joint, and each page holds its entity, whose `JointTrait` names both bodies, to draw a rope or a chain between them.
+
+The following file hitches a trailer behind a kart the room drives. `outsideTrailer.test.ts`, in the room's tests, runs it in a real room.
+
+```ts title="packages/room/test/outside/trailer.ts"
+import { createQuery, type World } from "koota";
+import { Vector3 } from "three";
+import {
+    box,
+    createJoint,
+    definePlugin,
+    definePrefab,
+    defineTrait,
+    fixedStepSeconds,
+    JointType,
+    RigidBodyType,
+    setNextPose,
+    spawn,
+    TransformTrait,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  A trailer behind a kart, on a map with no terrain, built as a creator's
+//  plugin is, from the engine's public entry alone: the room spawns a
+//  fixed floor, a kinematic kart it drives up the pitch and a dynamic
+//  trailer hitched to it on a ball joint, and the kart drags the trailer.
+//  Her page holds both as stand-ins and the hitch as the joint's entity,
+//  which names both bodies, to draw it between them.
+
+/** Metres a second the room drives the kart, along +z. */
+export const towSpeed = 2;
+
+/** Marks the kart and the trailer. */
+export const TowKartTrait = defineTrait("towKart");
+export const TowTrailerTrait = defineTrait("towTrailer");
+
+export const towing = definePlugin({
+    name: "towing",
+    systems: { rules: { tow: { system: towTrailer } } },
+});
+
+const floor = definePrefab("towFloor", {
+    collider: { shape: box({ size: [40, 1, 40] }) },
+});
+
+const kart = definePrefab("towKart", {
+    traits: [TowKartTrait],
+    body: { bodyType: RigidBodyType.Kinematic },
+    collider: { shape: box({ size: [1.4, 0.5, 2] }) },
+});
+
+const trailer = definePrefab("towTrailer", {
+    traits: [TowTrailerTrait],
+    body: { bodyType: RigidBodyType.Dynamic, mass: 40 },
+    collider: { shape: box({ size: [1.2, 0.5, 1.6] }) },
+});
+
+const karts = createQuery(TowKartTrait, TransformTrait);
+//  Where the kart drives to this tick, written in place.
+const next = new Vector3();
+
+/** The pitch on the room's first tick, the trailer hitched behind the
+ *  kart, then the kart driven up it each tick after. */
+function towTrailer(world: World, step: AuthoritativeStep) {
+    if (step.tick === 1) {
+        spawn(step, floor, { position: [0, -0.5, 0] });
+        const towing = spawn(step, kart, { position: [6, 0.3, 0] });
+        const towed = spawn(step, trailer, { position: [6, 0.3, -2.2] });
+        createJoint(step, towed, {
+            type: JointType.BallAndSocket,
+            to: towing,
+            anchor: [0, 0, 1.1],
+        });
+        return;
+    }
+    for (const each of world.query(karts)) {
+        const at = each.get(TransformTrait)?.position;
+        if (!at) continue;
+        next.set(at.x, at.y, at.z + towSpeed * fixedStepSeconds);
+        setNextPose(step, each, { position: next });
+    }
+}
+```
+
+### Queries
+
+A query asks the scene what is there and names the entity it meets: the crate, the ground for a hit on terrain, its edge walls or its scatter, and the character for a hit on her capsule. Five calls cover what Unity's `Physics.Raycast`, `RaycastAll`, `SphereCast`, `OverlapBox` and `CheckSphere` do:
+
+- `castRay(step, { from, direction, maxDistance })` returns the nearest hit, or null: its `entity`, its `point` and the surface's `normal` in world space, its `distance` along the direction, and `colliderIndex`, the place of the collider it met in its entity's `collider` list. A ray that starts inside a collider meets it at distance 0. `direction` takes any length but zero, and `maxDistance` reaches without end when left out.
+- `castRayAll` returns every collider the ray meets, nearest first, one hit per collider.
+- `castShape(step, { shape, from, rotation, direction, maxDistance })` sweeps a shape and returns the nearest hit, with `witness`, the point of the shape that touched. A shape that starts inside a collider meets it at distance 0 where its move leads further in, and passes out of it where the move leads out.
+- `overlapShape(step, { shape, position, rotation })` returns each entity the shape overlaps where it stands, once however many of its colliders it overlaps. It samples one pose: a swing that must hit all it passes through overlaps at several poses along it, as the file below does, or casts its blade with `castShape`.
+- `isTouching(step, entity, options)` answers whether any of the entity's colliders overlaps or lies within 2 cm of what the filter meets, or of the one entity `other` names, even a trigger. A predicted system asks it, since a re-run hears no event: a character standing on lava touches it, though her capsule floats a centimetre above.
+
+A query's shape is `box`, `sphere`, `capsule`, `cylinder`, `cone` or `convexHull({ points })`, by type: a triangle mesh, a heightfield, voxels and a model's hull are a body's alone. Every query takes the same filter: `collisionMask`, the layers it meets, every layer when left out; `collisionLayer`, the layer it stands in, so it meets only colliders whose own mask holds it, as a body there would, and every layer when left out, which a collider whose mask is empty never meets; `ignore`, entities it passes through, such as the caster's own, where one destroyed since passes silently; `includeTriggers: true` to meet trigger colliders, which a query passes through by default, as Unity's `QueryTriggerInteraction` does; and `bodyTypes`, the kinds it meets, read as each body declares its kind, so a page's stand-in for a ball the room rolls counts as dynamic. Two hits as near as each other come in order of entity id, and so do an overlap's entities.
+
+A query takes the step in a system and the world in a view. Through the step it meets the tick as its systems wrote it: a body spawned earlier in the tick, built at once; one destroyed, gone; one teleported, where it now stands. A kinematic body's `setNextPose` takes effect at the physics step, so a query before it meets the body where it stood. Through the world it reads the scene as the last physics step left it, so a frame's queries never vary the work a world does. On a page, a stand-in stands where the newest delta put it, a send ahead of where the view draws it; a view that picks what it draws under a cursor keeps three.js's raycaster on drawn meshes. Before the scene's first body, and while Rapier loads for it, a query meets nothing.
+
+A result is pooled, as a `readEvents` list is, so a query allocates nothing as it runs each tick: it holds until the system that asked returns, and in a view until the next query. Copy a field to keep it. A direction that points nowhere, a negative `maxDistance` and a hull whose points wrap no body throw in development, naming the system, and meet nothing deployed, logged once.
+
+The following file swings a sword on a press of hers: the room overlaps the blade's box at three poses of an arc in front of her character, on a layer its plugin declares, and strikes each training post it meets once a swing. `outsideSword.test.ts`, in the room's tests, runs it in a real room.
+
+```ts title="packages/room/test/outside/sword.ts"
+import type { Entity, World } from "koota";
+import { Quaternion, Vector3 } from "three";
+import {
+    box,
+    cylinder,
+    definePlugin,
+    definePrefab,
+    definePress,
+    defineTrait,
+    overlapShape,
+    readPresses,
+    RigidBodyType,
+    spawn,
+    TransformTrait,
+    type AuthoritativeStep,
+    type PredictedStep,
+} from "@spawnite/engine/core";
+
+//  A sword a player swings with a press, built as a creator's plugin is,
+//  from the engine's public entry alone: the room spawns training posts on
+//  a layer the plugin declares, and a press of hers sweeps the blade's box
+//  through three poses of an arc in front of her, overlapping each, so a
+//  post the arc passes through is struck once a swing, however many of the
+//  poses overlap it. A crate in the arc stands in no layer the blade
+//  meets. Her page reads each post's count from the stream.
+
+/** Marks a training post, and counts the swings that struck it. */
+export const PostTrait = defineTrait("swordPost", { hits: 0 });
+
+export const swords = definePlugin({
+    name: "swords",
+    collisionLayers: ["posts"],
+    messages: { swing: definePress({}) },
+    systems: {
+        input: { swing: { system: swingSwords, predicted: true } },
+        rules: { setUp: { system: setUpYard } },
+    },
+});
+
+const post = definePrefab("swordPost", {
+    traits: [PostTrait],
+    body: {
+        bodyType: RigidBodyType.Fixed,
+        collisionLayer: swords.collisionLayers.posts,
+    },
+    collider: { shape: cylinder({ radius: 0.2, height: 2 }) },
+});
+
+const crate = definePrefab("swordCrate", {
+    collider: { shape: box({ size: [0.6, 0.6, 0.6] }) },
+});
+
+/** The yard on the room's first tick: two posts before where her
+ *  character stands, facing down -z, one behind her, and a crate. */
+function setUpYard(_world: World, step: AuthoritativeStep) {
+    if (step.tick !== 1) return;
+    spawn(step, post, { position: [-0.75, 1, -0.75] });
+    spawn(step, post, { position: [0.75, 1, -0.75] });
+    spawn(step, post, { position: [0, 1, 2] });
+    spawn(step, crate, { position: [0, 1, -1] });
+}
+
+/** The blade: a box a metre and a half long, held out from her middle. */
+const blade = box({ size: [0.1, 0.1, 1.5] });
+/** Radians either side of her facing the arc runs through. */
+const arc = Math.PI / 4;
+const struck = new Set<Entity>();
+const turn = new Quaternion();
+const up = new Vector3(0, 1, 0);
+const tip = new Vector3();
+
+/** Sweeps one swing of `character`'s blade, on the room alone: three
+ *  overlaps along the arc, each post struck once. */
+function swing(step: AuthoritativeStep, character: Entity) {
+    const pose = character.get(TransformTrait);
+    if (!pose) return;
+    struck.clear();
+    for (const share of [-1, 0, 1]) {
+        turn.setFromAxisAngle(up, share * arc).premultiply(pose.rotation);
+        //  A body faces down -z at rest: the blade's middle 0.9 m ahead.
+        tip.set(0, 1, -0.9).applyQuaternion(turn).add(pose.position);
+        const poses = overlapShape(step, {
+            shape: blade,
+            position: tip,
+            rotation: turn,
+            collisionMask: [swords.collisionLayers.posts],
+        });
+        for (const { entity } of poses) struck.add(entity);
+    }
+    for (const hit of struck)
+        hit.set(PostTrait, { hits: (hit.get(PostTrait)?.hits ?? 0) + 1 });
+}
+
+/** Swings on each of her presses, on the room alone: her page, whose step
+ *  is no authority, reads the press and leaves the posts to the stream. */
+function swingSwords(_world: World, step: PredictedStep) {
+    const presses = readPresses(step, swords.messages.swing);
+    if (!step.authoritative) return;
+    for (const press of presses) swing(step, press.entity);
+}
+```
+
+### Contacts and triggers
+
+A contact and a trigger are events in the log, read with `readEvents` as any other, one per pair of entities however many of their colliders touch:
+
+- `CollisionEnteredEvent` lands on each entity of a pair that declares `reportContacts: true` on its body, the step the two first touch, and `CollisionExitedEvent` the step their last touching colliders part or one of them is destroyed. The entry's record names the `other` entity and its `otherKey`, which outlives it, the `point` and the `normal` from this entity to the other, the `relativeVelocity`, the other's velocity at the point less this one's before the step's solve, so a box dropped at 5 m/s reads about 5 m/s, the solver's `impulse`, and which collider of each touched, `colliderIndex` and `otherColliderIndex`. Reporting is opt-in, as Rapier's active events and Godot's `contact_monitor` are, so a pile of crates nobody watches costs nothing. A collision event stays on the world that emits it: a system that wants pages to hear a touch emits its own event.
+- `TriggerEnteredEvent` lands on a trigger, an entity with a collider of `trigger: true`, the step an entity first overlaps any of its colliders, and `TriggerExitedEvent` the step it overlaps none, or either is destroyed, with `other`, `otherKey` and, on the entry, the trigger's `colliderIndex`. A trigger reports always, and its events reach every page that holds it. A kinematic body, a character's capsule among them, enters a fixed trigger, and two kinematic bodies report a touch when either asks.
+- `readTriggerOccupants(world, trigger)` lists who stands inside a trigger now, the state its events report, so a reader added after an entry finds who is inside. It answers where the trigger is simulated: on a page, a trigger the room streams throws in development, and a page asks `isTouching(step, character, { other: trigger })` for her own character.
+
+A trigger samples what overlaps it at each physics step: an entity inside it at spawn enters at the first step, a teleport into it enters and one out of it exits at the next step, and a teleport from one side to the other in one tick raises nothing, as a ball faster than the trigger is deep can cross it unseen. A destroy ends every pair its entity held in the same tick, with the exits, and `other` reads null to a reader once that entity is gone. A body asleep in a trigger stays inside it with no second entry. Whether two entities still touch on a later step is `isTouching`; there is no event per step a pair stays in touch, as Unity's `OnCollisionStay` raises, since a system that asks reads the state. A page raises events only for the bodies it holds alone, never for two stand-ins, and a re-run steps no world, so it raises none. In development, a step that emits more than 1,024 contact and trigger events warns, naming the entity with the most.
+
+The following file scores a ball on a goal trigger. `outsideGoal.test.ts`, in the room's tests, runs it in a real room.
+
+```ts title="packages/room/test/outside/goal.ts"
+import type { World } from "koota";
+import { Vector3 } from "three";
+import {
+    applyImpulse,
+    box,
+    CollisionEnteredEvent,
+    createQuery,
+    definePlugin,
+    definePrefab,
+    definePress,
+    defineTrait,
+    readEvents,
+    readPresses,
+    RigidBodyType,
+    setLinearVelocity,
+    spawn,
+    sphere,
+    teleport,
+    TriggerEnteredEvent,
+    type AuthoritativeStep,
+    type PredictedStep,
+} from "@spawnite/engine/core";
+
+//  A goal that scores a ball, on a map with no terrain, built as a
+//  creator's plugin is, from the engine's public entry alone: the room
+//  spawns a floor, a ball that reports its contacts and a goal trigger
+//  down the pitch. A press of hers kicks the ball at the goal; the room
+//  scores on the trigger's entry, puts the ball back on its spot, and
+//  counts each time the ball touches something. Her page reads the score
+//  from the stream; the contact events stay on the room.
+
+/** The score and the ball's knocks, on the goal, which streams. */
+export const GoalTrait = defineTrait("goalCount", { goals: 0, knocks: 0 });
+/** Marks the ball. */
+export const GoalBallTrait = defineTrait("goalBall");
+
+/** Where the ball rests before each kick. */
+export const ballSpot = new Vector3(0, 0.4, 0);
+/** The kick, in newton-seconds along -z: about 5 m/s on a 0.45 kg ball. */
+const kick = new Vector3(0, 0, -2.25);
+
+export const goals = definePlugin({
+    name: "goals",
+    messages: { kick: definePress({}) },
+    systems: {
+        input: { kick: { system: kickBall, predicted: true } },
+        rules: { score: { system: scoreGoals } },
+    },
+});
+
+const floor = definePrefab("goalFloor", {
+    collider: { shape: box({ size: [20, 1, 40] }) },
+});
+
+const ball = definePrefab("goalBall", {
+    traits: [GoalBallTrait],
+    body: {
+        bodyType: RigidBodyType.Dynamic,
+        mass: 0.45,
+        reportContacts: true,
+    },
+    collider: { shape: sphere({ radius: 0.4 }) },
+});
+
+const goal = definePrefab("goalMouth", {
+    traits: [GoalTrait],
+    collider: { shape: box({ size: [4, 2, 1] }), trigger: true },
+});
+
+const balls = createQuery(GoalBallTrait);
+const mouths = createQuery(GoalTrait);
+
+/** The pitch on the room's first tick, then each goal scored and each
+ *  knock of the ball counted on the goal. */
+function scoreGoals(world: World, step: AuthoritativeStep) {
+    if (step.tick === 1) {
+        spawn(step, floor, { position: [0, -0.5, 0] });
+        spawn(step, ball, { position: ballSpot.toArray() });
+        spawn(step, goal, { position: [0, 1, -12] });
+        return;
+    }
+    const [mouth] = world.query(mouths);
+    const count = mouth?.get(GoalTrait);
+    if (!mouth || !count) return;
+    let { goals: scored, knocks } = count;
+    for (const entered of readEvents(step, TriggerEnteredEvent)) {
+        const scorer = entered.record.other;
+        if (entered.entity !== mouth || !scorer?.has(GoalBallTrait)) continue;
+        scored++;
+        teleport(step, scorer, { position: ballSpot });
+        setLinearVelocity(step, scorer, new Vector3());
+    }
+    knocks += readEvents(step, CollisionEnteredEvent).length;
+    if (scored !== count.goals || knocks !== count.knocks)
+        mouth.set(GoalTrait, { goals: scored, knocks });
+}
+
+/** Kicks the ball at the goal on each of her presses, on the room alone. */
+function kickBall(world: World, step: PredictedStep) {
+    const presses = readPresses(step, goals.messages.kick);
+    if (!step.authoritative) return;
+    const [kicked] = world.query(balls);
+    if (!kicked) return;
+    for (let index = 0; index < presses.length; index++)
+        applyImpulse(step, kicked, kick);
+}
+```
+
+## Behaviours
+
+A behaviour is a child component of an Entity, never a prop. Spin, Bob, Pickup, Interact, Trigger, Health, Chase and TrackMover compose on any Entity. Each is a trait, a system and a component; the component adds the trait on mount, sets it on prop change and removes it on unmount. A trait is koota's word for one piece of state on an entity, and the name of a trait a file exports ends in `Trait`, as `SpinTrait` below does, so it never takes the name of the component that adds it.
+
+Each behaviour also declares where it runs, as `runsOn` on the behaviour `defineBehaviour` makes, which pairs the trait with its context:
+
+- `RunContext.Client`, the default: the behaviour only changes how a thing looks. Spin and Bob are client behaviours, because the server has no reason to track a coin's rotation. So is Interact's prompt, and Trigger's `onEnter` and `onExit`.
+- `RunContext.Server`: the behaviour has a consequence. Pickup, Health, Chase, and the effect Interact triggers.
+- `RunContext.Both`: the server owns it, and the client also runs it to predict, so it feels instant. The local character's movement, a moving platform, a door sliding open.
+
+Every behaviour component is one call to `useBehaviour(behaviour, value)`, which adds, sets and removes the trait on the nearest Entity. A game tags an entity with a trait of its own the same way, such as a boss's `BossTrait` or a gate's keys: `defineBehaviour` for the trait, and a component inside the `<Entity>` that calls `useBehaviour`. An `entity.add` in a `useEffect` leaves the trait out of the devtools' Add behaviour and the Wiki tab, and writes it on a page's copy of an entity that a room streams, where `useBehaviour` leaves the room's copy to say. A system may destroy the entity mid-frame, a pickup being the usual case. The children unmount on React's next commit, so the rest of that frame still runs: a frame callback that reads its entity checks `isAlive()` first, as the hook and Entity's own cleanup do.
+
+`defineBehaviour` runs once, when its file is imported. It names the trait in the dump under `name`, the name the devtools' Add behaviour offers it by, and returns the behaviour typed by its trait, so `useBehaviour` checks the props a component passes. Each name belongs to one behaviour, and a behaviour whose trait has no name of its own shares the dump's names with traits: a second definition under a name already taken throws and names both. A module that hot reload runs again defines its own anew, and each new definition takes its name. So does every module after `beginDefinitionReload()`, which a host that runs a game's modules again in one process calls first, as a watched room does on an edit. One module defining one name twice is refused like any other pair.
+
+```tsx
+import { trait } from "koota";
+import { defineBehaviour, RunContext, useBehaviour } from "@spawnite/engine";
+
+const SpinTrait = trait({ speed: 1 });
+
+const SpinBehaviour = defineBehaviour({
+    name: "spin",
+    trait: SpinTrait,
+    runsOn: RunContext.Client,
+});
+
+export function Spin({ speed }: { speed: number }) {
+    useBehaviour(SpinBehaviour, { speed });
+
+    return null;
+}
+```
+
+A game reads or writes an entity's own movement the same way a behaviour does: `useEntity()` for the koota entity, `TransformTrait` and `VelocityTrait` from `@spawnite/engine` for its position and speed, and `useFrame` from `@react-three/fiber` for the callback. The seconds `useFrame` hands its callback follow the world's time: none while a pausing modal or the devtools hold the world, and fewer under the devtools' slow motion. A view that must keep the wall clock calls [`useUnscaledFrame`](/engine/ui/modal/#pausing) instead.
+
+```tsx
+import { TransformTrait, VelocityTrait, useEntity } from "@spawnite/engine";
+import { useFrame } from "@react-three/fiber";
+
+function LogSpeed() {
+    const entity = useEntity();
+
+    useFrame(() => {
+        if (!entity.isAlive()) return;
+        const position = entity.get(TransformTrait)?.position;
+        const velocity = entity.get(VelocityTrait);
+        console.log(position, velocity?.length());
+    });
+
+    return null;
+}
+```
+
+### Events
+
+An event is something that happened: a hit, a pickup, a round's end. Every emit is one event, delivered once to each system and once to each view that listens, in the order emitted, and two emits are never merged. A game makes an event with `defineEvent(name, record)`, at module scope in a module the room and the page both import; its name ends in `Event`, in the past tense, and it is no trait, so no query finds it. `DamagedEvent` is emitted on an entity each time it takes damage, one event per hit, and a trigger's `TriggerEnteredEvent` and `TriggerExitedEvent` as a player's character comes in or leaves.
+
+- **Emit** with `emitEvent(authority, event, record, { entity })`. An event is an outcome, so it takes an authority: the step inside `if (step.authoritative)` or in a system with no `runsOn`, `requireAuthority(world)` between steps, or `findAuthority(world, entity)` for an entity only this page holds. The record is copied as it is emitted, each field left out at its default.
+- **Read in a system** with `readEvents(step, event)`: every event emitted since the system last read it, oldest first, so a system reads each event once whether it runs before or after the emitter, and a system that skips ticks reads what it missed. `{ entity }` reads the events on one entity, which matches once that entity is destroyed too. A predicted system reads no events, which its step's type holds, since a replay would read them again.
+- **Hear in a view** with `useEvent(event, (event) => ...)`: the frame loop hands each event to the views once a frame, after the frame's steps, so a view hears each once however many steps the frame ran.
+- **Read the entity** as `event.entity`, which is null once the entity is destroyed. The record carries what a reader needs after its entity is gone, as `DamagedEvent` carries where the hit landed.
+
+`delivery` says where an event goes: `EventDelivery.Reliable`, the default, reaches every page that holds its entity; `EventDelivery.Cosmetic` may be dropped by a page that falls behind or hides its tab; `EventDelivery.ServerOnly` stays on the room, and `useEvent` refuses it by type; `EventDelivery.Local` is the drawing world's own, emitted with the world outside any step, as an animation's clip mark is, and `readEvents` refuses it by type. `scope: EventScope.World` makes an event about the world, with no entity. An event is this engine's version of Bevy's buffered message, read by each system from where it last read, not Bevy's observer; Unity's and Unreal's delegates call each listener inside the emit, which in a room would run only on the room.
+
+A behaviour lists the events its system reads or its view hears in `handles`. The Wiki links the behaviour to each of them, and each event back to the behaviours that handle it, so the map follows a hit to what it sets off. Trigger handles its own two events: its component fires `onEnter` and `onExit` as each is heard.
+
+```tsx
+import { trait } from "koota";
+import {
+    DamagedEvent,
+    defineBehaviour,
+    defineEvent,
+    RunContext,
+} from "@spawnite/engine";
+
+const FlinchTrait = trait({ seconds: 0.2 });
+const HitEvent = defineEvent("hit", { amount: 0 });
+
+export const FlinchBehaviour = defineBehaviour({
+    name: "flinch",
+    trait: FlinchTrait,
+    handles: [DamagedEvent, HitEvent],
+    runsOn: RunContext.Client,
+});
+```
+
+### Consequences are data
+
+A consequence is data on a trait handled by a system, never a callback prop. `<Pickup reward={1} />` puts the reward on the trait, and the pickup system credits the wallet where it runs. In the engine's source, a function prop on a behaviour declared `Server` or `Both` is a lint error: a closure lives in the browser's React tree and the server can never run it. A behaviour declared `Client` may take a callback for local UI, which is how Interact's `onInteract` opens a modal.
+
+A consequence the engine has no behaviour for is written by the game the way the engine writes its own: a trait, a system and a component, with the system declared `Server`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Trait: mount adds
+    Trait --> Trait: prop change sets
+    Trait --> [*]: unmount removes
+    note right of Trait
+        the system reads it every frame
+    end note
+```
+
+## Samples
+
+Three game components, each one Entity with behaviours as children:
+
+<Tabs>
+    <TabItem label="Coin">
+
+```tsx
+// src/components/Coin.tsx
+import { Entity, Spin, Bob, Pickup, type EntityProps } from "@spawnite/engine";
+
+export function Coin({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="coin" position={position}>
+            <Spin speed={1} />
+            <Bob height={0.2} />
+            <Pickup reward={1} />
+        </Entity>
+    );
+}
+```
+
+    </TabItem>
+    <TabItem label="Chest">
+
+```tsx
+// src/components/Chest.tsx
+import { useState } from "react";
+import {
+    Entity,
+    Interact,
+    Open,
+    Modal,
+    Text,
+    Button,
+    useScenes,
+    type EntityProps,
+} from "@spawnite/engine";
+
+export function Chest({ position }: Pick<EntityProps, "position">) {
+    const [open, setOpen] = useState(false);
+    const scenes = useScenes();
+
+    return (
+        <Entity model="chest" position={position}>
+            <Interact prompt="Open" onInteract={() => setOpen(true)} />
+            <Open reward={10} />
+            <Modal open={open} title="A chest">
+                <Text>Ten coins inside.</Text>
+                <Button onPress={() => setOpen(false)}>Take</Button>
+                <Button onPress={() => scenes.go("vault")}>Go inside</Button>
+            </Modal>
+        </Entity>
+    );
+}
+```
+
+The chest carries its reward as data. Interact's prompt and `onInteract` are client behaviour: they open the modal. When Interact fires, the Open effect runs on the server and credits the wallet; the Take button only closes the modal. The Modal sits inside the entity but draws at screen level; see [UI](/engine/ui/).
+
+    </TabItem>
+    <TabItem label="Yeti">
+
+```tsx
+// src/components/Yeti.tsx
+import {
+    Entity,
+    Health,
+    Anchor,
+    Chase,
+    Panel,
+    Text,
+    Bar,
+    useEntity,
+    useHealth,
+    type EntityProps,
+} from "@spawnite/engine";
+
+export function Yeti({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="yeti" position={position}>
+            <Health maximum={30} />
+            <Chase speed={4} />
+            <Nameplate />
+        </Entity>
+    );
+}
+
+function Nameplate() {
+    const health = useHealth(useEntity());
+    if (!health) return null;
+
+    return (
+        <Panel anchor={Anchor.Above}>
+            <Text>Yeti</Text>
+            <Bar
+                label="Yeti health"
+                value={health.current}
+                maximum={health.maximum}
+            />
+        </Panel>
+    );
+}
+```
+
+The nameplate reads its own entity through `useEntity()` and follows it in the world through `anchor`.
+
+    </TabItem>
+
+</Tabs>
+
+Each behaviour has its own page: [Spin](/engine/behaviours/spin/), [Bob](/engine/behaviours/bob/), [Pickup](/engine/behaviours/pickup/), [Interact](/engine/behaviours/interact/), [Trigger](/engine/behaviours/trigger/), [Health](/engine/behaviours/health/), [Chase](/engine/behaviours/chase/) and [TrackMover](/engine/behaviours/track-mover/).