incanto 0.74.0 → 0.75.0

package/skills/incanto-3d-character.md

@@ -64,6 +64,13 @@ did not until now.
 | `maxJumps` | `1` | `2` = double jump. Extra jumps work in mid-air. |
 | `airControl` | `0.2` | how much ground control you keep airborne (0 = committed, 1 = full). |
 | `fallGravity` | `2.5` | gravity multiplier while falling. Higher = snappier arc. |
+
+And one that is about the CAMERA rather than the jump:
+
+| prop | default | what it buys |
+|---|---|---|
+| `pitchStart` | `0` | where the camera RESTS before anyone looks around, in degrees. Negative looks down; `-14` is a good third-person default. On a PHONE it stops being a nicety: a portrait screen is very tall, so a level camera spends its top half on sky and a player with no mouse cannot fix it before they start dragging. |
+| `mantleHeight` | `0` | the pull-up: on the way down from a jump, a ledge ahead no higher than this above the capsule's bottom is caught and pulled up onto. A jump a hand short of a roof is the most common near-miss in a platformer; try `0.9`. `0` = a jump near a wall feels exactly as it did. |
 | `wallJumpImpulse` | `[0, 0]` | `[away, up]` m/s — airborne and pressing INTO a wall, `jump` kicks off it: away along the wall's normal, up. Try `[6.5, 7]`. A fixed arc (the jump cut never halves it) and air control stands down for 0.18 s so the stick still pointing at the wall cannot steer the kick back into it. Emits `wallJumped(normal)`. |
 | `wallSlideSpeed` | `0` | max fall speed while pressing into a wall (`fallGravity` stands down too). Try `2`. |
 | `platformCarry` | `true` | ride whatever you are standing on. Off = the controller steers in WORLD space, so standing still on a moving floor brakes you off it (measured: 95.9% of a moving deck's travel kept, 0.0% with this off). |
@@ -71,6 +78,15 @@ did not until now.
 Every one defaults to OFF (`0` / `1`) or to the previous hard-coded constant, so
 a scene that asks for nothing behaves exactly as before.
 
+**Getting hit is the controller's too.** When the body's `Health` (on the body,
+or on a child such as `Vitals`) declares `knockback` / `knockUp` /
+`staggerSeconds`, the controller drops the stick, the jump and the dash for the
+stagger and writes the kick as the body's velocity — `knockUp` is the hop. A
+club with `DamageOnContact` and a player Health of `knockback 7, knockUp 2.5,
+staggerSeconds 0.2` is a hit that knocks the player half a metre back, off the
+ground, and takes the controls for a fifth of a second — no game code. See
+"Hit reactions" in `incanto-gameplay-behaviors.md`.
+
 **The controller owns the wall-jump.** A kick written from a behaviour lasted
 three frames on a platformer built from the tarball: the jump cut halved its
 rise the moment the tap was released (7 → 2.2 m/s) and air control steered
@@ -92,6 +108,13 @@ measures 0.32 / 1.26 (`jumpCutMultiplier`), a double jump line
 (`maxJumps: 2`), and the coyote and buffer windows still measured with a double
 jump declared. It used to give up on both the moment `maxJumps` went above 1.
 
+**`stepHeight` steps onto a ledge at the APEX of a jump too.** A fence 1.5 m
+high was climbed by a jump that peaks at 1.3 m: at the apex the fence top sat
+0.2 m above the capsule's bottom, inside `stepHeight` 0.4, and the step-up
+lifted the character over. That is what makes landing on a ledge forgiving; a
+wall that must stop a walker is jump apex + `stepHeight` tall (`examples/steed-3d`'s
+fence is 2 m).
+
 **Jump reads the button EDGE.** Holding the jump key no longer re-jumps every
 frame — that auto-hop was never intended and it made coyote time incoherent (a
 held button would re-fire through the whole window).
@@ -126,6 +149,248 @@ at rest: 0.01 → y 0.839, 0.05 → 0.840, 0.3 → 1.008, 0.6 → 1.308 for a ca
 contact height is 0.84. Leave it at the default and use `stepHeight` for ledges (the
 docstring's own advice: a raised `floatHeight` makes the character weightless).
 
+## Swimming (water too deep to stand in)
+
+A `Water3D` is a surface with no bottom, and until now the controller never
+asked it anything: a player who walked off a beach into a four-metre lagoon
+stood on the bed with the camera underwater and the run clip playing, in every
+3D scene with water. Now the body SWIMS:
+
+| prop | default | what it buys |
+|---|---|---|
+| `swimSpeed` | `1.6` | the pace a plain key gives in water (m/s; `sprint` still multiplies, by the ratio it multiplies a run). **`0` turns swimming OFF** — the body sinks to the bed, which is what a drowning pit wants and what every scene got before. |
+| `swimDepth` | `0.35` | how far the body's origin rides BELOW the surface. The default keeps a 1.7 m character's head out of the water. |
+| `diveAction` | `"dive"` | held: swim DOWN at `swimSpeed`. Not in the input map = no diving, silently. |
+
+- **When.** The body swims when floating would put it HIGHER than standing:
+  the waterline (`surface − swimDepth`) above where the hover spring would
+  hold it on the bed it can see, or no bed within reach. That one comparison
+  is the whole wade-in/wade-out — walk down a beach and the water takes you
+  where the bed drops away; swim toward a shelf and the spring takes over
+  where it rises. No zones, no triggers.
+- **What.** Gravity is off, a spring holds the origin at the waterline (a
+  swimmer rides the swell the way a `Buoyancy` raft does — the same
+  `heightAt`), horizontal control is full (water gives purchase), and the
+  state is `swim` for the `animations` map / `movementStateChanged`.
+- **Diving.** Hold `dive` to go down; let go and you rise on your own. With
+  the head under (`controller.submerged`), holding `jump` swims UP. Air,
+  drowning and what is down there are your game's business — read
+  `controller.submerged` in a behavior and count.
+- **Getting out.** A swimmer's step is measured from the WATER, not from the
+  foot: swim into a shelf, a dock or a rock whose top is no more than
+  `stepHeight` above the surface and the body CLIMBS out on its own — driven
+  up at 2 m/s until its bottom is level with the ledge, then onto it. (The
+  capsule hangs `swimDepth + halfHeight` under the surface, so from its bottom
+  a shelf a hand under the waterline would be a 0.6 m wall; a swimmer at that
+  shelf simply puts their hands on it. The hover spring could not do this —
+  it is sized to hold a capsule a hair off the ground and stalled with the
+  body's round bottom a third of a metre under the ledge, pressed to its
+  face.) Higher than `stepHeight` above the water it is a wall, exactly as on
+  land. `jump` at the surface hops — SIZED to clear the surface by
+  `stepHeight`, whatever `jumpVelocity` says — and the same climb takes a
+  ledge on the way down. So author a dock or a rock a swimmer should reach
+  **no more than `stepHeight` above the water**. A beach needs nothing: the
+  bed rises, the standing height passes the waterline, and you walk out.
+- **Readbacks.** `controller.swimming`, `controller.submerged`.
+- **Found on the way (fixed, same release):** the ground probe's side rays
+  start `radius` out from the capsule's centre, so pressed against a wall one
+  of them started INSIDE the wall and hit it at distance zero — a character
+  hugging a wall in mid-air read as standing, the ground jump came back while
+  falling, and a hop out of the water at a rock's face was cancelled the frame
+  it started. A zero-distance hit is ignored now. And `wallSlideSpeed` held a
+  third of a metre a second loose (the solver added one tick of gravity back
+  after the clamp); at the cap gravity stands down.
+
+```json
+{ "name": "Controller", "type": "CharacterController3D",
+  "props": { "view": "free", "swimSpeed": 1.8, "stepHeight": 0.5,
+             "animations": { "idle": "$idle", "run": "$run", "swim": "$anims/swim" } } }
+```
+
+Composed in `examples/lagoon-3d` (a pearl dive with an air meter); the
+mixamorig `swim.glb` clip is on the CDN beside the locomotion set.
+
+## Ladders
+
+Every 3D game with a second floor has one, and until now an `Area3D`
+against a wall was a box the player walked into. A ladder is any `Area3D` in
+the controller's `ladderGroup` — no node type, no code:
+
+```json
+{ "name": "Ladder", "type": "Area3D", "groups": ["ladder"],
+  "props": { "position": [-3, 2.2, 0.35], "collider": { "shape": "box", "size": [1, 4.4, 0.7] } },
+  "children": [ …rails and rungs as MeshInstance3D… ] }
+```
+
+| prop | default | what it buys |
+|---|---|---|
+| `climbSpeed` | `1.5` | up and down the rungs, m/s, from the stick's OWN vertical (W/S — the camera gets no say). **`0` = no ladders.** |
+| `ladderGroup` | `"ladder"` | which `Area3D`s are ladders |
+
+- **Grabbing.** Push UP into a ladder you overlap and you are on it: gravity
+  off, held to the rungs, state `climb`. Walking PAST one never grabs it —
+  only pushing up does. Falling past one while holding DOWN grabs it too,
+  which is how you climb down from a ledge: stand at its edge over the
+  ladder, hold back, step off.
+- **The top.** The same climb that takes a swimmer out of the water takes the
+  body onto the ledge: the ladder should lean on the FACE of the thing you
+  are climbing onto (a terrace, a wall with a platform on top, a loft's
+  edge) so the ledge is AHEAD of the climber — a ladder up through a hole in
+  a floor has its ledge to the sides, and the climb-out looks forward.
+- **The bottom.** Down while standing at its foot steps off.
+- **Letting go.** `jump` pushes off the rungs, away from the ladder, with a
+  moment's lockout so it is not grabbed straight back.
+- **Animation.** The state is `climb` — map it in `animations`. The CDN's
+  mixamorig set has no climbing clip; `walk` reads as climbing well enough
+  on the rungs (`examples/tower-3d` does that).
+- **Readback.** `controller.onLadder`.
+
+Composed in `examples/tower-3d` ("Lantern Tower": three terraces, three
+ladders, a sweeping beam and a lantern that wants three flasks).
+
+## Mantling (the pull-up)
+
+A jump at `jumpVelocity: 5` rises 1.27 m and the capsule's round bottom rides
+a corner up to ~0.3 m more, so a 1.6 m roof is cleared and a 2 m one is a
+wall — a hand short. `mantleHeight: 0.9` catches it: on the way down from
+ANY jump, while the stick is held toward the ledge, a top ahead within that
+height of the capsule's bottom is taken by the same climb that takes a
+swimmer out of the water and a climber off a ladder (driven up at 2 m/s,
+then onto it; state `climb` meanwhile). Above the reach it is still a wall;
+a vertical hop beside a ledge is still a hop. Composed in
+`examples/rooftops-3d`.
+
+## Crouching (`crouchHeight`)
+
+A duct to crawl through, a laser to duck under, a desk to hide behind:
+every stealth game and shooter has a crouch, and the controller could not
+make itself shorter. One prop turns it on:
+
+```json
+{ "name": "Ctl", "type": "CharacterController3D",
+  "props": { "crouchHeight": 0.3, "crouchSpeedMultiplier": 0.5 } }
+```
+
+- **`crouchHeight`** (m, `0` = no crouch) is the capsule's `height` while the
+  `crouch` key is held — the standing capsule is `height` + 2 × `radius`
+  tall (1.6 m for the default rig), the crouched one `crouchHeight` +
+  2 × `radius` (0.94 m), so a duct with a metre of headroom is crawled
+  through and stops a standing character at its mouth. The body sinks by
+  half the difference in the same step, so the feet stay put and the eye
+  drops with them in first person; the Skin's authored offset is lifted by
+  the same amount so the model's feet stay on the floor, and restored on
+  standing.
+- **Hold-to-crouch.** The key let go stands you up — if there is headroom.
+  A ray from the capsule's top asks; under a duct you stay down until you
+  are out from under it, and `crouching` reads true the whole time. A jump
+  press while the key is held is not a hop and not a stand.
+- **`crouchSpeedMultiplier`** (0.5) is the pace, as a fraction of the standing
+  pace. `state` reads `crouch` (still) and `sneak` (moving), so the
+  `animations` map takes clips for both.
+- Declare the action: `"crouch": { "type": "button", "keys": ["KeyC", "ControlLeft"] }`
+  (`crouchAction` renames it). A missing action is tolerated and reported
+  once, like `sprint`.
+
+`examples/vents-3d` is the composition: ducts, a laser grid at head height,
+a guard's sightline you crouch under.
+
+## A death that falls — `Ragdoll3D`
+
+Every enemy in every example died the same way: the model played a clip, or
+vanished. Nothing crumpled, slid down a slope or hung off the rail, because a
+ragdoll is ten bodies and nine joints built from a skeleton nobody wanted to
+write. One node under the body, beside the Skin:
+
+```json
+{ "name": "Brute", "type": "CharacterBody3D", "children": [
+  { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$base" } },
+  { "name": "Hp", "type": "Node", "script": { "name": "Health", "props": { "max": 50 } } },
+  { "name": "Ragdoll", "type": "Ragdoll3D", "props": { "target": "../Skin", "lifetime": 8 } }
+] }
+```
+```jsonc
+{ "signal": "died", "from": "Brute/Hp", "to": "Brute/Ragdoll", "handler": "activate" }
+```
+
+- **Idle it is nothing.** `activate()` reads the skeleton at `target`
+  (Mixamo names — `Hips`, `Spine`, `Head`, `LeftArm`… with the forgiving
+  lookup `findBone` uses), builds a capsule `RigidBody3D` per limb where the
+  bones are — torso, head, upper arms, forearms, thighs, shins — joins each
+  to its parent with a spherical `Joint3D`, gives them the velocity of the
+  body they fell out of, and from then on writes the bones' world matrices
+  from the limbs every frame. The limbs go under the scene root in the
+  `ragdoll` group; `limbs()` lists them.
+- **Turn the rest off beside it**: the body's collider (`enabled: false`) so
+  the capsule stops holding the corpse up, the controller or the chase.
+  `Health.freeOnDeath` would delete the model the ragdoll is driving — leave
+  it off and let `lifetime` free the limbs, then free the corpse yourself on
+  the `reset` signal.
+- `mass` (70 kg, shared out by limb), `damping` (3 — how fast the flailing
+  dies), `collide` (limbs against each other; adjacent ones never). A rig
+  without hands or a `HeadTop_End` still builds — the forearm ends at the
+  wrist bone, the head is a ball.
+- **Headless there is no skeleton**: `activate(pose)` takes bone positions
+  (`{ Hips: [x, y, z], … }`), so a harness can build one where the model would
+  be and ask that it fell, that the elbow still joins, that the limbs carried
+  the run. `active` reads true while it is up.
+
+## Letting go — `enabled`
+
+The player gets into a car, sits through a cutscene, opens a menu: the
+controller has to LET GO, and `enabled: false` is that. For getting into a car or
+onto a horse, the whole handoff — this controller off, the body parked and
+riding along, the Skin on the saddle, the steed's controller or `Vehicle3D`
+on, and back — is the `Mount` gameplay behaviour (`incanto-gameplay-behaviors.md`). Off, it reads no
+input, applies no forces (no hover spring either), drives no camera and
+sets no animation — the body under it is an ordinary `RigidBody3D` until it
+is on again. A game parks the character out of sight beside it:
+
+```ts
+ctl.enabled = false;          // the controller lets go
+player.enabled = false;       // the body's collider is off — nothing bumps the empty seat
+player.visible = false;
+player.gravityScale = 0;      // a collider-less dynamic body would fall through the floor
+// …and each frame while driving: player.position = car.position
+```
+
+and on the way out puts it back where the door is, `enabled`/`visible` on,
+`gravityScale` 1, THEN `ctl.enabled = true` — the controller re-finds the
+current camera and drives it from the next frame (the camera pops to the
+rig; smooth it yourself if the cut shows). `Vehicle3D.enabled` is the same
+switch on the car's side, and `examples/errands-3d` flips both with one
+`Interactable` press.
+
+## Two players at one keyboard
+
+A second player is a second ACTION SET, and a controller told to read it:
+
+```jsonc
+// the scene's input map declares both
+"input": {
+  "move":  { "type": "vector2", "keys": { "up": ["KeyW"], "down": ["KeyS"], "left": ["KeyA"], "right": ["KeyD"] } },
+  "jump":  { "type": "button", "keys": ["Space"] },
+  "move2": { "type": "vector2", "keys": { "up": ["ArrowUp"], "down": ["ArrowDown"], "left": ["ArrowLeft"], "right": ["ArrowRight"] } },
+  "jump2": { "type": "button", "keys": ["ShiftRight"] }
+}
+```
+```json
+{ "name": "Controller", "type": "CharacterController3D",
+  "props": { "view": "quarter", "camera": "none",
+             "moveAction": "move2", "jumpAction": "jump2", "sprintAction": "sprint2" } }
+```
+
+- `moveAction` / `jumpAction` / `sprintAction` have been there since the
+  controller shipped and no example had ever set them. They work: measured on
+  `examples/coop-3d`, player one's keys move smith one 2.4 m and smith two
+  **0.00 m**.
+- **Every player's controller needs `camera: "none"`**, and one camera gets a
+  `GroupCamera` (see `incanto-gameplay-behaviors.md`) — otherwise two
+  controllers and the group camera all write the same camera every frame.
+- Anything else a player operates takes the same treatment: `Carry.action`,
+  `Interactable.action`, `Shoot`'s action — name the second player's own.
+- The playtest bot drives EVERY controller it finds, each on its own action set,
+  so a two-player game is exercised rather than half-exercised.
+
 ## Views
 
 | view | what it does | key props |
@@ -135,7 +400,21 @@ docstring's own advice: a raised `floatHeight` makes the character weightless).
 | `quarter` | fixed isometric pitch 35.264°, NO mouse look | `camDistance` 40, `mouseLook: false` |
 | `side` | camera at +z `camDistance`, lock movement to ±x | `mouseLook: false` |
 
-The controller drives the scene's `current` Camera3D every frame (smoothed).
+The controller drives the scene's `current` Camera3D every frame (smoothed) —
+unless you take it off that duty:
+
+```json
+{ "name": "Controller", "type": "CharacterController3D",
+  "props": { "view": "quarter", "camera": "none" } }
+```
+
+**`camera: "none"` leaves the camera exactly where the scene puts it.** A whole
+shelf of games has a FIXED view — a board game, a bomb arena, an isometric
+puzzle, a fixed-angle horror — and could not use this controller at all, because
+it re-posed their camera every frame. Pair it with an authored `Camera3D` (and
+a `FollowCamera` behaviour if the board scrolls); `incanto-check` no longer
+calls that pair a fight. The default is `"drive"`, which is what every existing
+scene already gets.
 Wheel zooms only when `zoomMax > zoomMin`.
 
 In `free` view the camera AIMS at the character every frame (`lookAt`), so the
@@ -160,7 +439,7 @@ enemy never yanks the camera in. `firstPerson` skips it (the camera is at the ey
 
 ## Animations
 
-`controller.state` is `idle | walk | run | fastRun | airborne`; the
+`controller.state` is `idle | walk | run | fastRun | airborne | swim | climb | crouch | sneak | dash`; the
 `movementStateChanged` signal fires on transitions — map states to clips
 (`$animation` assets are retargeted onto the skin's own rig — GLB and VRM alike — so a
 clip never changes your character's proportions):
@@ -168,7 +447,8 @@ clip never changes your character's proportions):
 ```ts
 controller.on('movementStateChanged', (state) => {
   skin.animation = { idle: '$idle', run: '$run', fastRun: '$runFast',
-                     airborne: '$jump', walk: '$walk' }[state];
+                     airborne: '$jump', walk: '$walk', swim: '$swim',
+                     climb: '$climb' }[state];
 });
 ```
 
@@ -225,7 +505,7 @@ Map movement states straight in JSON — no behavior needed:
 { "name": "Controller", "type": "CharacterController3D",
   "props": { "view": "free",
     "animations": { "idle": "$idle", "walk": "$walk", "run": "$run",
-                    "fastRun": "$sprint", "airborne": "$jump" } } }
+                    "fastRun": "$sprint", "airborne": "$jump", "swim": "$swim" } } }
 ```
 
 The controller writes `skin.animation` on every state change (crossfaded by
@@ -233,7 +513,7 @@ the model). The `movementStateChanged` signal still fires for extras.
 
 **Where those clips come from.** Locomotion clips live at
 `https://agent8-games.verse8.io/assets/3d/animations/mixamorig/<name>.glb`
-(`idle-00`, `walk`, `run-medium`, `run-fast`, `jump`) and play on any mixamorig
+(`idle-00`, `walk`, `run-medium`, `run-fast`, `jump`, `swim`) and play on any mixamorig
 model as they are — retargeted through the humanoid map for a VRM. You do not
 have to assemble any of this by hand: run the character URL your asset MCP gave
 you through `bunx incanto-model <url>` and it prints the whole thing — assets,
@@ -292,6 +572,11 @@ NPCs feel alive when they track you. One node, zero code:
 - `weight` (0.85) is how far the head commits; `forwardAxis` defaults to the
   mixamo head convention (+z).
 - Also good for chests (`bone: "Spine2"`, small weight) and turrets.
+- **`node.engaged`** (0..1) is how far it is committed RIGHT NOW — the whole
+  observable effect of this node, and until now nothing could read it. It turns
+  a rendered bone, so it stays 0 in a headless run (no GLB, no skeleton): check
+  it in the browser, where `attachedBone` tells you the bone was found and
+  `engaged` tells you the head is following.
 
 ## Facing a direction in 3D — the +Z-FORWARD rule (read before turning ANY skin)
 
@@ -383,6 +668,12 @@ This cannot be an `auditScene` warning: a scene file has no velocity, and the bu
 is a behavior writing a heading at runtime. `facingReport()` from `incanto/test`
 is the same check for your own tests.
 
+Like the feel numbers above it, this presses your title screen's START before
+driving the character — a paused world moves nowhere, and `did not move —
+nothing to compare` was the answer it gave about three shipped games whose only
+fault was that their menu was up. When nothing on screen starts the game it says
+THAT instead.
+
 ## Facing the mouse in a top-down view (twin-stick)
 
 In `quarter` view the mouse does not look, and the controller turns the skin
@@ -404,29 +695,76 @@ Measured on `examples/survivor-3d`: a cursor 10 m east is yaw 90°, and a bolt
 given `direction: [dx, 0, dz]` flies where the skin looks. Boot with
 `pointer: { lockOnClick: false }` — a locked cursor is no aim at all.
 
-## Lock-on and a dodge, in a few lines each
+## Lock-on (`lockOnAction`) and a dodge
 
-The controller's camera yaw is a public number in radians, and the rig's
-forward is `(-sin yaw, 0, -cos yaw)` — so putting the camera behind the player
-and on the enemy is one assignment per frame, measured on `examples/melee-3d`
-(forward · toEnemy = 1.00):
+Lock-on used to be a one-line recipe — the camera yaw toward the enemy, every
+frame — and the half it never had was the one that matters: the SKIN kept
+facing the move direction, so a locked player circling a brute showed it a
+shoulder, and a sword hitbox hung off the skin's yaw swung sideways. The
+controller owns it now:
 
-```ts
-const dx = enemy.position[0] - player.position[0];
-const dz = enemy.position[2] - player.position[2];
-controller.yaw = Math.atan2(-dx, -dz);       // every frame while locked
+| prop | default | what it does |
+|---|---|---|
+| `lockOnAction` | `""` | the button that toggles the lock (`""` = no lock-on) |
+| `lockGroup` | `"enemy"` | who can be locked: the nearest live, visible member within… |
+| `lockRange` | `12` | …this many metres; the lock lets go by itself at 1.5 × the range, or when the target dies or leaves the tree |
+
+```json
+{ "name": "Controller", "type": "CharacterController3D",
+  "props": { "view": "free", "lockOnAction": "lockOn", "lockRange": 14 } }
 ```
 
-A dodge is a dash plus i-frames that start BEFORE the hit — `Health.protect`,
-not `invulnerableFor` (which opens only after one):
+**Locked means the character FACES the target while its feet go anywhere.**
+The camera yaw follows player → target every frame, so the stick — which is
+camera-relative — strafes round it; the skin turns to the target (at
+`turnSpeed`) even standing still; `state` stays `walk`/`run` while circling.
+Anything you hang off the skin's yaw — `examples/melee-3d`'s `Edge` hitbox at
+`sin/cos(skin yaw)` — swings at the target. Methods `lock(node)`, `unlock()`,
+`toggleLock()`; readback `lockTarget`; signal `lockChanged(target | null)`.
+`examples/boss-3d` locks onto the colossus with `lockGroup: "boss"`,
+`lockRange: 40`.
+
+`incanto-feel` knows: a controller with a `lockTarget` is reported as
+`LOCKED ON` rather than measured against its travel — a strafe is the
+intended reading, not a defect.
+
+A dodge is a dash plus i-frames that start BEFORE the hit. The dash is the
+controller's (`dashSpeed` — see below); the i-frames are `Health.protect`,
+not `invulnerableFor` (which opens only after one), hung on the `dashed`
+signal:
 
+```json
+{ "name": "Ctl", "type": "CharacterController3D",
+  "props": { "dashSpeed": 9, "dashSeconds": 0.35, "dashCooldown": 0.5 } }
+```
 ```ts
-(player.behavior as Health).protect(0.35);   // immune for the roll
-body.linearVelocity = [dir[0] * 9, body.linearVelocity[1], dir[2] * 9];
+controller.on('dashed', () => (player.behavior as Health).protect(0.35));
 ```
 
-Keep writing the velocity for the roll's frames — the controller brakes toward
-its own target speed every step, so a single impulse dies in a few frames.
+## A dash / dodge roll (`dashSpeed`)
+
+Two examples carried the same twelve lines — a timer, a direction, and
+`body.linearVelocity = dir × 9` written EVERY frame because the controller
+brakes toward its own pace and a single impulse dies — while
+`CharacterController2D` had `dashSpeed` since 0.33. Now the 3D controller
+has it too:
+
+| prop | default | what it does |
+|---|---|---|
+| `dashSpeed` | `0` | m/s for the roll; `0` = no dash |
+| `dashSeconds` | `0.25` | how long the velocity is held |
+| `dashCooldown` | `0` | seconds after a roll ends before the next can start |
+| `dashAction` | `dash` | pressed = roll (tolerated when missing, like `sprint`) |
+| `dashBackstep` | `false` | with no stick, roll AWAY from where the skin faces — the Souls-like backstep a lock-on game wants |
+
+- The roll goes where the stick points (camera-relative), or with no stick
+  where the skin faces — or away from it with `dashBackstep`, which is what
+  a neutral roll means while locked on to something.
+- `state` reads `dash` for the roll — map a clip to it — and `dashed` fires
+  once per roll. Not while crouched, on a ladder or swimming.
+- The velocity is written last, every step of the roll, over whatever the
+  step's impulses did; gravity still runs, so a roll off a ledge falls.
+- `examples/melee-3d` rolls with it and keeps its i-frames on `dashed`.
 
 ## First-person weapon viewmodel + the tracer-from-the-muzzle rule
 

package/skills/incanto-audio.md

@@ -226,8 +226,30 @@ non-WebAudio paths use, so headless gameplay is unaffected.
 > (`refDistance: 100`, `maxDistance: 900` is a reasonable start); `incanto check`
 > warns when it sees `spatial: true` in a 2D scene with the defaults left alone.
 
-> **Headless / verify VM:** spatial is a no-op like all audio — `play()` won't
-> throw and your gameplay logic is unaffected.
+> **Headless / verify VM:** no sound comes out — and the ANSWER still does. The
+> audio record carries where each spatial sound arrived from, computed from the
+> scene's own current camera when no renderer has fed a pose:
+
+```ts
+const ring = engine.audio.recent().at(-1);
+ring.pan;       // −1 hard left … +1 hard right (absent when the sound is not spatial)
+ring.gain;      // 0..1 after the distance rolloff — 1 inside `refDistance`
+ring.distance;  // metres (px in 2D) from the listener when it sounded
+```
+
+Thirty shipped scenes set `spatial: true` before this existed and not one of
+them could be checked: the record said a sound FIRED and nothing about whether
+it was audible or which side it came from. Now "walk toward the ringing" is a
+mechanic a harness can verify — `examples/earshot-3d` is a whole game of it
+(a bell on the left records `pan −0.98`; turn the listener around and the same
+bell reads `+0.98`).
+
+Two things to know when you measure it:
+
+- **A sound that is not spatial has no `pan`/`gain`/`distance` at all** — the
+  fields are absent rather than zero, so a UI click never looks centred.
+- **A scene with no current camera has no listener**, and the record says
+  nothing rather than inventing a sound in the middle of your head.
 
 ---
 

package/skills/incanto-building-2d-games.md

@@ -216,7 +216,8 @@ ALWAYS confirm in the browser (`bun run dev`) that the feet touch the surface.
 | `smoothing` | `0` | 0 = snap; 0.85–0.95 = smooth chase (frame-rate independent) |
 | `zoom` | `1` | 2 = world pixels doubled |
 | `limits` | `[]` | `[minX,minY,maxX,maxY]` — view rect clamped inside |
-| `current` | `false` | mark exactly one |
+| `current` | `false` | mark exactly one — switch at runtime with `cam.makeCurrent()`, which clears the others (a wirable handler) |
+| `blendSeconds` | `0` | seconds the view FLIES (centre and zoom, eased) from the last drawn view to this camera when it becomes current; `0` = a cut; `makeCurrent(0.5)` asks once |
 Camera `position` is the view CENTER, and it composes with its ancestors like any
 other node — so parenting the camera to the player (the Godot/Phaser idiom) works,
 and so does putting it inside the container that holds the level. `follow` and the
@@ -346,6 +347,12 @@ between a readable and an unusable phone build.
 
 ## Game flow recipes
 
+- **A title screen that HOLDS the world**: `GameFlow.pause()` from a behaviour's
+  `onReady`, and `resume()` when the player presses your RUN button. The freeze
+  survives the boot — the tree readies inside `loadScene` and `setScene` resets
+  the time scale for the game-over swap, so a pause asked for during the load
+  used to be erased and the game booted with `state: 'paused'` and the player
+  walking around behind the title. `examples/shell-3d` is the whole shell.
 - **Scene transition** (level 2, title → game):
   ```ts
   import { loadScene } from 'incanto';
@@ -545,6 +552,8 @@ behaves exactly as before.
 | `dashSpeed` / `dashSeconds` / `dashAction` | `0` / `0.15` / `dash` | a straight-line dash |
 | `wallSlideSpeed` | `0` | capped fall while against a wall |
 | `wallJumpImpulse` | `[0, 0]` | `[away, up]` push off a wall |
+| `crouchHeight` | `0` | the collider's height (px) while `crouch` is held — a rect's `size[1]`, a capsule's `height`; the body drops by half the difference so the feet stay put, a low gap is ducked through, and a ceiling keeps you down until you are out from under it. Hold-to-crouch: a jump press under a held key is not a hop |
+| `crouchSpeedMultiplier` / `crouchAction` | `0.5` / `crouch` | the pace while crouched; the action (tolerated when missing) |
 
 ```json
 { "name": "Controller", "type": "CharacterController2D",
@@ -553,8 +562,18 @@ behaves exactly as before.
              "wallSlideSpeed": 60, "wallJumpImpulse": [260, 380] } }
 ```
 
+**Getting hit is the controller's too.** A `Health` on the body (or a child of
+it) with `knockback` / `knockUp` / `staggerSeconds` takes the stick and the jump
+for the stagger, and the controller writes the kick as the body's velocity — in
+topDown as the whole velocity, in platformer as `x` with `knockUp` as the hop
+(pass it positive; the engine flips it to `−y`). The platformer's hand-rolled
+`KNOCK_X` / `KNOCK_UP` / `CONTROL_LOCK` are `knockback 420, knockbackSeconds
+0.22, knockUp 360, staggerSeconds 0.22`; a controller of your own reads the
+kick itself (`applyKnockback: false`) — see "Hit reactions" in
+`incanto-gameplay-behaviors.md`.
+
 **`movementStateChanged(state)`** fires on every change — `idle` · `run` ·
