incanto 0.32.0 → 0.33.0

package/skills/incanto-hud.md

@@ -80,3 +80,44 @@ Typewriter reveal at `charsPerSecond` (0 = instant); clicking the box
 reveals the line then advances; choice lines render buttons and wait for
 `choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
 click-through.
+
+## Menus, options and inventories (UiPanel + the value widgets)
+
+The HUD widgets can SAY things. These arrange them and take a value back — which
+is what a title screen, pause menu, options panel, shop and inventory grid are.
+Before them every one of those was hand-rolled DOM, which drops the whole screen
+out of scene JSON, out of the editor, out of `incanto-check` and out of every
+headless check you have.
+
+**`UiPanel` is the box.** Widgets normally mount into the HudLayer's anchor slot
+no matter how the tree is shaped; anything under a panel mounts into the PANEL,
+so structure in the tree becomes structure on screen. Panels nest.
+
+```json
+{ "name": "Pause", "type": "UiPanel",
+  "props": { "anchor": "center", "layout": "column", "gap": 12, "padding": 20 },
+  "children": [
+    { "name": "Title", "type": "UiText", "props": { "text": "PAUSED", "size": 28 } },
+    { "name": "Volume", "type": "UiSlider", "props": { "label": "volume", "value": 0.8 } },
+    { "name": "Invert", "type": "UiToggle", "props": { "label": "invert Y" } },
+    { "name": "Quality", "type": "UiSelect", "props": { "options": "low,medium,high", "value": "high" } },
+    { "name": "Resume", "type": "UiButton", "props": { "label": "Resume" } }
+  ] }
+```
+
+| node | props | signal |
+| --- | --- | --- |
+| `UiPanel` | `layout` (column/row/**grid**), `columns`, `gap`, `padding`, `background`, `radius`, `width`, `height`, `border` | — |
+| `UiImage` | `src` (url or `$assetKey`), `width`, `height`, `fit`, `tint`, `opacity` | — |
+| `UiSlider` | `label`, `value`, `min`, `max`, `step`, `width`, `color` | `changed(value)` |
+| `UiToggle` | `label`, `value` | `changed(bool)` |
+| `UiSelect` | `label`, `options` (`"low,medium,high"`), `value` | `changed(value)` |
+
+**An inventory is a grid panel**: `"layout": "grid", "columns": 5`, one child per
+slot, each a small `UiPanel` holding a `UiImage` (`tint` greys out what you
+cannot afford) — and `Clickable` is on the world node, not the widget; for a
+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.
+

package/skills/incanto-node-reference.md

@@ -246,6 +246,17 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `jumpHeight` | `64` | number |
 | `moveAction` | `"move"` | string |
 | `jumpAction` | `"jump"` | string |
+| `coyoteSeconds` | `0` | number |
+| `jumpBufferSeconds` | `0` | number |
+| `jumpCutMultiplier` | `1` | number |
+| `maxJumps` | `1` | number |
+| `dashSpeed` | `0` | number |
+| `dashSeconds` | `0.15` | number |
+| `dashAction` | `"dash"` | string |
+| `wallSlideSpeed` | `0` | number |
+| `wallJumpImpulse` | `[0,0]` | array |
+
+Signals: `movementStateChanged(state)`
 
 ## `CharacterController3D` — `incanto/3d`
 
@@ -958,6 +969,63 @@ Signals: `pressed`
 
 Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 
+## `UiImage` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `src` | `""` | string |
+| `width` | `48` | number |
+| `height` | `48` | number |
+| `fit` | `"contain"` | one of: `contain` `cover` `fill` |
+| `tint` | `""` | string |
+| `opacity` | `1` | number |
+
+## `UiPanel` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `layout` | `"column"` | one of: `column` `row` `grid` |
+| `columns` | `4` | number |
+| `gap` | `8` | number |
+| `padding` | `12` | number |
+| `background` | `"rgba(0,0,0,0.55)"` | string |
+| `radius` | `10` | number |
+| `width` | `0` | number |
+| `height` | `0` | number |
+| `border` | `""` | string |
+
+## `UiSelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `options` | `""` | string |
+| `value` | `""` | string |
+
+Signals: `changed`
+
+## `UiSlider` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `value` | `0.5` | number |
+| `min` | `0` | number |
+| `max` | `1` | number |
+| `step` | `0.01` | number |
+| `width` | `180` | number |
+| `color` | `"#6ee7dc"` | string |
+
+Signals: `changed`
+
 ## `UiText` — `incanto`
 
 | Prop | Default | Kind |
