incanto 0.12.0 → 0.13.0

package/templates-app/beacon-isle-3d/PROJECT/Structure.md

@@ -0,0 +1,24 @@
+# Beacon Isle — Structure
+
+```
+generate-world.ts        the WORLD AUTHORING script (bun run world):
+                         island terrain + sea + groves/grass/flowers +
+                         quest sites on walkable ground → src/game.scene.json
+index.html               canvas + loading bar
+src/main.ts              preload → createGame3D
+src/game.scene.json      GENERATED — do not hand-edit; edit generate-world.ts
+src/behaviors.ts         IsleDirector (quest FSM, terrain-nav shade AI,
+                         ward relighting, fireworks, respawn) + SwordStrike
+verify.ts                audit + quest E2E + hunt + death/respawn + replay
+```
+
+## Key decisions
+
+- The nav grid is built ONCE in `IsleDirector.onReady` from the live
+  Terrain3D; shade hunts re-path every 0.4 s with `findPath` (cheap A*).
+- Shades are primitive-built (capsule + gem hood + emissive eyes + Trail3D
+  wisp) — zero external meshes, instantly reskinnable.
+- Quest state is a module singleton (`quest`) so death → `goToScene` respawn
+  keeps lit wards; `IsleDirector.onReady` re-applies their glow.
+- The whole Terrain subtree is static EXCEPT Sea and Clouds (auditScene
+  catches the freeze-the-water mistake if you regress this).

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

@@ -0,0 +1,38 @@
+<userRequest>
+YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
+
+1. 📖 READ THE SKILLS FIRST: `node_modules/incanto/skills/` is the engine
+   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.
+2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
+   replication all live in `src/game.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`.
+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
+   them as `"$key"`. Free extra key-values are preserved — use them to leave
+   notes for yourself (license, palette, source prompt).
+6. ⬆️ Y IS UP: 3D space is y-UP meters, +Z is "south", rotations are degrees
+   (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.
+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.
+</userRequest>