@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,328 @@
+---
+title: Abilities
+description: Spells and strikes a character casts at a target, which the room judges, winds up and releases.
+useCases:
+    - spell casting
+    - ability with a cooldown
+    - projectile spell attack
+    - area damage ability
+    - cast a spell at a target
+    - ability that costs mana
+    - cast animation and wind up
+    - slow or speed up a character
+    - action bar abilities
+    - make an enemy targetable
+sidebar:
+    order: 15
+---
+
+An ability is something a character does from a key or an action-bar slot, such as a spell. Its settings are data that the room and the page share, registered by name. The room judges each cast, so a page cannot cast what its player does not hold, cannot cast past a cooldown, and cannot cast at a target out of range or out of sight.
+
+`abilities()` needs `weapons()`, `cooldowns()`, `resources()` and `characters()` in the same plugins list, since a cast flies as a projectile, waits out a cooldown, spends a resource and is made by a character. A world made without one of them throws as it is made, naming the plugin to add, such as `abilities() needs weapons(): add weapons() to plugins.`
+
+## Register an ability
+
+[`registerAbility(world, name, settings)`](https://wiki.spawnite.com/reference/abilities/registerability/) registers an ability on a world. Call it in a plugin's `setup`, which the world runs as it is made, on the room and on every page, so each holds the same settings. List the plugin in the game's plugins beside `abilities()`, which it requires, and the four plugins `abilities()` requires. The engine's tests make a world from this file and read both abilities back:
+
+```ts title="packages/engine/test/outside/mage.ts"
+import type { World } from "koota";
+import {
+    abilities,
+    AbilityKind,
+    behaviours,
+    characters,
+    cooldowns,
+    definePlugin,
+    defineResource,
+    registerAbility,
+    resources,
+    stats,
+    weapons,
+} from "@spawnite/engine";
+
+export const mana = defineResource("mana", { maximum: 100, regen: 5 });
+
+function registerMageAbilities(world: World) {
+    registerAbility(world, "arcane-bolt", {
+        kind: AbilityKind.Projectile,
+        label: "Arcane Bolt",
+        castSeconds: 0.4,
+        cooldownSeconds: 0,
+        range: 25,
+        damage: { min: 20, max: 26, stat: "spellPower" },
+        projectile: { speed: 14, turnDegrees: 540 },
+    });
+    registerAbility(world, "frost-nova", {
+        kind: AbilityKind.Area,
+        label: "Frost Nova",
+        castSeconds: 0,
+        cooldownSeconds: 12,
+        cost: { [mana]: 25 },
+        radius: 6,
+        damage: { min: 25, max: 30, stat: "spellPower" },
+        slow: { percent: 50, seconds: 3 },
+    });
+}
+
+//  The world calls setup as it is made, on the room and on every page, so
+//  each holds the same settings.
+export const mageKit = definePlugin({
+    name: "mage-kit",
+    requires: [abilities],
+    resources: [mana],
+    setup: registerMageAbilities,
+});
+
+/** The plugins a game lists in src/game.ts: abilities() and the plugins
+ *  it requires, and the kit. */
+export const magePlugins = [
+    characters(),
+    stats(),
+    cooldowns(),
+    resources(),
+    behaviours(),
+    weapons(),
+    abilities(),
+    mageKit,
+];
+```
+
+An ability that plays a clip names it in `clip` in place of `castSeconds`, and the clip's `release` mark is its cast time, as [Casting](#casting) says. Register the clip with `registerClip` at module scope, before the plugin's `setup` runs.
+
+`cost` names what the cast spends, by the keys `defineResource` returns for each [resource](/engine/behaviours/resources/): `{ [mana]: 25 }`, or `{ [mana]: 20, [rage]: 30 }` for two. Left out, the ability is free. The cast holds the cost back under `castReservation`, so a game's own action on the same character, holding a cost under its own key, never spends the cast's or has its own spent by it.
+
+`approach` and `faceTarget` set how the caster moves for a cast at a target. Each is `true` when left out:
+
+- `approach: true` walks her toward a target past `range` and casts once she is in range. `approach: false` refuses the cast with "Out of range".
+- `faceTarget: true` turns her to face the target as the cast starts. `faceTarget: false` casts facing wherever she stands.
+
+`kind` says what the release does:
+
+- `AbilityKind.Projectile` launches a projectile at the target, which turns toward the target at `turnDegrees` a second. It passes through a friendly and through a hostile that is down, to what stands behind.
+- `AbilityKind.Area` strikes every hostile target within `radius` of the caster that she has line of sight to. It needs no target.
+- `AbilityKind.Chain` strikes the target, then jumps to the nearest hostile target within `jumpRadius` that it has not struck, `jumps` times. Each jump deals `falloff` times the damage of the one before it. It never strikes one target twice.
+
+## Give a character abilities
+
+A character casts only the abilities its `AbilitiesTrait` trait holds. Each grant has a source:
+
+- `<CharacterSpawn>`'s `abilities` grants abilities for as long as she is in the world, under the source `"player"`: `<CharacterSpawn abilities={["frost-nova"]} resources={[mana]} />`. In a room it holds for every player's character.
+- [`grantAbilities(entity, source, names)`](https://wiki.spawnite.com/reference/abilities/grantabilities/) grants abilities under a source, and [`revokeAbilities(entity, source)`](https://wiki.spawnite.com/reference/abilities/revokeabilities/) takes off that source's abilities and no other.
+- An item's `equip.abilities` grants abilities while the item is worn: `equip: { slot: EquipmentSlot.MainHand, abilities: ["arcane-bolt"] }`. Taking the item off takes those abilities off, and cancels a cast of one of them.
+
+## Targets
+
+An ability strikes an entity with the `TargetableTrait` trait, whose `faction` is `Faction.Hostile`, the default. A target frame names it with `useDisplayName`, as [Entity](/engine/entities/entity/#display-name) says. The caster's chosen target is the `TargetTrait` trait on the caster, which [`<Targeting>`](/engine/behaviours/targeting/) writes, and the cast press carries it to the room.
+
+`<Health>` alone does not make an entity a target, and neither does an [NPC](/engine/entities/npc/)'s `faction`. A game gives its enemies the trait with a behaviour of its own, as [Behaviours](/engine/entities/entity/#behaviours) describes, and puts it beside `<Health>`. A system that spawns an enemy adds `TargetableTrait` among its traits, as [the spawner on the Health page](/engine/behaviours/health/#spawn-one-at-runtime) does. The room's tests mount this dummy in a room's scene, check that a player's page holds it as a hostile target and that the room lets a cast target it, and check that an entity with Health alone is no target:
+
+```tsx title="packages/room/test/outside/TrainingDummy.tsx"
+import {
+    defineBehaviour,
+    Entity,
+    Faction,
+    Health,
+    RunContext,
+    TargetableTrait,
+    useBehaviour,
+    type EntityProps,
+} from "@spawnite/engine";
+
+const TargetableBehaviour = defineBehaviour({
+    name: "targetable",
+    trait: TargetableTrait,
+    runsOn: RunContext.Server,
+    description: "An entity abilities and Targeting can pick.",
+});
+
+interface TargetableProps {
+    /** Whose side it is on: abilities strike a hostile one. */
+    faction?: Faction | `${Faction}`;
+}
+
+export function Targetable({ faction = Faction.Hostile }: TargetableProps) {
+    useBehaviour(TargetableBehaviour, { faction: faction as Faction });
+    return null;
+}
+
+export function TrainingDummy({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity position={position}>
+            <Health maximum={60} />
+            <Targetable />
+            <mesh>
+                <cylinderGeometry args={[0.4, 0.4, 1.8]} />
+                <meshStandardMaterial color="#b08850" />
+            </mesh>
+        </Entity>
+    );
+}
+```
+
+## Cast from a key or a slot
+
+[`<AbilityBar />`](/engine/ui/action-bar/#the-players-abilities-on-the-bar) puts every ability the player holds on a slot and a key, and is the bar most games mount. Under it, [`useCast()`](https://wiki.spawnite.com/reference/abilities/usecast/) gives a page `cast(name)`, `refusal` and `refusalText`. `cast` sends the cast press with the player's target. `refusal` holds why the rules refused her last cast, until she casts again, and `refusalText` is the line to show for it, such as "Out of range" or "Not enough mana", or "Try again", `castDroppedText`, for a press the room dropped:
+
+```tsx
+import { useCast } from "@spawnite/engine";
+
+export function BoltButton() {
+    const { cast, refusalText } = useCast();
+    return (
+        <>
+            <button onClick={() => cast("arcane-bolt")}>Arcane Bolt</button>
+            {refusalText && <p>{refusalText}</p>}
+        </>
+    );
+}
+```
+
+[`describeCastRefusal(world, refused)`](https://wiki.spawnite.com/reference/abilities/describecastrefusal/) writes the same line from a `CastRefusedEvent` event, and `castRefusalText` holds the line for each reason. Each reason is one of the engine's shared [`Refusal`](https://wiki.spawnite.com/reference/replication/refusal/) codes, such as `Refusal.CoolingDown` and `Refusal.OutOfRange`, which the cast press declares as its refusals. A game's own press declares the codes it refuses with too, with its own beside them, as [Build a predicted mechanic](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-2-declare-the-action) shows.
+
+### What her page shows on the press
+
+The cast is a [press](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-2-declare-the-action): her page runs the cast on the tick she presses, and in a room the room runs it on the same tick. Her page shows the following on the frame of the press, with no wait for the room:
+
+- The cost comes off her resource bar, held back as `reserved`.
+- The cast starts: her `CastingTrait`, which the bar's rim, the clip, the charge and the hand's turn draw from.
+- A refusal shows its line, from the press's result in [`useLatestPressResult(castPress)`](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-2-declare-the-action).
+- At the release, the cost is spent and the global cooldown and the ability's own sweep on the bar.
+
+The room alone decides what the release does: the projectile, the strike, the damage, the slow and every event. Her page draws them as the room streams them, a round trip after the release. The room's answer settles the press: where it agrees, nothing changes, and where it refused the cast or a rule of the room changed her state, her page takes the room's word and replays her steps from it, as it does for her movement. A cast at a target out of range, which walks her there first, starts when the room starts it, as [Walk into range and turn](#walk-into-range-and-turn) says. The clip plays once per cast, as the cast starts on her character, and a refusal of that press stops it.
+
+A player may press casts 20 times a second, past a burst of two, and a press past that is refused with "Try again". `abilities({ castsPerSecond })` changes it for every ability: `abilities({ castsPerSecond: 30 })`. The rate is a flood guard, not a game rule: an ability's cooldown, the global cooldown and its cost are what limit casts in play. Set it to at least twice the fastest a player can honestly press, and leave it alone otherwise. The room and her page read it from the one plugins list both compose, and the room refuses a page whose list differs.
+
+To make an ability wait for the room, register it with `predicted: false`. Her page then takes its press and starts nothing of it, the room runs it on the tick she pressed, and her page shows the cast, its cost and its cooldowns as the room's word arrives, a round trip after the press. A cast at a target out of range still walks her toward it at once. Unreal's Gameplay Ability System gives the same choice as an ability's net execution policy: local predicted, the default here, or server only. A game played alone runs every cast at once either way. A page whose room predicts no cast, a room of an older build, sends every cast as a plain message too.
+
+## Casting
+
+`cast` sends the `abilities.cast` press, `castPress`, with the ability's name, the target, an `entity({ optional: true })` field that is null for an area ability, and a request id. [`createCastPress(world, character, name, request)`](https://wiki.spawnite.com/reference/abilities/createcastpress/) writes the same press for a game's own sender, which sends its payload with `sendPress(world, castPress, press.payload)` where [`castsAsPress(world)`](https://wiki.spawnite.com/reference/abilities/castsaspress/) is true. Where it is false, against a room of an older build that predicts no cast, the cast goes to the room as a plain message, the target as the key the room files it under, and `useCast` does both, with the walk into range her page makes for such a cast, so a game's own button calls `useCast`'s `cast` unless it needs more. The cast starts when all of the following hold:
+
+- The caster holds the ability and is neither downed nor already casting.
+- The ability's own cooldown and the global cooldown have run out.
+- The caster has enough of each resource in `cost`.
+- For a projectile or a chain, the target is alive, hostile, within `range`, and in line of sight.
+
+Otherwise the press is refused with the reason, and with the resource a cost fell short of as its `detail`. Where the world decides outcomes, on the room and in a game played alone, the refusal also adds `CastRefusedEvent { request, reason, resource }` to the caster, which every page and the devtools hear. A target past `range` is not refused at once: the cast waits while she walks into range, as [Walk into range and turn](#walk-into-range-and-turn) says.
+
+A started cast is the `CastingTrait` trait on the caster: the ability, the target's key, the seconds of wind-up left and the request id. The cast holds its cost back at its start, in each resource's `reserved`. It then runs as follows:
+
+1. **The wind-up.** A rooted cast ends the walk she is on as it starts, so nothing steers her and she runs down to a stand at her own deceleration. A cast is rooted unless the ability sets `rooted: false`.
+2. **The cancel.** The cast is cancelled when the caster goes down, her health reaches 0, she disconnects, or she loses the ability, and, on a rooted cast, when the player presses a move or jump key or sets off on a walk. The cost comes back and no cooldown starts. Her page cancels on her own key or walk on the same tick as the room; it learns that she went down from the room, and a press after that is refused on her page as on the room.
+3. **The release.** For a projectile or a chain, the target is checked again. A target that died or went out of sight fizzles the cast, which returns the cost and starts no cooldown. Otherwise the cost is spent, the global cooldown starts for 1 second, the ability's own starts when `cooldownSeconds` is above 0, and, on the room, the ability does what `kind` says.
+
+An ability's own cooldown runs under the key [`nameAbilityCooldown(name)`](https://wiki.spawnite.com/reference/abilities/nameabilitycooldown/), `ability:` and its name, and the global cooldown under `globalCooldown`. Read either with `isCoolingDown(caster, nameAbilityCooldown("fireball"))` or `readCooldown` in a system, and `useCooldown(caster, nameAbilityCooldown("fireball"))` in a view. `defineCooldown("fireball")` names a game's own key, which no ability starts.
+
+The cast time has one source. An ability with a `clip` releases at the clip's `release` mark, which `registerClip` names in seconds, so the spell leaves on the frame the hands let it go; `castSeconds` beside a clip throws, as does a clip with no `release` mark. An ability with no clip gives `castSeconds`, and `castSeconds: 0` is instant: the cast releases in the step it starts, and a move key does not cancel it. `spawnite play timeline` shows a cast frame by frame with the second under each, which is how a mark is read; [the player page](/engine/entities/player/#one-shot-clips) says how a look hears the clip's other marks.
+
+A projectile an ability launches carries `AbilityProjectileTrait { ability }`, which every page is streamed. When the projectile ends, on its target, on cover or at its range, the room emits `SpellLandedEvent { ability, at, hit }` on the caster: where an impact effect plays. An area ability emits one on the caster as it releases, `at` her feet and `hit` null. Two of her bolts ending in one step are two events, as two hits are two `DamagedEvent`s, and `useEvent` hears each once, as `SpellLook` does. The room emits `SpellStruckEvent { ability, at, from }` on each target an ability strikes: `from` is the caster for a projectile's hit, an area's strikes and a chain's first, and the link before it for each jump of a chain, so a page draws a beam along the chain.
+
+## Walk into range and turn
+
+A cast at a target past `range` walks the caster into range first, as Diablo's click to attack does, unless the ability sets `approach: false`:
+
+1. `cast` walks her toward the target along the navmesh, with the same walk that [click to walk](/engine/entities/player/) sends. In a room, her page walks her and predicts the walk, and the room runs the walk her page sends.
+2. The cast waits as the `PendingCastTrait` trait on the caster, and holds nothing back.
+3. She stops once the target is within 0.9 of `range`, `approachShare`, so a target that steps back as she stops is still in range.
+4. The room starts the cast once she is in range. A rooted cast waits for her to stop first. Her page shows the cast, its cost and its cooldowns as the room's word arrives, a round trip after she stops.
+
+A move or jump key drops the pending cast at no cost, as does a click to walk elsewhere, or the target dying or leaving. A target that moves while she walks is walked to again once she reaches where it stood. When she stands out of range for `pendingStandSeconds`, 0.5 s, because the navmesh reaches no nearer, the room refuses the cast with "Out of range".
+
+As a cast at a target starts, the caster turns to face the target over `castTurnSeconds`, 0.15 s, while the wind-up runs, unless the ability sets `faceTarget: false`.
+
+As the cast releases, the hand that holds her item turns so the item's tip points at the target, over whatever the clip did with her wrist: in over the last of the wind-up, 1 at the release and held there as the spell leaves, and back to the clip after. Each ability names its own window: `aimHand: { inSeconds: 0.3, holdSeconds: 0.2, outSeconds: 0.2 }`, any of the three, the rest filled from the engine's `characterMotion.castAim`, 0.15 s each, which `aimHand: true` or nothing takes whole. The turn starts from the press on her own page, which starts the cast. A projectile or a chain turns the hand unless the ability sets `aimHand: false`; an area, with no target, never does. The item says which way its tip points with `HeldItem`'s `forward`, `[0, 0, -1]` unless the item says otherwise, as [the player page](/engine/entities/player/#what-she-holds) describes. Unreal aims a weapon with an aim offset or a two-bone IK node driven by the target, Unity with an aim constraint on the hand bone, Godot with a look-at modifier on a bone; each layers the turn over the clip and weights it in and out, as this does, because a clip is authored with no target.
+
+Diablo walks the character into range and then attacks. Lost Ark and Genshin Impact turn the character toward the target on the press. World of Warcraft refuses a cast unless the player faces the target and is in range. Roblox, Unity, Unreal, Godot, PlayCanvas and Phaser leave both to each game. This engine walks and turns, because a player on a phone presses one button and expects the attack to happen.
+
+## How a spell looks
+
+The room owns an ability's numbers and the page owns its look. [`<SpellLook>`](https://wiki.spawnite.com/reference/abilities/spelllook/) draws one ability, for every caster and every projectile of it, the player's and each other player's alike. The three effects below come from `spawnite add asset`, which copies each into the game's `src/particles/`:
+
+```tsx
+// src/components/MageLooks.tsx
+import { Particles, SpellLook } from "@spawnite/engine";
+import effectBoltBurst from "../particles/bolt-burst.json";
+import effectBoltRunes from "../particles/bolt-runes.json";
+import effectBoltTrail from "../particles/bolt-trail.json";
+
+export function MageLooks() {
+    return (
+        <>
+            <Particles
+                effects={[effectBoltBurst, effectBoltRunes, effectBoltTrail]}
+            />
+            <SpellLook
+                ability="arcane-bolt"
+                color="#9ecbff"
+                charge={effectBoltRunes}
+                chargePosition={[0, 0.8, 0]}
+                projectile={[effectBoltTrail, effectBoltRunes]}
+                impact={effectBoltBurst}
+            />
+        </>
+    );
+}
+```
+
+It plays each effect at one moment of the spell:
+
+- `charge` plays in the caster's right hand while she winds the cast up, on her own page from the press, and stops at its release or its cancel. `chargePosition` moves it from the hand in the hand's axes, as [`HeldItem`](https://wiki.spawnite.com/reference/player/helditem/)'s `position` does, to a staff's tip, and `chargeRotation` turns it as `HeldItem`'s `rotation` does, so a swirl turns about the staff.
+- `projectile` rides each projectile of the ability, and `model` names a registered model drawn there.
+- `impact` plays once where each projectile ends, on a hit or a fizzle, and at the caster's feet as an area ability releases.
+- `strike` plays once on each target the ability strikes: a projectile's hit, each within an area, and each link of a chain.
+- `area` mounts its parts at the caster's feet as an area ability releases, for `areaSeconds`, 2 by default: a ring that races out, a rune circle, shards. Each part ages from its mount.
+- `beam` draws from where each strike came from to the target, for `beamSeconds`, 0.35 by default. It is a function of the two ends, both at the feet, as Roblox's `Beam` takes two attachments: `beam={({ from, to }) => <SpellBeam from={from} to={to} color="#c9a7ff" />}`. A chain draws one beam per jump, from the link before.
+
+Each takes one effect or a list. `charge` and `projectile` also take an element, such as a glowing mesh of the game's own, drawn in the hand or riding the projectile beside the effects: `projectile={[effectBoltTrail, <BoltCore />]}`. An element that animates reads where it is in its own `useFrame`. `color` tints the effects. The scene's [`Particles`](/engine/graphics/particles/) must hold every effect, from the asset library, the [three.quarks editor](https://quarks.art/create) or code. Past that, a game writes its own view that reads the `CastingTrait` trait, the entities with `AbilityProjectileTrait`, and the `SpellLandedEvent` and `SpellStruckEvent` events, as `SpellLook` does.
+
+The engine ships the parts a spell is built from, each a glowing mesh with props for its numbers and its colour, and a game's own element stands in any part's place:
+
+- [`SpellRing`](https://wiki.spawnite.com/reference/abilities/spellring/) races out along the ground to `radius` over `seconds`, for `area`: a nova's edge.
+- [`SpellRunes`](https://wiki.spawnite.com/reference/abilities/spellrunes/) is a rune circle left glowing on the ground, opening in a blink and fading over `seconds`, for `area`.
+- [`SpellShards`](https://wiki.spawnite.com/reference/abilities/spellshards/) stand up out of the ground in a ring and sink back, for `area`.
+- [`SpellBeam`](https://wiki.spawnite.com/reference/abilities/spellbeam/) arcs from `from` to `to`, both lifted to a body's middle, and fades, for `beam`.
+- [`SpellSpear`](https://wiki.spawnite.com/reference/abilities/spellspear/) flies point first with crystals turning round its shaft, for `projectile`: it turns to face the way its group has moved.
+- [`SpellSwirl`](https://wiki.spawnite.com/reference/abilities/spellswirl/) gathers crystals in from wide to tight over a cast's `seconds`, for `charge` at a staff's tip.
+- [`createGlowMaterial(color, intensity, opacity)`](https://wiki.spawnite.com/reference/abilities/createglowmaterial/) is the lit material each draws with, emitted above 1 so a scene's bloom takes it.
+
+The mmorpg's mage composes its three spells from these under `SpellLook`, as its kit page, `wiki/kit/mage.md` in the mmorpg's folder of [spawnite/examples](https://github.com/spawnite/examples), says. Unreal ships Niagara templates for the same reason: a spell's look is assembled from a few moving parts far more often than drawn from nothing.
+
+Unreal keeps an ability's look in its Gameplay Cues, apart from the effect that changes the numbers. Unity, Godot, Roblox, PlayCanvas and Phaser leave it to each game. This engine takes Unreal's split, as one component with a prop for each moment, so an agent writes a finished spell in one element.
+
+## Damage
+
+Each strike rolls its damage in these steps:
+
+1. A whole number from `damage.min` to `damage.max`, both included, on the world's seeded stream, so a replay rolls the same.
+2. Scaled by the caster's stat that `damage.stat` names, as a percentage: 20 `spellPower` makes it 1.2 times.
+3. A crit against the caster's `critChance` stat, 0.05 by default, multiplies it by her `critDamage` stat, 1.5 by default.
+
+The strike calls `dealDamage` with the ability's name as the hit's `weapon` and `{ crit }` as its data. [`rollAbilityDamage(step, caster, damage)`](https://wiki.spawnite.com/reference/abilities/rollabilitydamage/) rolls one strike for a game's own system, on the stream of the world whose step it takes. Damage is the room's, so it takes the room's step, and her page never moves the world's random stream.
+
+A `slow` leaves a timed modifier on the victim's `moveSpeed` stat, which sets `MovementTrait.speed`. The first slow declares the stat from the victim's own speed, so the slow runs out back to it.
+
+A game's own ability system uses the calls the engine's cast uses. `hasLineOfSight(world, looker, target)` says whether cover stands between two characters. `strikeTarget(step, { caster, victim, name, ability })` deals one strike: the roll, the damage, the ability's slow and the `SpellStruckEvent` event. `slowCharacter(step, entity, { ability, percent, seconds })` leaves the slow alone. Each of these outcomes takes the room's step first, as `dealDamage` and `launchProjectile` do, so a predicted system calls them inside `if (step.authoritative)`, and a system on the room alone calls them as they are. A game's own outcome takes `authority: Authority` first the same way, and code outside a step passes `requireAuthority(world)`. [Where a system runs](/engine/structure/systems/#where-a-system-runs) says which step is the room's.
+
+## Change a character's speed
+
+A slow works through the `moveSpeed` stat, which sets `MovementTrait.speed` each step once a slow has declared it. From then on, a write to `MovementTrait.speed` is overwritten. To change the character's own speed, set the stat's base instead, and the modifiers stay on top of it:
+
+```ts
+import { setStatBase } from "@spawnite/engine";
+
+setStatBase(entity, "moveSpeed", 7);
+```
+
+`moveSpeedStat` names the stat.
+
+## Resources
+
+A cast spends [resources](/engine/behaviours/resources/), such as mana or rage, as damage spends health. The resources page says how to register one, give it to a character and show it.
+
+## Debug a cast
+
+The devtools' Inspector has an [Abilities section](/engine/testing/devtools/#abilities) for a caster: each ability's range, cost, cooldown left and cast state, the target's reach and sight line, the last refusal, and a switch that draws the range rings and a line to the target. [`readAbilityInspection(world, caster)`](https://wiki.spawnite.com/reference/abilities/readabilityinspection/) reads the same numbers, and `spawnite play eval views` reads them under `"abilities"`.
+
+## What the other engines do
+
+Unreal's Gameplay Ability System keeps the ability, its cost, its cooldown, its target data and its cues apart, all replicated. Roblox, Unity, Godot and PlayCanvas ship no ability system. This engine takes Unreal's separation, and writes an ability as settings rather than a subclass, so an agent writes one correctly on its first try.

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

@@ -0,0 +1,37 @@
+---
+title: Bob
+description: Rises and falls an entity in place.
+useCases:
+    - floating up and down
+    - bobbing coin
+    - hovering pickup
+    - rise and fall animation
+    - idle bobbing effect
+    - hovering entity
+sidebar:
+    order: 2
+---
+
+Bob rises an entity above where it rests and back down, once every `seconds`. It applies as a difference from its last offset, so it rides on whatever else moves the entity, a kinematic body's next pose included.
+
+Its props are in [`BobProps`](https://wiki.spawnite.com/reference/entity/bobprops/).
+
+## On a body
+
+On an entity with a kinematic body, Bob raises 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 raises it, a kinematic body with it, and each page draws the pose the stream brings. On an entity only a page holds, that page raises it.
+
+```tsx
+import { Entity, Bob, type EntityProps } from "@spawnite/engine";
+
+export function BobbingCoin({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="coin" position={position}>
+            <Bob height={0.2} />
+        </Entity>
+    );
+}
+```

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

@@ -0,0 +1,158 @@
+---
+title: Chase
+description: Moves an entity toward the nearest player's character.
+useCases:
+    - enemy that chases the player
+    - monster follows the character
+    - zombie that pursues
+    - crowd of attacking monsters
+    - stop enemies stacking
+    - enemy ignores downed players
+    - chaser stops at attack reach
+    - monster catches the player
+    - lose when caught
+    - damage when an enemy reaches the player
+sidebar:
+    order: 6
+---
+
+Chase moves an entity toward the nearest controllable entity, one 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 [`ChaseProps`](https://wiki.spawnite.com/reference/entity/chaseprops/).
+
+Chase moves toward the nearest player's character, level with the ground, and stops within `reach`. It moves the entity; it does not turn it, so a model that should face the way it moves needs its own facing. The physics cuts the chaser's capsule to the body fields, and a field changed later reaches it from the next step. Its `controller` prop sets the character controller's settings it walks by, a partial `CharacterControllerTrait`, such as `controller={{ stepHeight: 0.3 }}`. A Chase marks its entity a character, which the characters' movement moves with `moveCharacter` by the velocity the chase sets, in the physics phase of the same tick.
+
+## How it moves
+
+A chaser moves along the world's navmesh, the floor a walker can reach with the rocks, the trees and the crates cut out of it. Each step moves it from where it stood toward where the chase puts it, round the edge of anything the navmesh leaves out, and stands its feet on the ground there, or on a rock or a fixed collider lower than its step, whose top the navmesh keeps as floor. It runs no walk: no sweep of its capsule and no floor probe, so a crowd of monsters costs the room a fraction of what the same number of players cost. Its capsule stays in the physics world, where the players' walks meet it as the collision layers below say. Unity's NavMeshAgent and Unreal's NavWalking mode move a character the same way; Godot's navigation agent only plans, and the game moves the body.
+
+The navmesh holds the ground, the map's scatter, every fixed [collider](/engine/entities/entity/#bodies-and-colliders) an Entity in the World gives, and every kinematic one at rest. Every World bakes it: on a page, in a room and in the CLI's headless play alike. A chaser on it follows these rules:
+
+- It stops at a crate, a platform or any other body a fixed collider gives, as it stops at a rock, and slides along its side. A dynamic collider moves, so the navmesh leaves it out, and a chaser passes through it, as it does a fixed one whose `collisionMask` leaves out `characters.collisionLayers.npcs`. A kinematic collider, such as a drawbridge, is left out while it moves and baked in once it has stood still for half a second, as Unity's "carve only stationary" does; its next move leaves it out again.
+- It never climbs onto anything taller than its step, falls, or jumps.
+- It reads its controller's `stepHeight` only to find a rock's top under it, and no `maxSlopeRadians`: the navmesh was baked for a player's character, and it stands where she can stand.
+
+The World bakes the navmesh again when a fixed collider joins or leaves it, moves, turns, or changes its shape, size, kind or layers, and when a kinematic one comes to rest or starts moving, so a crate that mounts late, or that a page learns of from the room, is cut out too. A bake of the meadow takes about 85 ms, which a room spends standing still. A page bakes a crate where the room streamed it, to the centimetre, and the room bakes it at that same precision, so both find the same paths. A room that steps a spawn function rather than a scene bakes once, as it starts, and leaves out a fixed collider spawned after that.
+
+`walks` asks for the walk a player's walker runs instead. A chaser that walks climbs and slides by its controller's `stepHeight` and `maxSlopeRadians`, falls, and meets a moving collider as a player does, at the cost of a player's walk each step it moves:
+
+```tsx
+import { Chase, Entity, type EntityProps } from "@spawnite/engine";
+
+export function Climber({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="yeti" position={position}>
+            <Chase speed={4} walks />
+        </Entity>
+    );
+}
+```
+
+A chaser also walks where the world has no navmesh, and on a step where no part of the navmesh lies within a metre of its feet, such as on top of a rock taller than its step.
+
+A chaser walks through the players by default: its `collisionMask`, `chaserCollisionMask`, leaves out `characters.collisionLayers.players`, so a player walks through a chaser and a chaser through a player, in the room and on every client alike. A crowd of monsters never pins a player where she stands. A game that wants its monsters to block the players gives them a mask that leaves out the other characters alone, and a chaser on the navmesh then keeps out of the players as well:
+
+```tsx
+import { Chase, characters, Entity, type EntityProps } from "@spawnite/engine";
+
+const blockingChaserMask = { except: [characters.collisionLayers.npcs] };
+
+export function Guard({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="yeti" position={position}>
+            <Chase speed={4} collisionMask={blockingChaserMask} />
+        </Entity>
+    );
+}
+```
+
+A chaser ignores other chasers by default too: its mask leaves out `characters.collisionLayers.npcs`, so a chaser that walks never tests another walker's capsule and a crowd costs the room no more than the same chasers spread apart. Chase keeps the crowd apart itself, moving any two chasers closer than their two radii to that distance each step. Two colliders meet only when each one's mask holds the other's layer: a monster that must block a doorway meets `npcs` again, and it stops the characters whose mask holds `npcs` too, not a chaser in the default. [The player page](/engine/entities/player/#collision-layers) lists the layers.
+
+## Which characters it chases
+
+A chaser runs at the nearest character, measured along the ground, so a character who jumps or stands on a rock is no farther away. It runs at every character unless the scene gives a test. `filterChaseTargets(world, accepts)` sets one test for every chaser in the world: a chaser then runs at the nearest character that `accepts` passes, and skips the rest. A chaser with no character that passes stands still, as it does on a world with no character. The function returns a disposer that takes the test away. The world holds one test at a time, and a disposer takes away only the test that it set.
+
+A game whose monsters leave a downed player alone gives the test from a component in its scene. `DownedTrait` is the engine's, which a character carries while she is down, as [Health](/engine/behaviours/health/#when-a-character-runs-out-of-health) says. The engine's tests mount this component and run a chaser past a downed character:
+
+```tsx title="packages/engine/test/outside/IgnoreDowned.tsx"
+import { useWorld } from "koota/react";
+import { useEffect } from "react";
+import { DownedTrait, filterChaseTargets } from "@spawnite/engine";
+
+export function IgnoreDowned() {
+    const world = useWorld();
+    useEffect(
+        () =>
+            filterChaseTargets(
+                world,
+                (character) => !character.has(DownedTrait),
+            ),
+        [world],
+    );
+    return null;
+}
+```
+
+## When it reaches a character
+
+The step marks `reached` with the character a chaser has within `reach`, or `null`, and emits an event on the step it changes:
+
+- `ChaseReachedEvent`, on the chaser, on the step it comes within `reach` of a character, with her as `target`.
+- `ChaseExitedEvent`, on the chaser, on the step it no longer has her in reach, with her as `target`. She moved off, went down or left the room, the world's `filterChaseTargets` test stopped accepting her, or the chaser went down.
+
+Each is emitted once per crossing: a chaser that stays within reach of her emits no second `ChaseReachedEvent`. Once she leaves, it reaches the next character within reach, on the same step. A downed character is never reached, and a downed chaser reaches nobody. A system reads either event with `readEvents` for a one-off outcome, such as a bite, a lost round or a sound, and a view hears it with `useEvent`. A rule that lasts while she stays caught, such as health drained each second, reads `reached` on each step.
+
+The engine's tests run this bite against a real room: a game's own rule reads `ChaseReachedEvent` and damages the character it names.
+
+```ts title="packages/room/test/outside/bite.ts"
+import type { World } from "koota";
+import {
+    ChaseReachedEvent,
+    dealDamage,
+    definePlugin,
+    readEvents,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  A monster's bite, built as a creator's plugin is, from the engine's
+//  public entry alone: each time a chaser comes within its reach of a
+//  player's character, the room deals her 10 damage. The chaser must leave
+//  her reach, or she must, before it bites again.
+
+/** Health a bite takes off. */
+export const biteDamage = 10;
+export const bite = definePlugin({
+    name: "outside-bite",
+    systems: {
+        rules: {
+            //  No `runsOn`, so it runs on the room alone, which adds the
+            //  event, and in a game played alone.
+            bite: (_world: World, step: AuthoritativeStep) => {
+                for (const { record } of readEvents(step, ChaseReachedEvent))
+                    if (record.target)
+                        dealDamage(step, record.target, {
+                            amount: biteDamage,
+                        });
+            },
+        },
+    },
+});
+```
+
+Godot's `NavigationAgent3D.target_reached`, Unreal's `OnMoveCompleted` and Roblox's `MoveToFinished` signal arrival from the mover too. Unity, PlayCanvas and Phaser leave it to a trigger or an overlap callback. For a mover that is not a chaser, a [Trigger](/engine/behaviours/trigger/) on it gives the same events in the room, as `TriggerEnteredEvent` and `TriggerExitedEvent`.
+
+## Where it runs
+
+Server. Chase has a consequence: it moves the entity toward a player's character, and it decides whom the entity reached. In a room, the room emits `ChaseReachedEvent` and `ChaseExitedEvent` and streams them with `reached` to every page, where `useEvent` hears them. A page never emits its own.
+
+```tsx
+import { Entity, Chase, type EntityProps } from "@spawnite/engine";
+
+export function Yeti({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="yeti" position={position}>
+            <Chase speed={4} />
+        </Entity>
+    );
+}
+```

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

@@ -0,0 +1,83 @@
+---
+title: Cooldowns
+description: One cooldown for everything that has one, kept on the entity by key, so a skill, a buff, a ground effect and an item share one system and can share one cooldown.
+useCases:
+    - ability cooldown
+    - skill recharge timer
+    - shared cooldown
+    - potion cooldown
+    - item use limit
+    - buff duration timer
+    - show a cooldown on a button
+    - global cooldown
+sidebar:
+    order: 14
+---
+
+An entity keeps its cooldowns in the `CooldownsTrait` trait, by key. Each cooldown holds `seconds`, how long it runs, and `left`, how long it has left. The step counts every cooldown down and removes each as it ends.
+
+Use the following four functions:
+
+- `defineCooldown(name)` defines a key, once, at module scope.
+- `startCooldown(entity, { key, seconds })` starts one.
+- `isCoolingDown(entity, key)` says whether one runs.
+- `readCooldown(entity, key)` returns it, or undefined.
+
+[`CooldownStart`](https://wiki.spawnite.com/reference/cooldowns/cooldownstart/) and [`Cooldown`](https://wiki.spawnite.com/reference/cooldowns/cooldown/) hold the fields.
+
+## Choosing a key
+
+`defineCooldown(name)` returns the key a cooldown runs under, a `CooldownKey`. A name is letters and digits starting with a lower case letter, such as `"bolt"`. Whatever starts the same key on an entity shares that cooldown, and one name defined in two places is one key:
+
+- **One thing alone.** A skill defines its own key, such as `defineCooldown("bolt")`.
+- **A group.** Three potions each start `defineCooldown("drink")`, so drinking one holds all three.
+- **A global cooldown.** Every ability starts `globalCooldown` for a second beside its own key, and checks both before it casts.
+- **A buff or a ground effect.** The system that lays a fire patch starts `defineCooldown("firePatch")` on the caster.
+- **An item.** The [inventory](/engine/behaviours/inventory/#using-an-item) starts `item:` and the item's name, or the item's `cooldownGroup`.
+
+The engine keeps the keys with a colon, so a game's key never shares a cooldown with the engine's by accident. An ability runs its own under `ability:` and its name, which `nameAbilityCooldown("bolt")` returns, so a game's `"bolt"` and an ability named `"bolt"` stay apart. `defineCooldown` refuses `"global"`: import `globalCooldown` to start or read the abilities' shared cooldown. A plain string is not a key: the type refuses it.
+
+A cooldown started under a key that already runs keeps the longer of the two, so a short cooldown never cuts a long one.
+
+A cooldown belongs to an entity. For a cooldown the whole world shares, such as a boss's summon that any player triggers, keep it on the entity that stands for the thing: the boss, or the round.
+
+## Showing a cooldown
+
+`useCooldown(entity, key)` reads a cooldown in a view. It returns the cooldown while one runs and undefined otherwise. `left / seconds` is the share left, which a button's rim draws.
+
+## What the other engines do
+
+Unreal's ability system keeps a cooldown as a timed effect that grants a tag, and an ability checks the tag: two abilities share a cooldown by sharing the tag. Minecraft's `use_cooldown` component has a `cooldown_group` that items share. Roblox, Unity, Godot, Phaser and PlayCanvas have no cooldown: each game keeps a timer by hand, a debounce in Roblox and a `Timer` node in Godot.
+
+This engine takes Unreal's and Minecraft's shape, a key on the entity, because a timer by hand is what every game in this repository wrote for itself, each with its own name and its own way to end.
+
+## Sample
+
+A bolt that holds for two and a half seconds, and holds every skill for one:
+
+```ts
+import {
+    defineCooldown,
+    globalCooldown,
+    isCoolingDown,
+    startCooldown,
+} from "@spawnite/engine";
+import type { Entity } from "koota";
+
+const boltCooldown = defineCooldown("bolt");
+
+export function castBolt(caster: Entity) {
+    if (
+        isCoolingDown(caster, boltCooldown) ||
+        isCoolingDown(caster, globalCooldown)
+    )
+        return;
+    startCooldown(caster, { key: boltCooldown, seconds: 2.5 });
+    startCooldown(caster, { key: globalCooldown, seconds: 1 });
+    //  The bolt itself.
+}
+```
+
+## Where it runs
+
+Both, for a player's character. `CooldownsTrait` is a [predicted trait](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-1-declare-the-state): her page counts her cooldowns down on every step as the room does, so her buttons drain smoothly between the room's sends, and the room's word corrects her page where the two differ, such as on a cooldown the room started. A system starts a cooldown where the simulation has the say. Every other entity's cooldowns count down on the room alone, and no page receives them. A page whose room is from before the predicted declaration counts nothing down and shows what the room sends.