incanto 0.12.0 → 0.14.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-s0DZuroe.js"></script>
+    <script type="module" crossorigin src="./assets/index-7qOYg7t8.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.12.0",
+  "version": "0.14.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": {
@@ -2245,8 +2371,7 @@
               "default": 0.5
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",
@@ -2433,8 +2558,7 @@
               "default": 1
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",
@@ -2526,6 +2650,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 +3477,18 @@
               "type": "boolean",
               "default": true
             },
+            "animationUpper": {
+              "type": "string",
+              "default": ""
+            },
+            "animationUpperLoop": {
+              "type": "boolean",
+              "default": false
+            },
+            "upperBodyRoot": {
+              "type": "string",
+              "default": "Spine"
+            },
             "receiveShadow": {
               "type": "boolean",
               "default": false
@@ -5393,8 +5654,7 @@
               "default": true
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",

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:
@@ -149,6 +168,22 @@ A sword in the hand, a hat on the head, sparks on a wingtip — parent them to a
 - `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)
 
 This trips people up REPEATEDLY, so here is the one rule. agent8's `base-model` (and

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
@@ -291,6 +326,15 @@ demo into a commercial-looking outdoor scene:
   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
@@ -422,6 +466,10 @@ if (cells) follow.setPath(cells.map(([cx, cy]) => nav.toWorld(cx, cy)));
   `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
 

package/skills/incanto-environment.md

@@ -358,14 +358,13 @@ tops radially away with a smooth falloff as a character wades through.
 | `coverage` | `0.85` | mesh: carpet fill in (0, 1] — below 1 noise carves dirt patches (load-time check) |
 | `flowers` | `0` | DEPRECATED — confetti heads; use a `Flowers3D` node (load-time check 0–0.2) |
 | `seed` | `1` | placement seed — identical field across runs/machines |
-| `drape` | `false` | **drape each blade onto a Terrain3D's surface** so a field follows rolling ground instead of floating on a flat plane — one big field covers a whole terrain |
-| `terrain` | `""` | drape target node path; empty = **auto-find the first Terrain3D** in the tree (the zero-config default when `drape` is on) |
+| `drape` | `null` | **AUTO by default**: whenever the scene has a Terrain3D, every blade roots on the ground under it (samples `heightAt`) — omit this prop and rolling terrain just works. `true` forces it (keeps retrying until a terrain appears — streamed worlds), `false` opts out (flat carpet at the node's Y) |
+| `terrain` | `""` | drape target node path; empty = **auto-find the first Terrain3D** in the tree. A non-empty path that is NOT a Terrain3D fails at load — no silent floating |
 
-> **Rolling terrain?** Set `drape: true` and the field's blades root on the
-> ground per-instance (it samples the Terrain3D's `heightAt`). Without draping a
-> Foliage3D/Flowers3D is a FLAT carpet at the node's Y, so on hills it
-> floats/sinks — either drape it, or place small patches at flat spots (the
-> generators still do the latter for backward-compatible output).
+> **Rolling terrain just works.** Since 0.14 draping is on by default: with a
+> Terrain3D in the scene the blades root on the ground per-instance, no wiring.
+> Only set `drape: false` if you WANT a flat carpet at the node's Y (e.g. grass
+> on a flat MeshInstance3D platform above the terrain).
 
 ## Flowers3D
 
@@ -415,8 +414,8 @@ billboard confetti. Deterministic from the `seed` PROP.
 | `height` | `0.45` | plant height, meters (±25% per-plant jitter) |
 | `clustering` | `0.6` | 0 uniform … 1 tight Voronoi patches (load-time check) |
 | `sway` | `0.5` | head-bob wind strength; 0 disables |
-| `drape` | `false` | drape each plant onto a Terrain3D's surface (rolling terrain) — see the Foliage3D drape note above |
-| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D |
+| `drape` | `null` | AUTO by default — plants root on the scene's Terrain3D when one exists; `true` forces, `false` opts out — see the Foliage3D drape note above |
+| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 
 ## Tree3D
 Procedural trees grown by the ported ez-tree generator (MIT, Dan Greenheck;
@@ -484,8 +483,8 @@ Every instance in a grove also gets a deterministic per-instance color jitter (
 | `leafFadeStart` | `0` | **leaf LOD** — leaf cards begin collapsing toward their branch at this camera distance (m). `0`/`0` disables (full leaves at any range) |
 | `leafFadeEnd` | `0` | leaf LOD — cards fully collapsed (zero overdraw) by here; tune ≈ the scene `fog.far` so the thinning hides in fog (load-time check: `> leafFadeStart`) |
 | `leafShadows` | `true` | `false` keeps trunk/branch shadows but drops the expensive alpha-cutout LEAF shadow pass — big FPS in dense forests |
-| `drape` | `false` | **drape a scattered grove onto a Terrain3D**: each instance roots at the ground height under it instead of the node's single Y, so a `count > 1` patch on rolling/carved terrain never floats or buries |
-| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (the zero-config default when `drape` is on) |
+| `drape` | `null` | AUTO by default: each scattered instance roots at the ground height under it (instead of the node's single Y) whenever the scene has a Terrain3D — a `count > 1` grove on rolling/carved terrain never floats or buries. `true` forces, `false` opts out |
+| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 
 > **Tree LOD / forest FPS.** Leaf overdraw + the leaf shadow pass dominate a
 > dense-forest frame (~90% in profiling). For big groves set `leafFadeStart`/
@@ -493,11 +492,11 @@ Every instance in a grove also gets a deterministic per-instance color jitter (
 > leaf cards (branch silhouette stays), and `leafShadows: false` to drop the leaf
 > shadow pass. Both default off → existing scenes are unchanged.
 
-> **Floating trees?** A scattered grove (`count > 1`) places every instance at
-> the node's single Y, so on rolling or basin-carved terrain the far instances
-> float or sink. Set `drape: true` (auto-finds the Terrain3D) so each instance
-> roots on the ground under it. The drape is a pure heightAt lookup — no rng
-> draw, so the seed/grove layout is byte-identical, only the Y shifts.
+> **Floating trees?** Since 0.14 groves drape automatically whenever the scene
+> has a Terrain3D — each instance roots on the ground under it. The drape is a
+> pure heightAt lookup — no rng draw, so the seed/grove layout is
+> byte-identical, only the Y shifts. `drape: false` restores the flat
+> single-Y placement.
 
 ## Terrain3D
 Procedural heightfield terrain with biome texture splatting (in `incanto/3d`,

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';