incanto 0.7.0 → 0.8.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-DzYFgZbl.js"></script>
+    <script type="module" crossorigin src="./assets/index-CVhnNkb3.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
     <link rel="stylesheet" crossorigin href="./assets/index-DF3tMeKJ.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -283,9 +283,15 @@
         {
           "$ref": "#/$defs/Terrain3D"
         },
+        {
+          "$ref": "#/$defs/TileMap2D"
+        },
         {
           "$ref": "#/$defs/Timer"
         },
+        {
+          "$ref": "#/$defs/Trail3D"
+        },
         {
           "$ref": "#/$defs/Tree3D"
         },
@@ -298,6 +304,12 @@
         {
           "$ref": "#/$defs/UiBar"
         },
+        {
+          "$ref": "#/$defs/UiButton"
+        },
+        {
+          "$ref": "#/$defs/UiDialogue"
+        },
         {
           "$ref": "#/$defs/UiText"
         },
@@ -1753,6 +1765,10 @@
             "skinYawOffset": {
               "type": "number",
               "default": 0
+            },
+            "animations": {
+              "type": "object",
+              "default": {}
             }
           },
           "additionalProperties": false
@@ -4842,6 +4858,124 @@
       },
       "required": ["name", "type"]
     },
+    "TileMap2D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "TileMap2D"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "position": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [0, 0]
+            },
+            "rotation": {
+              "type": "number",
+              "default": 0
+            },
+            "static": {
+              "type": "boolean",
+              "default": false
+            },
+            "scale": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [1, 1]
+            },
+            "renderOrder": {
+              "type": "number",
+              "default": 0
+            },
+            "orderGroup": {
+              "type": "string",
+              "enum": ["background", "terrain", "default", "characters", "effects", "overlay"],
+              "default": "default"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "texture": {
+              "type": "string",
+              "default": ""
+            },
+            "tileSize": {
+              "type": "number",
+              "default": 32
+            },
+            "columns": {
+              "type": "number",
+              "default": 0
+            },
+            "cells": {
+              "type": "array",
+              "default": []
+            },
+            "legend": {
+              "type": "object",
+              "default": {}
+            },
+            "solid": {
+              "type": "array",
+              "default": []
+            },
+            "opacity": {
+              "type": "number",
+              "default": 1
+            }
+          },
+          "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"]
+    },
     "Timer": {
       "type": "object",
       "x-signals": ["timeout"],
@@ -4906,6 +5040,129 @@
       },
       "required": ["name", "type"]
     },
+    "Trail3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "Trail3D"
+        },
+        "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"
+            },
+            "width": {
+              "type": "number",
+              "default": 0.3
+            },
+            "color": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "opacity": {
+              "type": "number",
+              "default": 0.8
+            },
+            "seconds": {
+              "type": "number",
+              "default": 0.6
+            },
+            "emitting": {
+              "type": "boolean",
+              "default": true
+            },
+            "additive": {
+              "type": "boolean",
+              "default": false
+            },
+            "minDistance": {
+              "type": "number",
+              "default": 0.05
+            }
+          },
+          "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"]
+    },
     "Tree3D": {
       "type": "object",
       "properties": {
@@ -5315,6 +5572,176 @@
       },
       "required": ["name", "type"]
     },
