incanto 0.1.0

package/skills/incanto-gameplay-behaviors.md

@@ -0,0 +1,707 @@
+---
+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). Use when a game needs health, score, pickups, damage, timers, interaction, enemy movement/AI, camera-follow, tweens, or spawning — BEFORE hand-rolling them as custom behaviors.
+---
+
+# Gameplay behaviors — the built-in logic library
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Incanto ships the game logic every game re-invents, as ready-made `Behavior`s.
+You compose them through scene JSON — `"script"` blobs attach them, `connections`
+wire one behavior's signal to another's method. **No TypeScript required.**
+
+`createGame2D`/`createGame3D` (and the headless `runScript`/`createPlaySession`)
+**auto-register all of them** — just reference the names in scene JSON. Opt out
+with `gameplay: false`, or register a subset yourself:
+
+```ts
+import { registerGameplayBehaviors } from 'incanto/gameplay';
+registerGameplayBehaviors();                 // all of them (default in createGame)
+
+import { Health, Pickup, registerBehavior } from 'incanto/gameplay';
+registerBehavior('Health', Health);          // or pick just what you use
+```
+
+A same-named user behavior always wins: `createGame({ behaviors: { Health: MyHealth } })`
+registers AFTER the built-ins (with `replace: true`), overriding `Health`.
+
+All behaviors are **dimension-agnostic** (operate on `position` arrays / Area
+trigger signals, never three) and **pure logic** — they verify headlessly.
+
+## How they compose (signals → methods)
+
+A behavior declares **signals** it emits and exposes **methods** other behaviors
+or `connections` call. Wiring is just JSON:
+
+```json
+{ "connections": [
+  { "signal": "collected", "from": "Coin", "to": "/root", "handler": "addScore" },
+  { "signal": "died",      "from": "Player", "to": "/root", "handler": "loseLife" }
+] }
+```
+
+The signal's args become the handler's args (e.g. `collected(value, other)` →
+`addScore(value)`).
+
+### Node paths — connections vs. behavior props (READ THIS)
+
+Two kinds of node path resolve from DIFFERENT origins — mixing them up is the
+#1 wiring bug:
+
+- **Connection `from`/`to` resolve from the SCENE ROOT.** Use a name relative to
+  the root (`Player`, `Player/Weapon`), `/root` / `.` for the root node itself,
+  or `/root/<name>` absolute. `/root` is the tree root **whatever it is named**.
+- **A behavior's node-path prop** (`Chase.target`, `FollowCamera.target`,
+  Spawner `prefab`) **resolves from the node the behavior sits on.** A spawned
+  enemy (a child of the Spawner) reaches the player with the ABSOLUTE
+  `/root/Player`, never a bare `Player` (which would look under the enemy).
+
+**Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
+path is `/root/Player` — NOT `/root/Game/Player`: `/root/` already *is* the
+`Game` root, so `/root/Game/...` double-counts it and dangles at load. Likewise
+a connection `to` the root is `/root` (or `.`), never `/root/Game`.
+
+> Behaviors that react to collisions (`Pickup`, `DamageOnContact`) listen to the
+> unified `triggerEnter(other)` signal, so their node **must be an `Area2D`/`Area3D`**
+> (or another body that emits it). Attach them to a non-Area node and they fail
+> loudly at load (`UNKNOWN_SIGNAL`) — see `incanto-physics-and-input.md` for Areas.
+
+---
+
+## Health
+
+Hit points with regen and post-hit invulnerability (i-frames). The universal
+"can be hurt / can die" behavior. Hurt it via `damage(n)` (e.g. from
+`DamageOnContact`); heal/kill via `heal(n)` / `kill()`. Clamps to `0..max`,
+dies once.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `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) |
+| `freeOnDeath` | `false` | `queueFree()` this node when it dies (clone-safe) |
+
+Signals: `damaged(amount, current)` · `healed(amount, current)` · `died`
+Methods: `damage(n)` · `heal(n)` · `kill()` — state: `current`, `isDead`
+
+```json
+{ "name": "Player", "type": "CharacterBody2D", "groups": ["player"],
+  "props": { "collider": { "shape": "capsule", "radius": 12, "height": 32 } },
+  "script": { "name": "Health", "props": { "max": 50, "invulnerableFor": 1 } } }
+```
+
+> **Freeing dying SPAWNED entities — use `freeOnDeath`, not a connection.**
+> Scene `connections` are NOT copied onto Spawner/WaveSpawner clones, so a
+> `{ signal: "died", … handler: "queueFree" }` connection only ever wires the
+> TEMPLATE, never the live clones — enemies would never disappear on death. Put
+> `Health` (with `freeOnDeath: true`) on the **entity ROOT** instead: it is
+> node-local, so it clones perfectly and frees the whole enemy with no wiring.
+> (Connections are still the right tool for NON-cloned nodes, e.g. the player's
+> `died → ScoreKeeper.loseLife`.)
+
+## Lifetime
+
+Self-destruct after a fixed time — bullets, particles, temporary spawns. Emits
+`expired` then `queueFree()`s its node. `startOnSignal: true` defers the
+countdown until `startTimer()` (wire a signal → `startTimer`).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `seconds` | `1` | lifespan before self-free |
+| `startOnSignal` | `false` | defer the countdown until `startTimer()` |
+
+Signals: `expired` — Methods: `startTimer()`
+
+```json
+{ "name": "Bullet", "type": "Area2D",
+  "props": { "collider": { "shape": "circle", "radius": 3 } },
+  "script": { "name": "Lifetime", "props": { "seconds": 2 } } }
+```
+
+## ScoreKeeper
+
+The game's **state hub** — score, lives, win/lose. Put it on the Root/Game node
+and feed gameplay signals into its methods. Reaching `scoreToWin` emits `won`
+once; reaching 0 lives emits `lost` once.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `score` | `0` | starting score |
+| `lives` | `0` | starting lives (0 = lives disabled) |
+| `scoreToWin` | `0` | score that triggers `won` (0 = disabled) |
+
+Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)`
+Methods: `addScore(n)` · `setScore(n)` · `loseLife()`
+
+```json
+{ "name": "Game", "type": "Node",
+  "script": { "name": "ScoreKeeper", "props": { "scoreToWin": 10, "lives": 3 } } }
+```
+
+## Pickup
+
+A collectible that vanishes when a collector overlaps it. **Goes on an Area.**
+On `triggerEnter` with a node in `collectorGroup`, emits `collected(value, other)`
+then `queueFree()`s itself. Wire `collected → ScoreKeeper.addScore` (value is
+arg 0) or `→ Collector.collect`.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `value` | `1` | worth (passed as `collected`'s first arg) |
+| `kind` | `"coin"` | free-form label ('coin', 'gem', 'key', …) |
+| `collectorGroup` | `"player"` | only nodes in this group collect it |
+
+Signals: `collected(value, other)`
+
+```json
+{ "name": "Coin", "type": "Area2D",
+  "props": { "collider": { "shape": "circle", "radius": 8 } },
+  "script": { "name": "Pickup", "props": { "value": 5 } } }
+```
+```json
+{ "connections": [
+  { "signal": "collected", "from": "Coin", "to": "/root", "handler": "addScore" }
+] }
+```
+
+## Collector
+
+A per-actor "collect N" tally, on the collector itself (usually the player). Adds
+its node to `group` at ready (so matching Pickups count it as a collector). Wire
+a Pickup's `collected → Collector.collect`.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `group` | `"player"` | group it joins (Pickups match `collectorGroup` against this) |
+
+Signals: `totalChanged(total)` — Methods: `collect(value)` — state: `total`
+
+```json
+{ "name": "Player", "type": "CharacterBody2D",
+  "script": { "name": "Collector", "props": { "group": "player" } } }
+```
+
+## DamageOnContact
+
+Deals damage to whatever it touches — projectiles, spikes, lava, enemy hitboxes.
+**Goes on an Area.** On `triggerEnter`, finds the contacted entity's `Health` and
+calls `damage(amount)`, then emits `dealtDamage(amount, healthOwnerNode)`.
+`oncePerTarget` (default) prevents re-hitting a resting body every frame;
+`destroySelf` frees the hazard after a hit (single-use projectiles).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `amount` | `10` | HP removed per contact |
+| `targetGroup` | `""` | only damage targets whose Health-owner is in this group (`""` = any) |
+| `oncePerTarget` | `true` | damage each target at most once |
+| `destroySelf` | `false` | `queueFree()` after the first hit |
+
+Signals: `dealtDamage(amount, target)`
+
+**`targetGroup` — stop enemies killing each other.** With no collision layers in
+v0 (everything overlaps everything), an enemy's contact hitbox would damage any
+`Health` it touches, including other enemies clustered at the spawn point. Gate
+it by group: a player weapon uses `"targetGroup": "enemy"`, each enemy hitbox
+uses `"targetGroup": "player"` — so only the intended side is hurt. The group is
+checked on the node that OWNS the `Health`, not the collider that delivered the
+contact.
+
+**Robust `Health` resolution.** A real entity rarely carries `Health` on the
+exact collider that overlaps. `DamageOnContact` searches, nearest-first: the
+contacted node and its descendants, then up the ANCESTOR CHAIN (so `Health`
+on the entity ROOT is found from a child collider). It never searches an
+ancestor's sibling subtrees, so a hazard can't reach an unrelated entity
+across the scene — put `Health` on the entity root (recommended) or on the
+collider's own subtree.
+The first `Health` wins; its node is the `dealtDamage` target and the
+`targetGroup` subject. So you can put `Health` on the enemy ROOT and a collider
+on a child `Hit` Area — a weapon contacting either finds the root's `Health`.
+
+```json
+{ "name": "Spike", "type": "Area2D",
+  "props": { "collider": { "shape": "rect", "size": [32, 8] } },
+  "script": { "name": "DamageOnContact", "props": { "amount": 20 } } }
+```
+
+**Scoring on kill (clone-safe).** Wire the KILLER's `dealtDamage → addScore`.
+The weapon is a non-cloned player child, so its connection survives — unlike a
+connection on a spawned enemy, which never clones:
+`{ "signal": "dealtDamage", "from": "Player/Weapon", "to": "/root", "handler": "addScore" }`.
+
+## Interactable
+
+A proximity-gated "press to use" — doors, levers, chests, NPCs. Each frame, if an
+actor in `actorGroup` is within `range` (distance on `position` arrays, 2D or 3D)
+and the `action` input was just pressed, emits `interacted(actor)` (nearest
+in-range actor). Declare the input action in the scene `input{}`.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `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 |
+
+Signals: `interacted(actor)`
+
+```json
+{ "input": { "interact": { "type": "button", "keys": ["KeyE"] } },
+  "root": { "name": "Level", "type": "Node2D", "children": [
+    { "name": "Door", "type": "Node2D", "props": { "position": [200, 100] },
+      "script": { "name": "Interactable", "props": { "range": 48 } } }
+  ] } }
+```
+
+---
+
+# Movement, AI, camera & spawning
+
+These act on the node's transform (`position` array — 2D `[x,y]`, 3D `[x,y,z]`;
+`rotation`; `scale`). **Dimension-agnostic** and **pure** — they verify
+headlessly. A node carries ONE script, so compose by splitting roles across a
+small subtree (e.g. an enemy with `Chase` on the body and `Health` on a child
+hitbox) and wiring signals.
+
+## FollowCamera
+
+THE camera behavior. Put it on a `Camera2D`/`Camera3D` (whose `position` is the
+view center/eye) and point `target` at the player — each frame the camera lerps
+toward `target.position + offset`. Works in 2D and 3D.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `target` | `""` | node path to follow (required) |
+| `offset` | `[]` | constant offset added to the target position |
+| `smoothing` | `0` | 0..1 retention: 0 = instant snap, 0.85–0.95 = smooth drag (60fps-independent) |
+| `deadzone` | `0` | don't move until the target drifts this far from the desired point |
+
+```json
+{ "name": "Camera", "type": "Camera2D", "props": { "current": true },
+  "script": { "name": "FollowCamera", "props": { "target": "/root/Player", "smoothing": 0.9 } } }
+```
+
+## Patrol
+
+Walk a node along fixed waypoints at constant `speed` — guards, moving platforms.
+`points` are position arrays OR node paths (read live each frame, so you can
+author markers). Emits `reachedPoint(index)` on arrival.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `points` | `[]` | waypoints: position arrays or node-path strings (required) |
+| `speed` | `60` | units per second along the path |
+| `loop` | `true` | wrap to the first point after the last (loop mode) |
+| `mode` | `"loop"` | `'loop'` wraps · `'pingpong'` reverses at the ends |
+| `pauseAt` | `0` | seconds to wait at each reached point |
+
+Signals: `reachedPoint(index)`
+
+```json
+{ "name": "Guard", "type": "Node2D",
+  "script": { "name": "Patrol", "props": { "points": [[100, 0], [300, 0]], "speed": 80, "mode": "pingpong" } } }
+```
+
+## Chase
+
+Homing enemy AI: each frame moves toward `target.position` at `speed`, stopping
+within `stopRange` (melee reach). `reachedTarget` fires once on entering range
+(re-arms on leaving); `loseRange` gives up the chase (emits `lostTarget`).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `target` | `""` | node path to chase, resolved from THIS node (required) |
+| `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 |
+
+Signals: `reachedTarget` · `lostTarget`
+
+`target` is a node-path prop, so it resolves from THIS behavior's node — a
+spawned enemy reaches the player with the absolute `/root/Player` (a bare
+`Player` would look under the enemy).
+
+**`moveParent` — Chase + Health on one entity.** A node carries ONE behavior. An
+enemy whose ROOT must hold `Health(freeOnDeath)` (for clone-safe death) puts
+`Chase` on a CHILD `AI` node with `moveParent: true`; the child then drives the
+whole entity toward the target. (Distance is measured from the moved parent.)
+
+```json
+{ "name": "Enemy", "type": "Node2D", "groups": ["enemy"],
+  "script": { "name": "Chase", "props": { "target": "/root/Player", "speed": 120, "stopRange": 20 } } }
+```
+
+## Wander
+
+Seeded random roaming inside a circle around the spawn point — idle critters,
+ambient wildlife. Uses `this.rng`, so a seeded engine wanders identically every
+run (replayable, test-stable).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `speed` | `40` | units per second while roaming |
+| `radius` | `50` | roam radius around the spawn point |
+| `changeEvery` | `2` | seconds before forcibly picking a new destination |
+
+```json
+{ "name": "Critter", "type": "Node2D",
+  "script": { "name": "Wander", "props": { "speed": 30, "radius": 60, "changeEvery": 1.5 } } }
+```
+
+## ZombieAI
+
+The staple monster AI in ONE behavior: SHAMBLE around on its own, then LOCK ON and
+CHARGE `aggroTarget` (the player) once it wanders within `aggroRange` — giving up
+again past `deAggroRange` (hysteresis, no boundary flicker). Use this instead of
+`Wander`+`Chase` (a node carries ONE behavior, so they can't co-exist) whenever you
+want enemies that idle/roam until the player gets close, then rush in.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `aggroTarget` | `""` | node path to charge once near (usually `/root/Player`) |
+| `aggroRange` | `12` | start charging within this distance |
+| `deAggroRange` | `0` | give up beyond this (0 = `aggroRange` × 1.5) |
+| `chaseSpeed` | `4` | units/second while charging |
+| `wanderSpeed` | `1.4` | units/second while roaming |
+| `wanderRadius` | `8` | roam jitter radius |
+| `wanderChangeEvery` | `3` | seconds before picking a new roam goal |
+| `goalTarget` | `""` | optional node path to DRIFT toward while roaming |
+| `stopRange` | `1.2` | stop (idle) this close to the active target |
+| `moveParent` | `false` | move the PARENT node instead of this one |
+
+Signals: `enteredAggro` · `exitedAggro` · `movementStateChanged('idle'|'walk'|'run')`
+
+- **Wire `movementStateChanged` to a skin** to swap animation clips — shamble (`walk`)
+  while roaming, sprint (`run`) while charging, `idle` when stopped at the target.
+- **`goalTarget` = "advance on the objective".** With it set, the enemy DRIFTS toward
+  that node (e.g. a base/obelisk the horde is attacking) while still wandering, so it
+  reads as a roaming horde that nonetheless closes on the objective — but peels off to
+  CHARGE you when you stray within `aggroRange`. Leave it `""` for pure roam-around-spawn.
+- **`moveParent`** is the same AI-on-a-child pattern as `Chase`: the entity ROOT holds
+  `Health(freeOnDeath)`, a child `AI` node carries `ZombieAI(moveParent:true)`.
+- 3D: moves only in the GROUND PLANE (x,z) and leaves the up axis (y) to YOU.
+  `aggroRange` is measured on the ground (terrain height ignored). **It does NOT
+  auto-fall:** an AI-driven body whose position is set from script is kinematic, so on
+  rolling terrain you must ground it yourself each frame (`y = terrain.heightAt(x,z)` —
+  see incanto-3d-models.md "Grounding a model"). On a FLAT floor or for a HOVERING enemy
+  (drone), keeping the up axis is exactly right — it stays at its spawn height for free.
+
+```json
+{ "name": "Zombie", "type": "CharacterBody3D", "groups": ["enemy"],
+  "script": { "name": "Health", "props": { "max": 30, "freeOnDeath": true } },
+  "children": [
+    { "name": "AI", "type": "Node3D", "script": { "name": "ZombieAI",
+      "props": { "aggroTarget": "/root/Player", "aggroRange": 11, "chaseSpeed": 5,
+                 "goalTarget": "/root/Obelisk", "wanderSpeed": 1.6, "moveParent": true } } } ] }
+```
+
+### Driving a model's animation from a custom AI
+
+Built-in AIs emit a STATE signal; YOU map it to clips on the skin (the engine never
+guesses your clip names). Two equivalent patterns — both clone-safe because the behavior
+instance is per-entity (so they work for `WaveSpawner` clones, whose scene `connections`
+are NOT cloned):
+
+- **(A) self-wire in `onReady`** (what the showcases use — robust for spawned clones):
+  ```ts
+  export class ZombieSkin extends Behavior {           // attach to the GLB Skin node
+    onReady() {
+      const skin = this.node as unknown as ModelInstance3D;
+      const ai = this.node.parent?.getNodeOrNull('AI');  // the sibling carrying ZombieAI
+      const clips = { idle: '$idle', walk: '$walk', run: '$runFast' };
+      ai?.on('movementStateChanged', (s) => { const c = clips[s]; if (c) skin.animation = c; });
+    }
+  }
+  ```
+- **(B) scene `connection`** (fine for a single authored entity, NOT for clones):
+  `{ "signal": "movementStateChanged", "from": "Enemy/AI", "to": "Enemy/Skin", "handler": "setClip" }`.
+
+Same `ZombieSkin` is the place to also FACE the heading and GROUND the body each frame
+(see incanto-3d-character.md "+Z-FORWARD rule" and incanto-3d-models.md "Grounding").
+
+## MoveTo
+
+Eased position tween from the start to a fixed `to` over `duration` seconds —
+opening doors, sliding platforms, scripted moves. Emits `arrived` once.
+`startOnSignal: true` arms it via `start()` (wire a signal → `start`).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `to` | `[]` | destination position (required) |
+| `duration` | `1` | seconds the move takes |
+| `ease` | `"easeInOut"` | one of `linear` · `easeIn` · `easeOut` · `easeInOut` |
+| `startOnSignal` | `false` | defer until `start()` (default: begin at ready) |
+
+Signals: `arrived` — Methods: `start()`
+
+```json
+{ "name": "Platform", "type": "Node2D", "props": { "position": [0, 100] },
+  "script": { "name": "MoveTo", "props": { "to": [400, 100], "duration": 2, "ease": "easeInOut" } } }
+```
+
+## Oscillate
+
+Continuous sine motion around the start value — floating platforms, bobbing
+pickups, spinning/pulsing coins. Drives one `axis` of `position`, `rotation`
+(`mode: 'rotation'` — a "spin"), or `scale` (a "pulse"):
+`value = start + amplitude · sin(2π · frequency · t)`.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `axis` | `"y"` | component to drive (`x`/`y`/`z`; 2D rotation is `z`) |
+| `amplitude` | `1` | peak displacement from the baseline |
+| `frequency` | `1` | cycles per second |
+| `mode` | `"position"` | one of `position` · `rotation` · `scale` |
+
+```json
+{ "name": "Coin", "type": "Sprite2D",
+  "script": { "name": "Oscillate", "props": { "axis": "z", "amplitude": 180, "frequency": 0.5, "mode": "rotation" } } }
+```
+
+## Spawner
+
+Drip-feed clones of a TEMPLATE into the scene on a timer — enemy generators,
+pickup fountains. `prefab` is a node PATH to a template (usually a hidden
+`visible:false` child); each `interval` it's cloned via the same serialize→rebuild
+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`.
+
+**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
+walks its `Chase` onto the player. Clones go INTO the tree; the template stays
+out. (Because it's detached, the first clone keeps the template's exact name;
+later clones get `EnemyTemplate2`, `EnemyTemplate3`, …)
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `prefab` | `""` | node path of the template to clone (required) |
+| `interval` | `1` | seconds between spawns |
+| `max` | `0` | max LIVE instances (0 = unlimited) |
+| `at` | `[]` | offset added to the spawner position ([x,y(,z)]) |
+| `autoStart` | `true` | begin ticking at ready |
+| `total` | `0` | total LIFETIME spawns (0 = infinite) |
+
+Signals: `spawned(node)` · `finished` — Methods: `spawn()` · `start()` · `stop()`
+
+```json
+{ "name": "Spawner", "type": "Node2D",
+  "script": { "name": "Spawner", "props": { "prefab": "EnemyTemplate", "interval": 1.5, "max": 8 } },
+  "children": [
+    { "name": "EnemyTemplate", "type": "Area2D", "groups": ["enemy"], "props": { "visible": false },
+      "script": { "name": "Chase", "props": { "target": "/root/Player", "speed": 90 } } }
+  ] }
+```
+
+## WaveSpawner
+
+Sequenced enemy waves — the survivor / tower-defense backbone. Each `waves` entry
+is `{ prefab, count, interval, delayBefore }`: after `delayBefore` it spawns
+`count` clones (one every `interval`), then waits until they're ALL cleared
+(freed) before the next. Free dying enemies clone-safely with
+**`Health(freeOnDeath: true)` on the enemy root** — NOT a `died → queueFree`
+connection, which never clones onto spawned instances (see Health). `Lifetime`
+also frees timed spawns.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `waves` | `[]` | array of `{ prefab, count, interval, delayBefore }` (required) |
+| `autoStart` | `true` | begin the first wave at ready |
+
+Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
+
+```json
+{ "name": "Waves", "type": "Node2D",
+  "script": { "name": "WaveSpawner", "props": { "waves": [
+    { "prefab": "Grunt", "count": 5, "interval": 0.5, "delayBefore": 1 },
+    { "prefab": "Brute", "count": 2, "interval": 1, "delayBefore": 3 }
+  ] } },
+  "children": [ { "name": "Grunt", "type": "Area2D", "props": { "visible": false } } ] }
+```
+
+## Projectile
+
+Straight-line, constant-velocity motion — bullets, arrows, thrown rocks. Pure
+MOVEMENT by design: **compose** it with `DamageOnContact` (deal damage), `Lifetime`
+(auto-despawn) and an Area collider on the SAME node — don't conflate them.
+`direction` is a vector OR `'forward'` (from the node `rotation`); it's a
+union-typed prop so its default is `null` (= `'forward'`).
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `speed` | `300` | units per second along `direction` |
+| `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) |
+| `gravity` | `0` | constant +y (downward, 2D y-down) pull for arcing shots |
+
+```json
+{ "name": "Bullet", "type": "Area2D", "props": { "rotation": 0 },
+  "script": { "name": "Projectile", "props": { "speed": 600, "direction": "forward" } } }
+```
+> Compose: add `DamageOnContact` and `Lifetime` to make it actually hurt and
+> despawn. One node carries one script, so attach `Projectile` here and wire the
+> others onto sibling/child Area nodes (or use a Spawner that clones a fully-built
+> bullet template).
+
+---
+
+## A complete tiny game (only built-in behaviors + JSON)
+
+Player collects 2 coins to win; touching a spike kills them and loses the game.
+Zero custom TypeScript — every node's logic is a built-in behavior, every
+interaction is a `connection`.
+
+```json
+{
+  "format": 1, "type": "scene", "name": "TinyGame", "dimension": "2d",
+  "input": { "move": { "type": "vector2",
+    "keys": { "up": ["KeyW"], "down": ["KeyS"], "left": ["KeyA"], "right": ["KeyD"] } } },
+  "root": {
+    "name": "Game", "type": "Node",
+    "script": { "name": "ScoreKeeper", "props": { "scoreToWin": 2, "lives": 1 } },
+    "children": [
+      { "name": "Player", "type": "CharacterBody2D", "groups": ["player"],
+        "props": { "position": [0, 0], "collider": { "shape": "circle", "radius": 12 } },
+        "script": { "name": "Health", "props": { "max": 30 } },
+        "children": [{ "name": "Ctl", "type": "CharacterController2D",
+          "props": { "mode": "topDown" } }] },
+      { "name": "Coin1", "type": "Area2D", "props": { "position": [80, 0],
+        "collider": { "shape": "circle", "radius": 8 } },
+        "script": { "name": "Pickup", "props": { "value": 1 } } },
+      { "name": "Coin2", "type": "Area2D", "props": { "position": [160, 0],
+        "collider": { "shape": "circle", "radius": 8 } },
+        "script": { "name": "Pickup", "props": { "value": 1 } } },
+      { "name": "Spike", "type": "Area2D", "props": { "position": [120, 80],
+        "collider": { "shape": "rect", "size": [24, 24] } },
+        "script": { "name": "DamageOnContact", "props": { "amount": 40, "oncePerTarget": false } } }
+    ]
+  },
+  "connections": [
+    { "signal": "collected", "from": "Coin1", "to": "/root", "handler": "addScore" },
+    { "signal": "collected", "from": "Coin2", "to": "/root", "handler": "addScore" },
+    { "signal": "died", "from": "Player", "to": "/root", "handler": "loseLife" }
+  ]
+}
+```
+
+Boot it with `createGame2D({ canvas, scene })` — the behaviors are already
+registered. Listen to the win/lose from your page:
+
+```ts
+const game = await createGame2D({ canvas, scene });
+game.scene.root.on('won', () => alert('You win!'));
+game.scene.root.on('lost', () => alert('Game over'));
+```
+
+Verify it headlessly (no browser) with `incanto/test` — see
+`incanto-verifying-your-game.md`.
+
+## The "survivor" recipe (movement + AI + spawn + camera + win/lose, ZERO custom code)
+
+A complete top-down survivor that **actually survives a headless run** (mirrored
+by `survivor-game.test.ts`): a `WaveSpawner` drips enemies that `Chase` the
+player; the player's weapon one-shots them and they free + score themselves;
+enemies deal contact damage that drains the player; a `FollowCamera` tracks the
+player; reaching the kill target WINS, dying LOSES. Every node's logic is a
+built-in, every interaction a `connection` — **no custom `Behavior` classes**.
+
+The five features that make it compose from the box (and obsolete the custom
+glue an early sim had to hand-write):
+
+1. **`DamageOnContact.targetGroup`** — the weapon hits only `enemy`, each enemy
+   hitbox hits only `player`. Without it, enemies clustered at spawn kill each
+   other before reaching the player.
+2. **`Health.freeOnDeath`** — node-local, so it clones; the dying enemy frees
+   ITSELF (no per-clone `died → queueFree` connection, which never clones).
+3. **weapon `dealtDamage → addScore`** — the connection is on the WEAPON (a
+   non-cloned player child), so it is clone-safe; scoring per kill just works.
+4. **`Chase.moveParent`** — a node has ONE behavior, so the enemy ROOT holds
+   `Health(freeOnDeath)` while a child `AI` carries `Chase(moveParent:true)` and
+   drives the whole entity.
+5. **correct paths** — behavior targets are absolute (`/root/Player`, resolved
+   from the enemy/camera node); connection `to` the root is `/root` or `.`.
+
+```json
+{
+  "format": 1, "type": "scene", "name": "Survivor", "dimension": "2d",
+  "input": { "move": { "type": "vector2",
+    "keys": { "up": ["KeyW"], "down": ["KeyS"], "left": ["KeyA"], "right": ["KeyD"] } } },
+  "root": {
+    "name": "Game", "type": "Node",
+    "script": { "name": "ScoreKeeper", "props": { "scoreToWin": 3, "lives": 1 } },
+    "children": [
+      { "name": "Player", "type": "CharacterBody2D", "groups": ["player"],
+        "props": { "position": [0, 0], "collider": { "shape": "circle", "radius": 12 } },
+        "script": { "name": "Health", "props": { "max": 100 } },
+        "children": [
+          { "name": "Ctl", "type": "CharacterController2D", "props": { "mode": "topDown" } },
+          { "name": "Weapon", "type": "Area2D",
+            "props": { "collider": { "shape": "circle", "radius": 24 } },
+            "script": { "name": "DamageOnContact",
+              "props": { "amount": 1, "targetGroup": "enemy" } } }
+        ] },
+      { "name": "Camera", "type": "Camera2D", "props": { "current": true },
+        "script": { "name": "FollowCamera", "props": { "target": "/root/Player", "smoothing": 0.9 } } },
+      { "name": "Spawner", "type": "Node2D",
+        "script": { "name": "WaveSpawner", "props": { "waves": [
+          { "prefab": "EnemyTemplate", "count": 3, "interval": 0.6, "delayBefore": 0 }
+        ] } },
+        "children": [
+          { "name": "EnemyTemplate", "type": "CharacterBody2D", "groups": ["enemy"],
+            "props": { "position": [300, 0], "visible": false,
+              "collider": { "shape": "circle", "radius": 12 } },
+            "script": { "name": "Health", "props": { "max": 1, "freeOnDeath": true } },
+            "children": [
+              { "name": "AI", "type": "Node2D",
+                "script": { "name": "Chase",
+                  "props": { "target": "/root/Player", "speed": 90, "moveParent": true } } },
+              { "name": "Hit", "type": "Area2D",
+                "props": { "collider": { "shape": "circle", "radius": 12 } },
+                "script": { "name": "DamageOnContact",
+                  "props": { "amount": 10, "targetGroup": "player", "oncePerTarget": false } } }
+            ] }
+        ] }
+    ]
+  },
+  "connections": [
+    { "signal": "dealtDamage", "from": "Player/Weapon", "to": "/root", "handler": "addScore" },
+    { "signal": "died",        "from": "Player",        "to": "/root", "handler": "loseLife" }
+  ]
+}
+```
+
+> **Role-splitting (one script per node):** the enemy ROOT carries
+> `Health(freeOnDeath)` (so freeing it removes the whole enemy on death); the
+> `AI` child carries `Chase(moveParent:true)` to move that root; the `Hit` child
+> carries the enemy's contact damage. The weapon contacts the enemy root or any
+> child — `DamageOnContact` resolves `Health` from the contacted node, its
+> descendants, then up the ancestor chain, so it finds the entity root's
+> `Health` either way (it won't cross into a sibling entity).
+> The weapon's `dealtDamage(amount, target)` scores `amount` (1) per hit; with
+> 1-HP enemies one hit = one kill = +1; 3 kills → `won`. The player dying →
+> `loseLife` → `lost`.
+
+> **Canonical full example:** `examples/star-survivor/` is this recipe grown into
+> a real, playable 2D game (real Area2D/CharacterBody2D nodes, FollowCamera,
+> `Oscillate` spinning star pickups, a `coin` sprite, and a HUD). It is built
+> from these built-ins with ZERO custom gameplay code — the only TypeScript is a
+> tiny `HudUpdater` that paints `ScoreKeeper.score`/`Health.current` into Labels
+> (the gameplay library is renderer-agnostic and intentionally doesn't draw HUD
+> text). Its `verify.ts` proves the win AND lose paths headlessly via
+> `runScript`. Copy it as the starting point for any survivor/arena game.
+
+## When to write a custom behavior instead
+
+These cover the common scaffolding. Write your own `Behavior` (see
+`incanto-behaviors-and-scripts.md`) for game-specific logic — enemy AI, custom
+movement, puzzle rules — and compose it WITH these via signals (e.g. your AI
+behavior calls `getNode('Player').behavior` ... or simpler, wire your behavior's
+signal into a built-in's method through a `connection`).
+
+## Exact contract
+
+Generated, always-current prop/signal tables for every behavior live in
+`incanto-node-reference.md` (the "Gameplay behaviors" section).
+```