incanto 0.56.0 → 0.58.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-DTdwKKIv.js"></script>
+    <script type="module" crossorigin src="./assets/index-CBgfM3WD.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -88,6 +88,7 @@
     "@pixiv/three-vrm": "^3.5.3"
   },
   "bin": {
+    "incanto": "bin/incanto.mjs",
     "incanto-skills": "bin/incanto-skills.mjs",
     "incanto-editor": "bin/incanto-editor.mjs",
     "incanto-model": "bin/incanto-model.mjs",

package/skills/incanto-assets.md

@@ -182,7 +182,11 @@ frame 40. Those frames draw whatever is at the wrong end of the sheet.
 ```
 
 The suggested sizes are the ones that actually divide your image, so the fix is
-usually in the message. `bunx incanto-assets info <name>` prints the real frame
+usually in the message. **All three nodes that cut a grid out of an image check
+it** — `AnimatedSprite2D`, `AnimatedSprite3D` and `TileMap2D` — because they do
+the same floor-division and it fails the same silent way. An
+`AnimatedSprite3D` with a sheet and no `frameWidth`/`frameHeight` also says so
+rather than drawing a mob-shaped hole. `bunx incanto-assets info <name>` prints the real frame
 size for a built-in, and the editor's 📚 picker fills it in from the catalog's
 metadata — or leaves it BLANK when the catalog does not carry it, because an
 invented frame size is exactly this bug.

package/skills/incanto-audio.md

@@ -350,6 +350,11 @@ background loop authored in scene JSON. Wire `crossfadeTo` from gameplay:
 this.engine.music.crossfadeTo('/audio/boss.mp3', 3);
 ```
 
+**A track that will never play says so.** A 404 or an undecodable file lands in
+the engine log (`[incanto] music '/audio/boss.mp3' will not play — could not
+load.`) instead of being indistinguishable from a game with no music. The
+autoplay gate is still just the gate — a track waiting for a tap is not an error.
+
 > Large music files are NOT bundled — reference them by URL (see §4).
 
 **Headless the state machine still runs and `current` still updates** — nothing
@@ -448,7 +453,8 @@ bricking the game.
 ### Quality tiers
 
 ```ts
-import { qualityEnvironment, readDeviceHints, suggestQuality, setEnvironment3D } from 'incanto';
+import { qualityEnvironment, readDeviceHints, suggestQuality } from 'incanto';
+import { setEnvironment3D } from 'incanto/3d'; // it applies a 3D environment
 
 const tier = engine.settings.get('quality') ?? suggestQuality(readDeviceHints());
 setEnvironment3D(engine, qualityEnvironment(tier));

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-gameplay-behaviors.md

@@ -20,7 +20,8 @@ with `gameplay: false`, or register a subset yourself:
 import { registerGameplayBehaviors } from 'incanto/gameplay';
 registerGameplayBehaviors();                 // all of them (default in createGame)
 
-import { Health, Pickup, registerBehavior } from 'incanto/gameplay';
+import { registerBehavior } from 'incanto';
+import { Health, Pickup } from 'incanto/gameplay';
 registerBehavior('Health', Health);          // or pick just what you use
 ```
 

package/skills/incanto-hud.md

@@ -167,6 +167,12 @@ widget use `UiButton`'s `pressed`.
 Setting `.value` from a behavior updates the control and does **NOT** re-emit
 `changed` — restoring a saved setting must not fire the handler that saved it.
 
+**Every prop is live.** `color`, `size`, `width`, `background`, `label` and
+`anchor` are re-read each frame, so flashing the score red, growing a health bar
+or moving a widget to another corner all work from a behavior — and from the
+editor's inspector, which is the same code path. They used to be baked in when
+the widget was built and could never be changed afterwards.
+
 ## Playable on a controller (focus navigation)
 
 A menu you can only click is not playable on a gamepad, and "add controller

package/skills/incanto-performance.md

@@ -92,6 +92,11 @@ that built a mesh), dispose it in the behavior's `onExitTree`.
 | `renderScale` | `0.25`–`2` | image softness only | **yes** |
 | antialiasing | follows the tier | jagged edges at `low` | **no — boot only** |
 
