incanto 0.57.0 → 0.59.0

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

@@ -10,6 +10,19 @@ description: Build 2D web games with Incanto — y-down pixel coordinates, strin
 
 Prerequisite: `incanto-scene-json-authoring.md` (this directory) for the file format. This skill covers the 2D taxonomy.
 
+## Fastest start: scaffold a whole game
+
+```bash
+bunx incanto new my-game --template platformer-2d    # tilemap, jump feel, follow cam, coins
+bunx incanto new my-game --template star-survivor    # endless waves, auto-attack, upgrades
+bunx incanto new --list                              # every starter, 3D and 2D
+```
+
+Templates are COMPLETE games — level, HUD, sound, and a `verify.ts` harness
+that plays them end to end — meant to be reshaped rather than read. Prefer
+starting from one over wiring from scratch; `bun run verify` in the new project
+tells you the moment a change breaks the game.
+
 ## Coordinate convention (Phaser/Godot prior)
 
 **1 unit = 1 px · (0,0) top-left · +y DOWN · positive rotation = clockwise (degrees).**

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

@@ -20,9 +20,9 @@ reports a file's real bounding box and animation names.
 ## Fastest start: scaffold a whole game
 
 ```bash
-bunx incanto-new my-game                     # Beacon Isle — 3D flagship template
-bunx incanto-new my-game --template tps-3d   # third-person shooter starter
-bunx incanto-new --list
+bunx incanto new my-game                     # Beacon Isle — 3D flagship template
+bunx incanto new my-game --template tps-3d   # third-person shooter starter
+bunx incanto new --list
 ```
 
 Templates are COMPLETE games (world generation, quest, enemies, verify

package/skills/incanto-localization.md

@@ -65,12 +65,29 @@ the `"$assetKey"` references you already write:
 
 ```json
 { "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } }
-{ "name": "Wave",  "type": "UiText",   "props": { "text": "@t:hud.wave" } }
+{ "name": "Wave",  "type": "UiText",   "props": { "format": "@t:hud.wave" } }
 ```
 
-Works on every text-bearing widget: `UiText.text`, `UiButton.text`,
-`UiBar.label`, `UiSelect.label`, `UiBanner.show()`, and `UiDialogue` lines,
-speakers and choices.
+Works on every text-bearing widget: `UiText.text` and `.format`,
+`UiButton.text`, `UiBar.label`, `UiSelect.label` **and `.options`**,
+`UiBanner.show()`, `UiDialogue` lines/speakers/choices — and `Label3D` / 2D
+`Label`, the text that lives in the world.
+
+**A key with a `{}` slot needs `format`, not `text`.** A prop resolves the key
+and paints the result verbatim: `"hud.wave": "Wave {n}"` in `text` puts the
+characters `Wave {n}` on screen. `format` is the template `setText` fills:
+
+```json
+{ "name": "Wave", "type": "UiText", "props": { "format": "@t:hud.wave" } }
+```
+```ts
+wave.setText(String(n));   // "Wave 3" — and it re-reads on a language switch
+```
+```json
+"strings": { "en": { "hud.wave": "Wave {}" }, "ko": { "hud.wave": "{} 웨이브" } }
+```
+
+The slot moves with the language, which is the whole reason it is a slot.
 
 From a behavior, `engine.t(key, params)`:
 
@@ -78,8 +95,9 @@ From a behavior, `engine.t(key, params)`:
 banner.show(this.engine.t('hud.wave', { n: this.wave }));
 ```
 
-`{n}` slots are filled from `params`; a slot with no matching param is left
-alone rather than blanked.
+`{n}` slots are filled from `params` — this is the ONLY path that fills a NAMED
+slot; a scene-JSON prop has no params to fill it from. A slot with no matching
+param is left alone rather than blanked.
 
 ## The language picker
 
@@ -96,10 +114,24 @@ because a player who cannot read the language on screen still has to find theirs
 Picking one switches the game **live** and persists the choice through
 `engine.settings`, so the next visit opens in it.
 
+### Text that lives in the world
+
+`Label3D` and the 2D `Label` resolve `@t:` too, and re-bake their texture when
+the language changes — a sign over a shop door, a nameplate, a damage number.
+The prop keeps the marker; only the painted words change.
+
+```json
+{ "name": "Sign", "type": "Label3D",
+  "props": { "text": "@t:sign.welcome", "height": 0.4 } }
+```
+
 ## What NOT to localize
 
-- **Values, not labels.** `UiSelect.options` are values the game compares
-  against (`"low,medium,high"`); translating them breaks the comparison.
+- **Option VALUES stay identifiers — but you can still translate what is shown.**
+  `UiSelect.options` are what the game compares against, and `@t:` in an option
+  changes only the words on screen: the value `changed` emits is exactly what
+  you wrote. So `"options": "@t:diff.easy,@t:diff.hard"` displays 쉬움/어려움
+  and still hands your handler `@t:diff.easy`.
 - **Node names, group names, asset keys, signal names, action names.** These are
   identifiers.
 - **Anything a behavior parses.** If code does `if (value === 'start')`, that

package/skills/incanto-multiplayer.md

@@ -49,9 +49,32 @@ Authority rules:
 ] }
 ```
 
+**The `network` block is validated at LOAD.** It used to be the one node-level
+block the loader cloned without looking at, and its typos are invisible at
+runtime — a string `sync`, a capitalised `mode`, the plural `syncs` each mean
+"nothing replicates and nothing says so", and produce a report identical to a
+working game's. All three are hard `BAD_FORMAT` errors now, and
+`bunx incanto check` catches them before you ever open a browser:
+
+```
+[BAD_FORMAT] "network.sync" must be an ARRAY of prop names, not "position"
+             — write ["position"] (on 'Player')
+```
+
+Valid keys: `mode` (`owner` | `observer`), `sync` (array of prop names),
+`throttleMs` (number). An `owner` with an empty `sync` is an error too — it is
+a half-finished edit that behaves exactly like a broken one.
+
 - **ONE owner node per player.** Its `sync` keys are relative to ITSELF
-  (`position` = own prop, `Skin.animation` = child path + prop). Changed values coalesce
-  into one throttled `setMyState({sync: {...}})` per window. Spawned entities (bullets,
+  (`position` = own prop, `Skin.animation` = child path + prop). A change to ANY
+  of them sends ALL of them, once per throttle window — the payload is the whole
+  set, deliberately: backends shallow-merge one level down, so a partial patch
+  would REPLACE the stored `sync` object and erase every key that had stopped
+  changing (a team colour, a skin, a name). Players already in the room would
+  never notice — they applied it once and kept it — while the next joiner
+  rendered the default forever. An idle owner still sends nothing until the
+  keyframe (`keyframeMs`, default 2 s) comes round, which is also what heals a
+  send that never reached the wire. Spawned entities (bullets,
   pickups) go through **collections**, never extra owner nodes.
 - **`NetworkSpawner`** (register with `registerNodesNet()`): `source: "users"` spawns one
   instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
@@ -193,8 +216,38 @@ It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
 **Verifying a whole match**: `playMultiplayer` from `incanto/test` runs N clients
 against one in-memory server for a fixed number of simulated seconds and reports
 what they ended up sharing — rooms, who saw whom, what each `NetworkSpawner`
-materialised, per-client frame errors, the final room state. See
-`incanto-verifying-your-game.md`.
+materialised, per-client frame errors, the final room state, and **whether the
+clients hold the same VALUES**.
+
+That last part is the one that matters and the one that used to be missing.
+"Saw p2" only ever meant "p2 is in the room" — the kernel puts an empty entry
+there at join — so a game whose replication was completely dead reported exactly
+what a working one did. After the match quiesces, every key in every owner's
+`network.sync` is read on the sender and on each other client's spawned copy and
+compared:
+
+| | |
+|---|---|
+| `missing` | that client never materialised the account at all |
+| `absent` | the key path does not resolve on the spawned scene — a renamed child |
+| `shape` | different array lengths; a componentwise lerp calls that "already correct" |
+| `mismatch` | the values differ beyond the interpolation tolerance |
+| `erased` | the live clients agree, and a LATE JOINER never got it |
+
+`erased` is why the harness brings one more client in after everything settles.
+Players already in the room applied a value once and kept it on their node, so
+they agree with each other while the authoritative snapshot is already wrong —
+a two-browser test cannot see it, and the next person to join sees the default
+forever. Set `lateJoin: false` to skip that half; `seed` makes the whole match
+reproducible.
+
+**What it does not prove.** One in-memory server means no latency, no loss, no
+reordering: this measures the apply path and the protocol shape, never the live
+wire. A reconnect that never re-joins, a throttle that discards a payload, a
+batch dropped on a closed socket — none of those are in reach, and the report
+says so on its own summary line.
+
+See `incanto-verifying-your-game.md`.
 
 **Driving one by hand**: server calls are QUEUED and only run when the event loop
 turns, so a synchronous frame loop enqueues a thousand ticks that never execute —

package/skills/incanto-node-reference.md

@@ -81,6 +81,7 @@ Signals: `animationFinished(name)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -97,6 +98,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -213,6 +215,7 @@ Signals: `finished`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `velocity` | `[0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
@@ -232,6 +235,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `velocity` | `[0,0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
@@ -713,6 +717,7 @@ Signals: `finished`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
 | `fixedRotation` | `false` | boolean |
@@ -735,6 +740,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
 | `fixedRotation` | `false` | boolean |
@@ -828,6 +834,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -844,6 +851,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -1377,6 +1385,16 @@ Signals: `dealtDamage(amount, target)`
 
 Signals: `dayPhaseChanged`
 
+### `FloatAway`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `rise` | `1` | number |
+| `seconds` | `0.7` | number |
+| `hold` | `0.3` | number |
+| `drift` | `0` | number |
+| `freeOnEnd` | `true` | boolean |
+
 ### `FollowCamera`
 
 | Prop | Default | Kind |

package/skills/incanto-physics-and-input.md

@@ -79,6 +79,32 @@ mesh or one model and warns when the body carries more.
   (capsule recommended), `velocity`, `stickToGround true`, `slopeLimitDeg 45`.
   API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`.
 
+### `enabled` — a collider that is off for now
+
+Every physics body takes **`enabled`** (default `true`). Off means no contacts
+and no `triggerEnter`/`triggerExit`; the body stays, so nothing is rebuilt and
+re-arming is one write.
+
+```jsonc
+// a melee hitbox: real collider, authored OFF
+{ "name": "Sword", "type": "Area2D",
+  "props": { "collider": { "shape": "circle", "radius": 30 }, "enabled": false } }
+```
+```ts
+sword.enabled = true;    // the active window of the swing
+sword.enabled = false;   // …and done
+```
+
+**Do not arm a hitbox by swapping `collider` in and out.** Replacing the
+collider prop tears the rigid body down and builds a new one — twice per swing —
+and a scene authored `"collider": {}` warns `has no collider — physics skips it`
+on every boot, which is true and unactionable and teaches its reader to ignore
+warnings.
+
+Good for anything that is sometimes solid: a door that opens, a platform that
+phases, a shield that is only up while blocking, a trigger that fires once and
+retires.
+
 Physics simulates WORLD positions: bodies under offset parents work (offsets compose),
 but ancestor ROTATION/SCALE are not supported for physics bodies — keep body ancestors
 untransformed or translation-only.

package/skills/incanto-playtesting.md

@@ -50,7 +50,8 @@ two.
 | `lost` | `GameFlow` `'gameover'`, a `lost` signal, or the player's `Health.died` |
 | `fell` | the player left the world past `--fall-below` (default: 50 m under the spawn in 3D, 1000 px under it in 2D) |
 | `error` | `stats().errors` went above zero — a behavior threw |
-| `stuck` | none of the above before the clock ran out |
+| `stuck` | the clock ran out AND the player never got more than 3 m (96 px) from its spawn — it is wedged, or nothing moves it |
+| `unfinished` | the clock ran out on a player that was getting around. Not a defect: a win that needs a SEQUENCE (talk to the NPC, then fetch, then return) is out of reach of a random walker, forever |
 | `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) |
 | `never fired` | signals a `connections[]` entry listens to that never happened |
 | `danger` | how many times the player's `Health` emitted `damaged` |
@@ -91,9 +92,20 @@ unreachable or the connection is wrong.
 is exactly right (a walking simulator). Usually it means the hazards are not
 wired up.
 
-**`stuck` in every run** with no `won` at all usually means the scene declares
-no win condition — add a `GameFlow` or a `ScoreKeeper` and the report becomes
-far more useful.
+**`stuck` in every run** means the player is not going anywhere: wedged in
+geometry, spawned inside a collider, or missing the input map that moves it.
+That is a real bug and worth chasing.
+
+**`unfinished` in every run** is the normal report for a quest or story game
+and means nothing is wrong. Random play cannot perform a sequence. Judge those
+games with a SCRIPTED harness — `runScript` from `incanto/test`, which every
+template's `verify.ts` is built on — and let the playtest tell you about
+crashes, falls and dead hazards instead. `incanto-verify` marks the rung
+`unmeasured` rather than failed for exactly this reason.
+
+(These were one word until 0.58: `stuck` was the default verdict, so a quest
+game that visited every landmark and fired two dozen signals was reported the
+same as a player stuck in a wall.)
 
 ## Replays
 
@@ -116,7 +128,9 @@ Then read where it ended. The player above left a walled 40×40 arena at
 read straight off the replay.
 
 One file per *kind* of failure — twenty identical "stuck" replays teach nothing
-the first one does not.
+the first one does not. `unfinished` runs write no replay at all: a replay is
+for reproducing a failure, and eight of them per verify bury the one that is
+real.
 
 ## Your behaviors
 

package/skills/incanto-verifying-your-game.md

@@ -29,16 +29,39 @@ failures — but `framing` and `assetErrors()` you have to ASK for.
 ## 0. The whole ladder, one command: `incanto-verify`
 
 ```
-$ bunx incanto-verify                       # finds your scene
+$ bunx incanto verify                       # finds your scene AND your behaviours
+· behaviours: src/behaviors.ts (found, not named)
 ✓ loads — the scene is legal and its assets resolve
-? plays — nothing declares a win — 8 runs played without error, and there was no end to reach
+? plays — 8 runs played without reaching a win (4 lost, 4 ran out the clock)
 ✓ feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
+· agrees — not run — this scene has no `multiplayer` header
 ? draws — the dev server is running on :5173, but no page answered
 
 passes what was measured — plays, draws not measured.
-next: if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)
+next: nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`
 ```
 
+### `agrees` — do two clients hold the same values?
+
+Skipped outright unless the scene has a `multiplayer` header. When it does,
+`incanto multiplay` runs a real match headlessly, lets it QUIESCE, then reads
+every key in the owner's `network.sync` on the sender and on each other
+client's spawned copy and compares them — plus one client that joins AFTER
+everything settles, which is the only observer that reads the authoritative
+snapshot fresh.
+
+```
+✓ agrees — 8 replicated value(s) match across clients and a late joiner
+           — over one in-memory server, not a live wire
+✗ agrees — p2 has no `Skin.rotation` for p1 — the key path does not resolve on
+           the spawned scene (a renamed child?), or it was never sent.
+```
+
+That trailing clause is not modesty, it is the measurement's boundary: one
+in-memory server has no latency, no loss and no reordering, so this proves the
+apply path and says nothing about a reconnect that never re-joins or a batch
+dropped on a closed socket.
+
 Runs the rungs below in order and says the ONE thing to do next. Three rules it
 encodes so you do not have to remember them:
 
@@ -773,7 +796,13 @@ bunx incanto-playtest src/game.scene.json --runs 20 --seconds 60
 A seeded bot plays it headlessly — reading the scene's own `input{}` for its
 controls — and reports the win rate, destinations it could never reach, wires
 that never fired, falls out of the world, and whether anything can hurt the
-player at all. Failing runs come back as replays. Exits 1 when nothing ever won.
+player at all. Failing runs come back as replays.
+
+**`won`, `lost` and `unfinished` are all gameplay; `error`, `fell` and `stuck`
+are defects.** A random bot cannot perform a sequence, so a quest or story game
+reports `unfinished` in every run and that means nothing is wrong — judge those
+with a scripted `runScript` harness and let this one tell you about crashes,
+falls and dead hazards.
 
 Read `incanto-playtesting.md` before shipping a level.
 

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.57.0",
+    "incanto": "^0.59.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/src/game.scene.json

@@ -2713,7 +2713,8 @@
               "volume": 0.6
             }
           }
