incanto 0.32.0 → 0.34.0

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.34.0",
     "three": "^0.184.0"
   },
   "devDependencies": {