+`maxFps` and `renderScale` apply in **2D as well as 3D** now — they persisted for
+every game and were applied by the 3D boot only, so a 2D options menu saved a
+number and changed nothing. `quality` remains a 3D tier (there are no shadows,
+bloom or clouds to drop in 2D).
+
 ### quality
 
 **Water follows the tier too, and it is the biggest single saving.**

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

@@ -192,6 +192,20 @@ engine.input.pressAction('jump');           // one justPressed frame, held until
 engine.input.releaseAction('jump');         // …released (one justReleased frame)
 engine.input.setActionVector('move', 1, 0); // analog vector2; (0, 0) clears
 ```
+
+**An action name you typed that does not exist says so.** A controller tolerates
+a missing action — a game with no sprint key must not crash — but a value you
+NAMED and never declared is a typo, and it used to be indistinguishable from the
+tolerated case:
+
+```
+[incanto] /Game/Player/Ctl: Unknown input action 'movement'.
+Declared actions: [move, jump]. The character will not move.
+```
+
+Once per node and action, and only when the prop differs from its default —
+leaving `sprintAction` alone in a game with no sprint key is the ordinary case
+and stays silent.
 Injected state combines with key state (vectors clamped to unit length).
 
 ## Patterns

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-save-slots.md

@@ -146,7 +146,8 @@ The engine does not route scenes — deliberately, because only your game knows
 what a key means. What it does is record the key, so the routing is a lookup:
 
 ```ts
-import { createGame2D, loadScene } from 'incanto';
+import { loadScene } from 'incanto';
+import { createGame2D } from 'incanto/2d';
 import level1 from './level1.scene.json';
 import level2 from './level2.scene.json';
 

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

@@ -29,14 +29,15 @@ 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
 ? 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`
 ```
 
 Runs the rungs below in order and says the ONE thing to do next. Three rules it
@@ -399,6 +400,10 @@ shouting the same thing every frame has one problem, not six hundred.
 
 ### `bunx incanto-frame` — what is actually on screen
 
+Works for **2D and 3D** games alike (as does `incanto-logs`, and `game.frame()`).
+Both used to be answered by the 3D boot only, so a 2D preview that was open and
+drawing reported "no page answered".
+
 The rung above framing. `framing` PREDICTS what the camera should see from the
 scene graph; this measures what the GPU drew — the only one that can catch a
 black screen, a material that failed, or a shader drawing where it should not.
@@ -769,7 +774,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.56.0",
+    "incanto": "^0.58.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).

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