+    "UiButton": {
+      "type": "object",
+      "x-signals": ["pressed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiButton"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "text": {
+              "type": "string",
+              "default": "OK"
+            },
+            "size": {
+              "type": "number",
+              "default": 16
+            },
+            "color": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "background": {
+              "type": "string",
+              "default": "rgba(255,255,255,0.14)"
+            },
+            "disabled": {
+              "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"]
+    },
+    "UiDialogue": {
+      "type": "object",
+      "x-signals": ["lineShown", "choiceMade", "dialogueFinished"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiDialogue"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "bottom"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "charsPerSecond": {
+              "type": "number",
+              "default": 40
+            },
+            "width": {
+              "type": "number",
+              "default": 520
+            }
+          },
+          "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"]
+    },
     "UiText": {
       "type": "object",
       "properties": {

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

@@ -97,6 +97,20 @@ shambling clip + glowing eyes for an enemy that reads as a different creature.
              "animation": "$walk", "castShadow": true } }
 ```
 
+## Animations without code
+
+Map movement states straight in JSON — no behavior needed:
+
+```json
+{ "name": "Controller", "type": "CharacterController3D",
+  "props": { "view": "free",
+    "animations": { "idle": "$idle", "walk": "$walk", "run": "$run",
+                    "fastRun": "$sprint", "airborne": "$jump" } } }
+```
+
+The controller writes `skin.animation` on every state change (crossfaded by
+the model). The `movementStateChanged` signal still fires for extras.
+
 The controller also yaw-rotates the sibling at `skinPath` ('../Skin') toward
 the move direction at `turnSpeed` rad/s (100 = instant snap) — the body
 itself never rotates. The skin MOUNTS at 180° (facing away from the default

package/skills/incanto-audio.md

@@ -98,6 +98,29 @@ something up, `hurt` when Health takes damage:
 > same unlock listener that retries `src` players also resumes the SFX context
 > (see §2).
 
+### Continuous voices — engine hum, wind, thrusters (`startVoice`)
+
+One-shot presets can't do a sound that **lasts and retunes** — a motor that
+follows the RPM, wind that rises with speed. `engine.sfx.startVoice(preset)`
+starts a live synth voice you retune every frame:
+
+```ts
+const motor = engine.sfx.startVoice('engine');        // presets: engine | wind | hum | noise
+// per frame (e.g. in a script's update):
+motor.set({ pitch: 0.8 + speed / maxSpeed, volume: throttle * 0.6 });
+// on destroy / scene change:
+motor.stop();          // fades out over 0.15s and frees the WebAudio nodes
+motor.stop(1.2);       // …or a slow custom fade
+```
+
+- **`pitch`** — 1 = the preset's base tone; drive it from speed/RPM/height.
+- **`volume`** — 0..1; `startVoice(preset, gain)` sets an overall ceiling.
+- Presets: `engine` (detuned-saw motor growl), `wind` (band-passed rush),
+  `hum` (soft pad — shields, auras, reactors), `noise` (thrusters, static).
+- Headless the handle is **inert** (`set`/`stop` are no-ops) — keep the same
+  call sites, no `if (browser)` guards. Voices need the same first-gesture
+  unlock as everything else.
+
 ---
 
 ## 2. The AudioPlayer node (preset vs src file)

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

@@ -61,6 +61,37 @@ A solid-colored rectangle — no texture, no asset file. Props: `size [100,100]`
 `color '#ffffff'`, `opacity 1`, `anchor [0.5,0.5]`. The prototyping workhorse
 (paddles, walls, platforms, flashes); swap in a `Sprite2D` when art arrives.
 
+### `TileMap2D` (a whole tile level in ONE node)
+Grid render in a single draw call **plus** greedy-merged static colliders —
+stop hand-placing dozens of ColorRect walls:
+
+```jsonc
+{ "name": "Level", "type": "TileMap2D", "props": {
+    "texture": "$tiles",      // atlas: tileSize×tileSize squares, L→R, T→B
+    "tileSize": 32,
+    "cells": [
+      "..................",
+      "......GGG.........",
+      "000000000000000000"
+    ],
+    "legend": { "G": 12 },    // chars → atlas tile index (digits 0-9 are free)
+    "solid": [0, 12]          // these tile indices become static colliders
+} }
+```
+
+- `.` / space = empty; digits `0-9` = atlas tile index directly; any OTHER char
+  must be in `legend` — unknown chars **hard-fail at load** (fix the map, not
+  the runtime).
+- `solid` tiles are merged into a handful of `StaticBody2D` rect colliders
+  (greedy rectangles), so a 100×50 level costs a few bodies, not thousands.
+- Cell (0,0) hangs its TOP-LEFT on the node's origin; position the node to
+  place the level. `columns: 0` (default) derives atlas columns from the
+  texture width.
+- No texture yet? Colliders still work — pair with ColorRect2D placeholders or
+  just leave it invisible while you block out the level.
+- Change the map at runtime by REPLACING `cells` (mutations are not watched):
+  `map.cells = [...rows]` — geometry and colliders rebuild next frame.
+
 ### `Sprite2D`
 | Prop | Default | Notes |
 |---|---|---|

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

@@ -358,6 +358,27 @@ paletteColors:[…saturated…], shimmer:8`), a lingering ember glitter
 spreadDeg:180`) with `renderOrder:100`, each parented to a stable
 node (NOT the collectible's container), self-removing on `finished`.
 
+## Trails (`Trail3D` — motion ribbons)
+
+A fading world-space ribbon behind whatever it's parented to — wingtip trails,
+sword arcs, tyre streaks, dash effects. Cheaper and crisper than particles for
+"where did it move" lines:
+
+```jsonc
+{ "name": "WingTrail", "type": "Trail3D",
+  "props": { "width": 0.4, "color": "#aaddff", "seconds": 0.8, "additive": true } }
+```
+
+Parent it to the MOVING node (it records that node's world position). The strip
+faces the camera and tapers + fades toward the tail over `seconds`.
+
+- `width` (m, default 0.3), `color`, `opacity` (0.8), `seconds` (0.6 lifetime).
+- `additive: true` for glowing energy trails (dark backdrops); default normal
+  blending reads better in daylight.
+- `emitting: false` stops laying NEW ribbon while the old tail fades out — flip
+  it from script for dash/boost effects (`trail.emitting = boosting`).
+- `minDistance` (0.05 m) filters jitter when the parent is near-stationary.
+
 ## Terrain
 
 `Terrain3D` is procedural heightfield terrain with biome texture splatting —

package/skills/incanto-gameplay-behaviors.md

@@ -745,6 +745,10 @@ Terminal states ignore further transitions; the restart action (or
 physics, input. Listen to the `flowChanged(state)` signal for custom UI.
 `restartScene(engine)` is exported standalone.
 
+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
 
 ```ts
