@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/behaviours/dialog.md

@@ -0,0 +1,172 @@
+---
+title: Dialog
+description: A conversation an NPC holds with the player who talks to it, with choices that act on the world.
+useCases:
+    - npc dialogue
+    - branching conversation
+    - player dialogue choices
+    - talk to an npc
+    - dialogue that depends on a condition
+    - dialogue choice that changes the world
+    - shopkeeper conversation
+    - quest giver dialogue
+sidebar:
+    order: 21
+---
+
+A conversation is what an [NPC](/engine/entities/npc/) says to the one player who talks to it, and the choices that player picks among. `dialog()` builds it as a tree of nodes: each node has a line, and either choices that lead to other nodes or an end. `<Dialog tree={...} />` inside an `Npc` gives the NPC its conversation, and a press of its [Interact](/engine/behaviours/interact/) prompt starts it. The `DialogPanel` in the game's HUD shows it. The MCP's `add_dialog`, or `spawnite add dialog <npc>`, gives an NPC that exists a short conversation to start from, in [the template](https://wiki.spawnite.com/platform/templates/#dialog).
+
+It is one of three layers of NPC speech:
+
+- A bark is a line over the NPC's head that everyone nearby sees, which a `say` step of [its routines](/engine/behaviours/routines/) draws over its name.
+- A conversation is a panel for the one player who is talking, so two players each hold their own with the same NPC. A player holds one conversation at a time.
+- A consequence is what a choice does, which a room runs on the server.
+
+## An example
+
+```tsx
+import {
+    addItem,
+    countItem,
+    Dialog,
+    dialog,
+    Interact,
+    Npc,
+} from "@spawnite/engine";
+
+const talk = dialog("mira", { gift: "potion", spareBelow: 2 })
+    .node("hello", (n) =>
+        n
+            .say("Morning, {player}! I'm {npc}.")
+            .choice("Could you spare a potion?", "gift", {
+                when: ({ player, values }) =>
+                    countItem(player, values.gift) < values.spareBelow,
+            })
+            .choice("Just passing by.", "bye"),
+    )
+    .node("gift", (n) =>
+        n
+            .do(({ player, values }) =>
+                addItem(player, { item: values.gift, count: 1 }),
+            )
+            .say("Here, take a {gift}.")
+            .choice("Thank you!", "bye"),
+    )
+    .node("bye", (n) => n.say("Safe roads, {player}.").end())
+    .start("hello");
+
+export function Mira() {
+    return (
+        <Npc name="Mira" title="Herbalist">
+            <Interact prompt="Talk" />
+            <Dialog tree={talk} />
+        </Npc>
+    );
+}
+```
+
+Mount one `DialogPanel` in the game's `Hud`, as a `Bag` is:
+
+```tsx
+import { DialogPanel, Hud } from "@spawnite/engine";
+
+export function GameHud() {
+    return (
+        <Hud>
+            <DialogPanel />
+        </Hud>
+    );
+}
+```
+
+## Named values
+
+`dialog("mira", { gift: "potion", spareBelow: 2 })` names the dialog and declares each value once; a dialog with no values takes its name alone, `dialog("guard")`. A line reads one as `{gift}`, and a `when` or a `do` reads the same one as `values.gift`, so a number is written in one place. The engine adds two values of its own: `{player}`, the talking player's name, or "traveller" for a player with none, and `{npc}`, the NPC's name. A value may be a function of the conversation, `{ coins: ({ player }) => player.get(WalletTrait)?.coins ?? 0 }`, which a line reads each time it shows. A name holds letters, digits and underscores, such as `herb_name`: `dialog()` refuses any other name with a type error, and again as it runs, naming the value.
+
+The names are typed: a `{name}` in a line that the dialog lacks is a type error, and the builder also refuses it as it runs, naming the node and the value. A choice's target and `start` are checked the same way: `start` reads which target names no node. A target held in a plain `string` variable is checked only as the builder runs. Choice text shows as written, with no values filled in. A node holds at most nine choices, one for each number key: the builder refuses a node with more, naming the node and its count, so split a longer list across two nodes with a choice that leads on to the rest.
+
+A line stays plain data, so the wiki, the devtools and a later translation file can list every line.
+
+## `when` and `do`
+
+Each is a function that receives the conversation: `world`, the `player`'s entity, the `npc`'s entity and the `values`.
+
+- `when` on a choice hides it while it returns false. It is read as the node begins, and again as the player's pick arrives: a pick of a choice whose `when` has turned false since is dropped, and the conversation stays on its node.
+- `do` on a node runs once each time the node begins, before its line is filled in, so a line can read what it changed.
+
+Both run only where the world runs its rules: in a room, on the server. The record a page receives carries the filled line and the choices that are shown, so a page evaluates nothing, and it reaches the talking player's page alone.
+
+## A shop
+
+A shop node charges with [`spendCoins`](/engine/behaviours/pickup/#coins-a-game-pays) and hands over with `addItem`. Give the item first: `addItem` returns the count the bag took, 0 for a full bag, so the node spends only once the potion is in. `spendCoins` returns false where the wallet no longer holds the price, and the node then takes the potion back out with `removeItem`, so it sells whole or not at all. The choice's `when` hides the sale from a player short of the price, and the room reads it again as her pick lands, so a player who spent her coins since the node began buys nothing. A `do` runs on the room, so `requireAuthority(world)` gives the authority `spendCoins` takes.
+
+```ts title="packages/room/test/outside/shop.ts"
+import {
+    addItem,
+    dialog,
+    removeItem,
+    requireAuthority,
+    spendCoins,
+    WalletTrait,
+} from "@spawnite/engine/core";
+
+export const shop = dialog("tobin", { item: "potion", price: 5 })
+    .node("hello", (n) =>
+        n
+            .say("A {item} for {price} coins?")
+            .choice("I'll take one.", "sold", {
+                when: ({ player, values }) =>
+                    (player.get(WalletTrait)?.coins ?? 0) >= values.price,
+            })
+            .choice("Not today.", "bye"),
+    )
+    .node("sold", (n) =>
+        n
+            .do(({ world, player, values }) => {
+                //  Into the bag first: a full bag takes none, and keeps
+                //  its coins. Where the wallet no longer holds the price,
+                //  the potion comes back out, so the node sells whole or
+                //  not at all even without the choice's `when`.
+                const potion = { item: values.item, count: 1 };
+                if (addItem(player, potion) === 0) return;
+                if (!spendCoins(requireAuthority(world), player, values.price))
+                    removeItem(player, potion);
+            })
+            .say("Mind your bag: what it can't hold, I keep.")
+            .choice("Thanks.", "bye"),
+    )
+    .node("bye", (n) => n.say("Come back soon, {player}.").end())
+    .start("hello");
+```
+
+## The panel
+
+`DialogPanel` stands along the bottom of the screen: the speaker's name and title, a portrait, the line typed out, and the choices as buttons below the pane. It fits a phone's width.
+
+- The number keys 1 to 9, or a tap, pick a choice. The numbers count the choices that are shown.
+- The Interact key shows the whole line while it types. Once the line is whole, it goes on where a node has one way on: past a node that ends, or through its only choice. A held key acts once, on its first press.
+- Escape ends the conversation and leaves the menu shut, as World of Warcraft's Escape closes a gossip window first; the next Escape opens the menu. The menu opening another way ends the conversation too.
+- The panel frees the cursor while the conversation is open, so a click picks a choice under a camera that captures the cursor, and the camera takes the cursor back when it ends, as [the camera page](/engine/entities/camera/#panels-that-free-the-cursor) says. The keys keep working with the cursor free.
+- Under reduced motion the line shows whole at once.
+
+Its `portrait` prop draws the speaker's face from the speaker's name, such as `portrait={(speaker) => <img src={faces[speaker]} alt="" />}`. Left out, the pane shows the first letter of the name.
+
+## The player while talking
+
+The player moves freely. A conversation holds out to the NPC's Interact radius plus the one metre a room allows a press, so a press the room accepted never ends in the same step, as World of Warcraft closes a gossip window farther out than it opens one. Walking past that ends the conversation, as a disconnect does. A press of another NPC's prompt while one conversation is open starts nothing. The NPC stops, faces the player, clears the line over its head, and holds its routine where it is. The conversation adds the `TalkingTrait` trait to the NPC, which holds its routine alone: every other [machine](/engine/structure/states/) on it keeps running, and a `MachinePausedTrait` the game added stays the game's. With two players talking to it, `TalkingTrait` stays until the last conversation ends. The routine then resumes at the step it was on: a walk heads back for the point it was walking to, and a wait keeps its seconds.
+
+## What it holds
+
+A conversation sits on the talking player's character. Its `conversation` trait holds the NPC by the key a dump files it under, the speaker's name and title, the node, its filled line, the choices that are shown, whether the Interact key ends it there, and `entered`, the count of nodes entered so far. Beside it sits the dialog's [machine](/engine/structure/states/), named for the name `dialog()` took, `miraDialog` for `dialog("mira", ...)`, so every NPC handed one build runs one machine, as [routines](/engine/behaviours/routines/#its-name) do: a node is a state, and a choice is the event `choose1`, `choose2` and so on. `spawnite play dump` shows both. A hot reload that builds the dialog again ends a conversation on the old build, and the next press starts one on the new.
+
+## In a room
+
+The room runs every conversation. A player's pick reaches the room as the `npcs.dialog` message, `{ npc, choice, entered }`, where `choice` is a choice's number, 0 for the Interact key past a node that ends, and -1 to end it, and `entered` is the record's count the page showed. The room checks each message by its shape, at most 8 a second, the sender's own conversation, and the sender's reach, as it checks an [Interact](/engine/behaviours/interact/) press. It takes the first pick a conversation gets in a step whose `entered` matches the record's, so a double click or a stale pick lands on no node the player has not seen; an end is taken whatever its count. The room streams each record and its machine to its own player alone, as it does her bag, since the dialog's machine declares `ownerOnly`: another player's page reads nothing of the conversation, the node included, and another player sees the NPC stop and face the player it talks to, and sees its barks as before.
+
+## What the others do
+
+Roblox ships `Dialog` and `DialogChoice` objects, a tree with a bubble over the head and a list of choices. Unity, Unreal, Godot, PlayCanvas and Phaser ship none; their games use Yarn Spinner, Ink or Dialogic, text scripts of nodes, choices, conditions and commands with `{variable}` substitution. World of Warcraft shows gossip menus with a condition on each option, and Old School RuneScape and Final Fantasy XIV a panel along the bottom with the speaker's name and portrait. The engine takes the node-and-choice tree all of them share and the bottom panel, and writes the tree in TypeScript on the engine's own machine, so a conversation dumps, streams and checkpoints like any other machine.
+
+## Reference
+
+[`DialogPanelProps`](https://wiki.spawnite.com/reference/npc/dialogpanelprops/), [`DialogProps`](https://wiki.spawnite.com/reference/npc/dialogprops/), [`Talk`](https://wiki.spawnite.com/reference/npc/talk/) and [`ConversationTrait`](https://wiki.spawnite.com/reference/npc/conversationtrait/).

package/dist/wiki/engine/behaviours/health.md

@@ -0,0 +1,330 @@
+---
+title: Health
+description: Tracks damage, reaps an entity at zero, and downs a player's character or an entity with a respawn until it comes back.
+useCases:
+    - health points
+    - player death and respawn
+    - downed state until revived
+    - healing mechanic
+    - enemy that dies or respawns
+    - deal damage to an entity
+    - health regeneration
+    - spawn enemies on a timer
+    - a wave every N seconds
+    - health bar over an enemy's head
+sidebar:
+    order: 5
+---
+
+Health gives an entity a pool of hit points, starting full. A player's character is an entity that carries the `ControlledTrait` trait, whether or not a player controls it now: every character `<CharacterSpawn>` spawns, and any other entity `control` linked to a player, a kart she has left among them. A view reads her own character with `useCharacter()`.
+
+Its props are in [`HealthProps`](https://wiki.spawnite.com/reference/entity/healthprops/).
+
+[`dealDamage(step, entity, { amount, source, weapon, data })`](https://wiki.spawnite.com/reference/entity/dealdamage/) takes an entity's health down, never below zero, and the step downs the entity at zero and [removes it the step after](#when-it-dies). Damage is an outcome, so its first argument is the room's step, or `requireAuthority(world)` outside a step, as [Where a system runs](/engine/structure/systems/#where-a-system-runs) describes. An entity with [`<Respawn>`](#when-anything-else-runs-out-of-health) is not reaped: it goes down and stands again. A player's character is not reaped either: she goes down, with the `DownedTrait` trait, stays in the world, and [respawns](#when-a-character-runs-out-of-health) a few seconds later unless the game turns that off. `source` is who dealt it, such as the shooter's character; the entity's `DamageSourceTrait` keeps the last one, and [`DiedEvent`](#when-it-dies) names the one whose hit took it to zero, so a game credits the kill. `weapon` names the weapon it came from, and `data` is the game's own record for the hit; both are optional. Each call emits one `DamagedEvent` on the entity, which [the weapon page](/engine/behaviours/weapon/#reading-its-hits) says how to read. An entity with the `InvulnerableTrait` trait takes none, and a game that keeps its characters' health in a trait of its own spares an `InvulnerableTrait` character too, as Holdfast's wardens do. A room started with `ROOM_INVULNERABLE=1` gives every player's character it, for `spawnite play profile --invulnerable`, the way Unreal's `bCanBeDamaged` and Roblox's `ForceField` stop damage.
+
+[`dealHealing(step, entity, { amount, source })`](https://wiki.spawnite.com/reference/entity/dealhealing/) gives health back, never past the maximum. It is an outcome too, so it takes the room's step, or `requireAuthority(world)` outside a step, as `dealDamage` does. Each call emits one `HealedEvent`, `{ amount, source }`, on the entity, so a view draws a rising number and a game credits the healer. Its `amount` is the heal as asked, which can be more than it restored where the entity stood near its maximum, as a hit's `amount` can be more than the health it had left. A view reads `HealedEvent` as it reads `DamagedEvent`, with `useEvent`, as [the weapon page](/engine/behaviours/weapon/#reading-its-hits) says, and `useFloatingText` draws the number over the entity. A downed character is healed and stays down until the game removes `DownedTrait`, as [a revive](#when-a-character-runs-out-of-health) does. An amount below 0, or no finite number, throws, naming `dealDamage` as the way to take health off, and an entity with no health throws too. A potion's heal is one of these, by the character who drank it. `changeResource` does not change health: `healthResource` is a type error there, and a key that holds it throws, so a page in a room cannot change an outcome. Unreal's ability system applies a heal as a gameplay effect beside damage, and Roblox leaves it to a script that sets `Humanoid.Health`; here a heal is its own outcome with its own event, as damage is.
+
+[`useHealth(entity)`](https://wiki.spawnite.com/reference/entity/usehealth/) reads an entity's `{ current, maximum }` for a bar or a label. It returns `undefined` while the entity has no Health, so the caller chooses whether to hide the bar or draw it full.
+
+## When it dies
+
+The reap, `behaviours.reapDead`, downs an entity whose health has reached zero, with `DownedTrait`, and emits `DiedEvent` on it: in the same step for a hit dealt before the reap, and in the next step for one dealt after it, such as a projectile or an ability in a later system. A system that reads `DiedEvent` after the reap reads it in the step it is emitted, and one before it reads it the next step, as every [event](/engine/structure/systems/#events) is read. The step after the reap, it removes the entity, unless it is a player's character or has a [respawn](#when-anything-else-runs-out-of-health). Between the two, the entity keeps its traits but does nothing: no ability targets it, a projectile passes through it, a chaser stops, and it fires no shot. So every game system reads its death and its traits, such as a boss's mark or a monster's loot table, before the entity goes. Roblox fires `Humanoid.Died` the same way, and Unity's `Destroy` and Godot's `queue_free` hold an object until the frame ends for the same reason.
+
+`DiedEvent` carries `source`: the entity whose hit first took the health to zero. A later hit in the same step does not take the credit, and a death no hit dealt, such as a game setting the health to 0 itself, names `null`. `source` is `null` too where the killer is already gone. A player's character and an entity with a respawn get `DiedEvent` once per life: a hit while she lies down fires nothing, and the next death after she stands again fires it again. An entity the game downed itself, such as a hostile it stunned at full health, dies as any other does when its health reaches zero. Healing an entity above zero before the step reaches it, or a game setting its health above zero, means it never dies, and a later death names only a hit dealt after that. Healing it after it died does not bring it back: the step after still removes it, unless the game takes `DownedTrait` off first, as a revive does.
+
+A game reads `DiedEvent` in a system with `readEvents`, and a page hears it with `useEvent(DiedEvent, …)`. In a room the room emits it, and every page that holds the entity hears it a send later, with the dead entity and its killer still standing in the page's world: a page keeps an entity the stream removed until its next step has read the events that name it, as [the systems page](/engine/structure/systems/#events) says. So a kill feed, a death animation or a drop on a page reads what died, where it fell and who killed it. A game that counts deaths counts them in a system on the room and streams the count, as the following kill count does. It runs on the room, and the engine's tests run it against a real room:
+
+```ts title="packages/room/test/outside/kills.ts"
+import type { World } from "koota";
+import {
+    definePlugin,
+    defineTrait,
+    DiedEvent,
+    readEvents,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  A kill count, built as a creator's plugin is, from the engine's public
+//  entry alone: the room adds one to a player's character's count for each
+//  death she dealt the lethal hit of, and the stream carries the count to
+//  every page.
+
+/** The kills a player's character has made; the stream carries it. */
+export const KillsTrait = defineTrait("outsideKills", { count: 0 });
+
+export const kills = definePlugin({
+    name: "kills",
+    onCharacterSpawn: (character) => {
+        character.add(KillsTrait);
+    },
+    //  No runsOn: the room alone counts, and a game played alone is its
+    //  own room.
+    systems: { rules: { count: { system: countKills } } },
+});
+
+function countKills(_world: World, step: AuthoritativeStep) {
+    for (const { record } of readEvents(step, DiedEvent)) {
+        const killer = record.source;
+        const tally = killer?.get(KillsTrait);
+        if (killer && tally) killer.set(KillsTrait, { count: tally.count + 1 });
+    }
+}
+```
+
+A round won on a boss's death reads `DiedEvent` the same way, as [the Round page](/engine/structure/round/#won-on-a-bosss-death) shows.
+
+## When a character runs out of health
+
+A player's character at zero health goes down, waits 5 seconds, and comes back at the point she spawned at with full health, whether `<CharacterSpawn>`, a room or `spawnCharacter` spawned her. In a room her connection stays open throughout, and her page shows the seconds left. A game needs no code for this. Roblox does the same with its `Players.CharacterAutoLoads` and `Players.RespawnTime`, 5 seconds by default. Unreal's game mode restarts a player's pawn when the game calls `RestartPlayer`, and Unity, Godot and PlayCanvas leave it to the game.
+
+To change it, set `respawn` on the scene's [`<CharacterSpawn>`](/engine/entities/player/):
+
+```tsx
+import { CharacterSpawn, RespawnPlace } from "@spawnite/engine";
+
+export function Character() {
+    return <CharacterSpawn respawn={{ seconds: 3, at: RespawnPlace.Fallen }} />;
+}
+```
+
+- `seconds` is how long she stays down first: 5 by default, and 0 brings her straight back.
+- `at` is where she comes back: `RespawnPlace.Spawn`, the point she spawned at, by default; `RespawnPlace.Fallen`, where she fell; or a point the game names, such as `[0, 2, 10]`.
+
+In a room `<CharacterSpawn>`'s `respawn` holds for every player's character. Each character carries it as her `RespawnTrait` trait, which the dump of a room or of a game played alone shows as `respawn`, and which no page's stream carries: `seconds`, `point`, and `inPlace` where she comes back where she fell. While she waits, her character keeps `DownedTrait` and carries `RespawningTrait`, whose `seconds` is the whole wait and whose `secondsLeft` counts down; a dump shows it as `respawning`. She walks, jumps and fires nothing while she is down.
+
+To own the death flow, such as a revive by a teammate, turn respawn off with `respawn={false}`. Her character then stays down, her connection stays open, and the game gets her up: it gives her health above zero, then removes `DownedTrait`. Removed at zero, the next step downs her again. A game that gets her up while she waits to respawn ends the wait. [Depthfield](https://wiki.spawnite.com/games/depthfield/) turns respawn off for its death screen. [Holdfast](https://wiki.spawnite.com/games/holdfast/) keeps its wardens' health on a trait of its own, so the engine never downs a warden, and turns respawn off as well.
+
+While her character waits, [Game](/engine/structure/game/#respawn-screen) draws the seconds left over the game. A game draws its own screen, or none, with Game's `respawnScreen`.
+
+## When anything else runs out of health
+
+Any other entity at zero health goes down for a step, then the step removes it, as [When it dies](#when-it-dies) says. To keep one in the world, such as a monster that comes back, give it `<Respawn>` beside its `<Health>`:
+
+```tsx
+import { Entity, Health, Respawn, type EntityProps } from "@spawnite/engine";
+
+export function Wolf({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="wolf" animation="idle" position={position}>
+            <Health maximum={60} />
+            <Respawn seconds={20} clip="death" />
+        </Entity>
+    );
+}
+```
+
+Its props are in [`RespawnProps`](https://wiki.spawnite.com/reference/entity/respawnprops/):
+
+- `seconds` is how long it stays down: 5 by default, as a player's character's wait is.
+- `clip` names the clip its model plays once as it goes down and holds until it stands, as [`playClip`](https://wiki.spawnite.com/reference/animation/playclip/) holds one. With none, its model keeps playing the animation it loops.
+
+At zero health the entity goes down on the next step, as a player's character does:
+
+- It carries `DownedTrait` and `RespawningTrait`, and its health stays at 0.
+- No ability targets it, and a projectile passes it to what stands behind.
+- A [chaser](/engine/behaviours/chase/) stops where it fell, and the other chasers walk over it. A game's own system that moves an entity leaves out one with `DownedTrait`, as it would a downed character.
+- After `seconds` it stands where it fell, at full health, and its held clip ends.
+
+It keeps its `TargetableTrait` and its collider while it is down. A game that gets it up first, with health above zero and `DownedTrait` removed, ends the wait and the held clip. In a room, the room runs the respawn, and every page draws the fall and the return from the stream.
+
+`<Respawn>` is for an entity a scene places. A player's character's respawn is `<CharacterSpawn>`'s `respawn`. Outside an `<Entity>`, `<Respawn>` throws where it renders and names that prop. Among `<CharacterSpawn>`'s children that is on a page, once her model is drawn: a room or a headless run draws none of `<CharacterSpawn>`'s children, so there it does nothing. A respawn at another spot is not built: a game spawns a new entity there instead, as [Spawn one at runtime](#spawn-one-at-runtime) shows.
+
+Roblox respawns a player's character and leaves a monster to a script that clones its model. Unity, Unreal, Godot, PlayCanvas and Phaser leave a monster's death and return to the game. The engine ships it, because a creator who asks for wolves that come back should need no code for it.
+
+## Spawn one at runtime
+
+A system spawns an entity at runtime with `spawn(step, prefab, { position })`: a wave of monsters, a summoned pet, a drop. `definePrefab` declares the kind once, its traits, its model and its collider, and a scene places the same prefab with `<Entity prefab={wolf} />`, so both carry the same traits. A spawn is an outcome, so it takes the room's step, in a system with no `runsOn` or inside `if (step.authoritative)`; a step on a page in a room is no authority, so a spawn there does not typecheck. Every trait the stream carries, the engine's, such as `TransformTrait`, `ModelTrait` and `HealthTrait`, and each a game makes with `defineTrait`, goes to every page, where the game's `<Replicas>` draws the entity: as its model, or, for a walker `spawnNpcBody` spawned, in the avatar its `AvatarTrait` names, which each page registers with `registerAvatar` as [the Player page](/engine/entities/player/) says, or else its placeholder body; a walker takes no `ModelTrait`. In a game played alone the engine draws the same entity in the same view, with nothing to mount. At zero health the entity is removed, as any other is. The engine's tests run this spawner against a real room and alone:
+
+```ts title="packages/room/test/outside/spawner.ts"
+import { createQuery, type World } from "koota";
+import { Vector3 } from "three";
+import {
+    ChaseTrait,
+    definePlugin,
+    definePrefab,
+    defineTrait,
+    fixedStepSeconds,
+    HealthTrait,
+    spawn,
+    TargetableTrait,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  Wolves spawned at runtime, built as a creator's plugin is, from the
+//  engine's public entry alone: the room spawns a wolf at once and every
+//  two seconds after, at the next spot of its den, up to three at once.
+//  Each is one prefab, which a scene places with `<Entity prefab={wolf} />`
+//  and the spawner spawns the same: a model that chases the nearest
+//  player's character, can be targeted, and is removed at zero health. Its
+//  traits stream, so every page draws it, and a game played alone draws it
+//  the same way.
+
+/** Marks a wolf, so the spawner counts its own; the stream carries it. */
+export const WolfTrait = defineTrait("outsideWolf");
+/** The most wolves standing at once. */
+export const wolvesAtOnce = 3;
+/** Seconds between two wolves. */
+export const wolfSeconds = 2;
+const den = [new Vector3(8, 0, 0), new Vector3(0, 0, 8), new Vector3(-8, 0, 0)];
+const wolves = createQuery(WolfTrait);
+
+/** One wolf: what a scene places and what the spawner spawns. */
+export const wolf = definePrefab("outsideWolf", {
+    traits: [
+        WolfTrait,
+        HealthTrait({ current: 30, maximum: 30 }),
+        ChaseTrait({ speed: 3, reach: 1 }),
+        TargetableTrait,
+    ],
+    model: "wolf",
+});
+
+export const spawner = definePlugin({
+    name: "spawner",
+    //  No runsOn: the room alone spawns, and a game played alone is its
+    //  own room.
+    systems: { rules: { wolves: { system: spawnWolves } } },
+});
+
+function spawnWolves(world: World, step: AuthoritativeStep) {
+    if (step.tick % Math.round(wolfSeconds / fixedStepSeconds) !== 0) return;
+    const standing = world.query(wolves).length;
+    if (standing >= wolvesAtOnce) return;
+    spawn(step, wolf, { position: den[standing] });
+}
+```
+
+Unity's `Instantiate`, Unreal's `SpawnActor`, Godot's `instantiate()` and Roblox's `Clone` copy a prefab or a template, and `definePrefab` is the same idea: each spawn copies the prefab's records, and the spawn's own `traits` go over them field by field, so `traits: [HealthTrait({ current: 10 })]` keeps the prefab's `maximum`. An entity with no prefab, such as a match record, is `spawn(step, { traits: [...] })`, and `destroy(step, entity)` takes any entity away, nulling every reference a trait holds to it.
+
+## Max health is a stat
+
+`maximum` is the base of the entity's `maxHealth` [stat](/engine/behaviours/stats/), which `<Health>` and the `<CharacterSpawn>` component declare with a `min` of 1. `maxHealthStat` names it. A modifier on it raises or lowers the cap, as an upgrade, an item or a curse would:
+
+```tsx
+import { useEffect } from "react";
+import {
+    addStatModifier,
+    maxHealthStat,
+    removeStatModifiers,
+    useEntity,
+} from "@spawnite/engine";
+
+export function Amulet() {
+    const wearer = useEntity();
+    useEffect(() => {
+        addStatModifier(wearer, maxHealthStat, { source: "amulet", flat: 20 });
+        return () => removeStatModifiers(wearer, "amulet");
+    }, [wearer]);
+    return null;
+}
+```
+
+Each step sets `maximum` to the stat's resolved value, then clamps `current`:
+
+- When the cap falls below `current`, `current` falls to the cap.
+- When the cap rises, `current` stays where it is. A game that wants the new points filled heals the entity itself.
+
+So the devtools inspector's Health card has no `maximum` slider on an entity with the stat, since the next step would overwrite an edit. The inspector's Stats card slides the `maxHealth` base instead, and the modifiers still apply over it.
+
+A save keeps the stat's base as `maximum`, never a buff over it, and keeps `current` as it was, which a saved modifier may hold above that base. The first step after a load caps `current` at the resolved maximum, so a save whose `current` is past every cap still loads.
+
+Unreal's Gameplay Ability System pairs Health with a MaxHealth attribute in the same way, and leaves the current value where it is when the cap rises. Unity, Godot, Roblox and PlayCanvas have no built-in health; their games and addons write the same pair.
+
+## Health is a resource
+
+Health is the [resource](/engine/behaviours/resources/) `healthResource`, the engine's own, so its bar and its regeneration work as mana's and stamina's do. Damage, death, the downed character, hit zones and the save stay Health's own.
+
+`<ResourceBar resource={healthResource}>` draws an entity's health in the theme's health tone, `var(--color-health-fill)`, under the label "Health". `label` names it otherwise, and `showValue` reads `30 / 120` beside it:
+
+```tsx
+import type { Entity } from "koota";
+import { healthResource, ResourceBar } from "@spawnite/engine";
+
+export function WolfHealth({ wolf }: { wolf: Entity }) {
+    return (
+        <ResourceBar
+            entity={wolf}
+            resource={healthResource}
+            label="Wolf health"
+            showValue
+        />
+    );
+}
+```
+
+Health does not regenerate unless a game registers a `regen` for it, as Unreal's and World of Warcraft's games each choose their own. Register it with `registerHealth` in a plugin's `setup`, with `regenDelaySeconds` for the seconds it waits after each hit, and a `color` or `label` where the theme's do not fit:
+
+```ts
+import { definePlugin, registerHealth } from "@spawnite/engine";
+
+export const healing = definePlugin({
+    name: "healing",
+    setup: (world) => registerHealth(world, { regen: 5, regenDelaySeconds: 4 }),
+});
+```
+
+- `registerHealth` takes no `maximum`: `<Health maximum>` and `<CharacterSpawn>`'s `health` give health and set its maximum, so leave `healthResource` out of `<CharacterSpawn>`'s `resources` and of `<Resource>`.
+- A `healthRegen` [stat](/engine/behaviours/stats/) on an entity takes the place of `regen` for it, as an item of regeneration would.
+- An entity at zero never regenerates: a downed character waits for her respawn or the game.
+- An ability's `cost` cannot name health, since a cast holds its cost back and health holds no reserve. An ability that spends health deals it to the caster with `dealDamage` in its effect.
+
+### A bar over its head
+
+To hang the bar over the entity, as a boss's or a monster's is, put it in a Panel anchored to the entity, [`<Panel anchor={Anchor.Above}>`](/engine/ui/panel/#anchored), inside the `<Entity>` beside its `<Health>`. The Panel follows the entity and faces the screen, and `useEntity()` names the entity for the bar. The engine's tests mount this boss and read his bar before and after a hit:
+
+```tsx title="packages/engine/test/outside/BossHealthBar.tsx"
+import {
+    Anchor,
+    Entity,
+    Health,
+    healthResource,
+    Panel,
+    ResourceBar,
+    useEntity,
+} from "@spawnite/engine";
+
+function BossHealthBar() {
+    const boss = useEntity();
+    return (
+        <Panel anchor={Anchor.Above} maxDistance={60}>
+            <ResourceBar
+                entity={boss}
+                resource={healthResource}
+                label="Yeti king health"
+                className="h-3 w-64"
+            />
+        </Panel>
+    );
+}
+
+export function YetiKing() {
+    return (
+        <Entity position={[0, 0, -30]}>
+            <Health maximum={500} />
+            <BossHealthBar />
+            <mesh>
+                <boxGeometry args={[2, 3, 2]} />
+                <meshStandardMaterial color="#dfe8f0" />
+            </mesh>
+        </Entity>
+    );
+}
+```
+
+A [Billboard](/engine/ui/billboard/) holds meshes rather than HTML, so a bar built from its meshes draws neither the ResourceBar's hit nor the theme's colours.
+
+## Where it runs
+
+Server. Health has a consequence: it can end the entity.
+
+```tsx
+import { Entity, Health, type EntityProps } from "@spawnite/engine";
+
+export function Yeti({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="yeti" position={position}>
+            <Health maximum={30} />
+        </Entity>
+    );
+}
+```

package/dist/wiki/engine/behaviours/interact.md

@@ -0,0 +1,41 @@
+---
+title: Interact
+description: Shows a prompt and fires a callback while the player's character is near.
+useCases:
+    - press e to interact
+    - clickable object
+    - open a door or chest
+    - talk to npc prompt
+    - interaction radius
+    - interact prompt above an object
+    - click to walk to an object
+sidebar:
+    order: 4
+---
+
+Interact shows a prompt above an entity while the player's character is near it, and fires a callback on a key press or a click. The player's character is an entity that carries the `ControlledTrait` trait, whether or not a player controls it now: every character `<CharacterSpawn>` spawns, and any other entity `control` linked to a player, a kart she has left among them. A view reads her own character with `useCharacter()`.
+
+Its props are in [`InteractProps`](https://wiki.spawnite.com/reference/entity/interactprops/).
+
+The prompt shows while the player's character is near, with the key that presses it, and the E key fires `onInteract`, except an E typed into a text field. Where the camera walks the player's character to a click, as the classic camera does, a click or a tap on the entity walks her to where it stood and fires `onInteract` once she comes within `radius`, stopping her there, as World of Warcraft's click-to-move does with an NPC. A click on the ground, a steer, or a walk that ends short of the entity, because it walked on, cancels the press; a second click follows it. A callback is allowed here because Interact is client behaviour. Each press also adds the `InteractedEvent` event to the entity, which a system or an [NPC's routine](/engine/behaviours/routines/) reads.
+
+## Where it runs
+
+Client. The prompt only changes what this client shows.
+
+In a room, "the player's character" is each page's own. The room steps the entity and streams its trait, whose `near` says whether any player's character stands within `radius`. Each page ignores that `near`: it shows the prompt while its own character stands within `radius`, and the E key fires the `onInteract` its own scene passed. A press on one page fires nothing on another. The press also reaches the room as the engine's `behaviours.interact` message, which every world registers: the room adds `InteractedEvent` to its own copy of the entity when the pressing player's character stands within `radius` plus 1 m, the metre covering the player's page walking ahead of the room. `InteractedEvent` carries `by`, the characters whose presses reached the entity in that step, so two players who press together each start their own [conversation](/engine/behaviours/dialog/); a press on a page with no room names no character. So an NPC's `talk` routine runs on the room, and every page sees it through the stream. A Server behaviour that needs to know which character is near reads `findNearestControlled` in its system, as Pickup and Chase do.
+
+```tsx
+import { Entity, Interact, type EntityProps } from "@spawnite/engine";
+
+export function Chest({
+    position,
+    onInteract,
+}: Pick<EntityProps, "position"> & { onInteract: () => void }) {
+    return (
+        <Entity model="chest" position={position}>
+            <Interact prompt="Open" onInteract={onInteract} />
+        </Entity>
+    );
+}
+```