@@ -0,0 +1,60 @@
+# Status — platformer-2d (Incanto)
+
+## Implemented
+
+- Full-window single-canvas page with loading overlay, an on-screen JUMP button,
+  and the iframe GAME_SIZE harness.
+- `game.scene.json` — **Castle Run**: viewport (`design [960,540]`, `fit:
+  expand`), `physics.gravity [0,1800]`, `move` (A/D + arrows) / `jump`
+  (Space/W/Up) input, `knight`/`goblin` sheets + `coin`/`gem` textures, and the
+  level —
+  - `Game` root: `ScoreKeeper` (`scoreToWin 100000`, `lives 3`).
+  - Parallax castle backdrop (sky, sun, clouds, far castle band + towers, near
+    castle band + battlements) via `ParallaxLayer`.
+  - `GroundA–D` stone with green moss caps and gaps; `Plat1–4` floating
+    platforms; `MovePlat` (`Patrol` horizontal) + `Lift` (`Oscillate` vertical),
+    both group `platform` (rideable).
+  - `Spikes1/2` (`hazard`), `DeathPlane` (`pit`), `Checkpoint`, `Goal`.
+  - `Gob1–3` goblins (`Patrol` + `GoblinSkin`, group `enemy`).
+  - 12 coins + 2 gems (`Pickup` + bobbing `Oscillate` sprite).
+  - `Player` (`CharacterBody2D` + `PlayerController`) with `Skin` (knight) +
+    `Feet` sensor; `Camera` (`FollowCam`); SFX players; HUD + banner UILayers.
+- Custom code in `src/behaviors.ts`: `PlayerController` (coyote/buffer/double-
+  jump/variable height/stomp/knockback/hearts+lives/checkpoint respawn/platform
+  carry/anim), `GoblinSkin`, `FollowCam` (follow + shake), `ParallaxLayer`,
+  `HudUpdater`. Particle puffs on double-jump/stomp/land/checkpoint via
+  `Particles2D`.
+- `connections`: each coin/gem `collected → addScore` (+ SFX); root `won/lost →
+  SfxWin/SfxLose`.
+- `main.ts`: inject the four asset urls, `createGame2D`, optional music, JUMP
+  button, remove loader, expose `window.game`. Node uids omitted (loader-
+  generated).
+
+## Works (verified)
+
+- `bun run check` → 1/1 scene valid. `bun run typecheck` → clean. `bun run lint`
+  → clean.
+- `bun run verify` (headless `runScript`): 13/13 assertions pass — run right,
+  jump off the ground and settle, a coin raises the score (Pickup → addScore), a
+  STOMP removes a goblin and scores, a side hit costs a heart, dying respawns the
+  knight at the checkpoint, the goal emits `won` once, and a pit fall with the
+  last life emits `lost`.
+- Played in a real browser (`bun run dev`, Playwright-driven): the knight + the
+  goblins render as their real animated sheets; coins/gems render as sprites;
+  ground has moss caps; the parallax castle bands scroll; HUD shows ◆ coins,
+  ♥♥♥ hearts and lives. A tap jump is a short hop (~41px), a held jump is full
+  (~156px), and a mid-air press double-jumps — variable height + double-jump
+  confirmed. FollowCam tracks + clamps to the level bounds. ZERO console errors.
+
+## Not Included (on purpose — and the next polish passes)
+
+- Background castle is styled `ColorRect2D` (no tilemap node in v0): two parallax
+  layers (`CastleFarLayer` 0.82 / `CastleNearLayer` 0.6), each a Node2D with ONE
+  `ParallaxLayer` whose children (wall band + towers + crenellation merlons + warm
+  glowing windows + a gate + a pennant) inherit the scroll. Reads clearly as a
+  castle skyline; swap for tile/sprite art later.
+- No wall-jump/dash, no enemy variety beyond the goblin, no melee (the knight
+  has an attack sheet 12–17 if you want it), no bundled music (SFX presets only).
+- One hand-authored level — extend by copying nodes into the right GROUP
+  (`enemy`/`hazard`/`pit`/`checkpoint`/`platform`); `PlayerController` picks them
+  up with no extra wiring.

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

