@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,274 @@
+---
+title: Resources
+description: "Mana, rage, stamina or a shield: a value a character fills and spends, shown on a bar or kept hidden."
+useCases:
+    - mana bar
+    - stamina that drains and recovers
+    - rage resource
+    - shield that absorbs damage
+    - ability costs mana
+    - resource regeneration
+    - hidden counter on a character
+    - show a resource on a bar
+    - stamina that drains while running
+    - spend a resource while the character moves
+sidebar:
+    order: 17
+---
+
+A resource is a value a character fills and spends, such as mana, rage, stamina, energy or a shield. Every resource has one shape: you define it once and get its key, give it to a character, and show it with a bar where the player should see it. An [ability](/engine/behaviours/abilities/)'s `cost` spends any of them but health.
+
+Health is the engine's own resource, `healthResource`, so `<ResourceBar resource={healthResource}>` draws it and a game turns its regeneration on with `registerHealth`. [The health page](/engine/behaviours/health/#health-is-a-resource) says what stays Health's own.
+
+## Define a resource
+
+[`defineResource(name, settings)`](https://wiki.spawnite.com/reference/resources/defineresource/) defines a resource and returns its key, a `ResourceKey`. Call it once, at module scope, in a file the room and every page import, as `defineCooldown` and `defineTrait` are called. Every call that names the resource takes the key, never its name as text, so a misspelt name fails to typecheck:
+
+```ts
+import { defineResource } from "@spawnite/engine";
+
+export const mana = defineResource("mana", {
+    maximum: 100,
+    regen: 5,
+    start: "full",
+    color: "#4aa3ff",
+    label: "Mana",
+});
+
+export const rage = defineResource("rage", {
+    maximum: 100,
+    regen: -2,
+    start: "empty",
+    color: "#d64545",
+    label: "Rage",
+});
+
+export const stamina = defineResource("stamina", {
+    maximum: 50,
+    regen: 10,
+    start: "full",
+    regenDelaySeconds: 1,
+    color: "#e0c341",
+    label: "Stamina",
+});
+```
+
+The settings are the following. Only `maximum` is required:
+
+- `maximum` is what it holds when full.
+- `regen`, which is 0 by default, is what it gains each second, up to `maximum`. A negative `regen` decays it toward 0, as rage does.
+- `start`, which is `"full"` by default, is where it starts when a character is given it: `"full"`, `"empty"`, or a number.
+- `regenDelaySeconds`, which is optional, stops its regeneration for that many seconds after a spend, as stamina does.
+- `saved`, which is optional and true by default, keeps what a character has of it in a save. With `saved: false`, the save leaves it out and a load starts it from `start`, as a shield that refills on each load wants.
+- `color`, which is optional, is the fill every bar draws it in: any CSS colour. Left out, a bar draws in the ui `Bar`'s own fill, the health tone.
+- `label`, which is optional, is what a player reads: the bar's name, and the line a refused cast shows, such as "Not enough mana". Left out, it is the name as words: `"Combo"` for `"combo"`, `"Lantern charges"` for `"lanternCharges"`.
+
+A resource's name is camelCase from a lowercase letter, such as `"mana"` or `"holyPower"`. It is also the name the dump, a room's stream and a save write it under, so the key reads as its name in every tool. A name another trait already uses, such as `"stats"`, throws, and so does `"health"`, the engine's. Defining a name again replaces its settings, as a reload of its module does.
+
+## A hidden resource
+
+Nothing draws a resource until a game places a `<ResourceBar>` for it or reads it with `useResource`, so a resource the player never sees needs only its `maximum`: a combo counter, a quest item's charges, or a boss's phase. It starts full and never regenerates unless its settings say so, and a system fills and spends it with `changeResource`:
+
+```ts
+import { defineResource } from "@spawnite/engine";
+
+export const combo = defineResource("combo", { maximum: 5, start: "empty" });
+export const lanternCharges = defineResource("lanternCharges", { maximum: 3 });
+```
+
+An ability's `cost` spends a hidden resource as it spends mana, and a refused cast names it by its label, "Not enough lantern charges" here. Give it a `label` where the name alone reads wrong to a player.
+
+## Give a character a resource
+
+Give every character of the game a resource with a plugin's `resources`, the player of one scene with `<CharacterSpawn>`'s `resources`, and any other entity with `<Resource>`:
+
+```tsx
+import {
+    defineResource,
+    definePlugin,
+    CharacterSpawn,
+    Entity,
+    Resource,
+} from "@spawnite/engine";
+
+const mana = defineResource("mana", { maximum: 100, regen: 5 });
+
+export const mageKit = definePlugin({ name: "mage-kit", resources: [mana] });
+
+export function Mage() {
+    return <CharacterSpawn abilities={["arcane-bolt"]} resources={[mana]} />;
+}
+
+export function Shaman() {
+    return (
+        <Entity position={[4, 0, -6]}>
+            <Resource resource={mana} />
+        </Entity>
+    );
+}
+```
+
+A plugin's `resources` gives each to a character as she spawns, before the plugin's own `onCharacterSpawn`, so the hook can read it. In a room, `<CharacterSpawn>`'s `resources` holds for every player's character, as its `health` does. A game's own system gives one with [`declareResource(entity, key)`](https://wiki.spawnite.com/reference/resources/declareresource/).
+
+Each resource is its own trait, `{ current, maximum, reserved }`, which the dump shows under the resource's name. A room streams it to every page, so a page draws another player's bar and a target's too. [`findResourceTrait(key)`](https://wiki.spawnite.com/reference/resources/findresourcetrait/) returns the trait for a system of your own.
+
+Each resource but health is a [predicted trait](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-1-declare-the-state) on a player's character: her page regenerates it on every step as the room does, so her bar fills smoothly between the room's sends, and the room's word corrects her page where the two differ, such as on a cost the room took. Her `maximum` follows her `max<Name>` stat, the room's word, so her page sets it again on each step and never corrects her for it alone. Health, and every resource of anything but a player's character, regenerates on the room alone, and each page draws what the room sends.
+
+## Show a resource
+
+[`<ResourceBar entity resource>`](https://wiki.spawnite.com/reference/resources/resourcebar/) draws the ui's `Bar` for an entity's resource, filled in the resource's colour, or the `Bar`'s own fill where it has none, and named by its label. What its reservations hold back shows as a lighter band after the fill. `color` draws one bar in another colour, `label` gives it another name, `showValue` reads `12 / 40` beside it, and `className` and `classNames` restyle it:
+
+```tsx
+import { defineResource, ResourceBar, usePlayer } from "@spawnite/engine";
+
+const mana = defineResource("mana", { maximum: 100 });
+
+export function ManaBars() {
+    const { entity } = usePlayer();
+    return (
+        <>
+            <ResourceBar entity={entity} resource={mana} />
+            <ResourceBar
+                entity={entity}
+                resource={mana}
+                color="#8b5cf6"
+                className="h-3 w-56"
+            />
+        </>
+    );
+}
+```
+
+To draw a resource any other way, such as an orb, a ring or a number, read it with [`useResource(entity, key)`](https://wiki.spawnite.com/reference/resources/useresource/). It returns `{ current, maximum, reserved }`, or `undefined` while the entity has none. Health's has no `reserved`, since no cast holds health back:
+
+```tsx
+import { defineResource, usePlayer, useResource } from "@spawnite/engine";
+
+const rage = defineResource("rage", { maximum: 100, start: "empty" });
+
+export function RageNumber() {
+    const { entity } = usePlayer();
+    const amount = useResource(entity, rage);
+    if (!amount) return null;
+    return <span>{Math.floor(amount.current)}</span>;
+}
+```
+
+## Fill and spend it from a system
+
+[`changeResource(entity, { resource, amount })`](https://wiki.spawnite.com/reference/resources/changeresource/) adds `amount`, or spends it where `amount` is negative, between 0 and the maximum: a hit that builds rage, a sprint that spends stamina. A spend pauses regeneration for `regenDelaySeconds`, as a hit from `dealDamage` pauses health's. Call it from a system, where the simulation has the say. Health is not one of these: it is an outcome, which `dealDamage` and [`dealHealing`](/engine/behaviours/health/) change with the room's authority, so `changeResource` refuses `healthResource` as a type error and throws on a key that holds it:
+
+```ts
+import { changeResource, defineResource, type Entity } from "@spawnite/engine";
+
+const rage = defineResource("rage", { maximum: 100, start: "empty" });
+
+export function buildRage(attacker: Entity) {
+    changeResource(attacker, { resource: rage, amount: 10 });
+}
+```
+
+### Spend it while the character moves
+
+A resource a character spends over time, such as stamina while she runs, is a system on her step. Each step it reads her `VelocityTrait`, the metres a second she moves, which the engine's movement writes from her input before the rules run. Where she moves faster than 0.1 metres a second, it spends the step's share of 25 a second; standing, it spends nothing, and the resource's `regen` fills it again once `regenDelaySeconds` have passed since the last spend.
+
+The system is predicted, `predicted: true`, and walks her with `step.updateEachPredicted`: her page spends on the tick the room does, as it regenerates, so her bar never waits a round trip, and the room's word corrects it. It runs `before` the engine's `resources.regenerate`, so the pause a spend starts holds regeneration from that same step. The room's tests walk her on a page joined to a room, with a correction from the room mid-walk, and check that her page never guessed her stamina wrong; a game played alone walks her for two seconds, then stands her still until she is full:
+
+```ts title="packages/room/test/outside/stamina.ts"
+import { createQuery, type World } from "koota";
+import {
+    changeResource,
+    definePlugin,
+    defineResource,
+    resources,
+    VelocityTrait,
+    type PredictedStep,
+} from "@spawnite/engine/core";
+
+//  Stamina that drains while she moves and refills while she stands, built
+//  as a creator's plugin is, from the engine's public entry alone. The
+//  resource's own regen refills it; the system only spends.
+
+export const stamina = defineResource("stamina", {
+    maximum: 100,
+    regen: 20,
+    regenDelaySeconds: 0.5,
+    color: "#e0c341",
+    label: "Stamina",
+});
+
+/** Stamina a second she spends while she moves. */
+const drainPerSecond = 25;
+/** Metres a second under which she stands still. */
+const stillSpeed = 0.1;
+
+const movers = createQuery(VelocityTrait);
+
+function drainStamina(_world: World, step: PredictedStep) {
+    step.updateEachPredicted(movers, ([velocity], character) => {
+        if (Math.hypot(velocity.x, velocity.z) < stillSpeed) return;
+        changeResource(character, {
+            resource: stamina,
+            amount: -drainPerSecond * step.deltaSeconds,
+        });
+    });
+}
+
+export const staminaPlugin = definePlugin({
+    name: "stamina",
+    resources: [stamina],
+    systems: {
+        rules: {
+            drain: {
+                system: drainStamina,
+                //  Her page spends it on the same tick the room does, as it
+                //  regenerates it, so her bar never waits for the room.
+                predicted: true,
+                before: [resources.systems.regenerate],
+            },
+        },
+    },
+});
+```
+
+List `staminaPlugin` in the game's plugins, and draw the bar with `<ResourceBar resource={stamina}>`, as [Show a resource](#show-a-resource) says.
+
+## How a cast spends it
+
+An ability's `cost` names what it spends by key, such as `{ [mana]: 25 }` or `{ [mana]: 20, [rage]: 30 }`: a record, so no resource is named twice. A plain name, `{ mana: 25 }`, fails to typecheck wherever the cost is written, in place or held in a variable, with an error that names it and the fix. A record widened to text keys, such as a `Record<string, number>`, is the one shape no type can refuse, since a keyed cost held in a variable has the same type. For a name in it that no `defineResource` made, `registerAbility` throws as the world is made, a development world throws at the first `checkCost`, `reserveCost` or `changeResource` that names it, and a deployed room logs it once, naming the call and the system, and reads the resource as none: `checkCost` finds the cost short, and a press refuses with `Refusal.NoResource`. The room refuses a cast whose cost the caster cannot pay, with `Refusal.NoResource`, and `CastRefusedEvent`'s `resource` names the one that fell short.
+
+A cast holds its cost back at its start: `current` drops and `reserved` rises, so a second cast cannot spend the same amount. The release spends what was held back, and a cancel or a fizzle gives it back. While a cast winds up, regeneration stops short of what is held back, so the resource never refills what the release spends.
+
+A game's own system holds a cost back the same way, under a key of its own, a `ReservationKey` from `defineReservation`, so its hold and the cast's never settle each other:
+
+- `checkCost(entity, cost)` returns the key of the first resource the entity has too little of, or `undefined` where the entity can pay.
+- `reserveCost(entity, reservation, cost)` holds the cost back under `reservation`.
+- `commitCost(entity, reservation)` spends what that key holds and pauses each resource's regeneration.
+- `refundCost(entity, reservation)` gives it back, up to each resource's maximum less what the other keys still hold.
+
+The strike that [Build a predicted mechanic](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#keep-outcomes-on-the-room) builds, which the engine's own tests run against a real room, defines its resource, its cost and its key at module scope:
+
+```ts title="packages/room/test/outside/strike.ts (part)"
+/** The resource a strike costs. */
+export const focus = defineResource("outsideFocus", { maximum: 100 });
+const cost: ResourceCost = { [focus]: 15 };
+const hold = defineReservation("outsideStrike");
+```
+
+Its press checks the cost with `checkCost(character, cost)` and holds it with `reserveCost(character, hold, cost)`, and its release spends it with `commitCost(character, hold)`. A strike and a cast on one character each settle their own hold.
+
+Each resource's `reserved` is the total of every key's hold, and `ReservationsTrait` holds each key's own, which the dump shows. Both are predicted on a player's character, so a correction restores every hold with the resources it holds back. The engine's cast holds its cost under `castReservation`, `ability:cast`, a name no `defineReservation` takes. Reserving again under a key that already holds a cost is a mechanic that never settled its last one: a development world throws, naming the key, and a deployed room keeps the first hold. The names follow Unreal's ability system, which checks, applies and commits an ability's cost.
+
+## The maximum is a stat
+
+`maximum` is the base of the character's `max<Name>` [stat](/engine/behaviours/stats/): `maxMana` for `"mana"`, `maxRage` for `"rage"`. A modifier on it raises or lowers the cap, as an item or a card would: `addStatModifier(entity, "maxMana", { source: "robe", flat: 20 })`.
+
+Where a character has a `<name>Regen` stat, such as `manaRegen`, it takes the place of the defined `regen`, so an item can raise it too.
+
+## Saving
+
+A save holds what the player has of each resource under `resources`, by name, counting what her reservations held back as hers, since a reload ends what held them. It holds each `max<Name>` stat with her other stats. `<CharacterSpawn>` restores her resources from the save by itself, and her stats from its `stats`, as [the stats page](/engine/behaviours/stats/) says, so pass the save's stats there too: `<CharacterSpawn resources={[mana]} stats={save.stats} />`. She then comes back with the mana she left with, under the cap she left with. A resource defined with `saved: false` starts from `start` instead. Health is the exception: the save holds it as the character's own `health`, as [the health page](/engine/behaviours/health/#max-health-is-a-stat) describes. `readResourcesSave` and `restoreResources` do the same for a game's own save code.
+
+## What the other engines do
+
+Unreal's Gameplay Ability System makes health, mana and stamina attributes that any ability's cost can spend. World of Warcraft gives each unit one power type, such as mana, rage that starts empty and decays, or energy, each with its own colour, and Diablo calls it the class's resource. Roblox builds in only `Humanoid.Health`, and Unity, Godot, PlayCanvas and Phaser ship none. This engine takes one shape for all of them, so an agent learns one pattern, and a creator makes a new resource and its look in one call. Like Unreal's attributes and this engine's own cooldown keys, a resource is a typed key rather than a name in text, so a misspelt resource is a type error rather than a cost that is always short. Unreal has no reservation: its ability system applies a cost at its commit and ties a predicted cost to a prediction key. A reservation key here gives each mechanic's hold its own name, as a cooldown key does, so two mechanics on one character never settle each other's cost.

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

@@ -0,0 +1,99 @@
+---
+title: Routines
+description: What an NPC does, step by step, and what it does when a player's character comes close.
+useCases:
+    - npc patrol route
+    - npc daily schedule
+    - npc walks between waypoints
+    - step by step npc actions
+    - npc reacts when player comes close
+    - shopkeeper that opens and closes
+    - guard that patrols then chases
+sidebar:
+    order: 20
+---
+
+`routines()` builds what an [NPC](/engine/entities/npc/) does: a set of named routines, each a list of steps, and the events that start one. It compiles to a [state machine](/engine/structure/states/): a routine is a compound state, each step a state inside it, and `resume` a deep history state. The machine declares `tags: false`, since a tag for each routine and step of every kind of NPC would slow the dump, so the routine system reads the step from the machine's record. Unreal splits an NPC the same way, with StateTree deciding and the controller moving: the machine decides, and the routine system writes the NPC's path as a click writes the player's.
+
+```ts
+import { NpcEvent, route, routines } from "@spawnite/engine";
+
+const market = route({
+    stall: [4, 0, -2],
+    well: [8, 0, -6],
+    herbs: [3, 0, -9],
+});
+const bench = route({ bench: [2, 0, -3] });
+
+const mira = routines("mira")
+    .routine("morning", (r) =>
+        r
+            .walk(market, { pause: { well: 4 } })
+            .wait(3)
+            .then("rest"),
+    )
+    .routine("rest", (r) =>
+        r
+            .walk(bench)
+            .wait({ between: [20, 40] })
+            .say("*yawns*")
+            .then("morning"),
+    )
+    .routine("greet", (r) => r.face().play("jump").say("Hello!").resume())
+    .on(NpcEvent.Approached, "greet")
+    .start("morning");
+```
+
+## Its name
+
+`routines("mira")` names the routines, and the machine is named for the name, `miraRoutines`: its trait dumps, streams and checkpoints under it. `toMachineId(name, kind)` makes that id, for a kit that builds machines of its own kind. Every NPC handed one build runs one machine, so a crowd of guards shares `routines("guard")` by intent, and two NPCs with one name over their heads and routines of their own each keep their own machine. A second build under a name, as a hot reload makes, takes the name over, so give each set of routines a name of its own. A name holds at least one letter or digit, and two names make two machines only when their letters and digits differ: `routines("north-guard")` after `routines("north guard")` throws, naming both. Unity's Animator Controller, Unreal's Behavior Tree and Godot's resources work the same way: the named asset holds the logic, and every character that references it runs it.
+
+## Steps
+
+- `walk(route, { repeat, yoyo, pause })`: walks the route once, and the step ends at its last point, so the routine goes on to its next step. `repeat` is how many more passes follow the first, 0 by default; `Infinity` walks the route until an event starts another routine. `yoyo` walks every second pass back down the points, so `{ repeat: 1, yoyo: true }` walks out and back. `pause` is seconds at every point, or, on a `route()`, seconds at each point by its name.
+- `wait(seconds)` or `wait({ between: [min, max] })`: counted by the fixed step, as any machine's wait. A roll between two numbers is drawn from the world's seeded random each time the wait begins, so two NPCs from one set of routines wait different lengths, and a replay waits as the run did. The roll sits on the machine's trait, so a checkpoint keeps it and a wait an event interrupts resumes with it.
+- `play(clip)`: a clip the avatar has, which the view crossfades to for two seconds and back, as it crossfades a change of pose. The avatars play their poses' clips: `idle`, `run`, `turnLeft`, `turnRight`, `jump`, `runJump` and `land`. A clip it lacks is skipped, and a dev world warns once naming it.
+- `say(line)`: a line right over its name for four seconds; the routine goes on at once. The line wraps when long and fades as the camera draws away. For a conversation with one player, give the NPC a [Dialog](/engine/behaviours/dialog/).
+- `turn(degrees)` and `face()`: a turn on the spot, left for a positive number, or a turn toward the nearest player's character, the one who came close or pressed the prompt.
+- `then(name)`, `resume()`, or nothing: go to a routine, go back to the routine an event interrupted at the step it was on, or repeat this one. A routine an event starts that names neither ends in `resume()`. `resume()` fits only a routine an event starts, and `start` refuses it on any other, naming the routine.
+
+A walk takes the shape of Phaser's `PathFollower` and GSAP's tweens, `repeat: 0` with `yoyo`, because a walk is one step in a sequence: it ends so that the next step can run. Unreal's and Roblox's `MoveTo` also move once and report arrival.
+
+## Routes
+
+A walk takes a route in one of three forms:
+
+- `route({ stall: [3, 0, -2], well: [8, 0, -6] })` names its points in the order the walk visits them, so a `pause` can name the well. A point is `[x, y, z]`, or `[x, z]` standing on the ground. Name each point with a word: an object puts a number-like key first, so `route()` refuses one.
+- `"meadowToRollingField"`, the name of a path the map holds under its `paths`, walked point to point with the ground giving each point's height. Its points have no names, so `pause` takes seconds for every point.
+- A list of points, `[[4, -2], [8, -6]]`, with `pause` in seconds for every point.
+
+The types keep a `pause` by name to a `route()` and its names. A map path the map does not hold, or a paused point the route does not name, skips the walk, and a dev world warns once naming the NPC, the routine and the name.
+
+## Events
+
+`on(event, name)` on the builder starts the routine `name` on the event from any routine an event did not start. Inside a routine it fires only there. `NpcEvent.Approached` fires when a player's character comes within the NPC's `Interact` radius, `NpcEvent.Interacted` when one presses its prompt, and `NpcEvent.Stuck` when a walk gives up on a point, as the fences below describe. An event routine takes no event, so a second event while it runs is dropped, and `Approached` fires again once the character leaves and comes back. A walk an event interrupts stops where the NPC stands and keeps its place on the route for a `resume`, a clip an event interrupts gives way to the pose, and a wait keeps the seconds it had counted.
+
+While a player holds a [conversation](/engine/behaviours/dialog/) with the NPC, the NPC holds the `TalkingTrait` trait and its routine holds: the NPC stops, faces the player, and takes no event, while every other machine on it runs on. Once its last conversation ends, the trait comes off and the routine goes on at the step it was on: a walk heads back for the point it was walking to, and a wait keeps its seconds. A game holds the routine itself with `MachinePausedTrait`, which holds every machine on the NPC until the game takes it off.
+
+## Fences
+
+Four fences keep an NPC in the world:
+
+1. The navmesh is the world's edge. A walk gives up on a route point `walkTo` refuses, and a dev world warns once naming the NPC, the routine, the point and the refusal.
+2. The `leash` on the NPC, from its spawn.
+3. A timeout per point: the distance over the walking speed, twice, plus 2 s, as Roblox's `MoveTo` gives up after 8 s. On a timeout the NPC is marked `StuckTrait`, the walk gives up on the point, and a dev world warns once.
+4. Every routine is finite: the builder makes lists, and `then` and `resume` are the only jumps. `start` refuses a routine name nobody declared, and a `resume()` in a routine no event starts.
+
+A walk that gives up on a point sends the routine `NpcEvent.Stuck`, and emits the `GaveUpEvent` event, which the dump's `events` lists as `gaveUp` with `{ point, reason }`: the point's place in the route from 0, and `"timeout"` or `"noRoute"`. A routine answers it with `.on(NpcEvent.Stuck, "lost")`, and a `resume()` in `lost` heads for the next point. With no `.on()` for it, the walk goes on to the next point, and past the last one the step ends. Roblox's `MoveToFinished` reports `reached` as false the same way, and Unreal's path following ends with `Blocked` or `Aborted` rather than `Success`.
+
+```ts
+const guard = routines("guard")
+    .routine("round", (r) => r.walk("gateToTower", { repeat: Infinity }))
+    .routine("lost", (r) => r.say("Hm, blocked.").resume())
+    .on(NpcEvent.Stuck, "lost")
+    .start("round");
+```
+
+## In words
+
+`describeRoutines` gives each routine as a line, such as `morning: walk stall to well to herbs, wait 3 s, then rest`, which the devtools' Wiki tab lists under the NPC.

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

@@ -0,0 +1,36 @@
+---
+title: Spin
+description: Turns an entity round y.
+useCases:
+    - spinning coin
+    - idle rotation of a collectible
+    - rotating pickup
+    - constant turning effect
+    - spinning powerup
+sidebar:
+    order: 1
+---
+
+Spin turns an entity around its y axis at a steady rate. A coin or any other collectible uses it for the idle turn it shows while it waits to be picked up.
+
+Its props are in [`SpinProps`](https://wiki.spawnite.com/reference/entity/spinprops/).
+
+## On a body
+
+On an entity with a kinematic body, Spin turns the body through its next pose, as `setNextPose` does, so it pushes what it meets and carries what stands on it. On a fixed or a dynamic body it throws in development, naming the entity, since a fixed body never moves and a dynamic one is the solver's: make the body kinematic, as the example's coin does.
+
+## Where it runs
+
+The room and every page. On an entity the room streams, the room turns it, a kinematic body with it, and each page draws the pose the stream brings. On an entity only a page holds, that page turns it.
+
+```tsx
+import { Entity, Spin, type EntityProps } from "@spawnite/engine";
+
+export function SpinningCoin({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="coin" position={position}>
+            <Spin speed={1} />
+        </Entity>
+    );
+}
+```

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

@@ -0,0 +1,220 @@
+---
+title: Stats
+description: Numbers that modifiers raise and lower, resolved by one formula.
+useCases:
+    - character stats
+    - buff that raises speed
+    - equipment stat bonus
+    - percent damage bonus
+    - temporary effect on a stat
+    - upgrade that boosts jump
+    - stat modifiers stacking
+    - level up numbers
+    - speed boost for the player
+    - stats the engine reads
+sidebar:
+    order: 10
+---
+
+Stats gives an entity numbers that items, upgrades and buffs change: a speed, a jump, a launch. You declare each stat's base, add modifiers, and read the result. The engine does the maths the same way every time.
+
+Its props are in [`StatsProps`](https://wiki.spawnite.com/reference/stats/statsprops/). Each prop is one stat, named by the prop: `<Stats speed={{ base: 6, max: 12 }} />`.
+
+## The formula
+
+```text
+clamp((base + Σflat) × (1 + Σpercent) × Π(1 + more), min, max)
+```
+
+A [`StatModifier`](https://wiki.spawnite.com/reference/stats/statmodifier/) sets one or more of three kinds:
+
+- `flat` adds to the base.
+- `percent` sums with the stat's other percents. `0.2` is +20%.
+- `more` multiplies with the stat's other mores. Two mores of `0.5` make ×2.25, where two percents of `0.5` make ×2.
+
+On a base of 1000, two `percent: 1` and one `more: 1` give 1000 × 3 × 2 = 6000. With all three as `percent`, they give 4000.
+
+The base never changes under a modifier. `min` and `max` clamp the value when it is read, never the base, so a modifier that ends restores the value it hid.
+
+## The verbs
+
+All take the entity and come from `@spawnite/engine/core`, so a system and a component call them alike:
+
+- `addStatModifier(entity, name, modifier)` adds a modifier to a stat.
+- `removeStatModifiers(entity, source)` removes every modifier that `source` added, on every stat: an item taken off, a buff cancelled.
+- `readStat(entity, name)` returns the resolved value, or `undefined` where the entity has no stat by that name.
+- `setStatBase(entity, name, base)` changes the base and keeps the bounds and the modifiers.
+- `resolveStat(stat)` applies the formula to a stat you already hold, such as one from `useTrait(entity, StatsTrait)`.
+
+A modifier with `seconds` lasts that many simulated seconds. The step counts it down and drops it the step it runs out. A modifier without `seconds` stays until its source is removed.
+
+Bases and modifiers are plain data, and a source is a string, so a save or a room can carry them as they are.
+
+## A buff for one round
+
+A buff that lasts one [round](/engine/structure/round/), such as a speed boost bought at a shop for the next run, is a modifier with a `source` and no `seconds`: a system adds it as the round's state reaches `RoundState.Playing` and removes it with `removeStatModifiers(character, source)` as the round is won or lost. A timed modifier would end at a time of its own rather than with the round. The character holds a trait of the game's own while the boost waits, which the game's [save](/engine/structure/saves/) keeps, so a boost bought in the lobby reaches the run. The modifier itself waits for the round, so she walks the lobby at her own speed. The engine's tests play a round with it:
+
+```ts title="packages/engine/test/outside/roundBoost.ts"
+import { createQuery, type World } from "koota";
+import {
+    addStatModifier,
+    definePlugin,
+    defineTrait,
+    moveSpeedStat,
+    removeStatModifiers,
+    stats,
+} from "@spawnite/engine/core";
+import { RoundMachine, RoundTrait, rounds } from "@spawnite/engine/rounds";
+
+//  A speed boost bought before a run, such as at the lobby's shop, which
+//  lasts the next round she plays: added as the round plays, under a
+//  source of its own, and taken off with that source as the round is won
+//  or lost, which uses the boost up.
+
+/** On a character who holds a boost; `active` while her round plays. The
+ *  game's own save keeps it, so a boost bought in the lobby waits for the
+ *  run. */
+export const BoostTrait = defineTrait("outsideBoost", { active: false });
+/** The source the boost's modifier is added under, so the round's end
+ *  takes it off and leaves her other modifiers. */
+export const boostSource = "round-boost";
+const boosted = createQuery(BoostTrait);
+
+export const roundBoost = definePlugin({
+    name: "round-boost",
+    requires: [rounds, stats],
+    //  No runsOn: the room alone owns the stats, and a game played alone
+    //  is its own room. In the physics phase, after every rule, so a round
+    //  any rule starts or wins moves the boost in that same step, before a
+    //  round screen can pause the next one.
+    systems: {
+        physics: {
+            boost: boostForTheRound,
+        },
+    },
+});
+
+function boostForTheRound(world: World) {
+    const round = world.queryFirst(RoundTrait);
+    if (!round) return;
+    const isPlaying = round.has(RoundMachine.is.playing);
+    const isOver =
+        round.has(RoundMachine.is.won) || round.has(RoundMachine.is.lost);
+    for (const character of world.query(boosted)) {
+        const isActive = character.get(BoostTrait)?.active === true;
+        if (isPlaying && !isActive) {
+            addStatModifier(character, moveSpeedStat, {
+                source: boostSource,
+                percent: 0.5,
+            });
+            character.set(BoostTrait, { active: true });
+        } else if (isOver && isActive) {
+            removeStatModifiers(character, boostSource);
+            character.remove(BoostTrait);
+        }
+    }
+}
+```
+
+## Stats the engine reads
+
+The engine reads the following stats itself, so a buff, an item or an upgrade on one of them changes the game with no system of the game's own:
+
+| Stat                                                            | Name in code                   | What it sets                                                                                                          | Declared by                                                             |
+| --------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `moveSpeed`                                                     | `moveSpeedStat`                | A character's walking speed, `MovementTrait.speed`, each step                                                         | `declareMoveSpeed(character)`, from its own speed, or an ability's slow |
+| `maxHealth`                                                     | `maxHealthStat`                | The cap of the entity's [health](/engine/behaviours/health/#max-health-is-a-stat)                                     | `<Health>` and `<CharacterSpawn>`                                       |
+| `healthRegen`                                                   | `"healthRegen"`                | Health the entity regains each second, in place of `registerHealth`'s `regen`                                         | The game, with `<Stats>` or `declareStats`                              |
+| `max<Name>`, such as `maxMana`                                  | `nameMaxResourceStat(mana)`    | The cap of a [resource](/engine/behaviours/resources/#the-maximum-is-a-stat)                                          | Giving it the resource                                                  |
+| `<name>Regen`, such as `manaRegen`                              | `"manaRegen"`                  | What a resource regains each second, in place of its `regen`                                                          | The game                                                                |
+| `critChance`, `critDamage`                                      | `"critChance"`, `"critDamage"` | An [ability](/engine/behaviours/abilities/#damage)'s chance to crit, 0.05 unset, and the crit's multiplier, 1.5 unset | The game                                                                |
+| The stat an ability's `damage.stat` names, such as `spellPower` | The name the ability gives     | The ability's damage, as a percentage                                                                                 | The game                                                                |
+| The stats a weapon's `stats` names, such as `damage`            | The name the weapon gives      | The weapon's [numbers](/engine/behaviours/weapon/#numbers-from-the-shooters-stats)                                    | The game, from a base of zero                                           |
+
+A modifier on a stat the entity has not declared starts it at a base of 0. Declare `moveSpeed` before a speed buff, or the buff stops the character: `declareMoveSpeed(character)`, then `addStatModifier(character, moveSpeedStat, { source: "boots", percent: 0.2 })` makes her 20% faster until `removeStatModifiers(character, "boots")`.
+
+## Reading them while it runs
+
+`dumpState` lists each entity's stats under `stats`: each stat's base and bounds, and its modifiers, a timed one with its seconds left. The devtools inspector shows the same in one Stats card, with the value each stat resolves to, whichever component or system declared the stats. Unreal's `showdebug abilitysystem` and Roblox's Attributes panel show attributes live in the same way.
+
+The card has a slider on each base, which sets it through `setStatBase`, so the modifiers still apply on top. A trait's field that a stat should set, as sled's rider sets its track mover's `sideSpeed` from `side`, takes one call beside the trait. From then on each step, before the move, sets that field to the stat's resolved value on every entity that has both, and the inspector hides the field's own slider, since the next step would overwrite an edit. The game writes no system for the copy. The field must hold a number, since a stat resolves to one: naming a text, boolean or object field is a type error. Health's `maximum` goes through the same call:
+
+```ts
+registerStatField("side", TrackMoverTrait, "sideSpeed");
+```
+
+[The devtools page](/engine/testing/devtools/#stats) says how the card reads and writes them.
+
+## Raising every weapon
+
+A weapon reads a player's stat differently from other code: it lays the stat on its own number rather than taking the stat's value. A card that adds `{ percent: 0.25 }` to her `damage` stat raises a 10-damage rifle to 12.5 and a 40-damage rail to 50, when both name `damage` in their `stats`. Her stat's base and flat modifiers add to the weapon's number, and its percent and more modifiers scale it; its bounds are not read. So a game's gun stats start at a base of zero, or are not declared at all. A stat can raise a weapon's damage, range, shots a second, pellets, spread and pierce, and a projectile's speed. [Weapon](/engine/behaviours/weapon/#numbers-from-the-shooters-stats) has the rules for each number.
+
+A system that lays several lists of modifiers on a number of its own, as a weapon does, sums them with the formula's totals: `clearModifierTotals(totals)` starts a sum, `addModifierTotals(totals, modifiers)` adds each list, and `applyModifierTotals(base, totals)` returns `(base + flat) × (1 + percent) × more`. One `ModifierTotals` record, kept at module scope, serves every step with no garbage.
+
+## Where it runs
+
+Server. A stat has a consequence: it decides how fast, how high, how hard.
+
+The step drops spent modifiers before the behaviours run, so every behaviour in a step reads the same value.
+
+## Saving and replication
+
+A save and a room carry each stat's base and its modifiers, never the value they resolve to. Whoever reads them resolves the value with the same formula.
+
+Where the game's save includes `stats`, the save keeps the player's stats under `engine.stats`:
+
+- The engine reads the character's stats there. It leaves out every modifier with `seconds`, so a reload never makes a buff permanent.
+- The `maxHealth` stat's base is the character's `health.maximum`, which the `character` save keeps.
+- The engine lays the saved stats on her once her spawn has set her up, before her worn items put their modifiers back.
+- A game whose player has no character keeps `readStatsSave(entity)` in its own save's state, and calls `restoreStats(entity, stats)` in its own `restore`.
+
+In a room, the room owns the stats:
+
+- The stream carries each entity's stats under the name `stats`: the bases, the bounds, and the modifiers with their seconds left. Every client receives them, and each one resolves the value locally.
+- A client never counts a modifier down. The room drops it when its seconds run out, and the next delta tells every client.
+- A `<Stats>` on an entity the room streams writes nothing, so a client's scene never replaces the room's bases.
+
+Unreal's Gameplay Ability System replicates each attribute's resolved value, and sends the active effects to the owning client alone in its mixed mode. Its save is the game's own code, which by convention keeps the base values and applies lasting effects again. Roblox Attributes replicate plain values, and a game writes its own DataStore save. Unity and Godot have no built-in stats, so their games replicate a value through a network variable or a synchronizer and save what they choose. Stats sends the bases and modifiers instead, so every client can show a buff's source and its seconds left, and resolves the same value the room does.
+
+## What other engines do
+
+| Engine or game                     | Kinds                                                           | Formula                                                |
+| ---------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
+| Unreal 5 GAS                       | AddBase, MultiplyAdditive, MultiplyCompound, AddFinal, Override | `((Base + AddBase) × MulAdd × MulCompound) + AddFinal` |
+| Unity, the common Kryzarel pattern | Flat, PercentAdd, PercentMult                                   | `(base + Σflat) × (1 + Σpct) × Π(1 + mult)`            |
+| Path of Exile, League of Legends   | flat, increased, more                                           | the same three buckets                                 |
+| Godot, the godot-attributes addon  | add, multiply                                                   | ordered calculators                                    |
+| Roblox, PlayCanvas                 | none built in                                                   | none                                                   |
+
+Stats keeps the three buckets that Unreal 5, Unity's common pattern, Path of Exile and League share, and leaves out Unreal's `Override` and `AddFinal`. It keeps Unreal's split between a permanent base and temporary modifiers. Unlike Unreal, which clamps in two places, it clamps once, when the value is read. The name `more` is Path of Exile's.
+
+An item adds its modifiers when it is equipped and removes them by its source when it comes off:
+
+```tsx
+import { useEffect } from "react";
+import {
+    Entity,
+    Stats,
+    addStatModifier,
+    removeStatModifiers,
+    useEntity,
+} from "@spawnite/engine";
+
+function Slingshot() {
+    const sled = useEntity();
+    useEffect(() => {
+        addStatModifier(sled, "launch", { source: "slingshot", more: 0.04 });
+        return () => removeStatModifiers(sled, "slingshot");
+    }, [sled]);
+    return null;
+}
+
+export function Sled() {
+    return (
+        <Entity>
+            <Stats launch={{ base: 20, min: 0 }} />
+            <Slingshot />
+        </Entity>
+    );
+}
+```