@@ -969,6 +1037,17 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `color` | `"#ffffff"` | string |
 | `shadow` | `true` | boolean |
 
+## `UiToggle` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `value` | `false` | boolean |
+
+Signals: `changed`
+
 ## `VoxelGrid3D` — `incanto/3d`
 
 | Prop | Default | Kind |
@@ -1084,6 +1163,16 @@ Signals: `submerged` · `surfaced`
 
 Signals: `reachedTarget` · `lostTarget`
 
+### `Clickable`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `button` | `0` | number |
+| `maxDistance` | `0` | number |
+| `enabled` | `true` | boolean |
+
+Signals: `clicked` · `hovered` · `unhovered`
+
 ### `Collector`
 
 | Prop | Default | Kind |

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

@@ -258,6 +258,56 @@ the tree says, without your scene falling over while you look at it. Use it for
 any "show me the collision geometry" tool. Do NOT use it to freeze a running
 game — that is `engine.timeScale = 0`, which keeps the world coherent.
 
+## Moving platforms carry their riders (2D **and** 3D)
+
+A `CharacterBody2D`/`CharacterBody3D` standing on a body that moves is dragged
+along by however far that body moved — elevators, patrol platforms, conveyors,
+rotating discs. It is what makes a floating-island game work.
+
+Author it the obvious way: move the platform's `position` (a behavior, a
+`PathFollow`, an `Oscillate`). Nothing else to declare.
+
+The carry stops the moment the character is no longer grounded on it, so walking
+off an edge or jumping is not "sticky", and it is vertical as well as horizontal
+— an elevator lifts you.
+
+## The mouse as gameplay input (click, hover)
+
+`pointerDelta()` answers "how far did the mouse move" — the mouse-look question.
+For match-3, tower defense, card games, point-and-click and RTS that is the
+wrong question, and it used to be the only one the engine could answer.
+
+```ts
+engine.input.pointerPosition();   // { x, y } in CANVAS pixels, or null
+engine.input.mousePressed(0);     // 0 left · 1 middle · 2 right
+engine.input.mouseJustPressed(0); // and mouseJustReleased(0)
+game.pick(x, y);                  // the node under that pixel, or null
+```
+
+A stretched canvas is handled: `pointerPosition()` scales client → canvas pixels,
+so the coordinates are the ones `pick()` wants.
+
+From scene JSON, the **`Clickable`** behavior needs no code at all:
+
+```json
+{ "name": "Tile", "type": "MeshInstance3D", "script": { "name": "Clickable" } }
+```
+
+| prop | default | |
+| --- | --- | --- |
+| `button` | `0` | 0 left · 1 middle · 2 right |
+| `maxDistance` | `0` | ignore clicks further than this (0 = any) |
+| `enabled` | `true` | stop responding without detaching |
+
+Signals: **`clicked`**, **`hovered`**, **`unhovered`** — wire them in
+`connections` like any other. `clicked` fires on RELEASE over the same node the
+press started on (a drag that ends elsewhere is not a click, the way every
+button on every platform behaves), and a hit on a CHILD counts as a hit on the
+node — the raycast lands on the visual mesh, which is usually a child.
+
+Headless there is no renderer and therefore no raycast: `Clickable` is inert
+rather than wrong, and `engine.picker` is null.
+
 ## Placement rules
 
 `CharacterController2D` MUST be a direct child of a `CharacterBody2D` — the

package/templates-app/beacon-isle-3d/docs/project-3d-rules.md

