incanto 0.72.0 → 0.74.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). 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), 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.
 ---
 
 # Gameplay behaviors — the built-in logic library
@@ -79,7 +79,7 @@ scaffolded project's `check` script passes it, and why a hand-written one that
 does not loses the check silently. `auditScene` from `incanto/test` is the same
 audit from inside your harness, once your behaviours are registered.
 
-`Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
+`FollowCamera.target` is `required` (and `Chase` needs `target` or `targetGroup`): an EMPTY one
 is a load error naming the node, not a surprise in the browser.
 
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
@@ -94,6 +94,11 @@ a connection `to` the root is `/root` (or `.`), never `/root/Game`.
 
 ---
 
+## Checkpoint
+
+On an `Area3D`/`Area2D`, pointing at a `Respawn`: touch it and the next fall
+puts you back HERE. Documented with `Respawn` in `incanto-behaviors-and-scripts.md`.
+
 ## Health
 
 Hit points with regen and post-hit invulnerability (i-frames). The universal
@@ -105,13 +110,13 @@ Hit points with regen and post-hit invulnerability (i-frames). The universal
 |---|---|---|
 | `max` | `100` | maximum HP; `current` starts here |
 | `regenPerSec` | `0` | HP regained per second (0 = off) |
-| `invulnerableFor` | `0` | seconds of immunity after a hit (i-frames; 0 = off) |
+| `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 |
 
 Signals: `damaged(amount, current)` · `healed(amount, current)` ·
 `healthChanged(current, max)` · `died` · `revived(current)`
-Methods: `damage(n)` · `heal(n)` · `kill()` · `revive(hp?)` — state: `current`,
+Methods: `damage(n)` · `heal(n)` · `kill()` · `revive(hp?)` · `protect(seconds)` — state: `current`,
 `isDead`
 
 **A dead Health STAYS dead until you revive it.** `damage`, `heal` and regen all
@@ -179,6 +184,28 @@ Signals: `expired` — Methods: `startTimer()`
   "script": { "name": "Lifetime", "props": { "seconds": 2 } } }
 ```
 
+**A fuse wired to a trigger on the floor is lit by the floor.** The natural
+`startOnSignal` composition — a mine whose child `Area3D` is wired
+`triggerEnter → startTimer` — sat on tps-3d's arena floor with a 1 m sphere at
+y 0.5, and `triggerEnter` fired on frame 1 from `/Game/Arena/Floor`
+(a `StaticBody3D`): the 1.5 s fuse expired at frame 91 with nobody near it.
+Areas report the static world too (see `overlapping()` in
+`incanto-physics-and-input.md`). The fix is the connection's own `filter`,
+which gates on the body that entered:
+
+```json
+{ "signal": "triggerEnter", "from": "Arena/Mine/Trigger", "to": "Arena/Mine",
+  "handler": "startTimer", "filter": { "group": "player" } }
+```
+
+The sensor still SEES the floor; the connection no longer fires on it, and the
+player (in group `player`) lights the fuse as before — measured: 0 expiries in
+200 frames with nobody near, 1 within 90 frames of the player stepping in. The
+same rule `Pickup.collectorGroup` and `DamageOnContact.targetGroup` carry on
+their props, for a bare connection. (An earlier version of this paragraph said
+a connection cannot filter by group and told you to lift the trigger. It can,
+and you do not have to.)
+
 ## ScoreKeeper
 
 The game's **state hub** — score, lives, win/lose. Put it on the Root/Game node
@@ -195,7 +222,7 @@ Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)` ·
 `livesChanged(lives)` — the EVENT and the COUNT: `lifeLost` fires when a life is
 spent (flash, respawn), `livesChanged` also fires when a save is restored, so a
 lives counter belongs on that one.
