incanto 0.11.0 → 0.13.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-DMCQXowF.js"></script>
+    <script type="module" crossorigin src="./assets/index-DSq0gdhE.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
     <link rel="stylesheet" crossorigin href="./assets/index-D8QvwvOm.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -27,6 +27,7 @@
     "skills",
     "bin",
     "editor",
+    "templates-app",
     "assets",
     "LICENSE",
     "THIRD-PARTY-NOTICES.md"
@@ -92,6 +93,7 @@
     "incanto-check": "bin/incanto-check.mjs",
     "incanto-assets": "bin/incanto-assets.mjs",
     "incanto-env": "bin/incanto-env.mjs",
-    "incanto-play": "bin/incanto-play.mjs"
+    "incanto-play": "bin/incanto-play.mjs",
+    "incanto-new": "bin/incanto-new.mjs"
   }
 }

package/schemas/scene.schema.json

@@ -193,6 +193,9 @@
         {
           "$ref": "#/$defs/BoneAttachment3D"
         },
+        {
+          "$ref": "#/$defs/BoneLookAt3D"
+        },
         {
           "$ref": "#/$defs/Camera2D"
         },
@@ -226,6 +229,9 @@
         {
           "$ref": "#/$defs/HudLayer"
         },
+        {
+          "$ref": "#/$defs/InstancedMesh3D"
+        },
         {
           "$ref": "#/$defs/Joint2D"
         },
@@ -1196,6 +1202,126 @@
       },
       "required": ["name", "type"]
     },