@@ -5,15 +5,17 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    manual, version-pinned to what is installed. Start with
    `incanto-building-3d-games.md`, `incanto-3d-character.md`,
    `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
-   `incanto-audio.md` — this template composes all five.
+   `incanto-hud.md` — this template composes them —
+   and FINISH with `incanto-verifying-your-game.md` (rule 11).
 2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
-   replication all live in `src/game.scene.json`. Add nodes there (or with
+   replication all live in `src/*.scene.json`. Add nodes there (or with
    `npx incanto-editor`), NOT by constructing them ad-hoc in code.
 3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
    registered with `registerBehavior('Name', Class)` and attached in JSON via
    `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
-   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
-   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+   before writing your own — this template already uses
+   Health, DamageOnContact, Interactable, PathFollow, DayNight, and its only custom behaviors are
+   `IsleDirector` and `SwordStrike`.
 4. 🔑 UIDS ARE GENERATED: every node uid comes from
    `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
@@ -23,21 +25,40 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    (Euler XYZ). Negative gravity falls.
 7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
    on a body node — never child shape nodes. Wrong shapes hard-fail at load.
-8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
-   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
-   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
-   headless runs are a no-op).
-9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
-   `enablePhysics3D` returns) draws every collider in the running game; or boot
-   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+8. 🖥️ THE HUD IS NODES: this template's HUD lives in the scene as a
+   `HudLayer` with `UiText`/`UiBar` children — the engine builds the DOM for
+   them and positions them by anchor. Edit the HUD in `*.scene.json` like any
+   other node. (A DOM-in-`index.html` HUD is the other valid shape, and what
+   `tps-3d` does; both are supported — do not mix them in one screen.)
+9. 🐛 DEBUG WHEN UNSURE: `VITE_INCANTO_DEBUG=1 bun run dev` adds the ☰ debug
+   menu — Explorer/Inspector (click a node, see and edit its live props), Logs,
+   Stats and Colliders (every physics shape as a wireframe, drawn by the same
+   Rapier the game runs). There is NO `VITE_INCANTO_DEBUG=1` URL toggle: it was
+   removed as deploy-unsafe. Never ship the env flag on.
 10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
     loader treats unknown/garbage props as hard errors, which is your friend.
-11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
-    proves the loop headlessly, then `bun run dev` and actually PLAY what you
-    changed (move, shoot, clear a wave) before declaring it done.
-12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
-    debug menu — Explorer/Inspector (click a node, see and edit its live props),
-    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
-    wireframe). Blocked in mid-air or falling through the floor is a Colliders
-    question; a mystery frame-rate is a Stats question. Never ship the flag on.
+11. ✅ VERIFY LIKE A USER, THEN READ THE FOUR SIGNALS. `bun run check` and
+    `bun run verify` are the start, not the end — you cannot SEE this game, and
+    each of these answers a failure that otherwise looks like nothing at all:
+
+    | read | it is not clean when |
+    | --- | --- |
+    | `bunx incanto-check` | the scene will not load, or renders black (no light) |
+    | `stats().errors` | something threw and was skipped to keep the game alive |
+    | `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+    | `framing` | the camera points the wrong way, or nothing is lit |
+
+    ```bash
+    printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+    ```
+
+    `framing` reports what the camera SEES — on screen / off screen / behind it
+    — plus what lights the scene and which colliders intersect. `behind` looks
+    exactly like "my model did not load"; nothing else can tell you apart.
+    Then `bun run dev` and actually PLAY what you changed.
+12. 🧯 A THROWN ERROR NO LONGER STOPS THE GAME: a behavior that throws is
+    reported once (node, script, phase, file:line) and SKIPPED — your script
+    stops, the node it is attached to keeps running, the game plays on. So a
+    game that looks fine can still be broken: read `stats().errors`, and
+    `engine.resumeErroredNodes()` after you fix it.
 </userRequest>

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.32.0",
+    "incanto": "^0.33.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/docs/project-3d-rules.md

@@ -5,15 +5,17 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    manual, version-pinned to what is installed. Start with
    `incanto-building-3d-games.md`, `incanto-3d-character.md`,
    `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
-   `incanto-audio.md` — this template composes all five.
+   `incanto-audio.md` — this template composes them —
+   and FINISH with `incanto-verifying-your-game.md` (rule 11).
 2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
-   replication all live in `src/game.scene.json`. Add nodes there (or with
+   replication all live in `src/*.scene.json`. Add nodes there (or with
    `npx incanto-editor`), NOT by constructing them ad-hoc in code.
 3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
    registered with `registerBehavior('Name', Class)` and attached in JSON via
    `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
-   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
-   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+   before writing your own — this template already uses
+   Health, DamageOnContact, Chase, WaveSpawner, ScoreKeeper, and its only custom behaviors are
+   `Shoot` and `HudUpdater`.
 4. 🔑 UIDS ARE GENERATED: every node uid comes from
    `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
@@ -23,21 +25,41 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    (Euler XYZ). Negative gravity falls.
 7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
    on a body node — never child shape nodes. Wrong shapes hard-fail at load.
-8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
-   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
-   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
-   headless runs are a no-op).
-9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
-   `enablePhysics3D` returns) draws every collider in the running game; or boot
-   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+8. 🖥️ THE HUD IS DOM HERE: this template's HUD, crosshair and banner are
+   plain HTML in `index.html`, and `HudUpdater` writes the live numbers into
+   them (guarded, so headless runs are a no-op). That is a CHOICE, not a
+   limit — `HudLayer` + `UiText`/`UiBar` nodes work in 3D scenes too (see
+   `incanto-hud.md`, and the `beacon-isle-3d` template). Do not mix them in
+   one screen.
+9. 🐛 DEBUG WHEN UNSURE: `VITE_INCANTO_DEBUG=1 bun run dev` adds the ☰ debug
+   menu — Explorer/Inspector (click a node, see and edit its live props), Logs,
+   Stats and Colliders (every physics shape as a wireframe, drawn by the same
+   Rapier the game runs). There is NO `VITE_INCANTO_DEBUG=1` URL toggle: it was
+   removed as deploy-unsafe. Never ship the env flag on.
 10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
     loader treats unknown/garbage props as hard errors, which is your friend.
-11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
-    proves the loop headlessly, then `bun run dev` and actually PLAY what you
-    changed (move, shoot, clear a wave) before declaring it done.
-12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
-    debug menu — Explorer/Inspector (click a node, see and edit its live props),
-    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
-    wireframe). Blocked in mid-air or falling through the floor is a Colliders
-    question; a mystery frame-rate is a Stats question. Never ship the flag on.
+11. ✅ VERIFY LIKE A USER, THEN READ THE FOUR SIGNALS. `bun run check` and
+    `bun run verify` are the start, not the end — you cannot SEE this game, and
+    each of these answers a failure that otherwise looks like nothing at all:
+
+    | read | it is not clean when |
+    | --- | --- |
+    | `bunx incanto-check` | the scene will not load, or renders black (no light) |
+    | `stats().errors` | something threw and was skipped to keep the game alive |
+    | `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+    | `framing` | the camera points the wrong way, or nothing is lit |
+
+    ```bash
+    printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+    ```
+
+    `framing` reports what the camera SEES — on screen / off screen / behind it
+    — plus what lights the scene and which colliders intersect. `behind` looks
+    exactly like "my model did not load"; nothing else can tell you apart.
+    Then `bun run dev` and actually PLAY what you changed.
+12. 🧯 A THROWN ERROR NO LONGER STOPS THE GAME: a behavior that throws is
+    reported once (node, script, phase, file:line) and SKIPPED — your script
+    stops, the node it is attached to keeps running, the game plays on. So a
+    game that looks fine can still be broken: read `stats().errors`, and
+    `engine.resumeErroredNodes()` after you fix it.
 </userRequest>

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.32.0",
+    "incanto": "^0.33.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/docs/project-3d-rules.md

@@ -5,15 +5,17 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    manual, version-pinned to what is installed. Start with
    `incanto-building-3d-games.md`, `incanto-3d-character.md`,
    `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
-   `incanto-audio.md` — this template composes all five.
+   `incanto-hud.md` — this template composes them —
+   and FINISH with `incanto-verifying-your-game.md` (rule 11).
 2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
-   replication all live in `src/game.scene.json`. Add nodes there (or with
+   replication all live in `src/*.scene.json`. Add nodes there (or with
    `npx incanto-editor`), NOT by constructing them ad-hoc in code.
 3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
    registered with `registerBehavior('Name', Class)` and attached in JSON via
    `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
-   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
-   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+   before writing your own — this template already uses
+   Health, DamageOnContact, Interactable, PathFollow, and its only custom behaviors are
+   `VillageDirector`, `GroveDirector` and `SwordStrike`.
 4. 🔑 UIDS ARE GENERATED: every node uid comes from
    `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
@@ -23,21 +25,40 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    (Euler XYZ). Negative gravity falls.
 7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
    on a body node — never child shape nodes. Wrong shapes hard-fail at load.
-8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
-   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
-   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
-   headless runs are a no-op).
-9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
-   `enablePhysics3D` returns) draws every collider in the running game; or boot
-   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+8. 🖥️ THE HUD IS NODES: this template's HUD lives in the scene as a
+   `HudLayer` with `UiText`/`UiBar` children — the engine builds the DOM for
+   them and positions them by anchor. Edit the HUD in `*.scene.json` like any
+   other node. (A DOM-in-`index.html` HUD is the other valid shape, and what
+   `tps-3d` does; both are supported — do not mix them in one screen.)
+9. 🐛 DEBUG WHEN UNSURE: `VITE_INCANTO_DEBUG=1 bun run dev` adds the ☰ debug
+   menu — Explorer/Inspector (click a node, see and edit its live props), Logs,
+   Stats and Colliders (every physics shape as a wireframe, drawn by the same
+   Rapier the game runs). There is NO `VITE_INCANTO_DEBUG=1` URL toggle: it was
+   removed as deploy-unsafe. Never ship the env flag on.
 10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
     loader treats unknown/garbage props as hard errors, which is your friend.
-11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
-    proves the loop headlessly, then `bun run dev` and actually PLAY what you
-    changed (move, shoot, clear a wave) before declaring it done.
-12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
-    debug menu — Explorer/Inspector (click a node, see and edit its live props),
-    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
-    wireframe). Blocked in mid-air or falling through the floor is a Colliders
-    question; a mystery frame-rate is a Stats question. Never ship the flag on.
+11. ✅ VERIFY LIKE A USER, THEN READ THE FOUR SIGNALS. `bun run check` and
+    `bun run verify` are the start, not the end — you cannot SEE this game, and
+    each of these answers a failure that otherwise looks like nothing at all:
+
+    | read | it is not clean when |
+    | --- | --- |
+    | `bunx incanto-check` | the scene will not load, or renders black (no light) |
+    | `stats().errors` | something threw and was skipped to keep the game alive |
+    | `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+    | `framing` | the camera points the wrong way, or nothing is lit |
+
+    ```bash
+    printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+    ```
+
+    `framing` reports what the camera SEES — on screen / off screen / behind it
+    — plus what lights the scene and which colliders intersect. `behind` looks
+    exactly like "my model did not load"; nothing else can tell you apart.
+    Then `bun run dev` and actually PLAY what you changed.
+12. 🧯 A THROWN ERROR NO LONGER STOPS THE GAME: a behavior that throws is
+    reported once (node, script, phase, file:line) and SKIPPED — your script
+    stops, the node it is attached to keeps running, the game plays on. So a
+    game that looks fine can still be broken: read `stats().errors`, and
+    `engine.resumeErroredNodes()` after you fix it.
 </userRequest>

package/templates-app/village-quest-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.32.0",
+    "incanto": "^0.33.0",
     "three": "^0.184.0"
   },
   "devDependencies": {