@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/entities/npc.md

@@ -0,0 +1,64 @@
+---
+title: Npc
+description: A character a routine drives instead of a player.
+useCases:
+    - add an npc
+    - npc that patrols
+    - npc that talks
+    - shopkeeper or quest giver
+    - guard standing at a post
+    - npc name and title above head
+    - enemy or friendly character
+    - non player character with routine
+sidebar:
+    order: 3
+---
+
+`<Npc>` spawns a non-player character inside a [World](/engine/structure/world/): the same walker, body, avatar, clips and navmesh path as [the player's character](/engine/entities/player/), driven by [its routines](/engine/behaviours/routines/) instead of a person. World of Warcraft makes an NPC the same way, as data: a name, a title, a level, a faction, and a path with a pause at each point. An NPC with no `routines` stands and plays idle. Its body is posed less often while it is small on screen or out of view, as [another player's character](/engine/entities/player/) is, unless `cullingMode` says otherwise.
+
+```tsx
+import { Faction, Interact, Npc, NpcEvent, routines } from "@spawnite/engine";
+
+const guard = routines("guard")
+    .routine("post", (r) => r.wait({ between: [10, 20] }).turn(90))
+    .start("post");
+
+export function Guard() {
+    return (
+        <Npc
+            name="Bram"
+            title="Gate guard"
+            level={8}
+            faction={Faction.Neutral}
+            position={[2, 0, 4]}
+            routines={guard}
+        >
+            <Interact prompt="Talk" />
+        </Npc>
+    );
+}
+```
+
+## Props
+
+It takes `<CharacterSpawn>`'s body fields, `avatar`, `shape`, `color`, `position` and `facing`, and these of its own:
+
+- `name` and `title`: drawn over its head in [Text](/engine/ui/text/)'s white with a dark edge, the title under the name as WoW draws a subname. The AI tree names it by them and its faction: "Mira, a herbalist, friendly".
+- `level`: a number a game reads.
+- `faction`: `Faction.Friendly`, `Neutral` or `Hostile`, friendly by default. It says which side the NPC is on, and does not make it a target: an ability strikes an NPC that carries `TargetableTrait`, which [Targeting](/engine/behaviours/targeting/#make-an-enemy-a-target) shows how to give it.
+- `routines`: what `routines()` built.
+- `leash`: metres from its spawn it may walk. A route point past the leash is skipped with a warning at spawn, and a walk that carries it past the leash ends and walks it home, as WoW's evade does. A routed NPC has none by default, since its route bounds it.
+
+Its children are behaviours on it, as on an [Entity](/engine/entities/entity/). `<Interact prompt="Talk" />` shows the prompt when a player's character comes close and emits the `InteractedEvent` event on a press, which a routine answers with `NpcEvent.Interacted`. `<Dialog tree={...} />` gives it [a conversation](/engine/behaviours/dialog/), which a press of that prompt starts for the player who pressed. While any conversation goes on, the NPC holds the `TalkingTrait` trait, which holds its routine alone.
+
+## What it holds
+
+Its `npc` trait holds its name, title, level and faction, and what its routine is doing: the routine and the step, the seconds on the step, the route point it walks to and the pass along the route it is on, and the line a `say` step gave it, which draws right over its name, wrapped and faded with the camera's distance. Its routines compile to a [state machine](/engine/structure/states/) whose trait dumps beside it under the name `routines()` took, `miraRoutines` for `routines("mira")`. A `spawnite play` dump shows both each step, so a test asserts where it is and what it is doing.
+
+## In the devtools
+
+The tree shows each NPC as a row under its name, and the Map tab counts it under the avatar it wears: a registered avatar by its name, and a body handed over whole by its `name`, or by its file's name where it has none, which a production build hashes. The inspector shows its `npc` trait and its machine's card: the routine, the step in words, such as `walk stall to well to herbs`, the machine's state and a wait's seconds left. The Wiki tab lists each NPC under the `npc` kind with its routines in words and, where it has a Dialog, its lines by node with the choices each offers. A conversation's machine shows in the Wiki tab under `machine`, as any machine does.
+
+## In a room
+
+The room spawns and steps an NPC, and each page draws the one the room streams at its place in the scene, as it does an Entity. The routine system runs on the server, as Chase does, and a single-player game runs it on the page. A player's press of its prompt reaches the room as [Interact](/engine/behaviours/interact/) describes, and the stream carries its `npc` trait and its machine's trait to every page, so each page draws the same line over its head. The room runs each conversation too, and streams its record to the talking player alone, as [Dialog](/engine/behaviours/dialog/) describes. Each page's `<Npc>` compiles the same `routines` as it mounts, so the machine's name is registered before the stream brings its trait, and the page's inspector and Wiki tab show the routines in words as the room's do.

package/dist/wiki/engine/entities/player.md

@@ -0,0 +1,435 @@
+---
+title: Player
+description: The player's character.
+useCases:
+    - player movement with wasd
+    - player jump
+    - running speed
+    - change player speed for a while
+    - player character model
+    - strafe while aiming
+    - name tag over other players
+    - player stuck in a wall
+    - player collision body
+    - sprint and walk
+sidebar:
+    order: 2
+---
+
+`<CharacterSpawn>` spawns the player's character inside a [World](/engine/structure/world/) and draws her. WASD and the arrows walk her in the camera's frame; the on-screen stick steers the same way. While the camera's lock is on or its eye is in her head, she faces the way the camera looks and the keys walk her sideways and back without turning her, as Roblox's shift lock does; [the camera page](/engine/entities/camera/#the-lock-and-first-person) says when. She runs at 5 m/s unless her [movement](#movement) says otherwise. [Game](/engine/structure/game/) listens to the keys, not `<CharacterSpawn>`, so a `<CharacterSpawn>` that remounts while a key is down, as one inside a `<World key={round}>` does on a new round, walks on. A walk `walkTo` starts, as a click on the ground does, shows a mark on the ground at the point asked for until she arrives or the player takes over: the pulse by default, a flash with waves running out and a beam that flares; a pulsing ring, a sigil or motes of light that land with a snap, or nothing, by `marker`, which takes a `GroundMark`, the same shapes [Targeting](/engine/behaviours/targeting/) draws under a target. In a room the walk goes to the room too, which finds her path on its own navmesh, baked from the same map, and starts her on it at the step her page did.
+
+An avatar is a `VrmBody`: the URL of a VRM file, its `scale`, the `armSpread` that holds its arms off its body, and, for a body with cloth, the `armColliders` that keep that cloth off its arms. The engine turns a VRM 1.0 body, whose front faces +z as glTF's does, so that she faces the way she walks, and leaves a VRM 0.x body, which already faces -z, as it is. `rotateY`, in radians, turns a body further, for a file that faces some other way. `avatar` takes a body, or the name `registerAvatar` registered one under. The engine ships no VRM body, so a game imports one by name from `@spawnite/assets/avatars`, such as `import { fris } from "@spawnite/assets/avatars"`, or its own file with `?url`. `spawnite model avatar` turns a character rigged by Meshy into a VRM body, as [Models](https://wiki.spawnite.com/learn/models/#turn-a-meshy-character-into-an-avatar) says. A body from `@spawnite/assets` takes the rest of its record from `@spawnite/assets/avatars.json`, keyed by the file's name, as the mmorpg's avatars table and the arena's registration do.
+
+In a room, every page draws every character in her avatar, her own included, with the same clips `<CharacterSpawn>` plays. Only a name travels: the room dresses each character in the avatar her page's join names, `avatar` in the Game's room options, or else in the one the scene's `<CharacterSpawn>` names. A character whose avatar this page never registered, or who has none, is drawn as the default body. Two characters in one avatar are two copies of it: the page parses the file once for each body it draws at once, and downloads it once. Roblox draws every player in the avatar she chose the same way.
+
+A page poses the body of another player's character every frame while she stands large on its screen, every other frame once she spans under 5 % of its height, and not at all while she is out of its view. Her clips play on while she is out of view, and her springs rest as she comes back, so she walks in mid-stride with her hair at rest. Nothing a game decides reads another character's pose, since a shot meets her capsule. The character the page steers is posed every frame, on screen or off, because a game may aim her shots from her hands. `cullingMode` on an Npc or a `CharacterView` sets it for one body: `AnimationCulling.AlwaysAnimate`, or `AnimationCulling.CullUpdateTransforms`, the default for every other character. The names are those of Unity's `Animator.cullingMode`. Roblox throttles the animation of a character small on screen by default in the same way, and leaves the player's own character alone.
+
+A raycast, a pointer event's included, meets an avatar as an invisible capsule the size of her physics body rather than her skinned model, so it costs no more over her than over any other mesh. A model or a primitive she wears is met on its own meshes.
+
+Its props are in [`CharacterSpawnProps`](https://wiki.spawnite.com/reference/player/characterspawnprops/).
+
+The three body fields, `radius`, `height` and `collisionMask`, are hers at spawn: the physics cuts her capsule to them. What she steps over, climbs and jumps is the character controller's, `controller`, a partial `CharacterControllerTrait` laid over its defaults: `stepHeight` 0.6 m, `maxSlopeRadians` 50 degrees, `floorSnapDistance` 0.6 m and `jumpHeight` 1.2 m among them. `pushes` lists the layers of the dynamic bodies she shoves as she walks into them, every layer when left out, and `turnWithPlatform`, off by default, turns her facing with a turning platform she stands on, though it does not carry her round the platform's axis. `maxSlopeRadians` is her one walkable angle: she climbs, stands on and walks down any ground up to it, and slides down anything steeper. Unreal's walkable floor angle, Unity's slope limit and Godot's floor max angle work the same way, each 45 degrees or near it by default. A game whose ground rises steeper than the default sets `controller={{ maxSlopeRadians }}`, the way Unity's CharacterController and Godot's CharacterBody3D carry their slope limit on the character. Past a ledge's edge she stands on its rim while the ground under her centre is walkable or lies farther below her feet than her height. Over a bank steeper than `maxSlopeRadians` within that reach, she slides. The controller walks her capsule itself, as Unreal's CharacterMovementComponent does, behind one call, `moveCharacter(step, character, { velocity, jump })`, which her movement makes once a tick: a move along the floor it found under her, one slide along a wall, a step onto what stands under `stepHeight`, and a push back out of any walker the move left her inside, cast like the move, so a wall or a ball in the way stops it. Each cast stops her 1 cm off a box or a rock's hull, at a corner too, where Rapier's own cast lets her dome come up to 6 mm nearer a corner. Two walkers that meet head-on stay a body's width apart, unless a wall pins one inside the other.
+
+Her `TransformTrait` is where her capsule stands: the dump and the stream carry it, and a room's correction rebuilds her capsule on it, in the room and on every client alike. Her model's feet are drawn apart from it, by her `DrawnFeetTrait` trait, which the view reads. On a slope the capsule rests above the ground under her axis, and her feet are drawn on that ground, no farther than her `stepHeight` under the capsule and no farther than the slope she rests on lifts a capsule, plus 5 cm. Over a ledge's rim, where the face she rests on is the ledge's level top, her feet stay within those 5 cm of the capsule's bottom, so she stands on the rock rather than in it. The stream carries no drawn feet. Each client casts its own rays against the same ground, so every tab that shows her large draws her feet at the same height. A client casts them for another walker from when she spans 3 % of its screen's height until she spans under 2.5 %, and for six steps after, while her feet ease from the measured ground back to her `TransformTrait`, the capsule's bottom. A smaller walker, or one out of view, is drawn at her `TransformTrait` and casts nothing once her feet have eased there. Her feet ease onto the measured ground over the same six steps as she grows past 3 %, so none jumps as she crosses a line. Unreal's CharacterMovementComponent and Unity's CharacterController work the same way: the capsule is the truth, and a separate pass places the mesh's feet without moving the capsule.
+
+Another walker's capsule is ground like any other face: she lands on a monster or on another player that blocks her, walks on it and jumps from it as from the ground. A jump from a walker's top lifts her feet `jumpHeight` above it, and her movement drops a press in the air, so she never climbs walkers in the air. A capsule's top is a dome, and where she holds on it follows her `maxSlopeRadians`. A default body holds anywhere the dome is within 50 degrees of level, up to about 0.5 m off the walker's axis for two default capsules, and a landing further out slides her off its side. On a walker her feet are drawn on its top, and every tab draws them at the same height while she moves. She stands on the middle walker of a stack three high with a 1 cm gap. A room and each of its clients stand her at the same height on a walker that stands still, and a walker that walks carries her by its own move in the same tick, since the room moves each walker no player controls before the players' characters and a base before its rider. Fortnite and Roblox let players stand on heads the same way. Unreal lets a pawn stand on another unless the base refuses it, and Zelda slides the player off an enemy.
+
+## Movement
+
+How she runs, stops, turns and jumps lives on her `MovementTrait` trait: her speed, her acceleration and deceleration, how fast she turns at speed, whether she turns on the spot from a stand, past which angle and at what rate, and how high she jumps. `preset` picks a whole record. `Responsive`, the default, brings her to full speed in a tenth of a second and pivots her at speed. `Realistic` takes a third of a second to reach speed and to stop, and plants her feet to turn on the spot before she walks off. `movement` lays single settings over the preset: `movement={{ speed: 7 }}`. The devtools inspector shows her settings on her row, each number as a slider and `turnInPlace` as a switch, and an edit moves her at once. Once a number feels right, the card's Copy as prop button copies the changed settings as `movement={{ speed: 7 }}`, ready to paste into `<CharacterSpawn>`.
+
+In a room she moves as she does alone. A scene holds one `<CharacterSpawn>`, and it is the one place a room reads its players' characters from. The room mounts the scene, and its `<CharacterSpawn>` spawns nobody there: the room spawns every player's character with the `<CharacterSpawn>`'s `preset`, `movement`, body fields, `facing`, `health`, `stats` and `respawn`, and hands each plugin's character hook the rest of its props, such as `bagSlots`, `weapons`, `abilities` and `resources`, all as they stood when the room started. `respawn` says whether she comes back once her health runs out, after how long and where, as [the health page](/engine/behaviours/health/#when-a-character-runs-out-of-health) says. Where the scene places no spawn points, a character spawns at `<CharacterSpawn>`'s `position`, as she does alone, unless another character stands within a metre of it. Then she takes the first free place of eight on a ring 1.5 m round it, so two players who join together stand apart. Unreal's GameMode skips an occupied PlayerStart the same way. The room refuses a scene's file that exports `movement`, so a game sets its characters' movement on `<CharacterSpawn>` alone. Each client reads her settings from the stream. The inspector shows them on her row read-only, greyed with the reason, unless the room takes edits. A room takes edits only when `startRoom` is given `allowEdits: true` or the room's process runs with `ROOM_EDITS=1`, as the arena's `spawnite.room` sets, so no client sets its own speed in a game others play. Where it does, a slider edit on your own character goes to the room as any devtools edit does, and the room clamps it to the slider's range and streams it to every client; [the devtools page](/engine/testing/editing/#editing-a-behaviours-props) says how. On a room's world her row holds the room's settings as they stood when she joined, so an edited card reads "Tried, not saved" and Copy as prop copies the fields that differ from the room's. To keep them, paste them into `<CharacterSpawn>`'s `movement`.
+
+A scene that places spawn points has the room stand each joining player's character at one of them instead, with `<CharacterSpawn>`'s other fields all the same. A scene calls `placeSpawnPoints(world, points)` with a list of `Vector3`s, in an effect after it mounts if it likes, since the room reads the list on each join. Each player holds a seat: the lowest number no other player in the room holds, freed when she leaves or her character is gone. The player in seat `n` spawns at point `n`, round the list again past its end. Her first step stands her on the ground under the point, whatever its height.
+
+## Keys
+
+She walks and jumps on the five inputs `characters()` declares, which ride every tick's input to the room, as any input a plugin declares does:
+
+| Input                | Kind                 | Keys                      | What it does                                                              |
+| -------------------- | -------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `characters.move`    | Vector               | W, A, S, D and the arrows | Steers her in the camera's view, at most 1 long: up away from the camera. |
+| `characters.jump`    | Button, `edge: true` | Space                     | Jumps her, once for each press.                                           |
+| `characters.heading` | Angle                | none                      | The camera's heading, which the move is read in; the camera sets it.      |
+| `characters.pitch`   | Angle                | none                      | How far the camera looks above level, her aim while she strafes.          |
+| `characters.strafe`  | Button               | none                      | Whether she faces the heading as she walks; the camera's lock sets it.    |
+
+`characters({ keys })` moves the move's and the jump's keys: `characters({ keys: { jump: ["Space", "Enter"] } })` jumps on Enter too, and `characters({ keys: { jump: [] } })` frees Space for a dodge. A system reads each with `readInput(character, characters.inputs.move)`, and a touch stick sets the move with `setInput`, as `useInput`'s `steer` does. A game that lists no `characters()` binds W, A, S, D and Space to its own inputs.
+
+[Game](/engine/structure/game/) binds the engine's own keys to these actions, each a handle in `engineActions` that `useAction` hears:
+
+| Action                             | Keys                      | What it does                                                  |
+| ---------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| `interact`                         | E                         | Uses what she stands near, whose prompt shows.                |
+| `cameraLock`                       | Shift                     | Turns the camera's lock on or off.                            |
+| `menu`                             | Escape                    | Opens or closes the play menu.                                |
+| `performanceStats`                 | F2                        | Steps the performance overlay through its levels.             |
+| `forward`, `back`, `left`, `right` | W, S, A, D and the arrows | Fly the devtools' free camera; a game may bind them.          |
+| `climbUp`, `climbDown`             | E, Q                      | Fly the devtools' free camera up and down; a game may bind Q. |
+
+`controls()` in the game's plugins moves or drops an engine action's keys: `controls({ keys: { cameraLock: [] } })` frees Shift for a sprint. As the world is made, every key a game's plugin binds, for a held input, a press or a page action, is checked against these and against each other, and a clash throws naming both and the fix. The ability bar's keys are its own prop, outside the check. Unity's Input System and Godot's Input Map bind actions to keys the same way; player rebinding and gamepads come later, as more sources for the same actions.
+
+## The jump
+
+A press of Space jumps her, and so does a tap on the phone: a game mounts `<Tap label="Jump" onTap={jump}>` beside its `Joystick`, with `jump` read off the `useInput` store. She leaves the ground at the speed that lifts her feet by `jumpHeight` on her `CharacterControllerTrait`, 1.2 m by default, under the scene's gravity, and the same gravity brings her down. Under the default 9.8 m/s² she leaves at 4.85 m/s and lands 0.99 s later; a game that raises it, with `definePhysics({ gravity: [0, -20, 0] })` passed to `<Game physics>`, keeps the height and shortens the arc. Unity's Starter Assets state the jump the same way, as a 1.2 m `JumpHeight`, and Roblox as `Humanoid.JumpHeight`.
+
+- One press is one jump. A held Space jumps once, as in Unity's and Godot's templates. Space on a focused button presses that button and does not jump her.
+- In the devtools' edit mode, Space pauses the world and does not jump her.
+- She jumps only from the ground. A press in the air is dropped: there is no coyote time and no jump buffer.
+- The stick steers her in the air as on the ground, at the same speed.
+- A jump that meets a ceiling stops rising there and falls from it, as in Unreal and Godot.
+- The jump is an edge button, `characters.inputs.jump`: the step carries the press on the one tick it was made, so a test, the harness and a room jump her as the keys do. The step takes the press off the input it reads, so `holdInput(game, characters.inputs.jump, true)` jumps her once, on the next step. A press that reaches the room up to 17 ticks late still jumps her, once, on the room's next tick.
+
+Her `CharacterTrait` says whether her last move ended with her on the ground, `isGrounded`, the entity she stands on, `standingOn`, how long she has been off the ground, `airSeconds`, the jumps since she left it, `jumpsSinceGrounded`, and her vertical speed in metres a second, negative on the way down, `verticalSpeed`. `moveCharacter` writes it as it moves her, so a game and the dump read it off her entity, as Unity's `isGrounded` and Godot's `is_on_floor()` do. In a room, a correction puts her body in the room's state, in the air or on the ground, and the slope under her, so a correction halfway through a jump leaves her the rest of the room's arc, and one on a hillside walks her on up it as the room does.
+
+On a VRM body she plays three clips over the jump:
+
+- `jump.vrma` when she leaves the ground standing, and `run-jump.vrma` when she leaves it running. The one chosen as she leaves holds until she lands, however the stick moves in the air.
+- `land.vrma` after she lands with the stick idle, held for the clip's whole length. A stick held on landing, or pushed during the crouch, goes straight to the run.
+
+The land clip plays from the moment her feet touch, 0.25 s in, because the frames before it carry a fall in her hips that the capsule has already made.
+
+## Changing her movement for a while
+
+Three calls change how she moves from a game's own predicted system, each predicted in a room and restored by a correction, as [Change the character's movement](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#change-the-characters-movement) shows with a sprint, a dash and a blink, and a fourth, a launch, is the room's:
+
+- **`addSpeedModifier(step, character, { key, more, seconds? })`** multiplies her top speed by `1 + more` under a key `defineSpeedModifier` makes: a sprint, a crouch, a root at `more: -1`. Keys multiply with each other and with her `moveSpeed` stat, and `readMoveSpeed(character)` answers the result.
+- **`pushCharacter(step, character, { velocity, seconds, endSpeed?, priority? })`** holds her horizontal velocity for a while, with no turn toward the stick: a dash, a knockback. A `velocity.y` above 0 launches her as a jump does.
+- **`teleport(step, character, { position, rotation?, keepVelocity? })`** places her body and her transform at a spot exactly, never short of it, keeping her velocity unless `keepVelocity` is false, and draws her there with no glide. Inside a wall there, it pushes her out by the shortest way, up to her radius; still inside, it answers `isClear: false` and marks her stuck, and her next move recovers her. A blink that stops at the first wall casts her capsule first with `castShape`, as the blink sample does.
+- **`addLinearVelocity(step, character, velocity)`** shoves her, on the room's step alone: its upward part lifts her off the floor, as Unreal's `LaunchCharacter` does, and its sideways part decays on the floor by her controller's `groundFriction`.
+
+Each of the first three takes the predicted system's step. A knockback or a teleport the room starts, such as a trap's, takes the room's step inside `if (step.authoritative)`. Unreal's `MaxWalkSpeed`, root motion sources and `TeleportTo`, and Roblox's `WalkSpeed` and `PivotTo`, do the same three jobs.
+
+## Collision layers
+
+Her capsule stands in `characters.collisionLayers.players`, and every other character's in `characters.collisionLayers.npcs`, two of [the collision layers](/engine/entities/entity/#layers) every world numbers; the terrain, its edge walls and its scatter stand in `CoreLayers.ground`, and a body that names no layer in `CoreLayers.default`. `collisionMask` lists the layers her sweeps and contacts meet, as a body's does, every layer when left out, or `{ except: [...] }` for every layer but those; a layer left out never stops her and never costs her a test. A [chaser](/engine/behaviours/chase/) leaves out both characters' layers. Two colliders meet only when each one's mask holds the other's layer, so a game that wants its monsters to block her gives them `{ except: [characters.collisionLayers.npcs] }`. A ghost that walks through everything but the floor meets `[CoreLayers.ground]`, the way Unity's layer collision matrix and Godot's collision mask narrow what a body meets.
+
+## Getting unstuck
+
+A walker whose capsule starts inside a rock, a tree or a prop has no way out on foot: a save restored where the scatter now stands, or a spawn onto a placement, leaves her there. `freeCharacter(world)` stands the player's character on the ground at the nearest spot within 10 metres where her capsule overlaps nothing, and she walks on from there. It answers whether she now stands clear. A character already clear stays where she is, and so does one with nowhere clear in reach, for whom it answers false. It moves the walker it is handed in place of the player's character. While her capsule overlaps a hull or a prop, the step keeps the `StuckTrait` tag on her character, and takes it off once she stands clear; another walker or a dynamic prop, such as a crate that fell on her, never counts, since she walks off either, and neither does a wall she walks into. A game shows its way out only while she carries the tag, as the mmorpg's **Unstuck** button does, the way Unreal's `OnCharacterStuckInGeometry` tells a game when its character overlaps geometry it cannot leave. A dump lists it as `stuck`. It searches the ground alone, so a rock top is never where it stands her. In a room the room's next correction puts her back; the room frees no one yet.
+
+## What she holds
+
+Each of the following comes from a plugin the game lists, as [What a plugin adds to a character](/engine/structure/plugins/#what-a-plugin-adds-to-a-character) describes: her weapons from `weapons()`, her abilities from `abilities()`, and her bag from `inventory()`. Her resources need no plugin.
+
+She starts holding the weapons `weapons` names, by the names `registerWeapon` gives them, as [the weapons a character holds](/engine/behaviours/weapon/#the-weapons-a-character-holds) says: in a room, a shot from any other is refused from the moment she spawns. Left out, she holds every registered weapon.
+
+She holds the abilities `abilities` names for as long as she is in the world, and has each resource `resources` names, such as `["mana"]`, where its settings say it starts, as [the abilities page](/engine/behaviours/abilities/#give-a-character-abilities) and [the resources page](/engine/behaviours/resources/) say. Left out, she holds no ability of her own and has no resource.
+
+In a game that lists `inventory()`, she carries a bag of 16 slots, or as many as `bagSlots` says, and wears the engine's equipment slots, as [the inventory page](/engine/behaviours/inventory/) describes. Roblox gives every character a Backpack and Minecraft every player an inventory; here a game that has no items lists no `inventory()`, and its characters carry none. The player's save keeps both where the game's save includes `inventory`, as [Saving progress](https://wiki.spawnite.com/learn/saving-progress/) says, so a game's save code never names them. A room gives her the same bag and slots, empty each time she joins.
+
+`<HeldItem>` draws its children in her right hand, so they move with the hand as her clips play. Put it in her overlay: `<CharacterSpawn>`'s children, or the `Replicas` overlay in a room, which draws every character her page draws, her own included. On an avatar it hangs on the hand bone; on the default body it stands at her right side, at 0.6 of her height. `position`, `rotation` and `scale` place the held thing in the hand's axes, which are hers while she stands at rest: y up, -z the way she faces and x to her right, so a barrel along -z points the way she faces. It draws nothing outside a character's overlay. Roblox welds a tool's handle to the right hand the same way, and Unity and Unreal attach it to a hand socket.
+
+While it holds something, an avatar's right hand closes round it: each frame, after her clip, the engine curls her thumb and fingers to a grip over whatever the clip does with her hand, and lets go when the `HeldItem` goes. The engine's grip closes round a handle about 3 cm across that runs along the hand's z axis, which on a VRoid body sits about `[0.055, -0.025, 0]` in the hand's axes: put a sword's or a wand's handle there. `grip` sets how far each finger closes, from 0, straight, to 1, a fist, over the engine's grip: `grip={{ index: 0 }}` points her index finger along the handle. An avatar with no finger bones, and the default body, draw no grip. `forward` names the way the held thing's tip points in its own axes, `[0, 0, -1]` unless set, which [a cast's hand turn](/engine/behaviours/abilities/#walk-into-range-and-turn) carries onto the target as the spell releases: a wand whose orb is up its y gives `[0, 1, 0]`. Unreal lays a hand pose over any animation with a layered blend per bone, and Unity plays a grip clip on a layer masked to the hand. The engine's grip is one curl per finger instead, as Unity's humanoid muscles describe a finger, so the same numbers fit every avatar.
+
+```tsx
+import { HeldItem, Replicas } from "@spawnite/engine";
+
+export function Heroines() {
+    return (
+        <Replicas>
+            {() => (
+                <HeldItem position={[0, 0, -0.15]}>
+                    <mesh>
+                        <boxGeometry args={[0.05, 0.08, 0.45]} />
+                    </mesh>
+                </HeldItem>
+            )}
+        </Replicas>
+    );
+}
+```
+
+## Aim and side-step
+
+While the camera's lock is on, or its eye is in her head, an avatar aims where the camera looks. Her right arm points along the look, so what `HeldItem` puts in her hand points at the crosshair's line, and her chest leans half the look's pitch. The arm follows the look to the camera's stops: 80 degrees up or down, and 89 in first person. A step to the side turns her hips and legs toward it, as far as 75 degrees, while her chest stays square to the camera, and a step back plays the run clip in reverse with her legs facing the camera. Where the characters' clips include strafe clips, a step within 30 degrees of square plays `strafeLeft` or `strafeRight` with her legs square, and a step back plays `backpedal`; each one missing falls back to the run. The engine ships none: a game adds one with `registerClip(StrafeClip.Left, url)`, as [Your own pose clips](#your-own-pose-clips) says. `spawnite model clip` writes a VRMA from a Meshy clip, as [Models](https://wiki.spawnite.com/learn/models/#turn-a-meshy-character-into-an-avatar) says. The pose eases in and out over about a quarter of a second as the lock turns on and off.
+
+Unity and Unreal build the same thing from clips: an aim offset of upper-body poses and a blend of walk clips in eight directions. The platform ships neither, so the pose is built from the bones over whichever clip plays. Every page draws it for every character from her `pose`: the step writes whether her input strafes and the pitch it aims at into `pose.strafe` and `pose.pitch`, and the room streams them, while her input itself stays on the room and her own page. What she holds points parallel to the camera's look from her shoulder, so its line runs a few tenths of a metre beside the crosshair's rather than meeting it.
+
+`aimAt(character, point)` aims a character at a point in the world, such as the enemy a system just shot at. It works on any character: `<CharacterSpawn>`'s avatar or `model`, and an Npc drawn the same way. While she aims, the step turns her to face the point, and her steer walks her without turning her, as the camera's lock does. Her legs turn toward her step, as far as 75 degrees off the point, and a step back plays her walk in reverse with her legs facing the point. On an avatar her right arm points at the point and her chest leans toward it, as they do for the camera's look. The point wins over the camera's lock while both are on. On a `model`, the whole model faces the point, and the bones under its spine, the hips and the legs, turn toward the step while the spine turns back. `aimAt(character, null)` lets go, and she turns back to her step. Her legs ease in and out over about a quarter of a second, as for the lock. The point lives on her `AimPointTrait`, so a room streams it to every page and the dump shows it. A point whose `x`, `y` or `z` is not a finite number throws, saying so.
+
+```ts
+// In a system, on each shot.
+aimAt(character, { x: target.x, y: 1, z: target.z });
+// Once nothing has fired for 0.5 s.
+aimAt(character, null);
+```
+
+Unreal builds this from an aim offset, which poses the upper body toward the aim, and Lyra's orientation warping, which turns the hips toward the step. Unity aims with a Multi-Aim Constraint from its Animation Rigging package, or with the Animator's LookAt IK. Godot turns a bone toward a target with `LookAtModifier3D`. Roblox turns `AutoRotate` off on the Humanoid, and the game turns the `Waist` joint itself. Each of those leaves the game to wire the aim to the gameplay and to the network. `aimAt` is one call that the step, the stream and every page's body read.
+
+## The default body
+
+With no `avatar`, the player is a blue capsule cut to her `height` and `radius`, 1.4 metres tall and 0.35 metres in radius by default, standing on its position. It is drawn from geometry rather than a model file, so a game starts without any other game's character and downloads no VRM or VRMA file; hand it an avatar to wear a VRM body, and her body and clips start downloading as `<CharacterSpawn>` first renders.
+
+`shape` swaps the capsule for another primitive and `color` paints it. A `PlaceholderShape.Box` is as tall as her and as wide as her capsule; a `PlaceholderShape.Sphere` is a ball her `radius` round, resting on her feet. `shape={PlaceholderShape.Sphere} color="red"` makes her a red ball.
+
+`model` names a model from the same registry [Entity](/engine/entities/entity/) reads, so a model `spawnite add asset` registers works for her too. The model stands with its lowest point on her feet, and its front, +z in the file as glTF puts it, faces the way she does. Where the file has clips, she plays the ones her pose asks for: `idle`, `walk` and `run` blended by her ground speed, and `jump` off the ground, once, holding its last frame until she lands. The jump fades in and out over 0.2 s. A model with no clips stands as its file poses it. Each clip `playClip` asks of her plays over them from its file, as an [Entity's model](/engine/entities/entity/#models) does. `ModelClip` names the four.
+
+The blend places the idle at 0 and the walk and the run each at its stride speed: the ground speed at which the clip, played at its own pace, keeps her feet planted. Between two neighbours the weights move linearly with her speed. The walk and the run share one phase, so a blend of the two never crosses her legs, and the phase turns as fast as the ground passes under her, so her feet hold on the ground at every speed. Below the walk's stride speed the walk plays at its own pace and takes a larger share of the blend as she speeds up; above the run's, the run plays faster. A loop that holds its first pose before its first key, as a Meshy walk and run do for a frame, starts at that key, so the loop does not hitch.
+
+The engine measures each stride speed when her model loads: the mean speed at which each toe moves back under the hips while it stays planted, at the scale the model is drawn. It finds the toes, or the feet where the rig has no toes, by the names Meshy, Mixamo and VRoid give them, such as `LeftToeBase`, `mixamorig:LeftFoot` and `J_Bip_L_Foot`. Where it finds neither, or the clip moves neither foot, that clip plays at its own pace, the walk blending in at half her top speed and the run at her top speed, and the model warns once in development, naming the model, the clip and the `clipSpeeds` to set. A missing clip leaves its place to its neighbour: a model with no `walk` blends from its `idle` straight into its `run`, and one with neither stands in its `idle`. A `run` that `clips` points at the walk's clip, such as `clips={{ run: "walk" }}`, is one place in the blend, as with no `run`: she walks at every speed past the walk's.
+
+Unity lays out the same blend as a 1D Blend Tree, whose Compute Thresholds → Speed reads each clip's speed off its root motion, and Unreal and Godot as a BlendSpace1D, with Unreal's sync groups keeping the walk and the run in step. Roblox's Animate script plays one clip at a time and scales the walk's rate by the character's speed.
+
+`clips` points a pose at a clip the file names differently, such as `clips={{ run: "Sprint" }}` for a file whose run is called `Sprint`. A name the file lacks warns once in development, listing the file's clips.
+
+`clipSpeeds` sets a stride speed in place of the one the engine measures, in metres a second at the scale the model is drawn, such as `clipSpeeds={{ walk: 0.7, run: 2.15 }}`. Set it where the measure reads a clip wrongly, such as a run whose feet slide, or where a clip warns that it cannot be measured. Each speed is a positive number, and the walk's is below the run's; anything else throws as `<CharacterSpawn>` mounts, saying what to change. The walk's speed stays below the run's once the engine adds the speeds it measures and the defaults for a clip it cannot measure, so a run set below a measured walk throws as her model loads, naming where each speed came from. `ModelClipSpeeds` is its type.
+
+`material` dresses her model: a function handed each mesh's own material, which returns the one she wears in its place, such as a glowing shader built over the file's texture. `<CharacterSpawn>` reads it when her model loads and again whenever the function changes, so define it once outside the component. The material it returns is the game's: `<CharacterSpawn>` never disposes it, so one material can dress every mesh and every character. Left out, her model wears the `material` it registered with, as an [Entity's](/engine/entities/entity/#materials) does.
+
+An avatar wins over a model, and a model over a primitive.
+
+Whatever she wears, her physics body stays the capsule the body fields cut. Her size never comes from her model, as a walker's does: she is 1.4 m tall and 0.35 m in radius unless `<CharacterSpawn>` sets `height` or `radius`.
+
+## Your own pose clips
+
+An avatar stands, runs, turns and jumps in the engine's clips unless the game gives its own. `registerClip` under a pose's name puts a VRMA file in place of that pose's clip for every avatar in the game, such as a heavier run for a knight or a creature's gait: `registerClip(PoseState.Run, trot)`, with `trot` a `?url` import of the file, as the [one-shot sample](#one-shot-clips) imports its clip. Register it before the first character draws, beside the game's other clips. The return forgets it: a character drawn after plays the engine's clip again, and one already drawn keeps her clips until she draws again.
+
+`PoseState` names the seven poses: `idle`, `run`, `turnLeft`, `turnRight`, `jump`, `runJump` and `land`. `StrafeClip` names the three strafe clips the engine ships none of. The engine's land clip starts where its feet touch the ground, since the capsule has already fallen by then. A game's land clip starts at its `touch` mark, `registerClip(PoseState.Land, url, { marks: { touch: 0.25 } })`, and plays whole without one. A room never loads a clip: every page plays the pose its room streams, with the clip its own game registered. A `model` character names its own clips with `clips` instead.
+
+Roblox swaps the clips of its default `Animate` script by name, and Unity's Animator Override Controller replaces a controller's clips by name the same way. Unreal and Godot give each character its own animation blueprint or tree. Here one call per pose replaces the clip and keeps the engine's blending, aiming and strafing over it.
+
+## One-shot clips
+
+`playClip(character, name)` plays a clip once over whatever her pose plays, then fades back to the pose, as Unreal plays a montage. A cast or a hit plays this way. Every avatar plays her pose clips and each clip `registerClip(name, url)` names: a VRMA file, a `?url` import, registered before the first character draws. A pose's name, such as `idle` or `strafeLeft`, puts the clip in place of that pose's, as [Your own pose clips](#your-own-pose-clips) says.
+
+```tsx
+import cast from "./animations/cast.vrma?url";
+import { registerClip } from "@spawnite/engine";
+
+registerClip("cast", cast, { marks: { release: 0.4, settle: 0.9 } });
+```
+
+`marks` names where things happen in the clip, in seconds from its start, as Unity's animation events, Unreal's notifies and Roblox's keyframe markers sit on the clip: a VRMA carries no event track, so the marks sit beside its file. `release` is the frame a cast lets its spell go, and an [ability](/engine/behaviours/abilities/#casting) that plays the clip casts at it. A look hears any mark with `useClipMark(entity, "settle", heard)`, called on the page that draws the clip as her one-shot crosses the mark, with the clip, the mark, its seconds and the play: where shards stand up as her hands come down, exact to the frame rather than to the room's tick. Each mark raises the `ClipMarkEvent` event on her for the step. `spawnite play timeline` shows a clip frame by frame with the second under each, which is how a mark is read, and [Animations](https://wiki.spawnite.com/learn/animations/) walks the whole path from a clip file to a confirmed mark.
+
+The clip fades in over `fadeSeconds`, 0.15 s by default, and fades out over its last `fadeSeconds`. By default it plays over her whole body. On an avatar, a run or a jump ends it early, faded out the same way, so she never slides across the ground in a cast. A model's one-shot plays on through a run or a jump to its end, so a model that moves while it casts plays the cast on `ClipLayer.UpperBody`. `{ hold: true }` holds the last frame instead, as a death does, until `stopClip(character)` fades her back, the next `playClip` replaces it, or she respawns. The call writes the `OneShotClipTrait` trait, which a room streams, so every page plays the clip on her. A name her clips lack plays nothing and stops the clip her layer plays, as `stopClip` does, and a dev world warns once with the names she has. [Entity](/engine/entities/entity/#models) plays a model's clips the same way.
+
+`layer: ClipLayer.UpperBody` plays the clip on the bones from her spine up, while her pose's clip goes on driving her hips and legs, so she shoots or waves while she runs. A run or a jump does not end an upper-body clip. A clip on each layer plays at once, the upper body's over the whole body's, and `stopClip(character, { layer: ClipLayer.UpperBody })` fades out the upper body's alone. The engine finds the spine itself: a VRM avatar's `spine` bone, and on a model the first bone whose name holds `spine`, such as a Meshy rig's `Spine02` or a Mixamo rig's `mixamorig:Spine`. A model with no such bone plays the clip on its whole body, and a dev world warns once with the bones it has. The upper body's clip writes the `UpperBodyClipTrait` trait, which a room streams as it does the whole body's.
+
+`start`, `end` and `speed` play part of a clip: from `start` seconds into the file's clip to `end`, at `speed` times its pace. A held clip holds its `end` frame. Marks keep the seconds of the file's clip, so a clip played from 0.3 s never raises a mark at 0.1 s. A `start` below 0, an `end` not after `start`, a `speed` of 0 or less, or any of them infinite throws, with what to pass. An `end` past the clip's length plays to the clip's end, and a dev world warns with that length. A gun that fires one shot of a looping burst clip plays its first shot on the arms alone:
+
+```ts
+//  In a system, on each shot.
+playClip(character, "shoot", {
+    layer: ClipLayer.UpperBody,
+    start: 2 / 30,
+    end: 10 / 30,
+    speed: 1.5,
+    hold: true,
+});
+//  When the aim lapses.
+stopClip(character, { layer: ClipLayer.UpperBody });
+```
+
+Unreal plays a montage into a slot that a layered blend per bone limits to the spine's branch, and sets a montage section's start and its play rate. Unity plays the clip on an Animator layer with an `AvatarMask` that holds the upper body, and sets a state's speed. Roblox has no mask: an animation track drives the joints its keyframes name, at a priority over the movement's track, with `AdjustSpeed` and `TimePosition`. The engine names the layer, as Unity and Unreal do, and finds the spine for you, so the same call fits a VRM avatar, a Meshy rig and a Mixamo rig.
+
+## Posing over the clips
+
+`useAfterPose(entity, callback)` calls `callback({ root, bone }, seconds)` on the page each frame, right after the engine has posed the entity's model: after its clips and one-shot clips, an avatar's aim, grip and humanoid rig, and before an avatar's springs, which follow what the callback moves. `root` is the model's root object, and `bone(name)` is the bone of its skeleton named `name`, as the file names it, or undefined. Call it in any component under the World, such as `<CharacterSpawn>`'s children. It works on `<CharacterSpawn>`'s `model`, a VRM `avatar` and an Entity's animated model, and it stops when the component unmounts.
+
+```tsx
+import { useAfterPose } from "@spawnite/engine";
+import type { Entity } from "koota";
+import { Quaternion, Vector3 } from "three";
+
+const recoil = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), 0.2);
+
+interface LeanProps {
+    character: Entity;
+    /** Radians the soldier leans back. */
+    lean: number;
+}
+
+export function Lean({ character, lean }: LeanProps) {
+    useAfterPose(character, ({ root, bone }) => {
+        root.rotation.x = -lean;
+        bone("RightHand")?.quaternion.multiply(recoil);
+    });
+    return null;
+}
+```
+
+A bone that the callback reaches through `bone` goes back to its clip's pose before the next frame, so a turn the callback adds each frame stays one turn, even over a held clip whose pose does not move. `root` keeps what the callback writes, so set its values rather than add to them. On a VRM avatar, `bone` reaches the raw bones, by the names her file gives them. Unity runs the same step in `LateUpdate` or `OnAnimatorIK`, after the Animator, and Unreal in a Control Rig or an animation blueprint's post-process graph.
+
+## Names over other players
+
+In a room, every page draws each other player's name over their character's head, and never the player's own. The name is white, 12 px semibold, the same size on the screen at any distance, with a thin dark outline and a soft shadow and no box behind it, as Roblox draws a display name, so it reads on grass, fire and sky. Its bottom stands 0.15 m over the top of the character's drawn body. While that player speaks in the room's voice, as [`useSpeaking`](/engine/audio/voice/) reads it, a green microphone stands left of the name: it shows within a tenth of a second of their voice and stays 0.3 s past their last word.
+
+Who sees a name, and how far:
+
+- **Anyone else:** whole to 20 m, fading out to nothing at 30 m. A wall between the camera and the name hides it; the page checks each name's line of sight five times a second, with the same ray a shot uses against cover.
+- **A teammate**, a character on the page's player's team: the name takes the team's colour, never fades with distance unless the game sets `fade` or `distance`, and shows through walls, as Fortnite's team nameplates and Roblox's `EnemyOcclusion` do.
+
+The plate hangs in the object the character's view draws, as the interact prompt does, so a game that draws its own characters, as Holdfast does, gets it with no code. A player turns every plate off with Show other players' names in [Settings](/engine/ui/settings/).
+
+The scene's `<CharacterSpawn>` sets how the plates look and when they show, with one prop, `nameplate`:
+
+- `nameplate={false}` draws no plates, for a game that draws names of its own.
+- `nameplate={{ fade: [30, 50], size: 14 }}` tunes the engine's plate: how far it shows and where it starts to fade, where it stands over the head, its size in pixels, the colour of a name with no team, whether walls hide it for everyone, for enemies only or for nobody, and whose plates show. `background: true` puts each name on a 50% black pill. [`NameplateOptions`](https://wiki.spawnite.com/reference/player/nameplateoptions/) holds each field and its default.
+- `nameplate={MyPlate}` draws each plate with a component of the game's own. It receives [`NameplateProps`](https://wiki.spawnite.com/reference/player/nameplateprops/): the character's `entity`, her `name`, whether she is `speaking`, the `color` her name draws in, whether she is a `teammate`, and the setting's `size` and `background`. The engine still places it, fades it and hides it behind walls. It draws in pixels, with the plate's bottom middle at its origin. `{ component: MyPlate }` does the same beside the other options.
+
+The engine's own plate is `Nameplate`, so a game's plate can draw it beside something of its own, such as a health bar:
+
+```tsx
+import {
+    CharacterSpawn,
+    Nameplate,
+    type NameplateProps,
+} from "@spawnite/engine";
+
+function PlateWithBar(props: NameplateProps) {
+    return (
+        <>
+            <Nameplate {...props} />
+            <mesh position={[0, -4, 0]} scale={[60, 4, 1]}>
+                <planeGeometry />
+                <meshBasicMaterial color="#ff4d5e" transparent />
+            </mesh>
+        </>
+    );
+}
+
+export function Run() {
+    return <CharacterSpawn nameplate={PlateWithBar} />;
+}
+```
+
+A team is the `TeamTrait` trait on a character: characters with the same non-empty `name` are teammates, and `color` is the team's CSS colour. A game's room sets it, such as `character.add(TeamTrait({ name: "red", color: "#ff6b6b" }))`, and the stream carries it to every page, as Roblox's `Player.Team` names a player's team and its `TeamColor`.
+
+The name is the one the player joined the room as: the room writes it on her character's `PlayerNameTrait`, and every page reads it through `useDisplayName`, where a `DisplayNameTrait` the game puts on her stands over it, as [Entity](/engine/entities/entity/#display-name) says.
+
+What the other engines do: Roblox is the one that draws names by default, over every character, hidden behind walls, out to 100 studs, and a creator changes it with `DisplayDistanceType`, `NameDisplayDistance` and `NameOcclusion`. Fortnite's island settings choose who sees nameplates, how far, whether obstacles hide them, and a voice indicator. Unity, Unreal, Godot and PlayCanvas draw no names, and give a game a billboard to build one. This plate takes Roblox's default and its look, Fortnite's controls and its team default, and draws on the engine's [Billboard](/engine/ui/billboard/).
+
+## A player's character is a character she controls
+
+`spawnNpcBody(world, { position, facing })` spawns a walker: the traits the step walks along a navmesh path, turns, jumps and poses, on the engine's default movement. `spawnCharacter` spawns the same walker and adds `ControlledTrait`, which makes it an entity a player may control, and her health; `<CharacterSpawn>` and the room add her body, name, bag and weapons. What walks, poses or draws her reads the character's traits, so `walkTo(world, destination, character)` sends a character with no `ControlledTrait` round the navmesh as it sends her, and `Replicas` draws a streamed character in its avatar as it draws a player's character. In a game played alone, the engine draws a character a system spawned in the same view, so it shows alone as it shows in a room. `ControlledTrait` says a player may control the entity, and which one does: a [chase](/engine/behaviours/chase/), the `Players` [collision layer](#collision-layers) and a room's seats read it, and pass over a character without it. The devtools' `walkTo`, which the CLI and the MCP call, is a test's step on top of this one: it sends the player's character and steps the world until she arrives or its steps run out. Unreal splits it the same way: one `Character` walks, and a player's controller or an AI controller possesses it.
+
+### When a walk is refused
+
+`walkTo` returns what it did. A walk it started is `{ corners, partial }`: the corners it walks, and `partial`, true where no route reaches the point and the corners stop at the nearest point the search reached, such as the foot of a rock the walkers cannot climb. She walks a partial route and stops at its end. A walk it refused is `{ refusal }`, a `WalkRefusal`:
+
+| Refusal              | When                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `NoNavMesh`          | The world has no navmesh: it mounts no `<World>`, whose ground every navmesh is baked from, or the bake has not finished.     |
+| `NoCharacter`        | None was named, and the world has no player's character.                                                                      |
+| `NotWalker`          | The entity named is gone, or walks no path: it was spawned without `spawnNpcBody` or `spawnCharacter`, so has no `PathTrait`. |
+| `StartOffMesh`       | The character stands too far off the walkable ground to snap onto the mesh.                                                   |
+| `DestinationOffMesh` | The point is too far off the walkable ground to snap onto the mesh, such as a click into the sky.                             |
+| `NoRoute`            | Both ends snapped and the search failed.                                                                                      |
+
+A refused walk changes nothing: the character keeps the path it had. A click into the sky leaves a walk under way alone, and a routine that wants its character stopped on a refusal clears the path itself, `character.set(PathTrait, { corners: [] })`. A click on an [interactable](/engine/behaviours/interact/) whose walk is refused forgets the interactable, so a walk under way presses nothing it passes. In a room, a walk her page started goes to the room, which finds its own route; a walk the room's navmesh refuses stands her there, since her page dropped her last walk for it, and the room logs it.
+
+Unity's `SetDestination` returns a bool and its `pathStatus` says complete, partial or invalid; Unreal's `MoveToLocation` returns `Failed` with a separate partial flag; Godot's agent answers `is_target_reachable()`; Roblox's path answers `NoPath`. None names why, and each walks a partial route to its nearest point, as this one does. A refused walk keeps the old path, as a Roblox walk goes on after a failed compute, where Unreal's `MoveToLocation` aborts the old move: a refusal here is an answer with no side effect, so the caller chooses whether to stop.
+
+### Control
+
+A player controls the entities her input drives: her character in most games, a drone or a kart beside it or in its place, or nothing at all in a card game. `ControlledTrait` holds the link: the controller, a player entity or none, the way it is simulated, `Simulation.Predicted` or `Simulation.Server`, and its control serial, a number each change of the link takes. Control changes on the room alone:
+
+- `control(step, player, entity, { simulation })` makes her control the entity from the next tick. The mode is required. A control of an entity another player holds hands it over in one change. Three options beside it: `visibility: ControlVisibility.Controller` hides who controls it from every page but hers, `context` names the [input context](#input-contexts) live on her page while she controls it, and `viewTarget: true` makes it the entity `ViewTargetTrait` on her player names, the one her camera is to follow.
+- `tryControl(step, player, entity, { simulation, from: null })` returns `{ ok: true }`, or `{ ok: false, refusal }` with a `ControlRefusal`: `EntityGone`, `ControllerLeaving`, `NotControllable` for a player or a room controller, `NotAController` for an entity that is neither, and `ControlledByOther` where `from` names another controller than the one that holds it. Two riders who reach for one seat in one tick get one `{ ok: true }`. `control` throws the same refusals in development and logs them in a deployed room.
+- `releaseControl(step, entity)` clears the controller: the entity reads each input at rest, and its systems step it on.
+
+Each call checks and reserves at once, and the change commits as the tick ends, so every system of a tick reads one controller per entity: `findController(world, entity)` reads the committed one, `findPendingController(step, entity)` the one after this tick's changes, `readControlled(world, player)` lists what she controls, and `readPendingControlled(step, player)` what she will control once the tick commits. A join hook may control the joining player's own entities with its step, as the `characters` plugin controls her character; a hook that reaches for another entity throws, which refuses the join. Destroying a controlled entity drops it from her control at once, and a player who leaves releases everything she controlled.
+
+Her input for each tick rides to the room once, whatever she controls: the room writes it onto her player entity, where `readInput(player, handle)` reads it, and into each entity she controls. Her page predicts each entity she controls in `Simulation.Predicted`, as it predicts her character: it steps the entity on her input the moment she presses, and a correction restores and re-runs every one of them. `useCharacter()` and `readLocalCharacter(world)` read the character her player controls, a character with its pose before a kart or a drone she controls beside it. The room's tests run two creators' plugins against a real room, `drone.ts` and `crank.ts`: a drone she flies in her character's place, and a game whose player has no character and plays through an axis of its own.
+
+A plugin's `onControlRelease(step, entity, { controller, reason })` runs once for each control that ended, at the commit, in plugin order, so a plugin tidies up without a system that polls. The `ReleaseReason` is `Released`, `HandedOver`, `EntityDestroyed`, `ControllerGone` for a player who left or a room controller destroyed, or `LevelChanged` for an entity the room's scene destroyed as it started again. The entity may be gone already, as the reason says. A control a hook stages commits at the next commit.
+
+A hidden control streams its controller as none to every page but the controller's: a prop hunt's disguised player reads, on every other page, as the empty prop beside her. Her own page learns of it in her acknowledgement, so `findController` there names her player. No page but hers receives a control's serial, mode or context.
+
+#### Bot players and room controllers
+
+Room AI drives an entity through the input path a player's page drives one through, so the entity's own systems, its prediction and its tuning stay one code:
+
+- `addController(step, { name })` makes a room controller: an entity `control` accepts, which is no player, never streams, and `readPlayers` leaves out. An NPC racer, an autopilot that lands a dropped pilot's dragon, or a takeover of a dropped player's hero each control through one. Destroying it releases what it controls. An entity it controls is simulated on the room alone.
+- `addBotPlayer(step, { name })` fills a seat with a player of the role `Role.Bot`, with every plugin's join hooks, so the `characters` plugin gives her a character and a scoreboard counts her. She holds no save, `kick` removes her, and the room's close runs her leave with every player's.
+- `writeInput(step, controller, { handle, value })` writes one field of a room controller's or a bot player's input for the next tick, as a page sends a player's before the tick it names; a field no system wrote for a tick reads at rest, an angle where it last stood. A player's own input comes from her page alone.
+
+The autopilot, `autopilot.ts` in the room's outside tests, is a creator's plugin a test runs against a real room: a room controller drives an NPC kart until a player takes the wheel, and a player hides in a prop no other page sees her control.
+
+#### Input contexts
+
+An input context is a named list of a plugin's inputs with a priority, `contexts: { driving: inputContext({ priority: 10, inputs: ["throttle", "handbrake"] }) }`, which a control names. While she controls an entity under it, the context is live on her page. Every input fills from its own keys, and a key two live contexts' inputs share fills the higher one's alone: W fills a kart's throttle and not her seated character's walk, since the `characters` plugin controls her character under `characters.walking`, at priority 0. A key a higher context took stays off the lower input until she lets it go, so leaving the kart with W held walks nowhere until she presses it again. An `exclusive: true` context, a menu's, rests every input below it. Two live contexts of one priority that share a key throw in development. Two inputs may share a key only where each is listed in a context. As Unreal's input mapping contexts and their priorities.
+
+Unreal possesses one pawn per controller, on the server, and Photon Fusion gives one player input authority over any number of objects, each reading her tick's input; control here takes Fusion's shape with Unreal's rule that the room alone possesses. Unlike `Possess`, a control is visible at once only through `findPendingController`, and every system reads the committed link.
+
+## Where it runs
+
+Her page, and in a room the room too. Her player entity and every entity she controls in `Simulation.Predicted` say `RunContext.Client` on her page, so her page runs them ahead of the room; everything else spawns under the server's authority. In a room, the room also runs each of her moves from her input and has the final say, and her page takes its correction. [Multiplayer](https://wiki.spawnite.com/platform/multiplayer/) says how.
+
+## Sample
+
+```tsx
+import {
+    CharacterSpawn,
+    World,
+    registerModel,
+    scatterModels,
+} from "@spawnite/engine";
+
+registerModel("tree-round", scatterModels.treeRound);
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn model="tree-round" position={[0, 0, 4]} />
+        </World>
+    );
+}
+```
+
+A rigged model she wears, in a glowing material over its own texture, playing a file's `Sprint` as her run:
+
+```tsx
+import { MeshStandardMaterial, type Material } from "three";
+import { CharacterSpawn, registerModel, World } from "@spawnite/engine";
+import spirit from "../assets/spirit.glb?url";
+
+registerModel("spirit", spirit);
+
+/** The file's texture, lit from within. */
+function glow(original: Material) {
+    const map = original instanceof MeshStandardMaterial ? original.map : null;
+    return new MeshStandardMaterial({
+        map,
+        emissiveMap: map,
+        emissive: "#8fbcff",
+    });
+}
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn
+                model="spirit"
+                material={glow}
+                clips={{ run: "Sprint" }}
+            />
+        </World>
+    );
+}
+```
+
+A VRM body she wears with her clips:
+
+```tsx
+import { CharacterSpawn, World, type VrmBody } from "@spawnite/engine";
+import model from "../assets/heroine.vrm?url";
+
+const heroine: VrmBody = {
+    model,
+    scale: 1,
+    armSpread: {
+        left: { out: 0, forward: 0 },
+        right: { out: 0, forward: 0 },
+    },
+};
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn avatar={heroine} position={[0, 0, 4]} />
+        </World>
+    );
+}
+```

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

@@ -0,0 +1,20 @@
+---
+title: SP0001
+description: "Dialog gives an NPC a conversation: put it inside an <Npc>."
+---
+
+The engine makes this error in `Dialog`, from `@spawnite/engine`. Its declaration's comment says what the call requires.
+
+## The message
+
+Each `%s` is a value the error names where it is thrown, such as an entity, a name or a number:
+
+```text
+Dialog gives an NPC a conversation: put it inside an <Npc>.
+```
+
+## What to do
+
+The message says what was asked, what was wrong and what to change. The line under it, which starts `Spawnite:`, names the system that ran, the engine call, the entity and the tick where the engine knew them.
+
+When the message and that line do not explain the failure, it may be a bug in the engine. [Errors and bug reports](/engine/testing/errors/) says how to reproduce it and write a bug bundle.

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

@@ -0,0 +1,20 @@
+---
+title: SP0002
+description: "%s needs the dragAndDrop plugin: add dragAndDrop() from @spawnite/engine to your Game's plugins."
+---
+
+The engine makes this error inside its own work, not in an engine call a game makes.
+
+## The message
+
+Each `%s` is a value the error names where it is thrown, such as an entity, a name or a number:
+
+```text
+%s needs the dragAndDrop plugin: add dragAndDrop() from @spawnite/engine to your Game's plugins.
+```
+
+## What to do
+
+The message says what was asked, what was wrong and what to change. The line under it, which starts `Spawnite:`, names the system that ran, the engine call, the entity and the tick where the engine knew them.
+
+When the message and that line do not explain the failure, it may be a bug in the engine. [Errors and bug reports](/engine/testing/errors/) says how to reproduce it and write a bug bundle.

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

@@ -0,0 +1,20 @@
+---
+title: SP0003
+description: "A hull collider is shaped from a model; name one"
+---
+
+The engine makes this error inside its own work, not in an engine call a game makes.
+
+## The message
+
+Each `%s` is a value the error names where it is thrown, such as an entity, a name or a number:
+
+```text
+A hull collider is shaped from a model; name one
+```
+
+## What to do
+
+The message says what was asked, what was wrong and what to change. The line under it, which starts `Spawnite:`, names the system that ran, the engine call, the entity and the tick where the engine knew them.
+
+When the message and that line do not explain the failure, it may be a bug in the engine. [Errors and bug reports](/engine/testing/errors/) says how to reproduce it and write a bug bundle.