-Methods: `addScore(n)` · `setScore(n)` · `loseLife()`
+Methods: `addScore(n)` · `setScore(n)` · `loseLife()` — state: `score`, `lives`, and read-only `won` / `lost` (the signals fire once; the flags stay true, which is what a HUD banner and a harness want to ASK)
 
 ```json
 { "name": "Game", "type": "Node",
@@ -262,7 +289,7 @@ calls `damage(amount)`, then emits `dealtDamage(amount, healthOwnerNode)`.
 |---|---|---|
 | `amount` | `10` | HP removed per contact |
 | `targetGroup` | `""` | only damage targets in this group — the tag may sit on the BODY or on the node carrying its `Health` (`""` = any) |
-| `oncePerTarget` | `true` | damage each target at most **once, ever** |
+| `oncePerTarget` | `true` | damage each target at most once **per overlap** — leave and come back (or disarm the hitbox and arm it again) and it lands again |
 | `repeatEvery` | `0` | seconds between re-hits while still overlapping (`0` = entry only) |
 | `destroySelf` | `false` | `queueFree()` after the first hit |
 
@@ -282,6 +309,32 @@ oncePerTarget=true   repeatEvery=0.5   → hp 0
 oncePerTarget=true   repeatEvery=0     → hp 90
 ```
 
+### A melee swing: arm the hitbox for the active frames
+
+A sword is an `Area3D` with `DamageOnContact` that is **disarmed** (`enabled:
+false`) and armed only while the swing can hurt — the engine's own
+`enabled` on the Area, flipped from the attack behaviour:
+
+```ts
+// in the attack behaviour's update(), `t` seconds into the swing
+edge.enabled = t >= 0.18 && t <= 0.42;       // the active frames of the clip
+```
+
+Arming over a foe you are already touching IS a hit (the engine synthesises the
+`triggerEnter`), and disarming ends the contact, so `oncePerTarget` stays at its
+default and every swing lands once per foe — a sword built from the tarball hit
+each brute exactly once per GAME before this was so. Two more things the build
+paid for: **the hitbox rides the BODY, not the skin** — physics composes
+ancestor offsets only, and the skin is what the controller turns, so an `Area3D`
+under `Skin` sat behind the player at every yaw (`incanto-check` now warns) —
+and it is **aimed from the skin's yaw** every frame, a +Z-forward model facing
+`(sin yaw, 0, cos yaw)`:
+
+```ts
+const yaw = (skin.rotation[1] * Math.PI) / 180;
+edge.position = [Math.sin(yaw) * 0.9, 0.3, Math.cos(yaw) * 0.9];
+```
+
 `repeatEvery` is the only prop that makes a resting overlap keep hurting, and it
 overrides `oncePerTarget` — lava pools, poison clouds, an enemy standing on you.
 Set it on **every enemy contact hitbox**; without it a game plays as though the
@@ -340,8 +393,24 @@ in-range actor). Declare the input action in the scene `input{}`.
 | `action` | `"interact"` | input action (button) that triggers it |
 | `range` | `2` | max distance an actor may be |
 | `actorGroup` | `"player"` | only nodes in this group can interact |
+| `prompt` | `""` | what the actor sees on it — `Open drawer`; read by whoever draws the "[E] …" line |
+| `focus` | `"any"` | which one answers when SEVERAL are in range: `any` (all of them) · `nearest` (the closest) · `facing` (of those inside `coneDeg` of the current camera's forward, the one nearest the CENTRE of the view — a crosshair, pitch included — so the note on the desk and the drawer under it are two looks, and in third person the plot the farmer looks at beats the plot under the farmer's feet; with no `Camera3D`, same as `nearest`) |
+| `coneDeg` | `40` | full width of the `facing` cone — a generous crosshair |
+
+Signals: `interacted(actor)` · `focused(actor)` · `unfocused(actor)`. Getter:
+`focusedBy` — the actor it would answer right now, or null.
 
-Signals: `interacted(actor)`
+**Three things within two metres and one press opened, lit and read all of
+them** — an escape room built from the tarball. Each Interactable answered the
+press on its own; nothing asked which one the actor MEANT. `focus: "facing"`
+is the first-person answer, `"nearest"` the top-down one, and the prompt line
+every adventure game draws is the focused one's `prompt`:
+
+```ts
+// HudUpdater.update — the "[E] Open drawer" line
+const focused = interactables.find((i) => i.focusedBy);
+promptText.text = focused ? `[E] ${focused.prompt}` : '';
+```
 
 ```json
 { "input": { "interact": { "type": "button", "keys": ["KeyE"] } },
@@ -402,6 +471,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 |
+| `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 |
 
