@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/structure/states.md

@@ -0,0 +1,202 @@
+---
+title: States
+description: A state that changes over time, such as a siege's phases or a round's countdown, declared once as a machine whose snapshot the world steps, dumps, streams and checkpoints.
+useCases:
+    - game phases
+    - boss fight phases
+    - state machine for a character
+    - wave that waits then fights
+    - countdown then play then win
+    - nested states
+    - pause state
+    - a wave every N seconds
+    - spawn enemies on a timer
+    - wave count
+sidebar:
+    order: 6
+---
+
+A machine holds a state that changes over time: a siege that waits, fights, breathes between waves and ends, or a round that counts down, plays and is won or lost. You declare it once with `states()`, and the engine keeps its snapshot in a trait, so a room dumps, streams, checkpoints and replays it as it does any trait. Every phase of a game, and the engine's own [round](/engine/structure/round/), is one.
+
+`states()` takes [XState](https://stately.ai/docs/machines)'s config, so a machine reads as XState writes one: states, events, guards, nested states and history states. The engine runs XState's pure `transition` on the snapshot in the trait and holds no actor of its own.
+
+Unreal is the one engine of the others that ships a state machine for gameplay, StateTree. Roblox, Unity, Godot and PlayCanvas ship animation state machines and leave a game's phases to an enum and a switch, which spreads one state across several fields. None of them resumes an interrupted state where it left off. A machine here does, through a history state, and a room checkpoints it with the rest of the world.
+
+Its API is in [`states`](https://wiki.spawnite.com/reference/state/states/).
+
+## Declaring a machine
+
+Declare a machine beside the game's traits. `id` is its name: the dump, the stream and the devtools list it by that name.
+
+```ts
+// src/siege/machine.ts
+import { states } from "@spawnite/engine";
+
+export const Siege = states({
+    id: "siege",
+    initial: "waiting",
+    context: { wave: 0 },
+    states: {
+        waiting: { on: { START: "fight" } },
+        fight: { on: { WAVE_HELD: "breather", ALL_DOWN: "over" } },
+        breather: { wait: { seconds: 12, then: "fight" } },
+        over: {},
+    },
+});
+```
+
+The machine types itself from the config: a state's name and an event's name are each written once. Sending an event that no state names, such as `Siege.send(world, "HALT")`, is a type error, and so is a target that names no state of the machine, in `on`, a wait's `then` or a `when` rule. A target is a sibling's key or its path, `patrol.watch`; a state of its own after a dot, `.watch`; or a state from the machine's top by its `id`, `#guard.patrol.watch`. The machine's own `on`, beside `states`, names a state after a dot, `.answer`, or by the `id`, as XState's root does. The error sits on the `states()` call and lists the targets that name no state.
+
+The context's type comes from `context` too, so call `states()` with no type arguments: a type argument sets every other one to its default, which turns the checks above off and opens `is` to any key. Where a field holds more than its first value says, type the value itself, as `context: { holder: null as number | null }`.
+
+Put the machine's trait where it belongs. A game's phases go on the world, with `world.add(Siege.trait)`, or on an entity of their own in a room game: a room streams an entity's traits, and the world's own traits stay on the room. A machine for each thing, such as each guard's patrol, goes on its entity: spawn the entity with `Guard.trait`. Pass the trait fields to start it with another context, as in `Siege.trait({ wave: 3 })`.
+
+A machine on a character that is its player's alone, such as a [conversation](/engine/behaviours/dialog/)'s, declares `ownerOnly: true`: a room streams its trait to that player and to nobody else, as it streams her bag, so another player's page reads nothing of it. Unreal's `COND_OwnerOnly` and Unity's owner read permission on a `NetworkVariable` draw the same line. The dump shows it.
+
+## Moving it and reading it
+
+A system, a component or a test moves a machine with `send` and reads it with `read`. Each takes the world or an entity.
+
+```ts
+Siege.send(world, "WAVE_HELD"); // true: a state took it
+Siege.read(world).value; // "breather"
+Siege.read(world).secondsLeft; // 12, the seconds its wait has left
+Siege.read(world).matches("breather"); // true
+```
+
+`send` returns whether a state took the event, including a transition that runs an action and moves nowhere. A state that names no such event, or whose guards all refuse it, leaves the machine as it was, and `send` returns false. A system that walks the machine's trait with `updateEach` sends after the walk, or walks with `readEach`: `updateEach` writes its copy of the record back over the send, as the round's system does. An event carries fields as XState's do: `Siege.send(world, { type: "WAVE_HELD", wave: 3 })`, which a guard reads from `event`.
+
+A page reads the top state a machine is in with `useMachineState`, which takes the entity that holds it, or the world for the world's machine, and rerenders when that state changes, on a replica as the stream writes it, while a wait's seconds leave the page as it is:
+
+```tsx
+import { states, useMachineState } from "@spawnite/engine";
+import { useQueryFirst } from "koota/react";
+
+const Siege = states({
+    id: "siege",
+    initial: "fight",
+    states: { fight: { on: { WAVE_HELD: "breather" } }, breather: {} },
+});
+
+function PhaseBanner() {
+    const phase = useMachineState(Siege, useQueryFirst(Siege.trait));
+    return phase === "breather" ? <p>Catch your breath</p> : null;
+}
+```
+
+It returns one of the machine's top state names, typed from the config, so `phase === "breathr"` is a type error, and `undefined` while the entity is undefined or holds no record. A state that holds states reads as its own name, `"patrol"` while the guard is in `patrol.watch`, and so does a parallel state while its regions move. Read a state inside another with its tag, `useHas(entity, Guard.is.patrol.watch)`. XState's React binding reads a state the same way, with `useSelector(actor, (snapshot) => snapshot.value)`.
+
+The machine decides and the systems act. Its context fields sit on its trait beside the state, so a system reads and writes them as it writes any trait, and a guard reads them to choose a way out. An action on a transition, an entry or an exit runs once the new state is written. A machine starts in its initial state as its trait is added, so that state's entry actions run the first time a transition enters it; what a game wants done at the start goes in the system that adds the trait.
+
+## Its states as tags
+
+Each state is a tag trait, `Machine.is.<state>`, and a state inside another is its parent's tag's key: `Guard.is.patrol.watch`. The tags follow the record: a send, a wait and a `when` move them as they move it, a spawn, the stream and a restore write them with it, and a parent's tag stays while its child's changes. A record spawned in a state holds that state's tag from its spawn: `RoundMachine.is.playing` matches a round spawned in play before any step. The engine's world writes the tags: a `<Game>`, `createHeadlessGame`, and a test's `world` or `createWorld` fixture from `@spawnite/engine/testing`. A world made with koota's own `createWorld` holds the record and writes no tag, so a test there reads every `is` as false. To put a machine in a state by hand, set its record's `state`, as `entity.set(Guard.trait, { state: "answer" })` or `spawnite play set <entity> guard.state answer`; its tags move at the start of the next step, before any system reads them, and a tool that names a tag rather than the state is refused. Find the entities in a state with a query, as you find `DownedTrait` ones:
+
+```ts
+world.query(Guard.is.answer);
+world.query(TransformTrait, Not(Guard.is.patrol));
+entity.has(RoundMachine.is.playing);
+```
+
+The dump names each tag `<id>.<state>`, such as `"guard.patrol.watch": true`. A room streams the record alone, and each replica writes the tags from the record it receives. The stream sends a record's changed fields, and a replica reads a changed `state` as the machine holds it: a move to another child of a state replaces the child it left, and a region of a parallel state that moves leaves the other regions as they stand. A page that joins mid-run, or reloads into a room, receives the record whole and holds the state it names, with none of the machine's initial state, as Unity's Netcode and Unreal write a replicated value whole on a client's first receipt. A checkpoint keeps the record alone too, and a restore writes the tags from it. The keys type the tags, so a misspelt state is a type error.
+
+Each tag is a koota trait, and the dump tests every entity for every tag. A machine that many kinds of entity each declare their own of, such as an NPC's routines, declares `tags: false`: its `is` is empty, it writes its record alone, and its systems read the state with `read`. Fifty kinds of NPC, a machine each of 36 states, make 1,800 tags, which make a dump of 1,000 NPCs about seven times slower. The tags cost the step little: a machine's move writes them with its record.
+
+## Moving on a trait
+
+A state's `when` lists tests and the state each moves to. Each step, after the waits, the machine runs the tests of the state an entity is in, a child state's before its parent's, and moves to the target of the first that holds. A test takes the entity, the world's own for the world's machine, and the world:
+
+```ts
+const isSlow = (rider: Entity) =>
+    (rider.get(TrackMoverTrait)?.speed ?? 0) < stallSpeed;
+
+sliding: { when: [[isSlow, "stalling"]] },
+stalling: {
+    when: [[(rider) => !isSlow(rider), "sliding"]],
+    wait: { seconds: stallSeconds, then: "stalled" },
+},
+```
+
+A wait that `when` enters counts that step's seconds, as a wait a system's send enters earlier in the step does. Use `when` for a condition that holds over time, such as a speed under a line, and `send` for what happens once, such as a hit. The step runs the machines in the order they were declared.
+
+## Waiting
+
+A state with `wait` holds for its seconds and then goes to `then`, a state or a transition: `then: { target: "watch", reenter: true }` on the `watch` state starts it over, entry actions and all. The fixed step counts the seconds, so a wait holds while the game pauses, and runs the same in a headless test. `seconds` may be a function of the context, as the round's countdown is:
+
+```ts
+countdown: {
+    wait: { seconds: ({ context }) => context.countdown, then: "playing" },
+},
+```
+
+A timer of the game's own, such as a wave of enemies every 30 seconds, is a wait like these, or a system that counts the step's ticks, as [the spawner on the Health page](/engine/behaviours/health/#spawn-one-at-runtime) does. Keep the wave count in the machine's `context`, as the siege's `wave` is, so every page, the dump and a save read it, and a [Counter](/engine/ui/counter/) draws it.
+
+A wait keeps its seconds on the trait, so a checkpoint restores it mid-way. A state left before its wait ends keeps the seconds it waited, and a history state that brings the state back resumes the wait from there. Entered any other way, or brought back by a history state that names another of its states, the wait starts from zero.
+
+```ts
+import { HistoryDepth, StateType, states } from "@spawnite/engine";
+
+export const Guard = states({
+    id: "guard",
+    initial: "patrol",
+    states: {
+        patrol: {
+            initial: "watch",
+            states: {
+                watch: { wait: { seconds: 4, then: "rest" } },
+                rest: { wait: { seconds: 10, then: "watch" } },
+                resumed: {
+                    type: StateType.History,
+                    history: HistoryDepth.Deep,
+                },
+            },
+            on: { BELL: "answer" },
+        },
+        answer: { on: { RESUME: "patrol.resumed", RESTART: "patrol" } },
+    },
+});
+```
+
+A state's `type` and a history state's `history` take the `StateType` and `HistoryDepth` enums, exported beside `states`. A guard three seconds into his watch hears the bell. `RESUME` brings him back to the watch with one second left; `RESTART` starts the patrol over.
+
+Add the `MachinePausedTrait` trait to an entity to hold every machine on it where it is: until the trait comes off, a wait counts no seconds and a `when` goes untested, and an event sent to the machine still moves it, as Godot's `process_mode` pauses a node. A game holds a character through a cutscene this way.
+
+To hold one machine and leave the others running, name the traits that hold it in its `heldBy`: `states({ id: "patrol", heldBy: [Stunned], ... })` holds the patrol's wait and its `when` rules while the entity has `Stunned`, and its other machines run on. An NPC's routine names the `TalkingTrait` trait, which a [conversation](/engine/behaviours/dialog/) adds, so a talking NPC holds its routine and every other machine on it keeps running.
+
+A wait sits on a state with no states of its own, and a machine counts one wait at a time. XState's own `after` delays fall outside that: they need an actor's clock, and a snapshot does not keep them.
+
+## Its trait
+
+The trait holds the context's fields and four of its own:
+
+- `state`: the state it is in, as XState writes a value, such as `"breather"` or `{ patrol: "watch" }`.
+- `waited`: the seconds spent in the current wait.
+- `paused`: the seconds each wait was left at, by its state's id, for a history state to bring back.
+- `history`: where each history state goes back to.
+
+`spawnite play dump` shows a machine under its name, as it shows the round under `round`. The step runs every machine's wait after the engine's rules, so a wait that a rule enters in a step counts that step's seconds.
+
+## What it costs
+
+A step reads each machine's wait without calling XState, so a wait costs a sum a step. Only a transition calls XState, about 11 µs each, and it makes about 1.5 kB of garbage. On a laptop, `pnpm nx bench @spawnite/engine` measures the machines' part of a step as follows:
+
+| Case                                         | Mean ms a step | Worst 1% ms |
+| -------------------------------------------- | -------------- | ----------- |
+| 1,000 machines, none waiting                 | 0.10           | 0.25        |
+| 1,000 machines in a long wait                | 0.16           | 0.41        |
+| 100 machines, each moving on every 5 seconds | 0.02           | 0.07        |
+| 1,000 machines, each moving on once a second | 0.50           | 11          |
+
+The last case makes a thousand transitions a second, and its worst steps are the garbage collector's pauses. Keep a machine's transitions to what changes the game: a routine's next step, not every frame.
+
+## Machines on the page
+
+The engine's own page machines, the room connection and the play menu, run on XState's actor, `createActor`, with its clock and its `after` delays, and show their state through a store: the connection's through `useRoom`'s `status`, and the menu's through `useMenu` and `useCursor`. A page machine belongs to one page and answers the browser, so no room steps it and no replay has to land it where it was: the actor's timers on the wall's clock serve it, and a store is what a HUD reads.
+
+A game's own machine uses `states()`: the room steps it on the fixed step, and a checkpoint or a replay brings it back mid-wait, which a timer on the wall's clock cannot.
+
+## In the devtools
+
+- The inspector shows each machine an entity holds: its state, the seconds its wait has left, and its states.
+- The Wiki tab lists every machine under `machine`, with its states, the entities that hold it, and the state the world's is in.
+- The AI tree says the state as a fact, such as "siege: breather, 8 s left", and names an entity that nothing else names by its machine.

package/dist/wiki/engine/structure/systems.md

@@ -0,0 +1,242 @@
+---
+title: Systems
+description: The functions each fixed step runs, where each runs, predicted systems, events, and how a system reads the player's input.
+useCases:
+    - run code every tick
+    - read a held key in a system
+    - order my system before the engine's
+    - react to an event
+    - move a character from a system
+    - code that runs only on the server
+    - fix a system that throws
+sidebar:
+    order: 2.3
+---
+
+Each fixed step runs the world's systems in order. A system is a function of the world and the step, `(world, { deltaSeconds, input }) => void`. A game adds one in [a plugin](/engine/structure/plugins/), under the phase it runs in.
+
+A system runs inside the step, so it creates no three.js object and no array on each call. Koota's `world.query` builds an array and a record per entity on each call, so a system walks its query with the engine's walk instead, as the engine's own systems do. [`updateEach`](https://wiki.spawnite.com/reference/game/updateeach/) and [`readEach`](https://wiki.spawnite.com/reference/game/readeach/) take a query made once with `createQuery`: Koota's, or the engine's from `@spawnite/engine/core` for a query that names a predicted trait, since Koota's refuses one. `updateEach` refuses a query of a predicted trait, and `readEach` hands that trait's record read-only. Both hand each entity's fields in one record they reuse, so a callback keeps a field, never the record. [`findEntity`](https://wiki.spawnite.com/reference/game/findentity/) finds the first entity a query matches, and [`readField`](https://wiki.spawnite.com/reference/game/readfield/) reads one field of one trait; neither builds anything.
+
+`updateEach` tells a view that watches a trait, such as one that calls `useMachineState`, of each value the walk changed, but it does not add the entity to a Koota `Changed` query of that trait. A view watches on a page and in a room that mounts the scene, and not in a headless test or a continue, so a walk that filled `Changed` queries would let a view change what the next step reads. Write with `entity.set` where a `Changed` query must see the write. This holds for a query of traits and `Not` alone: a query with `Or`, a tracking modifier such as `Changed`, or a relation runs Koota's own `updateEach`, which fills a `Changed` query of a trait while a view watches that trait, so a system that reads a `Changed` query does not walk its trait with one of those.
+
+The step's profile names each system as its plugin names it, `plugin.system`, such as `core.physics` or `regeneration.heal`. The devtools' wiki shows the line the entry's `description` gives beside that name. A headless game times its systems once its world has the `StepProfileTrait` trait, and `readStepProfile(game.world)` reads the times. `spawnite simulate` steps the scene on the `plugins` list the scene's file exports, else on the one `src/game.ts` exports, else on the building blocks alone; `--profile` times that step.
+
+## When a system throws
+
+What a throw does depends on where the system runs:
+
+- **On a room the platform hosts,** the room catches the throw at the system. The rest of that system's tick is skipped, while what it wrote before the throw stays, and the step runs the systems after it. The system runs again next tick. The room logs a `systemFaulted` line naming the system, the tick, the message and the stack. It logs each message once per heartbeat, and at most four per system. The heartbeat counts every throw by system, so a system that fails every tick shows a count equal to the room's steps.
+- **In a development room,** the throw closes the room, so you see it at once. The room stores every player's save first, logs a `failed` line with the stack, and closes each page with `roomFailedCloseCode`. Its reason, read with `readRoomFailedReason`, says whether her save was stored. Her page joins again as a new player when the room starts again, and that join loads her save.
+- **In a headless test or `spawnite simulate`,** the step throws, as any function does.
+
+A system that throws midway may leave what it wrote half done for that tick, as a Roblox script that errors does. Roblox, Unity and Godot also keep running a script that errored, and run its handler again next frame. A throw from the room's own work around the systems, such as its send or a save, closes even a hosted room, and every player's save is stored first. A loop that never ends cannot be caught: it stops the whole room.
+
+## Where a system runs
+
+In a game with a room, a system runs on the room alone unless its entry declares otherwise. The room judges the rule and streams the result, and each page draws it. Set `runsOn` on the entry to run the system elsewhere:
+
+```ts
+import { definePlugin, RunContext } from "@spawnite/engine/core";
+
+export const moves = definePlugin({
+    name: "moves",
+    systems: {
+        rules: {
+            // Nothing declared: the room alone.
+            scoreKills,
+            // Works out a `local` trait on each end, which nothing rolls back.
+            footing: { system: readFooting, runsOn: RunContext.Both },
+            // Only draws, so the room skips it.
+            trailSparks: { system: trailSparks, runsOn: RunContext.Client },
+        },
+    },
+});
+```
+
+The following table shows where each declaration runs:
+
+| `runsOn`                         | The room | A page of a room | A game with no room |
+| -------------------------------- | -------- | ---------------- | ------------------- |
+| Left out, or `RunContext.Server` | Runs     | Skipped          | Runs                |
+| `RunContext.Both`                | Runs     | Runs             | Runs                |
+| `RunContext.Client`              | Skipped  | Runs             | Runs                |
+
+Declare `RunContext.Both` for a system the room and a page each run for themselves and that writes nothing her page predicts, such as one that works out a `local` trait. A system that writes what her page predicts, her character's velocity or any other predicted trait, is a predicted system instead: `predicted: true` runs it on both ends and again in a correction, as [Predicted systems](#predicted-systems) describes. A `RunContext.Both` system cannot write a predicted trait of yours, since Koota's functions refuse one, and one that writes an `anyEntity` predicted trait of her character is reported by [the prediction checks](https://wiki.spawnite.com/platform/networking/debugging/#the-prediction-checks). A single-player game has one world that is both the room and the page, so it runs every system and needs no declaration.
+
+A page's world lacks the traits only the room holds, so a room's rule that ran on a page would write from what is missing. The default keeps that rule off the page. Unreal runs gameplay code on the server unless a function is marked for a client, and Roblox runs a `Script` on the server and a `LocalScript` on a client. Unity's Netcode and Godot leave the check to the code, with `IsServer` and `is_multiplayer_authority()`.
+
+The devtools' wiki says where each system runs under its name.
+
+An outcome, such as damage, a heal, loot or a score, runs only on the world that decides outcomes: the room, or a game with no room. The type holds this rule. Every outcome function takes an `Authority` first, `dealDamage(step, target, { amount: 30 })` and `dealHealing(step, target, { amount: 20 })`, and only the room's step is one:
+
+- **A system whose entry leaves `runsOn` out** receives the room's step, an `AuthoritativeStep`, so it calls an outcome with no check.
+- **A system that runs on both, or a predicted system,** receives a step that may be her page's. `step.authoritative` is true on the room and in a game with no room, and false on a page in a room, and `if (step.authoritative)` narrows the step to the room's. An outcome outside that check fails to typecheck, so a page that predicts a hit never deals it.
+- **Code outside a step,** such as a message handler or a test, calls `requireAuthority(world)`, which throws on a page in a room. Ask `isAuthoritative(world)` first where the code also runs on a page. `isRoomWorld(world)` says whether the world is a room's own, the one its pages join, which a game played alone is not: a component that spawns what a room holds for its players, such as `<Round>`'s round, which waits there for the first page, asks it.
+
+Give a game's own outcome, such as a score, the same first parameter, `authority: Authority`, so its callers pass the room's step too, and read its world from it with `readAuthorityWorld(authority, "awardScore")`, which throws, naming your function, for an authority no step and no `requireAuthority` made. Should a cast or a plugin in JavaScript get past the type, the engine's outcome functions throw on a page in a room, naming the function and the fix. Every step also carries `step.tick`, the step's number on the world's clock. Unreal's `HasAuthority()` and Roblox's `RunService:IsServer()` answer the same question at run time; here the compiler asks it.
+
+### A page's read of a room-only trait
+
+A page of a room never holds a trait defined with `serverOnly`. A system that runs there and reads one finds nothing, acts on that, and the room corrects what it did at every send, 60 or 30 times a second. In development, the page throws on the first such read instead, and names the system and the trait:
+
+```text
+moves.sprint read "stride" on a page, where it never is: the trait is serverOnly, so only the room holds it. Move the read to a system whose entry leaves runsOn out, which runs on the room alone. Where the page needs the value too, define the trait without serverOnly so the room streams it, with predicted: true where her page predicts it on her character, or with local: true so the room and the page each keep their own.
+```
+
+The check covers a system declared `RunContext.Both` or `RunContext.Client`, and a predicted system, through `query`, `queryFirst`, `get`, `has`, `set` and `add` on the world and on an entity, and through the engine's `updateEach`. It runs where the world is a dev world: the development page, a headless game and a test. A built game carries no check. A game with no room holds every trait itself, so nothing is refused there. Outside a system, the dump and the devtools read every trait as before.
+
+To fix the error, take the first of the following that fits:
+
+- **The rule belongs to the room.** Move the read to a system whose entry leaves `runsOn` out.
+- **The page needs the value.** Define the trait without `serverOnly`, so the room streams it.
+- **Her page predicts the value on her character.** Define the trait with `predicted: true`, as [Predicted systems](#predicted-systems) describes.
+- **The room and the page each work the value out, and nothing rolls it back.** Define the trait with `local: true`, as [Choose who a trait reaches](https://wiki.spawnite.com/platform/room-messages/#choose-who-a-trait-reaches) describes.
+
+The check knows a trait made with `defineTrait`. A trait made with Koota's `trait` has no name and no options, so the check cannot tell who holds it.
+
+None of the other engines checks this before the game runs, and each fails as the game runs: Roblox's `ServerStorage` is empty on a client, so a read of it errors, Unity's Netcode throws on a client's write to a server's `NetworkVariable`, and Unreal's game mode is null on a client.
+
+## Predicted systems
+
+In a multiplayer game, mark each system that steps a player's character as a predicted system: set `predicted: true` on its entry in the plugin. The engine runs a predicted system on one kind of step besides the world's: a replay. When the room corrects where her page has her, her page runs her latest moves again from the corrected spot. The room steps every character once on each of its ticks, on her input for the tick or, where it has none, on her last input and then a still one, so a character's steps and the world's are the same steps on the room.
+
+The room and her page both step her, so a predicted system runs on both and declares no `runsOn`. `definePlugin` refuses `predicted: true` beside `RunContext.Server` or `RunContext.Client`.
+
+On a replay, only the predicted systems run, in the order the step runs them, and `step.rerunEntity` names the one character the step moves. An unmarked system runs once on each of the world's steps and never on a replay. A single-player game has no room, so it never replays, and the mark changes nothing there.
+
+To tell the two kinds apart, ask which clock the system runs on:
+
+- **A dash's charges are a predicted system's.** It recharges them as she moves. Left unmarked, it would not run on her page's replay, so her page would replay her steps without the recharge and refuse a dash the room ran, and the room would correct her again.
+- **A monster's AI is not.** It steps the monster once per world step. Marked, it would run again on every replay on a page that predicts it, and the monster would move faster there whenever the room corrects her. The `regeneration.heal` system in [the plugin above](/engine/structure/plugins/#a-games-own-plugin) runs on the world's clock too, and leaves `character` out.
+
+A predicted system follows these rules:
+
+- Walk the characters with `step.updateEachPredicted(query, callback)`, which hands the callback each character the step may touch that the query matches, with the query's traits and the character as a `PredictedEntity`, whose predicted traits it may write: every character on the room and in a game played alone, her own character alone on her page, and on a replay the one character `step.rerunEntity` names. It never hands over an entity that is not a character. In a dev world, the engine prints a warning naming a predicted system that moves another character on a replay, as one that walks `anyEntity` traits with `updateEach` can. It is the one pass that writes a predicted trait of yours.
+- Keep the system's state for a character in a trait declared `predicted`. Her page keeps every predicted trait of her character for each step, and when the room's value differs, it restores every one of them to the room's exact value and replays the steps since. A timer in a predicted trait is where the room had it after the replay, so the replay counts it down again from there. A timer in any other trait is not restored, so the replay counts it down a second time. Keep no state for a character in a module variable or a closure either: the replay never restores it, and no check names it.
+- Draw a number both ends predict with `step.random(character)`, the same on the room and her page for one tick and character. Draw a hidden roll, such as loot, or read the clock only where `step.authoritative` is true, so the room alone draws it and her page takes the result. In a room in development, [the prediction checks](https://wiki.spawnite.com/platform/networking/debugging/#the-prediction-checks) name a predicted system that calls `Math.random`, `random(world)` or `Date.now` there, or that writes a trait of hers it does not predict.
+- Leave a character's predicted traits to the predicted systems. The type holds it for a trait declared `predicted: true`: only the `PredictedEntity` a predicted system is handed writes it, and a one-off change the room makes goes through `grantPredicted`, as [When the room changes the player's character](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#when-the-room-changes-the-players-character) shows. For an `anyEntity` trait, in every dev world, the room's and a headless game's among them, the prediction checks name a game's system that is not a predicted system as it writes one.
+
+Type the function as a `PredictedSystem`, whose step is a `PredictedStep`. TypeScript then refuses it in an entry that leaves out `predicted: true`.
+
+The following plugin recharges a dash's charges as a predicted system, in the `rules` phase, where a timer counts. The dash itself is a push: a press calls `pushCharacter`, which holds the character's velocity for the dash's length, as [Change the character's movement](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#change-the-characters-movement) describes. Never write her velocity yourself: the engine's steer sets it from the input on every tick.
+
+```ts
+// src/dash.plugin.ts
+import type { World } from "koota";
+import {
+    createQuery,
+    definePlugin,
+    defineTrait,
+    type PredictedStep,
+} from "@spawnite/engine/core";
+
+/** A character's dash charges, and the seconds toward the next: predicted, so
+ *  her page counts them as the room does and rolls them back with her. */
+const ChargesTrait = defineTrait(
+    "charges",
+    { charges: 2, recharge: 0 },
+    { predicted: true },
+);
+const chargers = createQuery(ChargesTrait);
+
+/** Brings a charge back every three seconds, up to two. */
+function rechargeDashes(_world: World, step: PredictedStep) {
+    step.updateEachPredicted(chargers, ([state]) => {
+        if (state.charges >= 2) return;
+        state.recharge += step.deltaSeconds;
+        if (state.recharge < 3) return;
+        state.charges += 1;
+        state.recharge = 0;
+    });
+}
+
+/** A dash's charges for each character. */
+export const dash = definePlugin({
+    name: "dash",
+    description: "A dash's charges for each character.",
+    onCharacterSpawn: (character) => {
+        character.add(ChargesTrait);
+    },
+    systems: {
+        rules: {
+            rechargeDashes: {
+                system: rechargeDashes,
+                description: "Brings a dash charge back every three seconds.",
+                character: true,
+            },
+        },
+    },
+});
+```
+
+The step's profile and the devtools name the system `dash.rechargeDashes`.
+
+A press reaches a predicted system on its tick: `readPresses(step, handle)` returns the tick's presses, each with `character`, a `PredictedEntity`, `payload`, `origin` and `refuse`. Her page keeps each press and hands it to every replay of its tick, so a dash started by a press replays with the press. [Presses](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-2-declare-the-action) describes how the room settles each one.
+
+A predicted system keeps its state in a predicted trait, and a replay restores that trait before it runs the system again, so the system never asks whether a step is a replay. A step of one character, `step.rerunEntity`, names her; it happens in her page's replay, and on a room that catches one player up. [The multiplayer page](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#step-1-declare-the-state) says what a predicted trait is and how it travels.
+
+## The player's input
+
+On a page and in a game played alone, the step carries the player's input as `input`, a [`StepInput`](https://wiki.spawnite.com/reference/game/stepinput/): one tick of every input the game's plugins declare, the character's `move`, `heading` and `jump` among them where the game lists `characters()`, each at its place in the composition. A room's own step carries no input, because each player's character holds what that player's page last sent. A system reads a value by its handle, never by its place.
+
+Which system reads the input depends on what the player drives:
+
+- **A controlled entity that is no character, such as a car on a track:** the step copies the character's move into each track mover the player steers, `steer` from its x and `throttle` from its y, and a system reads them off the mover, as [the TrackMover's throttle](/engine/behaviours/track-mover/#a-throttle) does.
+- **A player's character:** a predicted system reads the character it steps, with `readInput(character, plugin.inputs.name)`, for a key the game declares in [its plugin's `inputs`](/engine/structure/plugins/#a-games-own-plugin). A room then steps each character on its own player's keys, as [Hold a key](https://wiki.spawnite.com/platform/networking/predicted-mechanic/#hold-a-key-a-sprint-a-block-an-aim) describes.
+
+## Events
+
+An event is something that happened, kept in a log each world holds. Every emit is one event, delivered once to each system and once to each view that listens, in the order emitted; two emits are never merged. A system reads it with `readEvents`, a view hears it with `useEvent`, `spawnite play dump` lists it under the dump's `events`, and in a room it reaches every page that holds its entity. The engine's own include `DamagedEvent`, [`DiedEvent`](/engine/behaviours/health/#when-it-dies), `HealedEvent`, `TriggerEnteredEvent`, `TriggerExitedEvent`, `ChaseReachedEvent`, `ChaseExitedEvent`, `TakenEvent`, `InteractedEvent` and `ItemAcceptedEvent`. A game makes its own with `defineEvent`, which takes the name the log, the dump and the room know it by, then the record's defaults, or a function that makes them, or none for an event with no record. Every field that holds an entity, or a list of them, goes in `entities`, one level into a record or a list of records included, or the event fails to typecheck: it travels as the entity's key, and a page reads it back as its own copy of that entity, or null where the page holds none. A list the default holds empty names what one of its records is in `elements`, so a page reads a streamed list by it and a vector in a record comes back a vector.
+
+```tsx
+// src/Chain.tsx
+import type { Entity } from "koota";
+import { defineEvent, useEvent } from "@spawnite/engine";
+
+/** On the monster a chain of lightning starts from: each monster it
+ *  jumped to after, in order. */
+export const ChainedEvent = defineEvent(
+    "chained",
+    (): { hits: Entity[]; damage: number } => ({ hits: [], damage: 0 }),
+    { entities: ["hits"] },
+);
+
+/** The game's own effect: an arc from each monster to the next. */
+declare function drawArcs(monsters: readonly Entity[]): void;
+
+/** Draws each chain on this page, once, as the frame hears it. */
+export function ChainArcs() {
+    useEvent(ChainedEvent, ({ entity, record }) => {
+        if (entity) drawArcs([entity, ...record.hits]);
+    });
+    return null;
+}
+```
+
+A system in the room emits it with `emitEvent(step, ChainedEvent, { hits, damage }, { entity: first })` as it deals the damage to each monster, and `ChainArcs` on every page draws the arcs, between the monsters where they stand now.
+
+- **Each system reads every event once.** `readEvents(step, event)` returns every event emitted since that system last read the event, so a system that runs before the emitter reads it the next step and one after reads it the same step, and a system that skips ticks, by its own counter or a schedule, reads every event since its last read. The world keeps an event for a system that has read it before for up to `maximumUnreadSteps`, one second; a read later than that gets what is left, counted in the room's heartbeat and named in development. A system never reads its own emits of the run that made them: it reads them on its next run. The array is valid until the system returns.
+- **A predicted system reads no events.** A replay after a correction runs predicted systems again, which would read each event again; `readEvents` refuses a predicted step by type. A reaction that changes predicted state runs in an ordinary system on the room, which runs once a step, and writes the predicted value with `grantPredicted`, which her page takes as one correction.
+- **An event is an outcome, so emitting one takes an authority**: the step inside `if (step.authoritative)` or in a system with no `runsOn`, `requireAuthority(world)` between two steps, such as in a room's message handler, or `findAuthority(world, entity)`, which on a page returns an authority over an entity only that page holds, as Unreal gives a client authority over an actor it spawned that is not replicated, and null for a streamed one. An emit between two steps is read by every system of the next step. No page emits an event about an entity the room streams, so neither its prediction nor its replay can play one twice: the room's event reaches her page a round trip after she acts.
+- **Each emit is one event.** Two hits on one monster in one step are two `DamagedEvent`s, each with its own record: who dealt it, the weapon, the game's own data and where it landed, as [the weapon page](/engine/behaviours/weapon/#reading-its-hits) shows. A moment that touches many entities may still carry them in one event, as the chain does, which each page draws between their current positions.
+- **A view hears each event once, after the frame.** The frame loop hands each world's events to its views once a frame, after the frame's steps and its animation, however many steps the frame ran. A view hears each event emitted after it subscribed; unmounting drops the rest. A listener's throw is reported and the other listeners still hear the event, and an event a listener emits is heard at the next frame. A room never draws, so it keeps nothing for views.
+- **A view hears every entity's event** unless it passes `{ entity }`, even a view mounted under one `<Entity>`. An effect that belongs to one entity, such as a coin's sparks, passes `{ entity: useEntity() }`, as [the Pickup page's coin](/engine/behaviours/pickup/#an-effect-where-it-is-taken) does.
+- **An event outlives its entity.** `event.entity` reads null once the entity is destroyed, and `{ entity }` still matches it, so put what a reader needs in the record: `DamagedEvent` carries where the hit landed, so a damage number shows for a killing blow. On a page in a room, the entity stands until its readers are done, as the next bullet says.
+- **Where it goes** is the event's `delivery`. `EventDelivery.Reliable`, the default, reaches every page that holds its entity, kept through a page that falls behind or hides its tab, up to `maximumHeldEvents`. `EventDelivery.Cosmetic` is dropped by a page more than a second behind or with its tab hidden, as a spark or a tracer should be. `EventDelivery.ServerOnly` stays on the room, and `useEvent` refuses it by type. `EventDelivery.Local` is the drawing world's own, emitted with `emitEvent(world, ...)` outside any step, as the engine's `ClipMarkEvent` is as a clip passes a mark, and `readEvents` refuses it by type. `scope: EventScope.World` makes an event about the world, with no entity, such as the engine's `ShotJudgedEvent`.
+- **In a room**, each send carries every event emitted since the last, one entry per emit, with the tick it was emitted at. A page holds them for its next step's systems and its frame's views. When the stream removes an entity that an event the page holds still names, as its entity or in an entity field, the entity stays in the page's world until the page's next step has read the event and, in a game's frame, its views have heard it. Only then does the page remove it. So a page reads a death with the dead entity standing, even when one send carries the death and the removal, or one frame lands both sends. It stands as the page last held it: a write the room made in the tick it destroyed the entity never reaches the page. A page's reader may therefore find an entity standing that the room's reader, running later in the same step as the destroy, read as null. A system that skips ticks and reads later reads null, as it would on the room. An event whose entity the room destroyed before the send arrives marked gone, so a page that never held the entity reads it as null. A player who joins hears every event emitted after the tick her welcome's snapshot stands at, and none before, since the snapshot holds their consequences.
+- **A world holds at most `maximumHeldEvents` events, and `maximumHeldEventBytes` bytes of records, at once.** Past either, a room refuses an emit, which throws in development naming the system emitting most and is counted in the heartbeat in a deployed room, and a page that has fallen behind drops its oldest, with a development warning.
+- **A reader can tell it missed events.** `readEvents` returns its list with `gap`, true where the read came more than `maximumUnreadSteps` after the system's last read, or its page fell past the bound behind the room. After a gap, read the state the events describe rather than trust the events: whether a trigger stands occupied, not that a missed exit never happened.
+- **A record is the reader's to keep.** The engine copies each record as it is emitted and never reuses one, so a view may keep it, in React state or anywhere else, and a reader never sees it change.
+- **An entity a page does not hold reads as null.** An entity field naming an entity the page holds no copy of reads null there, and a list leaves it out, so an event never hands a page an entity it was not sent. A `null` the list held stays, so a list beside it keeps its places.
+
+Roblox's `BindableEvent`, Unreal's delegates, Unity's `UnityEvent` and Godot's signals call a listener inside the emit, which in a room runs only where the emit runs. Here an event is a log that systems read, as Bevy's buffered messages are, each reader from where it last read, so the dump lists it, the room streams it and a replay replays it. An agent from Bevy 0.17 reads this engine's event as Bevy's message, not Bevy's observer. `emitEvent` takes its verb from Godot's `emit` and Node's `EventEmitter`, and does what Bevy's `MessageWriter::write` does: it hands the event to the systems that read it, and calls no listener.
+
+## State a continue can carry
+
+A dev room keeps a checkpoint of its world, and [a continue](/engine/testing/replay/#continuing-a-moment) writes it back into a fresh room to run a moment again. The checkpoint holds every trait of every entity, the world's own traits, the physics world and the world's random stream, so keep a system's state in those places:
+
+- **Keep a system's state in a trait.** A count, a timer or a list a system keeps in a variable of its module, or in a closure it made, starts afresh in a continue, which then parts from the room. Put it in a trait, on an entity or on the world with `world.add`. A scratch vector written before each read is safe.
+- **Draw from the world's stream.** [`random(world)`](https://wiki.spawnite.com/reference/game/random/) draws from 0 up to 1, [`randomRange`](https://wiki.spawnite.com/reference/game/randomrange/) between two numbers and [`randomInt`](https://wiki.spawnite.com/reference/game/randomint/) a whole number between two, both included, as Godot's `randi_range` and Roblox's `NextInteger` do, and [`shuffle`](https://wiki.spawnite.com/reference/game/shuffle/) shuffles a list in place, as Godot's `Array.shuffle` does. The stream's state is the world's `WorldRandomTrait` trait, so a continue draws what the room drew; Every world starts from the same seed, as a test's world should, and a room seeds its own from the wall's randomness as it starts, so no two runs play alike; [`seedRandom`](https://wiki.spawnite.com/reference/game/seedrandom/) starts it from a seed of your own, as Unity's `Random.InitState` does. `Math.random` stays fine for what only the page draws, a spark's scatter or a sound's pitch.
+- **Read no wall clock in a system.** Count the step's `deltaSeconds` instead.
+
+A game's lint warns on `Math.random`, and on a variable of the module a system writes, in any function that takes the world or is typed `System`. [`spawnite replay check`](/engine/testing/replay/#checking-a-continue-comes-back-exactly) proves the rest: it names the first trait where a continue parts from the room.

package/dist/wiki/engine/structure/track-level.md

@@ -0,0 +1,73 @@
+---
+title: Track level
+description: A track game's level as a file, and the command that prints it as numbers.
+useCases:
+    - racing level file
+    - design a race track level
+    - track centerline points
+    - place obstacles on a track
+    - finish line in a level file
+    - sled level
+    - check a track level's numbers
+    - track width and zones
+sidebar:
+    order: 15
+---
+
+A track game keeps each level as a JSON file in `src/levels`, named `level-<number>.json`. The file lists the points the centerline passes through, what stands along the course, what a rider hits, and the finish. The schema package reads the file, so a bad file fails at load with the field it gets wrong. Sled's levels are the first of these files.
+
+Everything on the course is in track coordinates: `at` is metres along the centerline, and `side` is metres across it, positive to the right of travel. [TrackMover](/engine/behaviours/track-mover/) rides in the same coordinates.
+
+## The file
+
+A level has the following fields:
+
+- `name`: the level's name.
+- `track.points`: two or more points, each with `x`, `y` and `z` in metres, the lane's `width` edge to edge, and an optional `zone`, the material tag the point stands in, such as `ice`. The width and the zone blend to the next point.
+- `placements`: lists of copies that stand along the course, by kind, each with `at`, `side` and an optional `scale`.
+- `triggers`: lists of spots a rider hits, by kind, each with `at`, `side` and an optional `lift`, the metres it floats higher, such as a coin over a rock that only a rider in the air takes.
+- `finish.at`: metres along the centerline where the run ends.
+
+A key the schema does not know fails the file, so a misspelt field never goes missing in silence.
+
+```json
+{
+    "name": "Level 1",
+    "track": {
+        "points": [
+            { "x": 0, "y": 0, "z": 0, "width": 6.3, "zone": "snow" },
+            { "x": 3, "y": -4, "z": -46, "width": 6.3, "zone": "snow" }
+        ]
+    },
+    "placements": { "trees": [{ "at": 8, "side": -14, "scale": 1.5 }] },
+    "triggers": { "pickups": [{ "at": 12, "side": 1.2 }] },
+    "finish": { "at": 40 }
+}
+```
+
+## Reading a level as numbers
+
+`spawnite track describe <game> <level>` prints a level as numbers, so you can tune a course without drawing a frame. It builds the engine's `Track` from the points through the game's own Vite, so each number describes the curve the rider follows rather than the points in the file. Add `--json` for one object an agent parses.
+
+The command prints the following:
+
+- The length along the centerline, the drop from the first point to the last, and the height range.
+- The steepest drop and the steepest climb, as percent grade, and where each lies.
+- The tightest turn seen from above: its radius over 2 m of track, its direction, and where it lies.
+- The lane's narrowest and widest width.
+- Each run of points in one zone, from the first point's distance to the last one's.
+- The finish, and every placement and trigger by kind, as metres along and across, with a trigger's lift where it has one.
+
+For sled's level 1, `spawnite track describe sled 1` prints:
+
+```text
+track Level 1: 76.6 m long, drops 9 m, height -9 to 1.2 m, finish at 66 m
+  steepest drop 42.9% at 41.1 m, steepest climb 6.4% at 16.5 m
+  tightest turn 20.9 m radius, left, at 58.6 m
+  lane 6.3 m wide
+  zone snow from 0 to 76.6 m
+placements trees 3: 8 m -14, 57.1 m +13, 71.1 m -15
+triggers pickups 7: 12 m +1.2, 18 m -1.2, 24 m +1.2, 32 m -1.2, 46 m +1.5, 50 m +1.5, 54 m +1.5
+triggers slabs 1: 39 m 0
+triggers boulders 1: 60 m -2
+```