-`jump` · `fall` · `wallSlide` · `dash` — so an `AnimatedSprite2D` follows the
+`jump` · `fall` · `wallSlide` · `dash` · `crouch` · `sneak` — so an `AnimatedSprite2D` follows the
 character from scene JSON instead of a behavior polling velocities. The 3D
 sibling has had this signal since it shipped.
 

package/skills/incanto-building-3d-games.md

@@ -58,7 +58,10 @@ One call does register → load → physics → input → renderer → start. Ph
 disables); `pointer: { lockOnClick: false }` for look without lock. `seed` /
 `fixedHz` / `pixelRatio` / `adaptiveResolution` pass through (adaptive
 resolution is ON by default: slow frames render fewer pixels and recover
-automatically — pass `false` for screenshots and pixel-diff tests). The manual `Engine` + `loadScene` +
+automatically — pass `false` for screenshots and pixel-diff tests). `autoStart: false`
+hands back a game that has not run a frame — call `game.engine.start()` once
+everything that must exist before the first one does (a `NetworkManager`; see
+`incanto-multiplayer.md`). The manual `Engine` + `loadScene` +
 `Renderer3D` boot still exists for full control.
 
 Imperative per-frame logic can hang off `game.engine.updated.connect((dt) => { ... })`; for
@@ -281,9 +284,41 @@ and `Fill.position = [-(1 - frac) / 2, 0, 0.01]`. The offsets stay local to the
 (rotated) bar, so the drain always hugs the bar's left edge.
 
 ### `Camera3D`