+    "BoneLookAt3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "BoneLookAt3D"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "position": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "rotation": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "static": {
+              "type": "boolean",
+              "default": false
+            },
+            "scale": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [1, 1, 1]
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "renderOrder": {
+              "type": "number",
+              "default": 0
+            },
+            "orderGroup": {
+              "type": "string",
+              "enum": ["background", "terrain", "default", "characters", "effects", "overlay"],
+              "default": "default"
+            },
+            "target": {
+              "type": "string",
+              "default": ""
+            },
+            "bone": {
+              "type": "string",
+              "default": "Head"
+            },
+            "lookAt": {
+              "type": "string",
+              "default": ""
+            },
+            "maxAngleDeg": {
+              "type": "number",
+              "default": 75
+            },
+            "weight": {
+              "type": "number",
+              "default": 0.85
+            },
+            "forwardAxis": {
+              "type": "string",
+              "enum": ["+x", "-x", "+y", "-y", "+z", "-z"],
+              "default": "+z"
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "Camera2D": {
       "type": "object",
       "properties": {
@@ -2526,6 +2652,131 @@
       },
       "required": ["name", "type"]
     },
+    "InstancedMesh3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "InstancedMesh3D"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "position": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "rotation": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "static": {
+              "type": "boolean",
+              "default": false
+            },
+            "scale": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [1, 1, 1]
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "renderOrder": {
+              "type": "number",
+              "default": 0
+            },
+            "orderGroup": {
+              "type": "string",
+              "enum": ["background", "terrain", "default", "characters", "effects", "overlay"],
+              "default": "default"
+            },
+            "mesh": {
+              "type": "string",
+              "enum": ["box", "sphere", "capsule", "plane", "cylinder", "gem"],
+              "default": "box"
+            },
+            "size": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [1, 1, 1]
+            },
+            "material": {
+              "type": "object",
+              "default": {}
+            },
+            "transforms": {
+              "type": "array",
+              "default": []
+            },
+            "castShadow": {
+              "type": "boolean",
+              "default": false
+            },
+            "receiveShadow": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "Joint2D": {
       "type": "object",
       "properties": {
@@ -3228,6 +3479,18 @@
               "type": "boolean",
               "default": true
             },
+            "animationUpper": {
+              "type": "string",
+              "default": ""
+            },
+            "animationUpperLoop": {
+              "type": "boolean",
+              "default": false
+            },
+            "upperBodyRoot": {
+              "type": "string",
+              "default": "Spine"
+            },
             "receiveShadow": {
               "type": "boolean",
               "default": false

package/skills/incanto-3d-character.md

@@ -102,6 +102,25 @@ shambling clip + glowing eyes for an enemy that reads as a different creature.
              "animation": "$walk", "castShadow": true } }
 ```
 
+## Two-layer animation: attack WHILE running (`animationUpper`)
+
+A single `animation` clip owns the whole body — setting an attack clip freezes
+the legs. The UPPER LAYER fixes that:
+
+```ts
+skin.animationUpper = '$anims/attack';   // spine-up plays the attack…
+// …while `animation` (idle/run via the controller) keeps driving the legs.
+// One-shots AUTO-CLEAR when the clip ends (and emit animationFinished) —
+// set it per attack and forget it.
+```
+
+- `upperBodyRoot` (default `'Spine'`, Mixamo spellings matched) picks the bone
+  subtree the layer owns; the base clip is automatically masked to the rest,
+  so there's no half-blended overlap and no stride reset (time stays aligned).
+- `animationUpperLoop: true` for sustained upper loops (carry, aim, wave).
+- Works with the controller's `animations` map untouched — locomotion logic
+  never learns the attack exists.
+
 ## Animations without code
 
 Map movement states straight in JSON — no behavior needed:
@@ -146,7 +165,24 @@ A sword in the hand, a hat on the head, sparks on a wingtip — parent them to a
 - Purely VISUAL: it follows the rendered skeleton, so headless the node stays
   at its prop transform — keep hit checks range-based from the body, never
   bone-based.
-- `model.boneNames()` lists every bone at runtime when you need to hunt one.
+- `model.boneNames()` lists every bone at runtime when you need to hunt one
+  (the editor's inspector offers the same list as a dropdown on the `bone` prop).
+
+## Heads that WATCH things (`BoneLookAt3D`)
+
+NPCs feel alive when they track you. One node, zero code:
+
+```jsonc
+{ "name": "HeadTrack", "type": "BoneLookAt3D",
+  "props": { "target": "../Body", "bone": "Head", "lookAt": "%Player" } }
+```
+
+- Runs on top of the playing animation each frame; blends in/out smoothly and
+  DISENGAGES when the target leaves the `maxAngleDeg` comfort cone (75° —
+  no owl necks).
+- `weight` (0.85) is how far the head commits; `forwardAxis` defaults to the
+  mixamo head convention (+z).
+- Also good for chests (`bone: "Spine2"`, small weight) and turrets.
 
 ## Facing a direction in 3D — the +Z-FORWARD rule (read before turning ANY skin)
 

package/skills/incanto-building-3d-games.md

@@ -17,6 +17,19 @@ GLB/glTF/VRM files load via `ModelInstance3D` — see `incanto-3d-models.md` for
 asset declaration, `targetHeight` sizing, and the `bunx incanto-model` inspector that
 reports a file's real bounding box and animation names.
 
+## Fastest start: scaffold a whole game
+
+```bash
+bunx incanto-new my-game                     # Beacon Isle — 3D flagship template
+bunx incanto-new my-game --template tps-3d   # third-person shooter starter
+bunx incanto-new --list
+```
+
+Templates are COMPLETE games (world generation, quest, enemies, verify
+harness) meant to be reshaped — regenerate the Beacon Isle world with
+`bun run world`, keep the game logic. Prefer starting from one over wiring
+from scratch.
+
 ## Boot sequence (the only TypeScript you need to start)
 
 ```ts
