incanto 0.12.0 → 0.14.0

package/skills/incanto-node-reference.md

@@ -144,6 +144,24 @@ Signals: `finished`
 | `target` | `""` | string |
 | `bone` | `""` | string |
 
+## `BoneLookAt3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `target` | `""` | string |
+| `bone` | `"Head"` | string |
+| `lookAt` | `""` | string |
+| `maxAngleDeg` | `75` | number |
+| `weight` | `0.85` | number |
+| `forwardAxis` | `"+z"` | one of: `+x` `-x` `+y` `-y` `+z` `-z` |
+
 ## `Camera2D` — `incanto/2d`
 
 | Prop | Default | Kind |
@@ -312,7 +330,7 @@ Signals: `movementStateChanged(state)`
 | `height` | `0.45` | number |
 | `clustering` | `0.6` | number |
 | `sway` | `0.5` | number |
-| `drape` | `false` | boolean |
+| `drape` | `null` | null |
 | `terrain` | `""` | string |
 
 ## `Foliage3D` — `incanto/3d`
@@ -344,7 +362,7 @@ Signals: `movementStateChanged(state)`
 | `coverage` | `0.85` | number |
 | `flowers` | `0` | number |
 | `seed` | `1` | number |
-| `drape` | `false` | boolean |
+| `drape` | `null` | null |
 | `terrain` | `""` | string |
 
 ## `HudLayer` — `incanto`
@@ -354,6 +372,24 @@ Signals: `movementStateChanged(state)`
 | `zIndex` | `100` | number |
 | `visible` | `true` | boolean |
 
+## `InstancedMesh3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
+| `size` | `[1,1,1]` | array |
+| `material` | `{}` | object |
+| `transforms` | `[]` | array |
+| `castShadow` | `false` | boolean |
+| `receiveShadow` | `false` | boolean |
+
 ## `Joint2D` — `incanto/2d`
 
 | Prop | Default | Kind |
@@ -460,6 +496,9 @@ Signals: `movementStateChanged(state)`
 | `targetHeight` | `0` | number |
 | `castShadow` | `false` | boolean |
 | `animationLoop` | `true` | boolean |
+| `animationUpper` | `""` | string |
+| `animationUpperLoop` | `false` | boolean |
+| `upperBodyRoot` | `"Spine"` | string |
 | `receiveShadow` | `false` | boolean |
 | `tint` | `""` | string |
 | `metalness` | `-1` | number |
@@ -797,7 +836,7 @@ Signals: `timeout`
 | `leafFadeStart` | `0` | number |
 | `leafFadeEnd` | `0` | number |
 | `leafShadows` | `true` | boolean |
-| `drape` | `false` | boolean |
+| `drape` | `null` | null |
 | `terrain` | `""` | string |
 
 ## `UILayer` — `incanto/2d`
@@ -961,6 +1000,18 @@ Signals: `totalChanged(total)`
 
 Signals: `dealtDamage(amount, target)`
 
+### `DayNight`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `daySeconds` | `240` | number |
+| `startHour` | `10` | number |
+| `maxSunElevationDeg` | `55` | number |
+| `nightDarkness` | `0.75` | number |
+| `paused` | `false` | boolean |
+
+Signals: `dayPhaseChanged`
+
 ### `FollowCamera`
 
 | Prop | Default | Kind |

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

@@ -0,0 +1,44 @@
+# Beacon Isle — Context
+
+**The incanto 3D template.** A complete island action-adventure vertical
+slice designed to be COPIED as the starting point for 3D vibe-coding: a
+generated world, a real quest loop, enemies with terrain-aware AI, readable
+combat, win AND lose states, mobile controls, and a headless verify harness —
+all in ~2 files of game code.
+
+## What it plays like
+
+You wash up on a golden-hour island. The lighthouse keeper (walk up, **E**)
+asks you to relight three ancient wards. Shades — floating wraiths with
+burning eyes — patrol each ward and HUNT you across the island surface when
+you come close. Cut them down (**click/F**, a real melee swing with the sword
+riding your hand bone), stand at the dark crystal and press **E**: it blazes
+back to life. Three lit wards → report back → fireworks over the lighthouse.
+The shades bite; at 0 HP the isle takes you and you respawn — lit wards stay lit.
+
+## The template story (why it's built this way)
+
+1. **The world is GENERATED, the game is AUTHORED.** `bun run world` re-emits
+   `src/game.scene.json` from `generate-world.ts` (deterministic seeds):
+   island terrain, sea, tree groves, grass, flowers, and QUEST SITES picked on
+   provably walkable ground (the same `buildTerrainNav` grid the enemies use).
+   Change the seed → new island, game logic untouched.
+2. **Game code is two behaviors** (`IsleDirector`, `SwordStrike`); everything
+   else — movement/camera/animations, NPC proximity, dialogue, HUD, touch
+   controls, contact damage, physics — is engine surface declared in JSON.
+3. **Verified headlessly**: `bun run verify` plays the whole quest, proves the
+   shades hunt, proves death keeps progress, and replays recorded input
+   bit-identically.
+
+## Feature map (engine 0.12)
+
+| Feature | Where |
+|---|---|
+| `generateTerrain` island + Water3D sea | generate-world.ts |
+| `buildTerrainNav` + `findPath` | ward-site picking AND shade patrol/hunt AI |
+| `BoneAttachment3D` | sword in the right hand |
+| `environment.post` + bloom | golden-hour grade, glowing ward crystals |
+| input-map `"touch"` keys | joystick + buttons on phones, zero code |
+| `UiDialogue`/`UiBar`/`UiBanner` | keeper quest, HP, win/lose |
+| `startVoice('wind')` | speed-reactive ambience |
+| `startRecording`/`replay` | determinism regression in verify.ts |

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

@@ -0,0 +1,16 @@
+# Beacon Isle — Requirements
+
+1. Quest arc: keeper dialogue (choice) → 3 wards guarded by shades → clear +
+   E to relight each → report back → win banner + fireworks.
+2. Shades: patrol rings AROUND their ward on the island surface; hunt the
+   player within 9 m (re-path through terrain, never through sea/cliffs);
+   bites drain 20 HP per 1.2 s of contact.
+3. Losing: 0 HP → banner → fresh respawn; lit wards persist.
+4. A dark ward with living guards refuses to light (hint line).
+5. One strike fells a shade (dissolve poof); the sword rides the hand bone
+   and plays the melee clip.
+6. Works on phones: joystick + jump/interact/attack touch buttons from the
+   input map alone.
+7. `bun run verify` green: audit 0 warnings, quest E2E, hunt proof,
+   death/respawn proof, bit-identical replay.
+8. `bun run world` regenerates the island deterministically.

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>