-`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`, `lookAt: ""`.
+`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`, `lookAt: ""`, `blendSeconds: 0`,
+`minHorizontalFov: 0`.
 Mark exactly ONE camera `current: true` (otherwise the first camera in tree order is used).
-Aspect ratio is automatic.
+
+**`fov` is VERTICAL**, and the aspect comes from the canvas — so what the player
+sees ACROSS is `2·atan(tan(fov/2)·aspect)`. A `fov: 60` camera shows 91° across a
+16:9 window and **30° across a 390×844 phone held in portrait**.
+`minHorizontalFov` is the floor: ask for a width in degrees and the vertical fov
+widens until the screen carries it, while any window already wider keeps the
+authored fov. `52` suits a game meant to be playable in one hand — and note what
+the geometry costs: 52° across a 9:19.5 screen is a 93° vertical fov, so ask for
+a width, not for everything.
+
+`cam.viewFov(aspect)` answers what the camera will actually render with at a
+given shape of screen — the authored `fov`, or the widened one. Use it in a
+harness rather than copying the formula:
+
+```ts
+const cam = game.scene.root.getNode('Camera') as Camera3D;
+cam.viewFov(390 / 844);   // 93 — the vertical fov a portrait phone gets
+cam.viewFov(16 / 9);      // 60 — the authored one, on a desktop window
+```
+To SWITCH at runtime call `cam.makeCurrent()` — it clears every other camera's
+`current`, which setting your own never did, so a cutscene camera that set
+itself `current` changed nothing visible. It is a handler a connection can name:
+`triggerEnter → DoorCam.makeCurrent`. Aspect ratio is automatic.
+
+**A switch is a CUT unless the camera asks otherwise.** `blendSeconds` on the
+camera being switched TO makes the picture FLY from the last drawn pose to that
+camera over so many seconds of real time — position, orientation and fov, eased
+in and out — and `makeCurrent(0.6)` asks for it once. The nodes never move:
+picking, framing and the editor read the node; only the picture takes the long
+way round. A second switch mid-flight starts from where the picture IS.
+`examples/heist-3d`'s door camera and gameplay camera declare `0.6`; a camera
+that is the FIRST frame (an intro rail) has nothing to fly from and cuts.
 
 **Point it with `lookAt`, not with a `rotation` you worked out.**
 