@@ -65,6 +78,28 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 | `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, clearcoat: 0..1, clearcoatRoughness: 0..1, envMapIntensity: >=0, wireframe, flatShading, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). CAR PAINT: `clearcoat: 1` adds a glossy lacquer layer with its own reflection over a metallic base (`clearcoatRoughness` ~0.05-0.1 = mirror lacquer) — THE premium vehicle-paint look; `envMapIntensity` scales how strongly the surface mirrors the scene's sky/HDRI (glass windows want ~2, matte surfaces <1; needs a `sky`/`hdri` environment to reflect — at night with no sky there is nothing to mirror). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
 | `castShadow` / `receiveShadow` | `false` | |
 
+### `InstancedMesh3D` (hundreds of props, one draw call)
+
+Scattered rocks, fence posts, crates, gravestones — identical meshes should
+never be one node each. One instanced node draws them all at once:
+
+```jsonc
+{ "name": "Rocks", "type": "InstancedMesh3D",
+  "props": { "mesh": "gem", "size": [0.7, 0.5, 0.7],
+    "material": { "color": "#8a8f98", "roughness": 0.95, "flatShading": true },
+    "transforms": [
+      [12.2, 0.1, -8.4, 40, 1.3],
+      [-6.0, 0.2, 14.1, 210, 0.8],
+      [3.5, 0.0, 22.7, 118, 1.0]
+] } }
+```
+
+- Each row: `[x, y, z, yawDeg?, scale?]` — dense enough to GENERATE hundreds
+  (pair with `terrain.heightAt` for y).
+- Same `mesh`/`size`/`material` surface as MeshInstance3D. Replace the whole
+  `transforms` array to update. No per-instance colliders — add a few
+  StaticBody3D boxes only where gameplay needs blocking.
+
 ### `LoftMesh3D` (smooth swept hulls — vehicle bodies, canopies)
 
 A SMOOTH curved surface swept through cross-sections — what box/capsule assemblies can
@@ -283,6 +318,23 @@ demo into a commercial-looking outdoor scene:
   dreamier), `strength` how strongly the blurred glow is added back (default
   0.85; ~1.2 = neon night). One extra half-res blur pass per frame — cheap.
   Caustics/clouds composites take precedence (pipelines don't stack yet).
+- `post`: the color-grade tail — `{ "vignette"?, "saturation"?, "contrast"? }`.
+  `vignette` 0..1 darkens the corners (0.3 = cinematic, 0.6 = heavy mood);
+  `saturation` 0..4 (0 = grayscale, 1 = neutral, 1.2 = vivid); `contrast`
+  0.2..3 around mid-gray (1 = neutral). Applied after tone mapping on the same
+  composite pass as bloom — declaring `post` WITHOUT `bloom` costs just one
+  offscreen pass. The fastest way to give a scene a LOOK: dusk = vignette 0.35
+  + saturation 0.85, candy = saturation 1.25 + contrast 1.08. Caustics/clouds
+  composites take precedence (pipelines don't stack yet).
+- **Runtime changes**: the renderer re-reads `environment` every frame — call
+  `setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 })`
+  (from `incanto/3d`) to change the look LIVE. One-level deep merge, `null`
+  deletes a key, and a bad patch throws in YOUR call stack, never mid-render.
+  For a full day/night loop, attach the built-in `DayNight` behavior instead:
+  `{ "script": { "name": "DayNight", "props": { "daySeconds": 240 } } }` —
+  sun arc + ambient/exposure ramps + a `dayPhaseChanged(dawn|day|dusk|night)`
+  signal to hook spawners/music to. Its `hour` field is writable (jump to a
+  time, or `paused: true` and animate it yourself).
 - `shadows`: `true` | `false` | `{ "mapSize": 1024|2048, "radius": n }`.
   Truthy makes the main DirectionalLight cast (PCF soft, terrain + trees +
   meshes cast/receive, mesh grass RECEIVES only). One static ortho box (±75 m
@@ -388,6 +440,37 @@ from a `seed`, with `heightAt(x, z)` for spawning/placement and a
 `StaticBody3D`). Full themes table, custom layer format and the water/beach
 pairing live in the **incanto-environment** skill.
 
+### Navigation on terrain (`buildTerrainNav` + findPath)
+
+Enemies that chase across an open world need paths that respect the surface —
+`buildTerrainNav` samples the heightfield into a walkable grid for the core
+A* (`findPath`), and lifts waypoints back ONTO the surface:
+
+```ts
+import { buildTerrainNav } from 'incanto/3d';
+import { findPath } from 'incanto';
+
+const nav = buildTerrainNav(terrain, {
+  cellSize: 2,        // meters per cell (character-scale corridors)
+  maxSlopeDeg: 40,    // steeper cells are unwalkable
+  minHeight: 0.5,     // below sea level = unwalkable (pair with your Water3D y)
+});
+const cells = findPath(nav.grid, nav.toCell(ex, ez), nav.toCell(px, pz));
+if (cells) follow.setPath(cells.map(([cx, cy]) => nav.toWorld(cx, cy)));
+// nav.toWorld's y IS the terrain height — PathFollow rides the surface.
+```
+
+- Build it ONCE per scene (onReady) — sampling is O(cells); re-pathing with
+  `findPath` per second is cheap (binary-heap A*).
+- Trees/rocks/buildings aren't in the heightfield: stamp them out with
+  `nav.setSolid(...nav.toCell(x, z))` after building.
+- Walkability is judged inside each cell (corner samples), so a flat trail
+  beside a cliff stays walkable — only genuinely steep cells go solid.
+- **See what the enemies see**: `root.addChild(createNavDebugNode(nav))`
+  paints every walkable cell as a translucent quad on the surface (one
+  instanced draw call) — add while tuning `cellSize`/`maxSlopeDeg`, drop when
+  the routes look right.
+
 ## Performance levers for big scenes
 
 - **`static: true`** (any Node3D): the renderer syncs that subtree ONCE and

package/skills/incanto-editor.md

@@ -119,9 +119,9 @@ active brush. The palette chips offer every char already used in `cells`, the
 single char (digits map straight to atlas tile indices, other chars need a
 `legend` entry). The grid grows right/down automatically when you paint past
 the edge — to grow left/up, move the node instead (cell (0,0) hangs on the
-node origin). Merged solid colliders re-derive live as you paint. Each painted
-cell is one undo step; toggle paint off (or select another node) to get normal
-click-select back.
+node origin). Merged solid colliders re-derive live as you paint. A whole
+drag stroke is ONE undo step; toggle paint off (or select another node) to
+get normal click-select back.
 
 ## Generate environments
 

package/skills/incanto-gameplay-behaviors.md

@@ -749,7 +749,29 @@ Multi-scene games: `flow.goToScene(nextSceneJson, { fadeSeconds: 0.4 })`
 fades to black, swaps, fades back (headless = instant). Title → level →
 next level is three JSON files and this one call.
 
-## Boot loading overlay
+## DayNight (live 24-hour cycle)
+
+Drives the scene `environment` (needs an atmosphere sky): sun elevation/
+azimuth arc, ambient + exposure ramps with a moonlight floor.
+
+```jsonc
+{ "script": { "name": "DayNight", "props": { "daySeconds": 240, "startHour": 9 } } }
+```
+
+| Prop | Default | Notes |
+|---|---|---|
+| `daySeconds` | 240 | real seconds per full day |
+| `startHour` | 10 | 0-24 clock at scene start |
+| `maxSunElevationDeg` | 55 | noon height |
+| `nightDarkness` | 0.75 | 0 = night looks like day, 1 = black |
+| `paused` | false | freeze the clock; write `hour` yourself |
+
+Signals: `dayPhaseChanged('dawn'|'day'|'dusk'|'night')` on transitions — hook
+spawners, music, or monster aggression to it. The `hour` field (0-24) is
+writable: jump to a time of day in one assignment. For one-off look changes
+use `setEnvironment3D(engine, patch)` from `incanto/3d` directly.
+
+## Boot loading overlay## Boot loading overlay
 
 ```ts
 import { preloadSceneAssets } from 'incanto';

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 |
@@ -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 |
@@ -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.