incanto 0.11.0 → 0.13.0

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

@@ -0,0 +1,38 @@
+# Beacon Isle — Status
+
+## Round 2 (2026-07-12)
+
+- **The Shadeheart**: lighting the third ward summons a glowing violet
+  colossus (primitive-built — a keeper.glb attempt rendered at zero scale,
+  see Learnings below) that hunts the player across the island via the
+  terrain nav; five strikes (recoil + eye-flare per hit) fell it in a triple
+  burst; only then does the keeper's report end the quest.
+- **The clock IS the quest** (paused DayNight, director-lerped `hour`):
+  dusk start → each lit ward buys back light → the boss drags the isle to a
+  deep-red horizon (17.8 — sun kept ABOVE the horizon; below it the
+  atmosphere sky and its IBL go black) → victory brings morning.
+- **Gliding**: hold JUMP while falling — capped descent + dash trail.
+- Keeper NPC tracks the player with `BoneLookAt3D`; shoreline rocks are one
+  `InstancedMesh3D` draw call.
+
+## Round 1 (2026-07-11)
+
+- Full quest loop, terrain-nav shade AI, bone-mounted sword, golden-hour
+  grade, headless verify + replay determinism, 4-iteration visual pass.
+
+## Learnings
+
+- `PathFollow` writes WORLD coordinates into `node.position` — such nodes
+  must be ROOT children. Parenting one under a positioned wrapper doubles
+  the offset ON SCREEN while all position-based gameplay math stays
+  self-consistent: invisible-boss bugs that verify green.
+- keeper.glb mounts at a degenerate scale through ModelInstance3D's
+  targetHeight fit (the known "explicit scale" trap) — primitives with
+  emissive materials are the reliable monster path.
+- Atmosphere rule: keep `elevationDeg` (or DayNight `hour`) sun-above-horizon
+  in playable scenes; the sky + IBL die within ~1° below.
+
+## Ideas next
+
+- Boss attack telegraphs (charge-up glow, ground slam particles).
+- A hurt/attack clip for shades once one lands in the catalog.

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>