package/skills/incanto-editor.md

@@ -134,12 +134,23 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   node in the scene; the handler is a dropdown of real methods when the target
   has no script, and free text when it does (those handlers live in your
   TypeScript, which the editor never loads). An end that no longer resolves is
-  marked red with the reason. For what a row cannot express — `filter` and `once`
-  — the scene header still has `connections` as raw JSON. (It used to say "bound
-  args" as well: a connection has never had them. Its keys are exactly
-  `[signal, from, to, handler, once, filter]`, and since they became a closed
-  set an invented one is a load error rather than a key that quietly does
-  nothing.)
+  marked red with the reason. For what a row cannot express — `filter`, `once`
+  and `args` — the scene header still has `connections` as raw JSON. A
+  connection's keys are exactly `[signal, from, to, handler, once, filter,
+  args]`, a closed set, so an invented one is a load error rather than a key
+  that quietly does nothing. **`args` survives editing but is not shown**: a row
+  whose wire carries bound arguments reads as `phase2 → HUD/Banner.show` with no
+  hint of the words it says.
+
+  **Re-pointing a target keeps your handler.** A handler the new target does not
+  have is replaced (the row would otherwise stay green here and hard-fail at
+  load), and the row remembers what it started with — so changing your mind and
+  putting the target back puts the handler back. Before that, a round trip left
+  `phase2 → HUD/Banner.show` as `HUD/Banner.childNames`: the replacement took
+  the target's first offer, and the offers included the tree plumbing every node
+  inherits. They do not any more — the node base class is read the way the
+  behavior base class always was, so `queueFree` stays and `childNames`,
+  `wiringPath` and the rest are gone.
   **Validation now runs WITH connections**: the editor used to strip them before
   loading, so it reported green for a scene the game hard-fails to open.
 - **Viewport with DIRECT MANIPULATION** — a mode toolbar (top left) + the