@@ -765,3 +769,27 @@ save.set('highScore', Math.max(score, save.get('highScore', 0)));
 
 JSON round-tripped; headless/private-mode falls back to in-memory (never
 throws). `clear()` wipes only your namespace.
+
+## Pathfinding (grid A* + PathFollow)
+
+```ts
+import { findPath, gridFromRows } from 'incanto';
+
+const grid = gridFromRows([   // or { width, height, solid(x,y) } over your map data
+  '..........',
+  '..######..',
+  '..........',
+]);
+const cells = findPath(grid, [0, 1], [9, 1]);          // null = unreachable
+(npc.behavior as PathFollow).setPath(
+  (cells ?? []).map(([cx, cy]) => [cx * TILE, cy * TILE]),
+);
+npc.on('arrived', () => attack());
+```
+
+`findPath` is pure and dimension-free (cells in, cells out; diagonals on by
+default, corner-cutting forbidden; `{ diagonal: false }` for 4-way).
+`PathFollow` (registered behavior) walks waypoints at constant `speed`
+(units/sec — px in 2D, meters in 3D), emits `waypointReached(i)` /
+`arrived`, and `loop: true` patrols. Corners never eat frame budget — the
+speed is exact across bends.

package/skills/incanto-hud.md

@@ -56,3 +56,27 @@ banner.show('YOU DIED', { color: '#ef4444', seconds: 0 }); // sticky until next
 
 Pair with the `Health` / `ScoreKeeper` gameplay behaviors: listen to their
 signals and write the widget props — that is the whole HUD wiring.
+
+## Interactive widgets: UiButton & UiDialogue
+
+```json
+{ "name": "Talk", "type": "UiDialogue" },
+{ "name": "Start", "type": "UiButton",
+  "props": { "anchor": "center", "text": "START" } }
+```
+
+```ts
+const talk = this.node.getNode('%Talk') as UiDialogue;
+talk.say('Elder', 'Welcome to Lumina Village...');
+talk.say('Elder', 'Will you help us?', ['Yes', 'No']);
+talk.on('choiceMade', (i) => { if (i === 0) startQuest(); });
+talk.on('dialogueFinished', () => player.frozen = false);
+// while talk.active, skip player input — the box eats clicks to advance
+
+(this.node.getNode('%Start') as UiButton).on('pressed', () => flow.restart());
+```
+
+Typewriter reveal at `charsPerSecond` (0 = instant); clicking the box
+reveals the line then advances; choice lines render buttons and wait for
+`choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
+click-through.