incanto 0.74.0 → 0.76.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,29 @@ 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.
 
+**`slopeLimitDeg` (55) is the steepest ground the character STANDS on**, and
+below it a character does not slide at all — measured, on a hillside, for as
+long as you leave it there. It used to slide down everything: 0.18 m in three
+seconds on a 6.9° slope, 2.87 m on a 27° one, always exactly downhill. The
+cause is the hover spring measuring its clearance STRAIGHT DOWN while the
+clearance that decides whether the capsule touches is measured perpendicular
+to the surface — negative past ~13° — and every rig setting `friction: 0` (the
+right setting: the character rides the spring, so floor friction only brakes
+it) then slid on the contact. So the spring aims perpendicular now, and on
+ground inside the limit the controller cancels downhill drift it was not asked
+for. Steeper than the limit the ground stops being ground — no `grounded`, no
+jump reset — and the body slips off the face, which is what a slope limit means
+everywhere else. 55 is a person; a goat is 80, something on wheels 25, and `90`
+is the old no-limit behaviour. `controller.groundSlopeDeg` reports what it is
+standing on, and `controller.groundNormal` which way that faces.
+
+**`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 +165,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` | `null` | how far the body's ORIGIN rides below the surface. `null` derives it from the capsule so the head rides 15 cm clear and the rest is in the water — which is what treading water looks like, and what a fixed number cannot be for every character size. (It used to default to a flat `0.35`, and on the 1.68 m capsule every template ships that put the head 0.46 m clear: the character floated along on top like a boat.) A number still wins. |
+| `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 +416,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 +455,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,13 +463,23 @@ 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];
 });
 ```
 
 Setting `animation` to a new clip **crossfades** (0.2s blend) from the current
 one — idle↔walk↔run↔jump transitions are smooth, not a hard cut.
 
+**A state your map does not name falls back — it never leaves the last clip
+playing.** `swim → walk → idle`, `dash → fastRun → run → walk → idle`,
+`sneak`/`climb → walk → idle`, `crouch`/`airborne → idle`. Every chain ends at
+`idle`, so a map with one clip in it still animates. Without this, a scene that
+mapped only the original five (which is every scene there was) put a swimmer
+across the bay in a frozen JUMP pose, and did the same for `dash`, `climb`,
+`sneak` and `crouch`. Map the state itself when you have the clip: the shipped
+water templates now declare `swim` (`mixamorig/swim.glb` on the agent8 CDN).
+
 ## Reskin one model with `tint` (many variants from one GLB)
 
 `ModelInstance3D` has a `tint` prop (hex, `""` = off) that MULTIPLIES into every
@@ -225,7 +530,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 +538,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 +597,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 +693,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 +720,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.**