-        ]
+        ],
+        "uid": "n_klf0y16b0ct0deyk"
       },
       {
         "name": "Sky",
@@ -2917,7 +2918,7 @@
           {
             "name": "Quest",
             "type": "UiText",
-            "uid": "n_bi_quest",
+            "uid": "n_ysul3v903v7r9bqw",
             "props": {
               "text": "Find the lighthouse keeper [E]",
               "size": 16,
@@ -2928,7 +2929,7 @@
           {
             "name": "HP",
             "type": "UiBar",
-            "uid": "n_bi_hp",
+            "uid": "n_x49lxq49wej0w332",
             "props": {
               "anchor": "topRight",
               "value": 100,
@@ -2939,7 +2940,7 @@
           {
             "name": "Banner",
             "type": "UiBanner",
-            "uid": "n_bi_banner",
+            "uid": "n_7kqv8wsefrki826x",
             "props": {
               "anchor": "center"
             }
@@ -2947,7 +2948,7 @@
           {
             "name": "Dialogue",
             "type": "UiDialogue",
-            "uid": "n_bi_dialogue",
+            "uid": "n_y0bq7vt5tewf88ny",
             "props": {
               "anchor": "bottom",
               "charsPerSecond": 45
@@ -2956,7 +2957,7 @@
           {
             "name": "Hint",
             "type": "UiText",
-            "uid": "n_bi_hint",
+            "uid": "n_osy8mwjnmfp9zicd",
             "props": {
               "text": "WASD move · Shift sprint · E interact · click/F strike",
               "size": 12,

package/templates-app/platformer-2d/PROJECT/Context.md

@@ -0,0 +1,70 @@
+# Context — platformer-2d (Incanto)
+
+## Project Overview
+
+**Castle Run** — a polished 2D adventure PLATFORMER, the clone-and-modify
+starter for the platformer genre. You run a medieval knight through a castle:
+solid ground with gaps, floating platforms, a horizontal patrolling platform and
+a vertical bobbing lift you RIDE, spinning coins + gems to grab, spikes and a
+bottomless pit to avoid, patrolling goblins you STOMP from above (and chain-
+bounce off), a checkpoint flag, and a gold goal flag. Three hearts per life,
+three lives; touch the goal to clear the castle, run out of lives for GAME OVER.
+
+The level is BUILT-IN gameplay wired in scene JSON. What's custom is the
+platformer GAME FEEL the renderer-agnostic library leaves open: a hand-tuned
+`PlayerController` (coyote-time, jump-buffer, double-jump, variable jump height,
+stomp, knockback, hearts+lives, checkpoint respawn, moving-platform carry) plus
+presentation glue (`GoblinSkin`, `FollowCam` with screen-shake, `ParallaxLayer`,
+`HudUpdater`).
+
+## Tech Stack
+
+_Exact versions are in `package.json`._
+
+- **Game engine**: `incanto` (scene-JSON-first, three.js-rendered) +
+  `incanto/2d` (createGame2D, 2D nodes: CharacterBody2D/StaticBody2D/Area2D,
+  AnimatedSprite2D, ColorRect2D, Camera2D, UILayer/Label, Particles2D,
+  AudioPlayer) + `incanto/gameplay` (auto-registered Pickup, Patrol, Oscillate,
+  ScoreKeeper, …).
+- **Art**: built-in animated sheets `medieval-knight` (player) + `goblin`
+  (enemy), and `coin` + `gem` item textures — all bundler-imported from the
+  package and injected into the scene asset urls in `main.ts`. Ground, platforms,
+  spikes, flags and parallax castle are styled `ColorRect2D`.
+- **Audio**: zero-asset procedural SFX presets (jump/coin/hit/hurt/powerup/
+  win/lose); an OPTIONAL `engine.music` hook for a looping track.
+- **Build / Lang**: Vite, TypeScript. **Headless verify**: `incanto/test`
+  (`runScript`) — see `verify.ts`. No React — a single full-window canvas.
+
+## Critical Memory
+
+- READ THE SKILLS FIRST: `node_modules/incanto/skills/` —
+  `incanto-gameplay-behaviors.md`, `incanto-physics-and-input.md` (2D bodies +
+  input + units), `incanto-building-2d-games.md`, `incanto-audio.md`.
+- MOVEMENT is the custom `PlayerController` (NOT the built-in
+  `CharacterController2D`, which is frame-perfect/stiff). It integrates velocity
+  on the `CharacterBody2D` and adds the forgiveness a good platformer needs:
+  coyote-time, jump-buffer, double-jump, variable jump height (release early =
+  short hop), stomp-to-kill + bounce, side-hit knockback + i-frames.
+- DAMAGE IS CENTRALISED + GROUP-DRIVEN: the player has NO built-in `Health`.
+  `PlayerController` owns hearts (3) + reads `ScoreKeeper.lives`, and resolves
+  ALL contact each frame by AABB against GROUPS — `enemy` (stomp from above /
+  hurt on the side), `hazard` (spikes), `pit` (death plane), `checkpoint`,
+  `goal`, `platform` (rideable). One authority → no stomp-vs-damage double-hit.
+- RESPAWN is IN-LEVEL: `Health` can't revive (dies once, `heal` is a no-op when
+  dead), so the player uses hearts/lives instead and `PlayerController` teleports
+  to the last `checkpoint` on death (no scene reload). `ScoreKeeper.loseLife` at
+  0 lives emits `lost`.
+- WIN: touching the `goal` group sets the score to `scoreToWin` (100000) →
+  `won`. Coins (10) + gems (50) are score flavour only; they can't reach the
+  threshold, so only the flag wins.
+- MOVING-PLATFORM CARRY: the kinematic controller doesn't inherit platform
+  velocity, so the player has a `Feet` Area sensor that remembers the `platform`
+  it stands on; `PlayerController` adds that platform's per-frame delta so you
+  ride it.
+- ENGINE ACCESS IS DEFERRED: `this.engine` throws in `onReady` during
+  `loadScene` (scene not attached yet) — read scene config (gravity) lazily on
+  the first `fixedUpdate`. `getNode`/signal wiring is fine in `onReady`.
+- `FollowCam` does follow + screen-shake in ONE behavior (one script per node):
+  `PlayerController.shake()` calls into it on stomps/landings/hits.
+- Node uids are omitted in the JSON — the loader generates them. `window.game`
+  exposes the Game handle in the console.

package/templates-app/platformer-2d/PROJECT/Requirements.md

@@ -0,0 +1,63 @@
+# Requirements — platformer-2d (Incanto)
+
+## Coding Patterns
+
+- Game STRUCTURE belongs in `src/game.scene.json` (nodes, props, input map,
+  assets, scripts, connections, viewport, physics). Prefer a BUILT-IN gameplay
+  behavior over hand-writing logic — check
+  `node_modules/incanto/skills/incanto-gameplay-behaviors.md` and
+  `incanto-physics-and-input.md` BEFORE writing a Behavior class.
+- MOVEMENT is the custom `PlayerController` on the player `CharacterBody2D` (the
+  built-in `CharacterController2D` is intentionally stiff; a great platformer
+  needs coyote-time/jump-buffer/double-jump/variable height/stomp). It integrates
+  `velocity` + `moveAndSlide()` + `isOnFloor()` itself. Tune feel with the
+  constants at the top of `behaviors.ts` (RUN_SPEED, JUMP_V, COYOTE, BUFFER,
+  STOMP_BOUNCE, …), not by editing the loop.
+- Custom logic in TypeScript (`src/behaviors.ts`):
+  - `PlayerController` — run/gravity/coyote/buffer/double-jump/variable height,
+    stomp + knockback, hearts+lives, checkpoint respawn, moving-platform carry,
+    and the idle/run/jump sprite + facing + i-frame blink.
+  - `GoblinSkin` — face the patrol heading + play the goblin walk clip (it lives
+    on the goblin's `AI` child, so it reads the PARENT's position and `../Skin`).
+  - `FollowCam` — follow the knight (look-ahead + smoothing + world clamp) AND
+    screen-shake on demand (one script per node).
+  - `ParallaxLayer` — scroll a castle backdrop slower than the camera.
+  - `HudUpdater` — paint score/hearts/lives into the HUD + win/lose banner.
+- DAMAGE + INTERACTIONS are GROUP-DRIVEN, not per-node wiring: tag a node with a
+  group and `PlayerController` handles it by AABB each frame — `enemy`, `hazard`,
+  `pit`, `checkpoint`, `goal`, `platform`. Adding an enemy/hazard = add a node in
+  the right group. (Pickups are the exception: coins/gems use the built-in
+  `Pickup` + `connections` `collected → ScoreKeeper.addScore` + `→ AudioPlayer.play`.)
+- Moving platforms: `Patrol` (horizontal ferry) / `Oscillate` (vertical lift) on
+  a `StaticBody2D` in the `platform` group — the `Feet` sensor + carry logic ride
+  them. Bobbing pickups: `Oscillate` on the sprite child.
+- Keep `main.ts` thin: inject the four built-in asset urls (knight/goblin/coin/
+  gem), boot `createGame2D` with the scene + behaviors, optional music, the
+  on-screen JUMP button, remove the loader, expose `window.game`. There is NO
+  respawn-via-scene-reload (respawn is in-level in `PlayerController`).
+- Omit node `uid`s (the loader generates them).
+- VERIFY headlessly first: `bun run verify` drives the real scene through
+  `incanto/test`'s `runScript` and asserts run+jump, coin scoring, STOMP, side-
+  hit hearts, checkpoint respawn, the win path, and the lose path.
+
+## Known Issues / Constraints
+
+- No collision LAYERS in v0 — gameplay collisions are resolved by `PlayerController`
+  AABB against groups, so PLACE content in the right group; physics solids
+  (`StaticBody2D`) are only for standing/colliding.
+- `Health` dies once and exposes no revive, so the PLAYER deliberately does NOT
+  use it — hearts/lives live in `PlayerController` + `ScoreKeeper`, and respawn is
+  an in-level teleport to the last checkpoint (no scene reload, no lost progress
+  jump-cut). Goblins are removed with `queueFree()` on stomp (no `Health` needed).
+- Score is flavour: coins 10, gems 50; `scoreToWin` 100000 so ONLY the goal flag
+  wins (collecting everything can't reach the threshold).
+- Built on `incanto/2d` physics (auto-enabled — the scene has bodies). Player =
+  `CharacterBody2D` (kinematic KCC), platforms/ground = `StaticBody2D`, pickups/
+  hazards/checkpoint/goal/feet-sensor = `Area2D`.
+- Sprites: `medieval-knight` (idle 0–5, move 6–11, attack 12–17; jump reuses a
+  move frame) and `goblin` (idle 0–6, move 7–12). Swap a sheet by changing only
+  the asset entry + the import in `main.ts`.
+- The parallax "castle" is styled `ColorRect2D` bands + towers (no tilemap node
+  in v0). Background art is the obvious next polish pass; the hero sprites carry
+  the look. Music is OPTIONAL (`MUSIC_URL` empty by default; SFX presets need no
+  files).