@@ -438,11 +508,14 @@ within `stopRange` (melee reach). `reachedTarget` fires once on entering range
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `target` | `""` | node path to chase, resolved from THIS node (required) |
+| `target` | `""` | node path to chase, resolved from THIS node — this or `targetGroup` |
+| `targetGroup` | `""` | the OTHER way to name a target: the NEAREST member of this group, re-picked every `retargetEvery` s (`0.25`). A guard in an RTS, a co-op, a survival game with allies chases "whichever of the six is closest" — `target: "%Player"` was written for one hero. No member in reach: it waits |
+| `retargetEvery` | `0.25` | seconds between nearest-of-group picks (`0` = every frame) |
 | `speed` | `60` | units per second |
 | `stopRange` | `0` | stop (and emit reachedTarget) within this distance |
 | `loseRange` | `0` | give up beyond this distance (0 = never lose) |
 | `moveParent` | `false` | move the PARENT node instead of this one |
+| `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 |
 
@@ -462,6 +535,19 @@ whole entity toward the target. (Distance is measured from the moved parent.)
   "script": { "name": "Chase", "props": { "target": "/root/Player", "speed": 120, "stopRange": 20 } } }
 ```
 
+**`ground` — a walker, not a flyer.** A chaser used to move straight at
+`target.position` in every axis, so a player on a ledge was met by enemies
+pushing diagonally up whatever face was in the way — a 70° cliff included —
+and `slopeLimitDeg` never got a say. A `CharacterBody3D` mover is a walker by
+construction, so it now chases along the ground by default: the target's
+height is ignored, the KCC's `slopeLimitDeg` and `stepHeight` decide what it
+climbs (tps-3d's enemies declare `stepHeight: 0.7` and `slopeLimitDeg: 50`, and
+the arena's harness walks one up a 40° hill and into a 70° cliff), and it
+FALLS off what it walks off — scene gravity, accumulated while `isOnFloor()`
+says no. A flying enemy on a kinematic capsule says `ground: false`. In 2D it
+is opt-in (`ground: true` for a platformer's ground chaser), because a top-down
+game chases in y on purpose.
+
 **`facePath` — an NPC that does not run backwards.** `CharacterController3D`
 turns the PLAYER's skin toward its travel; for an NPC nothing did, so every 3D
 game hand-wrote the same `yaw = atan2(dx, dz)` — against a formula
@@ -481,12 +567,22 @@ It is opt-in (empty default turns nothing), it is the exact math and the exact
 `rotation` (`atan2(dy, dx)`) — right for top-down, so a PLATFORMER that faces
 with `flipX` should leave `facePath` empty.
 
-**A character body chases through the level, not through walls.** When the node
-being moved is a `CharacterBody2D`/`3D`, `Chase` (and `Patrol`) move it with
-`moveAndSlide()`, so it collides and slides like any character. A plain
+**A character body chases through the level, not through walls — and it IS one
+to the player.** When the node being moved is a `CharacterBody2D`/`3D`, `Chase`
+(and `Patrol`) move it with `moveAndSlide()`, so it collides and slides like any
+character. A kinematic body is immovable to a `RigidBody3D` player: a chaser
+coming head-on down a 6 m ramp held the player at the foot of it through six
+hits and two deaths, and an approach offset by 1.8 m went through with one.
+Give a choke point a way round, or the chaser is a door. A plain
 `Node2D`/`Node3D` — the example above — has no collider and keeps the direct
 write, which is also what you want for a ghost or a flying marker.
 
+**A horde ignores itself.** A hundred chasers that are all `CharacterBody3D`
+cost a second a step once they crowd the player — every `moveAndSlide` shape-casts
+against every neighbour. Give a swarm's template `collideWithCharacters: false`
+(measured on `examples/survivor-3d`: 120 husks, 1008 ms → 2.0 ms a step); they
+overlap each other and still hit the walls.
+
 This is straight-line homing, not pathfinding: a body can now be STOPPED by
 geometry it used to walk through. When enemies must find their way around a
 level, that is what `buildTerrainNav` + `findPath` + `PathFollow` are for (see
@@ -547,6 +643,31 @@ 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()`.
 
+## Turret
+
+The oldest verb in games: the nearest live member of `targetGroup` within
+`range`, hit for `damage` every `cooldown`. A defense tower, a ship's gun, a
+sentry, a trooper who fights what he meets. Two games in a row wrote these
+forty lines by hand before it existed — the engine had `Chase` for going TO a
+target and `Projectile` for the bullet, and nothing that decides to shoot.
+
+```json
+{ "name": "Gun", "type": "Node3D",
+  "script": { "name": "Turret", "props": { "range": 7, "damage": 12, "cooldown": 0.5, "facePath": "../Barrel" } } }
+```
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `targetGroup` | `"enemy"` | who it shoots — the nearest LIVE member (a dead `Health` is skipped) |
+| `range` | `6` | reach, in the scene's units |
+| `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` |
+| `facePath` / `turnSpeed` | `""` / `100` | a barrel to turn toward the target |
+
+Signals: `acquired(target)` · `fired(target)` · `lost()`. Getters: `target`,
+`shots`. Dimension-agnostic — a 2D tower is the same node with `[x, y]`.
+
 ## FaceTarget
 
 Turn toward the nearest thing in a group and say when you are pointed at it —
@@ -829,6 +950,12 @@ this.node.getNode('/Game/Towers').addChild(tower);
 
 Methods: `make(name)` · `names()`
 
+**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
+step; a listener attached a frame later (a director scanning a container in
+`update`) misses it. `make()` returns the node detached: wire `collected`,
+`died`, whatever you need, THEN `addChild`.
+
 - **Its children never enter the tree.** Claimed in `onEnterTree` (parent-first,
   so a template carrying its own shelf is taken intact), so nothing has to be
   `visible: false` and nothing has to be `"enabled": false`. A template left in
@@ -850,6 +977,14 @@ clone the editor uses (scripts and children come along; the clone gets a fresh
 identity). `max` caps LIVE instances (drops as spawned children free, so it
 refills); `total` caps LIFETIME spawns then emits `finished`.
 
+**One template per spawner, and do not move a spawner that has spawned.** The
+clones are the spawner's CHILDREN, so a gate that was moved to a new edge before
+each spawn dragged every husk it had ever made along with it (measured: they
+fell through the world). Four gates sharing one template lost it to the first —
+the detach below takes it out of the tree, and the other three found nothing.
+Give each spawner its own template child and let a director call `spawn()` on
+whichever gate it likes.
+
 **The template never ticks.** On first resolution the Spawner DETACHES the
 template node from the live tree (holding it only as a clone source), so its
 behaviors never run and it never renders — a `visible:false` template no longer
@@ -865,6 +1000,7 @@ later clones get `EnemyTemplate2`, `EnemyTemplate3`, …)
 | `at` | `[]` | where the clone appears, as an offset from the spawner ([x,y(,z)]) |
 | `autoStart` | `true` | begin ticking at ready |
 | `total` | `0` | total LIFETIME spawns (0 = infinite) |
+| `into` | `""` | node path of the CONTAINER clones are added to (`""` = under the spawner). Clones are placed at the spawner's world position plus `at`, and stay put when the spawner moves — the way to let a gate wander |
 
 Signals: `spawned(node)` · `finished` — Methods: `spawn()` · `start()` · `stop()`
 
@@ -966,7 +1102,15 @@ the heading on the projectile itself.
 |---|---|---|
 | `speed` | `300` | units per second along `direction` — **live**, rescales in flight |
 | `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) — **live** |
-| `gravity` | `0` | constant +y (downward, 2D y-down) pull for arcing shots |
+| `gravity` | `0` | constant DOWNWARD acceleration for arcing shots, in the scene's own convention (+y in 2D, −y in 3D): `9.81` lobs a 3D shell, `980` a 2D one |
+
+**Down is the scene's down.** It used to add to +y whatever the scene — the 2D
+convention — so `"gravity": 9.81` in a y-up 3D scene was a shell that CLIMBED
+(measured on tps-3d's mortar, speed 8, direction `[0.8, 0.6, 0]`: y 19.4 m after
+1.5 s and still rising at 59.8 m when its `Lifetime` freed it). A positive value
+now pulls down in both dimensions, the way `Chase.ground` signs its fall: the same
+mortar peaks at 2.1 m at 0.47 s and is under the floor by 1.5 s, the parabola a
+lob at 4.8 m/s up should draw.
 
 ### Aiming a bullet you just spawned
 
@@ -1239,6 +1383,7 @@ smashTheCrystal();
 session.step(200);
 
 session.engine.effects.countOf('explosion');            // 1
+session.engine.effects.countKind('shake');              // by KIND — a camera shake has no name
 session.engine.effects.countFrom('/Game/Crystal/Boom'); // 1
 session.engine.effects.recent();
 // [{ kind: 'burst', name: 'explosion', from: '/Game/Crystal/Boom', amount: 60, at: 1.2 }]
@@ -1316,8 +1461,18 @@ probably already carries the game's director script.
 
 Terminal states ignore further transitions; the restart action (or
 `flow.restart()`) reloads the scene from its source JSON — fresh nodes,
-physics, input. Listen to the `flowChanged(state)` signal for custom UI.
-`restartScene(engine)` is exported standalone.
+physics, input. Listen to the `flowChanged(state)` signal for custom UI —
+`state` is one of `"playing" | "paused" | "gameover" | "won"` (a LOSS is
+`"gameover"`, not "lost"; the signal the ScoreKeeper emits is `lost`, the
+state the flow lands in is `gameover`). `restartScene(engine)` is exported
+standalone.
+
+**A game that has ended does not advance.** `freezeOnEnd` (default `true`)
+sets the engine's `timeScale` to 0 on `won`/`gameover`, so every `engine.step()`
+after that — a harness's `do:` steps included — moves nothing and reports
+nothing; a page of zeros after a win is the game being over, not the
+controller being broken. Read `flow.state`, or set `freezeOnEnd: false` for a
+harness that keeps measuring past the end.
 
 **Any scene swap thaws.** The freeze lives on the engine, not on the flow, so
 leaving a game-over screen by your own route — `engine.setScene(loadScene(next, { engine }))`
@@ -1378,7 +1533,9 @@ runtime, which it keeps looking for.
 Signals: `dayPhaseChanged('dawn'|'day'|'dusk'|'night')` on transitions — hook
 spawners, music, or monster aggression to it. The `hour` field (0-24) is
 writable: jump to a time of day in one assignment. For one-off look changes
-use `setEnvironment3D(engine, patch)` from `incanto/3d` directly.
+use `setEnvironment3D(engine, patch)` from `incanto/3d` directly. A written `hour`
+announces its new phase on the NEXT update (a bed that jumps to dawn fires
+`dayPhaseChanged('dawn')` one frame later); only the sky patch is throttled.
 
 ## Boot loading overlay
 
@@ -1449,5 +1606,11 @@ npc.on('arrived', () => attack());
 default, corner-cutting forbidden; `{ diagonal: false }` for 4-way).
 `PathFollow` (registered behavior) walks waypoints at constant `speed`
 (units/sec — px in 2D, meters in 3D), emits `waypointReached(i)` /
-`arrived`, and `loop: true` patrols. Corners never eat frame budget — the
+`arrived`, and `loop: true` patrols. `moveParent: true` walks the PARENT —
+the AI-on-a-child pattern `Chase`/`Patrol`/`Wander` share, so a unit keeps
+its `Health` on the body and its path on a child — and the move lands through
+`moveBody`, so a kinematic unit walks its path with its collisions rather than
+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.