@@ -0,0 +1,77 @@
+# Structure — platformer-2d (Incanto)
+
+## `index.html`
+
+Full-window page: inline favicon, loading overlay (removed once the game boots),
+one `#game` canvas, an on-screen `#btn-jump` button (mobile parity), the
+iframe-embed GAME_SIZE script, and the module entry.
+
+## `src/game.scene.json`
+
+THE whole level (open it with `npx incanto-editor`):
+
+- scene header — `environment.background`, `viewport` (`design [960,540]`, `fit:
+  expand`), `physics.gravity [0,1800]`, `move`/`jump` input, and the
+  `knight`/`goblin` spritesheets + `coin`/`gem` texture `assets` (urls injected
+  in `main.ts`).
+- `Game` root — `ScoreKeeper` (`scoreToWin 100000`, `lives 3`).
+- Parallax castle backdrop — `Sky`/`Sun`/`Cloud1–3` (far), `CastleFar` band +
+  `TowerFarA–C`, `CastleNear` band + `BattlementA/B` — `ColorRect2D` +
+  `ParallaxLayer` (factor 0.6–0.96, higher = farther).
+- `GroundA–D` — `StaticBody2D` stone (brown body + green `Moss` cap) with GAPS
+  (pits) between them.
+- `Plat1–4` — static floating platforms; `MovePlat` (`Patrol` pingpong, group
+  `platform`) ferries the first pit; `Lift` (`Oscillate` vertical, group
+  `platform`) crosses the spike pit.
+- `Spikes1/2` (group `hazard`) and `DeathPlane` (group `pit`, far below).
+- `Checkpoint` (group `checkpoint`, blue flag) and `Goal` (group `goal`, gold
+  flag + gate).
+- `Gob1–3` — Node2D (group `enemy`) + `Patrol`; children `Skin`
+  (`AnimatedSprite2D` goblin) + `AI` (`GoblinSkin`).
+- `Coins/Coin1–12` — Area2D `Pickup` (value 10) with a bobbing `coin` sprite
+  child; `Gem1/2` — Area2D `Pickup` (value 50) with a bobbing `gem` sprite.
+- `Player` — `CharacterBody2D` (group `player`, capsule) + `PlayerController`;
+  children `Skin` (`AnimatedSprite2D` knight idle/run/jump) + `Feet` (Area2D
+  sensor for moving-platform carry).
+- `Camera` — `Camera2D` (`current`) + `FollowCam` (look-ahead, clamped `limits`,
+  screen-shake).
+- `SfxJump/Coin/Stomp/Hurt/Checkpoint/Win/Lose` — `AudioPlayer` SFX presets
+  (PlayerController plays jump/stomp/hurt/checkpoint directly; coins/win/lose via
+  `connections`).
+- `HUD` — UILayer (top-left, `HudUpdater`): Coin / Hearts / Lives / Hint Labels.
+  `BannerLayer` — UILayer (center) win/lose `Banner`.
+- `connections` — each coin/gem `collected → ScoreKeeper.addScore` (+ SFX); root
+  `won/lost → SfxWin/SfxLose`. (Stomp/hit/checkpoint/respawn/win-trigger are
+  resolved by `PlayerController`, not connections.)
+
+## `src/behaviors.ts`
+
+- `PlayerController` — the heart: run/gravity/coyote/buffer/double-jump/variable
+  height, stomp + bounce, side-hit knockback, hearts+lives, checkpoint respawn,
+  moving-platform carry (via the `Feet` sensor), sprite clip + facing + i-frame
+  blink. All enemy/hazard/pit/checkpoint/goal contact is AABB against groups in
+  `resolveContacts()`.
+- `GoblinSkin` — face the patrol heading + play the goblin walk clip.
+- `FollowCam` — follow (look-ahead + smoothing + world clamp) + `shake()`.
+- `ParallaxLayer` — re-anchor a backdrop to `cameraX · factor` for depth.
+- `HudUpdater` — score/hearts/lives Labels + win/lose banner.
+
+## `src/main.ts`
+
+Boot: inject the four built-in asset urls, `createGame2D({ canvas, scene,
+behaviors })`, optional `engine.music`, the JUMP button, remove the loader,
+expose `window.game`.
+
+## `verify.ts`
+
+Browserless proof via `incanto/test` `runScript`: run+jump (off the ground and
+back), coin scoring, STOMP (goblin removed + scored), side-hit costs a heart,
+checkpoint respawn (die → back at the flag), WIN (goal → `won`), LOSE (pit with
+the last life → `lost`). Run with `bun run verify`.
+
+## `docs/project-2d-rules.md`
+
+The vibe-coding rules: read the skills, JSON structure, built-ins first, omit
+uids, declared assets, y-down space, collider props, GROUP-DRIVEN centralised
+damage (§8), deferred engine access (§11), debug draw, delta discipline, verify
+like a user.