incanto 0.74.0 → 0.76.0

package/skills/incanto-gameplay-behaviors.md

@@ -1,6 +1,6 @@
 ---
 name: incanto-gameplay-behaviors
-description: The batteries-included game-logic library (incanto/gameplay) — ready-made Behaviors you wire from scene JSON with ZERO custom code. State & interaction: Health (hit points, i-frames, regen), Lifetime (self-destruct), ScoreKeeper (score/lives/win-lose hub), Pickup (collectibles), Collector (collect-N tally), DamageOnContact (projectiles/hazards), Interactable (press-to-use doors/levers/NPCs), Checkpoint (move where a Respawn puts you back), Turret (shoot the nearest enemy in range). Movement, AI, camera, spawning & juice: FollowCamera (camera tracks a target), Patrol (waypoint paths), Chase (homing enemy AI), Wander (seeded roaming), ZombieAI (wander-then-charge monster AI with proximity aggro), MoveTo (eased position tween), Oscillate (sine float/spin/pulse), Spawner (interval spawning), WaveSpawner (sequenced enemy waves), Projectile (straight-line motion), Buoyancy (float/bob/ride the swell on a Water3D). Use when a game needs health, score, pickups, damage, timers, interaction, enemy movement/AI, camera-follow, tweens, spawning, rafts/boats/floating objects — BEFORE hand-rolling them as custom behaviors.
+description: The batteries-included game-logic library (incanto/gameplay) — ready-made Behaviors you wire from scene JSON with ZERO custom code. State & interaction: Health (hit points, i-frames, regen), Lifetime (self-destruct), ScoreKeeper (score/lives/win-lose hub), Pickup (collectibles), Collector (collect-N tally), DamageOnContact (projectiles/hazards), Interactable (press-to-use doors/levers/NPCs), Checkpoint (move where a Respawn puts you back), Turret (shoot the nearest enemy in range). Movement, AI, camera, spawning & juice: FollowCamera (camera tracks a target), ChaseCamera (behind a vehicle, turning with it), Patrol (waypoint paths), Chase (homing enemy AI), Wander (seeded roaming), ZombieAI (wander-then-charge monster AI with proximity aggro), MoveTo (eased position tween), Oscillate (sine float/spin/pulse), Spawner (interval spawning), WaveSpawner (sequenced enemy waves), Projectile (straight-line motion), Buoyancy (float/bob/ride the swell on a Water3D), Shatter (break a crate into pieces that fly and vanish), Carry (pick up, carry, drop and throw a body), Mount (get on a horse or into a car and drive it; off beside it), Sight (a watcher's eyes — cone, range, line of sight, suspicion; spotted/lost). Use when a game needs health, score, pickups, damage, timers, interaction, enemy movement/AI, camera-follow, tweens, spawning, rafts/boats/floating objects — BEFORE hand-rolling them as custom behaviors.
 ---
 
 # Gameplay behaviors — the built-in logic library
@@ -94,6 +94,43 @@ a connection `to` the root is `/root` (or `.`), never `/root/Game`.
 
 ---
 
+## Phases
+
+A boss that changes at two thirds and again at a third — the last common wiring
+that needed TypeScript.
+
+```json
+{ "name": "Boss", "type": "CharacterBody3D", "uid": "n_…",
+  "script": { "name": "Health", "props": { "max": 600 } },
+  "children": [
+    { "name": "Mood", "type": "Node3D", "uid": "n_…",
+      "script": { "name": "Phases", "props": { "at": [0.6, 0.3] } } }
+  ] }
+```
+```json
+{ "signal": "phase2", "from": "Boss/Mood", "to": "Adds", "handler": "start" },
+{ "signal": "phase2", "from": "Boss/Mood", "to": "HUD/Banner", "handler": "show",
+  "args": ["THE CINDERS CATCH", { "color": "#ffb454", "seconds": 1.6 }] },
+{ "signal": "phaseChanged", "from": "Boss/Mood", "to": "HUD", "handler": "onPhase" }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `at` | `[]` | the health FRACTIONS the phases begin at, highest first. `[0.66, 0.33]` is three phases |
+| `health` | `""` | whose health to watch; empty finds the nearest `Health` — this node, its subtree, then its ancestors — so a `Phases` under the boss needs no path |
+
+- Signals: `phaseChanged(n)` for a HUD, and `phase2`…`phase5` for the wiring.
+  The numbered ones exist because a connection cannot filter on a NUMBER, so
+  "phase two starts the adds" has to be a line in the scene file rather than a
+  switch in TypeScript.
+- **It never goes backwards.** Healing a boss does not give its phase back, and
+  a single huge hit still announces every phase it passed THROUGH — so the
+  wiring for phase two runs even when the fight went from full to a tenth in
+  one blow.
+- `phase` is the readback, and it survives a save.
+- What a phase DOES is still your game's: `Phases` owns the thresholds and
+  nothing else. Past five phases, wire `phaseChanged` and switch on the number.
+
 ## Checkpoint
 
 On an `Area3D`/`Area2D`, pointing at a `Respawn`: touch it and the next fall
@@ -101,10 +138,11 @@ puts you back HERE. Documented with `Respawn` in `incanto-behaviors-and-scripts.
 
 ## Health
 
-Hit points with regen and post-hit invulnerability (i-frames). The universal
-"can be hurt / can die" behavior. Hurt it via `damage(n)` (e.g. from
-`DamageOnContact`); heal/kill via `heal(n)` / `kill()`; bring it back with
-`revive(hp?)`. Clamps to `0..max`.
+Hit points with regen, post-hit invulnerability (i-frames), and the hit
+REACTION — the shove and the stagger. The universal "can be hurt / can die"
+behavior. Hurt it via `damage(n, from?)` (e.g. from `DamageOnContact`, which
+passes where it hit from); heal/kill via `heal(n)` / `kill()`; bring it back
+with `revive(hp?)`. Clamps to `0..max`.
 
 | Prop | Default | Meaning |
 |---|---|---|
@@ -113,11 +151,77 @@ Hit points with regen and post-hit invulnerability (i-frames). The universal
 | `invulnerableFor` | `0` | seconds of immunity AFTER a hit (i-frames; 0 = off). Immunity BEFORE one — a dodge roll, a spawn, a cutscene — is `protect(seconds)`: it opens the window now, extends one already open and never shortens it |
 | `freeOnDeath` | `false` | `queueFree()` this node when it dies (clone-safe) |
 | `freeParent` | `false` | with `freeOnDeath`, free the PARENT — the enemy, when `Health` rides a child node |
+| `knockback` | `0` | units/s the struck body is shoved AWAY from the hit's source, decaying to nothing over `knockbackSeconds` (so it travels about `knockback × knockbackSeconds / 2`). Needs a source: `damage(n, from)` |
+| `knockbackSeconds` | `0.15` | how long the shove lasts |
+| `knockUp` | `0` | the vertical part of the shove — a hop. 3D `+y` is up; in 2D pass the same positive number, the engine flips it to `−y` |
+| `staggerSeconds` | `0` | how long the body's movers and controllers ignore their inputs after a hit — a brute mid-swing is interrupted, a player loses the stick |
+| `applyKnockback` | `true` | who moves the body. `true`: Health does (a `CharacterController2D/3D` under the body is detected and applies it itself). `false`: YOUR behaviour drives the body every frame and reads the kick — see "Hit reactions" |
 
 Signals: `damaged(amount, current)` · `healed(amount, current)` ·
-`healthChanged(current, max)` · `died` · `revived(current)`
-Methods: `damage(n)` · `heal(n)` · `kill()` · `revive(hp?)` · `protect(seconds)` — state: `current`,
-`isDead`
+`healthChanged(current, max)` · `died` · `revived(current)` · `staggerEnded`
+Methods: `damage(n, from?)` · `heal(n)` · `kill()` · `revive(hp?)` · `protect(seconds)` — state: `current`,
+`isDead`, `invulnerableRemaining`, `staggered`, `knocked`, `kickVelocity`, `hitDirection`
+
+### Hit reactions: a hit that MOVES something and STOPS something
+
+Five shipped games wrote the same thirty lines: a `KNOCK_X`, a `CONTROL_LOCK`,
+a position nudged along the blow, a `WeakMap` counting flinches. Every one was
+a hit the ENGINE saw and did nothing about — `damage(n)` took the points and
+the body stood exactly where it was. Now the reaction is three props on the
+Health, and the direction comes from the hit itself:
+
+```json
+{ "name": "Brute", "type": "CharacterBody3D",
+  "script": { "name": "Health",
+              "props": { "max": 50, "knockback": 4, "staggerSeconds": 0.4 } },
+  "children": [
+    { "name": "AI", "type": "Node3D",
+      "script": { "name": "Chase", "props": { "target": "%Player", "moveParent": true } } }
+  ] }
+```
+
+- **The source is the direction.** `DamageOnContact` and `Turret` pass their
+  own world position; your code passes whatever hit — `health.damage(25,
+  swordTip)`. The body is shoved AWAY from that point on the ground plane
+  (3D x/z, 2D x/y); `damage(n)` with no source takes the points and moves
+  nothing, exactly as before. A source ON the body (zero distance) moves
+  nothing either — put the hitter's position in, not the victim's.
+- **Stagger holds every built-in mover.** `Chase`, `Patrol`, `PathFollow`,
+  `MoveTo`, `Wander`, `ZombieAI` all move through one door, and that door says
+  "not now" while `staggered` is true — so the Brute above stops mid-charge for
+  0.4 s and its `Chase` resumes on its own. Your own mover can ask the same
+  question: `isStaggered(node)` is not exported, but `findHealth`-style lookup
+  is one line — the Health on the node, its children, or its ancestors — and
+  `health.staggered` is the answer.
+- **The player's controller honours it too.** `CharacterController2D` and
+  `CharacterController3D` drop the stick, the jump and the dash while the
+  body's Health is staggered, and write the kick as the body's velocity
+  (`knockUp` becomes the hop). `Health` may sit on the body or on a child
+  (`Vitals`, when the body's own script slot is taken); the controller finds it
+  either way.
+- **Your own controller reads the kick.** A behaviour that writes the body's
+  velocity every frame (the platformer's `PlayerController` does) sets
+  `"applyKnockback": false` and reads it where it writes velocity — otherwise
+  two writers fight over one body:
+
+  ```ts
+  const kick = health.kickVelocity;           // [] when not knocked, else decaying
+  if (kick.length > 0) vx = kick[0] ?? vx;
+  const lift = health.takeLift();             // knockUp, ONCE — then gravity owns it
+  if (lift !== 0) vy = lift;
+  if (!health.staggered) vx = stick.x * RUN_SPEED;
+  ```
+
+- **A dynamic `RigidBody3D`/`2D` gets a velocity write; a kinematic body
+  slides** (`moveAndSlide`, so a knockback never throws anyone through a
+  wall); a plain node is nudged. `revive()` clears a kick and stagger still
+  running, so a respawn does not arrive flying backwards from the blow that
+  killed it.
+- Sized from the games that measured it: a sword on a brute `knockback 4`
+  (0.3 m), a club on the player `knockback 7, knockUp 2.5` (0.5 m back and a
+  hop), a bolt on a 2D goblin `knockback 240` px/s (18 px), a goblin on a 2D
+  knight `knockback 420, knockbackSeconds 0.22, knockUp 360, staggerSeconds
+  0.22` (30 px against a held stick, 33 px up).
 
 **A dead Health STAYS dead until you revive it.** `damage`, `heal` and regen all
 no-op once it has died — which is what makes a lives system work at all, and
@@ -283,7 +387,9 @@ Signals: `totalChanged(total)` — Methods: `collect(value)` — state: `total`
 
 Deals damage to whatever it touches — projectiles, spikes, lava, enemy hitboxes.
 **Goes on an Area.** On `triggerEnter`, finds the contacted entity's `Health` and
-calls `damage(amount)`, then emits `dealtDamage(amount, healthOwnerNode)`.
+calls `damage(amount, from)` — `from` being this Area's own world position, so a
+target with `Health.knockback` is shoved away from the hitbox that struck it —
+then emits `dealtDamage(amount, healthOwnerNode)`.
 
 | Prop | Default | Meaning |
 |---|---|---|
@@ -471,6 +577,7 @@ author markers). Emits `reachedPoint(index)` on arrival.
 | `mode` | `"loop"` | `'loop'` wraps · `'pingpong'` reverses at the ends |
 | `pauseAt` | `0` | seconds to wait at each reached point |
 | `moveParent` | `false` | move the PARENT node instead of this one |
+| `requireSight` | `false` | a static-only ray from half a metre over the mover to half a metre over the target must reach it — a wall or a crate between means no target, and the hound waits instead of walking into the wall forever. `chasing` reads the node being chased this frame, or null |
 | `ground` | `null` | chase along the GROUND — the target's height is not a direction. `null` = yes for a `CharacterBody3D` mover, no for anything else; `true`/`false` overrides |
 | `facePath` | `""` | node path to TURN toward the direction of travel (e.g. `"../Skin"`) |
 | `turnSpeed` | `100` | turn rate rad/s; 100 is an instant snap |
@@ -500,6 +607,66 @@ body puts `Patrol` on a CHILD. Without it a patrolling body had to carry
 `Patrol` itself and could hold nothing else — a patrolling enemy you could not
 hurt.
 
+## ChaseCamera
+
+A camera BEHIND something that turns — a car, a boat, a tank, a horse. `FollowCamera`
+keeps a fixed WORLD offset, which is right for a top-down or side view and wrong for a
+vehicle: the offset has to swing round with the target's heading, and lazily, or
+every corner snaps the view. Four examples (a van, a boat, a car, a race car) wrote
+this by hand before it existed. Aim the camera with `Camera3D.lookAt`; this places it.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `target` | `""` | the node to sit behind (required) |
+| `back` | `8` | how far behind, along the target's heading (m or px) |
+| `up` | `3` | how far above it (3D) |
+| `smoothing` | `0.85` | 0..1 retention per 60 Hz frame of the followed heading AND position — 0 rigid, 0.9 lazy; a chase camera switched on across the map flies in instead of snapping (`snap()` places it at once) |
+
+```json
+{ "name": "Camera", "type": "Camera3D", "props": { "current": true, "lookAt": "/root/Car" },
+  "script": { "name": "ChaseCamera", "props": { "target": "/root/Car", "back": 9, "up": 4 } } }
+```
+
+The heading is read from the target's rotation BASIS, not from `rotation[1]`: a tilted
+hull past 90° of yaw spells its Euler XYZ triple `[180, 180−yaw, 180]`, and a camera that
+read the middle number swung to the wrong side. `heading` (radians) is readable for a
+harness; `enabled: false` parks it (an errand game turns it on when the player boards).
+
+## GroupCamera
+
+One camera, several players — the couch co-op camera. `FollowCamera` follows ONE
+target and `ChaseCamera` rides behind ONE character, so a game with two players
+at the same keyboard had nothing that framed a PAIR: whoever the camera was on
+could walk the other player off the screen, and their half of the game went with
+them.
+
+```json
+{ "name": "Camera", "type": "Camera3D", "props": { "current": true, "fov": 48 },
+  "script": { "name": "GroupCamera",
+              "props": { "targets": "player", "offset": [0, 15, 11],
+                         "minZoom": 0.9, "maxZoom": 2.1, "smoothing": 0.18 } } }
+```
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `targets` | `"player"` | the GROUP whose members are framed — members joining and leaving are picked up as they come |
+| `offset` | `[0, 12, 14]` | where the camera sits relative to the group's centre, at zoom 1 |
+| `minZoom` / `maxZoom` | `1` / `2.5` | how far that offset may shrink and stretch to fit everyone |
+| `padding` | `0.25` | fraction of the view kept clear around the furthest pair |
+| `smoothing` | `0.15` | easing; `0` snaps |
+| `lookAtGroup` | `true` | keep aiming at the centre (a camera that only moves goes cross-eyed) |
+
+State: `zoom`, `centre`. Methods: `snap()` — after a teleport or a scene swap.
+
+**Take the characters off camera duty.** `CharacterController3D` drives the
+scene's current camera in every view it has, so every player's controller needs
+`"camera": "none"` or they fight this behaviour (and each other) for the same
+camera, every frame. `incanto-check` says so when it sees both.
+
+Measured on `examples/coop-3d`: shoulder to shoulder the camera sits 11.8 m up;
+sent to opposite corners it climbs to 29.3 m, and `describeFraming` reports both
+players still on screen.
+
 ## Chase
 
 Homing enemy AI: each frame moves toward `target.position` at `speed`, stopping
@@ -643,6 +810,56 @@ is a far worse failure than one running when it was meant to sleep.
 
 From TypeScript it is the same switch: `this.getNode('../Hunt').behavior.enable()`.
 
+## Sight (eyes for a watcher)
+
+Five examples cast their own sightline — a cone, a range, a static-only ray
+from eye to chest — and `Chase` and `Turret` cast none: an enemy chased you
+through a wall and a turret shot you through one. `Sight` is the built-in
+eye, on a child of the watcher's body:
+
+```json
+{ "name": "Guard", "type": "CharacterBody3D", "children": [
+  { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$base" } },
+  { "name": "Eyes", "type": "Node",
+    "script": { "name": "Sight", "props": { "range": 12, "coneDeg": 70, "fillSeconds": 1 } } },
+  { "name": "Hunt", "type": "Node",
+    "script": { "name": "Chase", "props": { "target": "%Player", "enabled": false } } }
+] }
+```
+```jsonc
+{ "signal": "spotted", "from": "Guard/Eyes", "to": "Guard/Hunt", "handler": "enable" },
+{ "signal": "lost",    "from": "Guard/Eyes", "to": "Guard/Hunt", "handler": "disable" }
+```
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `range` | `12` | how far it sees (m) |
+| `coneDeg` | `70` | the FULL cone angle; `360` = all round |
+| `targetGroup` | `player` | only nodes in this group are seen |
+| `facingPath` | `../Skin` | the node whose yaw is the look direction (+Z-forward — the Skin the controller turns); `''` = the body's own rotation |
+| `eyeHeight` / `chestHeight` | `0.6` / `0.3` | where the ray starts above the watcher's position, and where it aims above the target's |
+| `fillSeconds` | `0` | seconds of being seen before `spotted`; `0` = the first frame. Draining back takes as long |
+| `los` | `true` | a STATIC-only ray from eye to chest must reach the target — walls and crates hide you, other guards do not |
+
+Signals: `spotted(node)` when `suspicion` reaches 1, `lost(node)` when it
+drains to 0 — once each, an edge, so a connection can flip a state and a
+game can hang an alarm on it. Readbacks any frame: `sees(node)`, `seen()`
+(nearest first), `target` (the nearest), `suspicion` (0..1 — a HUD's
+"detection" bar is this number).
+
+In 2D it is the same eye on the x/y plane: the watcher faces along its
+scalar `rotation` (0 = +x, positive clockwise on the y-down screen) or the
+node at `facingPath`, `eyeHeight`/`chestHeight` are ignored, and the ray is
+the 2D adapter's.
+
+It runs headless — the ray is the physics adapter's — so a harness can stand
+the player behind a crate and ask `sees()`. `examples/stealth-3d`'s guards
+see with it, and the enemy that changes its mind above is now three
+connections and no code. `Chase` and `Turret` cast the same ray themselves
+with `requireSight: true` — a hound behind a wall waits, a turret holds its
+fire — so a simple enemy needs no `Sight` at all, and a guard with a
+detection meter wants both.
+
 ## Turret
 
 The oldest verb in games: the nearest live member of `targetGroup` within
@@ -660,14 +877,67 @@ target and `Projectile` for the bullet, and nothing that decides to shoot.
 |---|---|---|
 | `targetGroup` | `"enemy"` | who it shoots — the nearest LIVE member (a dead `Health` is skipped) |
 | `range` | `6` | reach, in the scene's units |
+| `requireSight` | `false` | a static-only ray from the turret to the target must reach it — no firing through walls |
 | `damage` | `10` | hitscan damage per shot (`target.behavior.damage(n)`) |
 | `cooldown` | `0.6` | seconds between shots |
 | `shelf` + `prefab` | `""` | fire a CLONE instead: a `PrefabShelf` and a template on it; each shot lands at the turret + `muzzle`, its `Projectile` pointed at the target, under `into` (default: the turret's parent). The clone does the hurting then — give it `DamageOnContact` and a `Lifetime` |
+| `muzzle` | `[]` | where clones start, relative to the turret — **in the `facePath` node's frame** when there is one, so the tip of a barrel stays the tip of the barrel as it turns |
 | `facePath` / `turnSpeed` | `""` / `100` | a barrel to turn toward the target |
+| `arc` | `"flat"` | `"low"` / `"high"` LOB a falling shell — see below |
 
 Signals: `acquired(target)` · `fired(target)` · `lost()`. Getters: `target`,
 `shots`. Dimension-agnostic — a 2D tower is the same node with `[x, y]`.
 
+### Lobbing: a shot that has to come DOWN on something
+
+A `prefab` with `Projectile.gravity` aimed STRAIGHT at its target is a shell
+that falls out of the sky on the way. Measured on the shipped tank game, whose
+enemy guns fire a 22 m/s shell with `gravity: 9.81`: at 28 m — comfortably
+inside their own 32 m `range` — every shell passed **6.5 m under the tank** and
+kept going down to −1100 m. They could only ever hit at point-blank range, and
+nothing said so.
+
+```json
+{ "name": "Gun", "type": "Node3D",
+  "script": { "name": "Turret",
+    "props": { "targetGroup": "player", "range": 150, "cooldown": 4.5,
+               "shelf": "/root/Shelf", "prefab": "Shell", "into": "/root/Shots",
+               "facePath": "../Barrel", "muzzle": [0, 0, 2.6], "arc": "low" } } }
+```
+
+- `"low"` is the flat, fast arc; `"high"` is the mortar's — the SAME landing
+  point, a much taller flight, and the one that clears a wall in between.
+- The angle is solved from the shell's own `speed` and `gravity` (read off the
+  template on the shelf, so the numbers can never disagree), from the MUZZLE,
+  which is where the shell actually starts.
+- The `facePath` barrel is ELEVATED to match — `faceTravel` only ever wrote yaw,
+  so a lobbing gun used to point flat while its shells climbed.
+- Out of reach it fires at 45°, which is as far as that shell can go: a gun that
+  falls short in front of you is honest, a gun that silently holds fire is not.
+- `arc` on a prefab whose `Projectile` has no `gravity` is a hard error — there
+  is nothing to arc against, and a silent no-op would be a gun that looks aimed.
+
+The same arithmetic is yours to use directly — an aiming line, a grenade toss, a
+catapult, a basketball:
+
+```ts
+import { ballisticAim, ballisticPath, maxRangeAim } from 'incanto/gameplay';
+
+const dir = ballisticAim(from, target, speed, 9.81, 'high');   // null = out of reach
+const path = ballisticPath(from, dir ?? aim, speed, 9.81, {
+  seconds: 14,
+  stop: (at) => (at[1] ?? 0) <= groundHeightAt(at[0] ?? 0, at[2] ?? 0),
+});
+```
+
+**Draw the preview with `ballisticPath`, not with a parabola of your own.**
+`Projectile` integrates step by step (the fall accumulated first), and a
+closed-form curve drifts from it — measured at **ten metres** over an
+eight-second flight, which is the difference between a hit and a crater in the
+wrong field. `ballisticPath` walks exactly what the shell will fly; the beads
+and the crater then land on the same spot (0.1 m apart over 120 m in
+`examples/artillery-3d`).
+
 ## FaceTarget
 
 Turn toward the nearest thing in a group and say when you are pointed at it —
@@ -709,8 +979,9 @@ every shop, build mode, upgrade tree and economy game wrote its own wallet.
 | `amount` | `0` | what you start with |
 | `max` | `0` | ceiling (0 = none) |
 
-Signals: `changed(amount)` · `earned(gain)` · `spent(cost)` · **`refused(cost)`**
+Signals: `changed(amount)` · `earned(taken)` · `spent(cost)` · **`refused(amount)`**
 Methods: `spend(cost) -> boolean` · `earn(gain)` · `canAfford(cost)` · `setAmount(n)`
+State: `room` (how much more it can hold; `Infinity` with no ceiling)
 
 ```ts
 if (!wallet.spend(TOWER_COST)) return;   // `refused` already fired for the HUD
@@ -721,6 +992,13 @@ placeTower(pad);
 "you cannot afford that" is one wire to a banner. It saves through `serialize()`
 like `Health` and `ScoreKeeper`.
 
+**A CEILING refuses too.** `earn` takes what fits, emits `earned` with what it
+actually TOOK, and emits `refused` with the remainder — so a pickup that will
+not fit can stay on the floor. This clamped silently and said `earned(gain)`
+anyway: measured on a game whose purse holds four, the fifth ember vanished off
+the ground, the HUD read `4 / 4`, and nothing anywhere had the ember. `room` is
+the question to ask before offering.
+
 A NON-POSITIVE amount is ignored, the way `Health.damage`/`heal` have always
 ignored one — and a negative is reported, because it is a sign flip in the
 caller rather than an offer. `spend(-5)` used to PAY you five (any negative
@@ -829,6 +1107,58 @@ disconnect, or pass `{ owner: someNode }`.)
 Same `ZombieSkin` is the place to also FACE the heading and GROUND the body each frame
 (see incanto-3d-character.md "+Z-FORWARD rule" and incanto-3d-models.md "Grounding").
 
+## Mount
+
+Get on something and drive it; get off beside it. A horse, a car, a boat, a
+turret seat: the rider's controller lets go, the rider's body PARKS (collider
+off, hidden, weightless, riding along so everything that targets the rider
+follows), the rider's `skin` moves onto the steed's `saddle`, and the steed's
+`drive` — a `CharacterController3D` or a `Vehicle3D` — is enabled. `dismount()`
+puts everything back beside the steed, on its right, and hands the camera yaw
+back. Two examples (`errands-3d`'s car, `steed-3d`'s horse) wrote these sixty
+lines before it existed, and each forgot something the other remembered.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `rider` | `""` | the player's body (required) |
+| `steed` | `".."` | the thing ridden — this node's parent |
+| `drive` | `""` | the steed's controller / vehicle whose `enabled` flips (default: the first child that has one) |
+| `walk` | `""` | the rider's controller whose `enabled` flips (default: the first child that has one) |
+| `skin` | `"Skin"` | a child of the rider carried onto the saddle (`""` = nothing moves) |
+| `saddle` | `""` | where it sits while mounted — a node under the steed (`""` = the steed itself) |
+| `skinOnSaddle` / `skinOnRider` | `[0,0,0]` | the skin's local position there, and back |
+| `dismountAt` | `[1.8, 0.3, 0]` | where the rider stands afterwards, in the steed's frame (+x = its right) |
+
+Methods: `mount()`, `dismount()`, `toggle()` — signals `mounted(steed)`, `dismounted(steed)`;
+`mounted` reads back.
+
+```json
+{ "name": "Horse", "type": "RigidBody3D", "props": { "fixedRotation": true, "friction": 0, "mass": 400,
+    "collider": { "shape": "capsule", "radius": 0.7, "height": 1 } },
+  "children": [
+    { "name": "Ride", "type": "CharacterController3D", "props": { "enabled": false, "maxSpeed": 7, "jumpVelocity": 6.5 } },
+    { "name": "Skin", "type": "Node3D", "children": [ { "name": "Saddle", "type": "Node3D", "props": { "position": [0, 1.7, -0.15] } } ] },
+    { "name": "Whistle", "type": "Node3D", "script": { "name": "Interactable", "props": { "range": 3.2, "prompt": "ride" } } },
+    { "name": "Reins", "type": "Node", "script": { "name": "Mount",
+        "props": { "rider": "/root/Player", "saddle": "../Skin/Saddle", "skinOnRider": [0, -0.85, 0] } } }
+  ] }
+```
+```json
+{ "signal": "interacted", "from": "Horse/Whistle", "to": "Horse/Reins", "handler": "toggle" }
+```
+
+- **Keep the steed OUT of the Interactable's `actorGroup`.** A horse that is in
+  `player` (so the wolves' `DamageOnContact` can bite it) is its own nearest
+  actor, at distance 0, and its prompt is focused from anywhere. Give the bites
+  their own group (`prey`: the player and the horse) and leave `player` to the
+  walker.
+- Two `CharacterController3D`s in one scene is what this is; `incanto-check`
+  used to warn that both drive the same camera — it skips one authored
+  `enabled: false` now.
+- The parked rider rides along every frame, so a `Chase` aimed at the player
+  follows the horse, and a bite that reaches the horse's body hurts the HORSE
+  (its own `Health`), not the parked rider.
+
 ## MoveTo
 
 Eased position tween from the start to a fixed `to` over `duration` seconds —
@@ -842,7 +1172,9 @@ opening doors, sliding platforms, scripted moves. Emits `arrived` once.
 | `ease` | `"easeInOut"` | one of `linear` · `easeIn` · `easeOut` · `easeInOut` |
 | `startOnSignal` | `false` | defer until `start()` (default: begin at ready) |
 
-Signals: `arrived` — Methods: `start()`
+Signals: `arrived` — Methods: `start()`, `finish()` (land on `to` NOW and say
+`arrived` once — a skipped cutscene must leave the door it opens OPEN; wire
+`skipped → Door.finish`).
 
 ```json
 { "name": "Platform", "type": "Node2D", "props": { "position": [0, 100] },
@@ -873,6 +1205,168 @@ cuts, a swinging gate blocks. (Before 0.62 it turned only the mesh: a body's
 angle was applied once at creation and never followed again, so every spinner
 built this way was decoration.)
 
+## Blast
+
+Hurt everything NEAR a point — a grenade, a rocket, a barrel, a keg, a boss's
+ground slam. `DamageOnContact` is a HITBOX (it hurts what touches it) and an
+explosion is not one, so every explosive game wrote the radius query, the
+falloff and the direction of the shove itself.
+
+Put it on a CHILD of the thing that explodes, the way `Shatter` sits under what
+breaks. A keg with a fuse is then four built-ins and NO TypeScript:
+
+```json
+{ "name": "Keg", "type": "Node3D", "groups": ["keg"],
+  "script": { "name": "Lifetime", "props": { "seconds": 2.4 } },
+  "children": [
+    { "name": "Vitals", "type": "Node3D",
+      "script": { "name": "Health",
+                  "props": { "max": 1, "freeOnDeath": true, "freeParent": true } } },
+    { "name": "Boom", "type": "Node3D",
+      "script": { "name": "Blast",
+                  "props": { "when": "expired,died", "radius": 4.6, "damage": 90,
+                             "groups": "crate,enemy,player,keg" } } },
+    { "name": "Bits", "type": "Node3D",
+      "script": { "name": "Shatter", "props": { "when": "expired", "pieces": 10 } } }
+  ] }
+```
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `radius` | `4` | how far it reaches, in the scene's units |
+| `damage` | `40` | damage at the CENTRE |
+| `falloff` | `"linear"` | fades to nothing at the rim; `"none"` hits everything inside for the full `damage` (what a grid game wants) |
+| `groups` | `""` | comma-separated groups to hurt; empty hurts EVERYTHING with a `Health` in reach, the player included — an explosion does not check whose side you are on |
+| `when` | `"died"` | comma-separated signals on the PARENT that set it off (`Lifetime` emits `expired`, `Health` emits `died`); `""` = only `blast()` |
+| `self` | `false` | whether the carrier's own `Health` is in the blast (a mine that must destroy itself says `true`) |
+| `throughWalls` | `true` | `false` casts a static-only ray at each victim, so a pillar shields what is behind it |
+
+Signals: `blasted(count)`. Methods: `blast()` (returns how many it hurt) —
+state: `spent`.
+
+- **A victim is measured where its BODY is**, not where its `Health` node sits.
+  A health hangs on a child with no transform of its own, so the blast walks up
+  to the nearest thing with a position. It used to ask every node in the tree
+  "is there a health under you", which the scene ROOT always answers — with the
+  shallowest health in the whole game, measured at the root's own origin, and
+  then marked as already considered. Every scene lost exactly one victim to its
+  own root; measured on a keep game, a firepot at the player's feet reported
+  **0 hits**.
+- **The damage carries the blast's own position**, so a `Health` with
+  `knockback` is thrown AWAY from the crater without anyone writing a
+  direction. Measured: a keg 1.2 m away throws the player 1.1 m.
+- **A chain reaction is not a feature.** A keg's own `Health` is one of the
+  things a blast can damage, and `when: "expired,died"` means "my fuse ran out,
+  OR someone else's blast killed me". `examples/bomb-3d` codes no chain.
+- **It goes off once.** A keg caught in two blasts explodes once, and `spent`
+  says so.
+- `throughWalls: false` knows two things a line-of-sight test has to know about
+  a BOMB: the floor it is lying on is not a wall (a ray from y=0 on a surface at
+  y=0 reports a hit at zero distance — measured, `0.00 m → /Floor`), and a
+  crate solid enough to walk into is not a wall between the blast and ITSELF.
+
+## Shatter
+
+Break a thing into pieces that fly, tumble and vanish. Every game with a
+crate wants it to burst — pots, barrels, a wall of boxes, the rock you
+blast — and `Health` + `freeOnDeath` only made a crate VANISH. Put `Shatter`
+on a child of the breakable body (the way `Respawn` sits under the player),
+or on the body itself:
+
+```json
+{ "name": "Crate", "type": "RigidBody3D", "groups": ["breakable"],
+  "props": { "mass": 8, "collider": { "shape": "box", "size": [1, 1, 1] } },
+  "script": { "name": "Health", "props": { "max": 1 } },
+  "children": [
+    { "name": "Mesh", "type": "MeshInstance3D",
+      "props": { "material": { "color": "#a0703a", "roughness": 0.9 }, "castShadow": true } },
+    { "name": "Shards", "type": "Node3D", "script": { "name": "Shatter", "props": { "pieces": 8 } } }
+  ] }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `pieces` | `8` | how many fragments — a grid of smaller boxes cut from the body's mesh |
+| `impulse` | `4` | outward speed, m/s (2D: ×100 px/s) |
+| `spin` | `6` | random tumble, rad/s |
+| `lifetime` | `2.5` | seconds the pieces lie there before they are swept up; `0` = they stay |
+| `when` | `"died"` | the breakable's signal that breaks it — `Health` emits `died`; `""` = only `break()` |
+| `mesh` | `""` | the `MeshInstance3D` (2D: `ColorRect2D`/`Sprite2D`) whose size and material the pieces copy; `""` = the first one under the body |
+| `free` | `true` | free the breakable when it breaks |
+
+- When the body's `died` fires (or `break()` is called), `pieces` fragments of
+  the body's own mesh and material are built where it stood, each its own
+  `RigidBody3D` with a box collider, flung outward with a tumble and carrying
+  a `Lifetime`; the body's collider is switched off and the body freed FIRST,
+  so the pieces are not born inside it. `shattered(body)` fires on the
+  Shatter's node.
+- 2D bodies burst into `RigidBody2D` + `ColorRect2D` pieces of the rect's
+  colour (or the sprite's `tint`).
+- Everything is drawn from `engine.rng`, so a seeded run breaks the same way
+  twice — a replay shows the same tumble.
+- A `StaticBody3D` breaks too (`when: ""` and `break()` from your own trigger —
+  a wall you blast, a floor that gives way).
+- Composed in `examples/smash-3d` ("Smash Depot": a bat, twelve crates, three
+  barrels that take two hits and bite back, a key in one of the crates).
+
+## Carry
+
+The physics hand: pick a thing up, carry it in front of you, drop it, throw
+it. "Pick up the box" is the first physics thing a player tries and the first
+thing an author asks for, and the engine had no route to it — a joint made at
+runtime hangs the crate's weight on the hover spring and the player sinks; a
+kinematic swap loses the collisions. Put `Carry` on a child of the player's
+body (the way `Respawn` sits under it) and declare the actions:
+
+```json
+{ "name": "Player", "type": "RigidBody3D", "props": { "…": "…" },
+  "children": [
+    { "name": "Controller", "type": "CharacterController3D" },
+    { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$avatar" } },
+    { "name": "Hands", "type": "Node3D", "script": { "name": "Carry", "props": { "range": 2.2, "maxMass": 30 } } }
+  ] }
+```
+```json
+"input": { "grab": { "type": "button", "keys": ["KeyE"] }, "throw": { "type": "button", "keys": ["KeyQ"] } }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `action` | `"grab"` | press: pick up the nearest carryable in reach, or drop what is held |
+| `throwAction` | `"throw"` | press: throw what is held; `""` = no throwing |
+| `range` | `2.2` | how far from the hand a thing may be to pick up (m) |
+| `group` | `"carryable"` | only bodies in this group can be carried (`RigidBody3D` only — a static thing is the world) |
+| `maxMass` | `30` | heavier than this stays where it is — you can still PUSH it |
+| `holdDistance` / `holdHeight` | `1.2` / `0.5` | where the held thing rides: ahead of the body's origin, and above it (m) |
+| `throwSpeed` | `9` | m/s forward, with a little lift |
+| `gain` | `14` | how stiffly the held thing follows the hand (1/s) |
+| `inheritMotion` | `1` | how much of the THROWER's own motion goes with the throw (0..1). A throw used to WRITE the velocity, so a docker sprinting at the rail threw exactly as far as one standing at it — and one running backwards threw just as hard forwards. `0` is that old absolute throw, for a game that wants the arcade answer |
+| `facePath` | `"../Skin"` | the node whose yaw is "ahead" (+Z-forward, as `CharacterController3D` turns the skin); `""` = the body's own rotation |
+
+- A held body keeps its collider and loses its gravity: it is DRIVEN toward
+  the hand every step (capped at 12 m/s), tumble damped, so a held crate
+  still stops at a wall, pushes a door and rests on whatever you set it on.
+- Drop it on a shelf and it stays; drop it over a ledge and it falls; a
+  crate that is freed while in hand (shattered) leaves the hand empty.
+- Signals `grabbed(body)`, `dropped(body)`, `thrown(body)`; readback `held`.
+- `throwAction: ""` is a game with no throwing, and the engine says nothing
+  about it — an empty action name is an off switch everywhere in this engine,
+  never a typo.
+- Stack two crates and the character climbs them like any step (the hover
+  spring's `stepHeight`, or a jump) — that is the whole "stack boxes to
+  reach the ledge" puzzle, with no code.
+- **Pushing is mass.** A thing over `maxMass` can still be shoved by walking
+  into it — but the controller's push scales with the PLAYER's mass, and the
+  default `RigidBody3D` mass is 1 kg, which shoves nothing (measured: a 1 kg
+  porter against a 2 kg crate on a concrete floor, no movement). Give the
+  player `mass: 70` and a walk moves a crate, a run moves a safe on casters.
+  And a static floor's authored `friction` WINS the pair (the pad rule), so a
+  low-friction body on a `friction: 0.9` floor is glued: leave the floor at
+  its default and author the casters on the body.
+- Composed in `examples/porter-3d` ("Porter": four crates onto the truck, one
+  on a shelf you need a stack to reach, a bell to throw at, a safe you can
+  only push).
+
 ## Buoyancy
 
 Float on water. Hangs on a `RigidBody3D` and asks the water how high it is at
@@ -900,10 +1394,23 @@ wire them to a splash `Particles3D`, a sound, or a "you dropped the cargo" rule.
   "script": { "name": "Buoyancy", "props": { "draft": 0.25, "size": [2.4, 1.4], "drift": 0.8 } } }
 ```
 
+The other way to float is the PROP: `RigidBody3D.buoyancy` (see "Things
+that float" in `incanto-environment.md`) is Archimedes on the collider — mass
+against volume decides, nothing is authored, and there is no `drift`. This
+behaviour is for a waterline you want to author and a swell you want the
+body to wander with; the prop is for a body whose weight should decide. One
+or the other on a body, never both.
+
 `drift` is the part players notice: a wave face is a slope, and a floating
 thing slides down it, so a raft left alone wanders with the swell instead of
-bobbing on the spot. The lift is capped at a few g — water pushes back, it
-never launches a body that has been dragged deep.
+bobbing on the spot. The lift is capped at a few g — water pushes back — and
+**it can never launch the body**: it may not leave a body rising faster than
+gravity alone would have carried it up from the waterline, zero at the line
+itself. A 50-gram bobber cast into a pond used to ride six g up from half a
+metre under and leave the water at six metres a second, into the air and back,
+eighty-eight crossings in four seconds; every shipped float had started AT the
+surface and nothing had ever been thrown in. A cork now goes under, comes up
+and sits — `examples/fishing-3d` is the cast.
 
 **The lift cancels gravity AT the waterline**, so the hull holds that line
 instead of sinking until a spring happens to match its weight. That is what
@@ -948,7 +1455,10 @@ this.node.getNode('/Game/Towers').addChild(tower);
 |---|---|---|
 | `prefabs` | `""` | comma-separated child names to take; empty takes them ALL |
 
-Methods: `make(name)` · `names()`
+Methods: `make(name)` · `names()` · `template(name)` — the held template itself,
+to ASK it something (what `Turret.arc` reads a shell's speed and gravity off,
+rather than re-declaring those numbers where they could disagree). Never change
+what it hands back: every future clone is a copy of it.
 
 **Listen before it enters the tree.** A clone placed where a body already is —
 an XP orb dropped at the player's feet — is collected on its very first physics
@@ -1133,7 +1643,12 @@ Mid-flight, writing `direction` or `speed` re-bakes immediately (the fall
 `gravity` has accumulated is kept — it is a fact about the world, not about the
 shot). What is deliberately NOT live is `rotation` after that first step: a
 projectile that spins for looks must not have its spin become its trajectory.
-Call **`aim()`** to re-derive from the current rotation on purpose:
+Call **`aim()`** to re-derive from the current rotation on purpose — and
+**`aim(direction, carry)`** to add the SHOOTER's velocity: a shell fired from a tank
+doing 16 m/s left the muzzle at the standing tank's 30 m/s until it did, so a tank
+could outrun its own shot and a sideways shell landed behind what the barrel pointed
+at. `carry` is added once, at launch (`examples/tank-3d`'s `Gunner` passes the hull's
+`linearVelocity`):
 
 ```ts
 bolt.rotation = newHeadingDeg;
@@ -1455,6 +1970,90 @@ can only click is not playable on a controller.
 The pause key is polled in `update()`, which still runs at `timeScale 0` — a
 menu that cannot be closed by the key that opened it is worse than no menu.
 
+### The whole shell, without a script
+
+A title screen and an options panel are the other two screens every shipped game
+has, and the hard one is BACK: options open from the title AND from the pause
+menu and have to return to whichever asked. Two more props and seven
+`connections` rows are the entire thing:
+
+```json
+{ "root": { "name": "Game", "type": "Node3D",
+    "script": { "name": "GameFlow", "props": { "titlePanelPath": "/root/HUD/Title" } },
+    "children": [
+      { "name": "HUD", "type": "HudLayer", "children": [
+        { "name": "Title", "type": "UiPanel", "props": { "anchor": "center" }, "children": [
+          { "name": "Play", "type": "UiButton", "props": { "text": "PLAY" } },
+          { "name": "Options", "type": "UiButton", "props": { "text": "OPTIONS" } } ] },
+        { "name": "PauseMenu", "type": "UiPanel", "props": { "visible": false }, "children": [
+          { "name": "Resume", "type": "UiButton", "props": { "text": "RESUME" } },
+          { "name": "Options", "type": "UiButton", "props": { "text": "OPTIONS" } },
+          { "name": "Restart", "type": "UiButton", "props": { "text": "RESTART" } } ] },
+        { "name": "Options", "type": "UiPanel", "props": { "visible": false }, "children": [
+          { "name": "Back", "type": "UiButton", "props": { "text": "BACK" } } ] }
+      ] }
+    ] },
+  "connections": [
+    { "from": "/root/HUD/Title/Play", "signal": "pressed", "to": ".", "handler": "resume" },
+    { "from": "/root/HUD/Title/Options", "signal": "pressed", "to": ".",
+      "handler": "screen", "args": ["/root/HUD/Options"] },
+    { "from": "/root/HUD/PauseMenu/Resume", "signal": "pressed", "to": ".", "handler": "resume" },
+    { "from": "/root/HUD/PauseMenu/Options", "signal": "pressed", "to": ".",
+      "handler": "screen", "args": ["/root/HUD/Options"] },
+    { "from": "/root/HUD/PauseMenu/Restart", "signal": "pressed", "to": ".", "handler": "restart" },
+    { "from": "/root/HUD/Options/Back", "signal": "pressed", "to": ".", "handler": "back" }
+  ] }
+```
+
+| prop / method | what it does |
+| --- | --- |
+| `titlePanelPath` | a screen shown at BOOT, holding the world (`""` = start playing) |
+| `saveSlots` | the `SaveSlots` namespace this game keeps saves in (`""` = no saving) |
+| `screen(path)` | push a screen over whatever is up; freezes the world if it was running |
+| `back()` | close the top screen and show **whoever asked** — the title, or the pause menu |
+
+`back()` with nothing left on the stack and no menu under it RESUMES, so a screen
+opened during play (an inventory, a map) closes back into the game.
+
+### SAVE and CONTINUE, from the same menu
+
+`SaveSlots`, `captureState` and `restoreState` have been there since 0.62 and no
+shipped starter used any of them: a scaffolded game could not be closed and come
+back. The API was never the problem, the SEQUENCE was — write a slot, reload the
+scene from source, wait for the reload, restore by uid. `restart()` is already
+the engine's verb for "reload this scene"; these are its two siblings.
+
+```json
+{ "from": "/root/HUD/PauseMenu/Save",     "signal": "pressed", "to": "/root/Flow", "handler": "save" },
+{ "from": "/root/HUD/PauseMenu/Continue", "signal": "pressed", "to": "/root/Flow", "handler": "continueFrom" }
+```
+
+| method | what it does |
+| --- | --- |
+| `save(slot = "1")` | write this scene's behaviour state into the slot; `false` and an error if `saveSlots` is empty |
+| `hasSave(slot = "1")` | is there something to come back to (a CONTINUE button asks this) |
+| `continueFrom(slot = "1")` | reload the scene and hand every behaviour its state back |
+
+**WHEN to save is still yours** — the rule in `incanto-save-slots.md` stands,
+there is no autosave, and `save` is a handler you wire to whatever signal marks
+the moment: a checkpoint, a level end, a button.
+
+**A save belongs to the SCENE that wrote it.** `continueFrom` checks the scene's
+name and refuses a slot from another one, saying so — routing between levels is
+the game's, because the engine has no map of them. A multi-scene game loads the
+right scene first and then restores (see `incanto-save-slots.md`).
+
+Composed in `examples/beacon-isle-3d` — the template `incanto-new` scaffolds by
+default — as two buttons in its pause menu.
+
+**Author every screen that is not up at boot with `"visible": false`.** `GameFlow`
+owns the visibility of the ones it knows about — the title, the pause menu, and
+any screen it has been asked to open — and it cannot hide one it has never seen.
+
+`examples/shell-3d` is the whole shell composed this way: seven rows of JSON, and
+its behaviour file keeps only the clock, the best time and the two settings the
+game itself invented.
+
 **Give the Flow its own node.** A node holds one behavior, and your root
 probably already carries the game's director script.
 
@@ -1557,10 +2156,11 @@ parented to a rock: `position` is `[0, 3.02, 0]` and the world point is
 `[13, 14.31, 80.18]` — **82 m apart**.
 
 ```ts
-import { localFromWorld, worldPosition } from 'incanto/gameplay';
+import { localFromWorld, worldDirection, worldPosition } from 'incanto/gameplay';
 
 const here = worldPosition(crate);              // [13, 14.31, 80.18]
 crate.position = localFromWorld(crate, [0, 20, 0]);   // put it at world [0,20,0]
+const forward = worldDirection(barrel, [0, 0, 1]);    // which way it POINTS
 ```
 
 Both work headless and in both dimensions — arity comes from the node (2 for a
@@ -1569,10 +2169,15 @@ nothing. Do NOT reach for `_ensureObject3D().matrixWorld`: it is internal, and
 in a headless verify script there is no renderer to parent the object, so it
 hands back the LOCAL position with no warning.
 
-**Translation only.** They sum ancestor positions and ignore ancestor rotation
-and scale — the same contract physics already uses (`worldPosition2D` /
-`worldPosition3D`) and that `applyGroundSnap` assumes. A node under a ROTATING
-parent needs the renderer's matrix, not this.
+**Rotation composes.** Every ancestor's turn is applied on the way down, the
+same as the renderer and physics do — a muzzle two metres down the +z of a
+turret that is itself yawed on a hull reports where it is DRAWN. (It sums
+positions and rotations; scale is still ignored.)
+
+`worldDirection(node, local)` is the direction half: a local vector turned by
+the node's own rotation and every ancestor's. `worldDirection(node, [0, 0, 1])`
+is the +Z-forward convention every 3D skin here follows, and it is what a barrel
+tip, a hardpoint or a chase camera wants. Two games wrote it by hand first.
 
 ## Persistence (high scores, unlocks, settings)
 
@@ -1614,3 +2219,46 @@ through the crate in the way. `facePath`/`turnSpeed` turn a node (a skin, a
 hull) toward the direction of travel, the way every other mover does — a ship
 on a rail flew every bend sideways without it. Corners never eat frame budget — the
 speed is exact across bends.
+
+**A rail you place in the editor.** `path` names the node whose CHILDREN are the
+waypoints, in tree order, in world space — no `setPath` call, no sorting by a
+tag — and `autoStart: false` holds the rig until `start()`, a handler a
+connection can name (a cutscene camera waits for its cue). A `path` that
+resolves to nothing is a load error, not a rig that stands still.
+
+```json
+{ "name": "Rail", "type": "Node3D", "children": [
+    { "name": "W0", "type": "Node3D", "props": { "position": [-16, 3.8, 13] } },
+    { "name": "W1", "type": "Node3D", "props": { "position": [-6, 4.6, 8] } },
+    { "name": "W2", "type": "Node3D", "props": { "position": [9, 3.2, -3] } } ] },
+{ "name": "CamRig", "type": "Node3D",
+  "script": { "name": "PathFollow", "props": { "path": "../Rail", "speed": 4.5, "autoStart": false } },
+  "children": [ { "name": "IntroCam", "type": "Camera3D", "props": { "lookAt": "/root/Vault/Door" } } ] }
+```
+
+## A cutscene
+
+A cutscene is five things the engine already has, in order — `examples/heist-3d`
+("Vault") is the composition, and its `Director` behaviour is the recipe:
+
+1. **Take the camera**: `doorCam.makeCurrent()` — or from JSON,
+   `{ "signal": "triggerEnter", "from": "Vault/DoorTrigger", "to": "Vault/DoorCam", "handler": "makeCurrent" }`.
+   Give the door camera and the gameplay camera `blendSeconds: 0.6` and the
+   switch there and back FLIES instead of cutting (`makeCurrent(0.6)` asks once).
+   A rail shot is a `Camera3D` under a `PathFollow` rig with `path` + `autoStart: false`, started on cue.
+2. **Let go of the player**: `CharacterController3D.enabled = false` (and zero
+   its velocity); **freeze what could hurt them**: each guard's `Patrol`,
+   `Chase` and `Sight` behaviours `enabled = false`, and its grab `Area3D`
+   `enabled = false` — a switched-off sensor overlaps nothing.
+3. **Bars and a line**: `hud.letterbox = 0.11`; `talk.say(...)` with
+   `autoAdvanceSeconds` on the `UiDialogue`, and wait for `dialogueFinished`.
+4. **The world changes on camera**: `door.start()` (`MoveTo`) and wait for
+   `arrived`.
+5. **Skip**: on the skip action, apply every remaining side effect at once —
+   `door.finish()`, `talk.clear()`, `rig.stop()` — then give everything back:
+   the gameplay camera `makeCurrent()`, the controller and the guards enabled,
+   `letterbox = 0`. A skipped cutscene leaves the world as the whole one would have.
+
+Offline (`incanto verify`, the editor's ▶ play) the same steps run; a harness
+reads `playing`, the current camera and the controller's `enabled` to prove
+the stick moves nobody during the shot and moves the player after it.