incanto 0.13.0 → 0.15.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-DSq0gdhE.js"></script>
+    <script type="module" crossorigin src="./assets/index-CofH0yGY.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.13.0",
+  "version": "0.15.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -2371,8 +2371,7 @@
               "default": 0.5
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",
@@ -2559,8 +2558,7 @@
               "default": 1
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",
@@ -5656,8 +5654,7 @@
               "default": true
             },
             "drape": {
-              "type": "boolean",
-              "default": false
+              "default": null
             },
             "terrain": {
               "type": "string",
@@ -6452,6 +6449,22 @@
             "underwater": {
               "type": "boolean",
               "default": true
+            },
+            "swell": {
+              "type": "number",
+              "default": 0
+            },
+            "swellDirectionDeg": {
+              "type": "number",
+              "default": 0
+            },
+            "swellWavelength": {
+              "type": "number",
+              "default": 30
+            },
+            "whitecaps": {
+              "type": "number",
+              "default": 0
             }
           },
           "additionalProperties": false

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`,
@@ -610,7 +609,9 @@ non-default composition.
 
 A commercial-quality water surface (in `incanto/3d`, registered by
 `registerNodes3D`). The default `quality: 'fancy'` is a real water shader:
-9-iteration simplex-FBM wave displacement with analytic normals, THREE
+9-iteration simplex-FBM wave displacement with analytic normals, optional
+DIRECTIONAL TRAVELING SWELL trains + open-water whitecaps (`swell` /
+`whitecaps` — the open-ocean look; see the prop table), THREE
 animated ANISOTROPIC detail-normal layers — wind-stretched (~2.8× along the
 wind), ridge-sharpened fine ripple in crossing directions, each layer
 distance-faded at its own range so the far field goes glassy instead of
@@ -669,6 +670,10 @@ hue reads grey.
 | `detailStrength` | `0.3` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
 | `absorption` | `0.15` | Beer's-law constant per meter of water depth (≥ 0; lower = clearer/wider turquoise band; red absorbs ~3× faster than blue under the hood) |
 | `refraction` | `true` | screen-space refraction of the submerged scene |
+| `swell` | `0` | **THE open-ocean dial** (fancy only, 0.15.0): directional traveling swell amplitude in meters. Three peaked wave trains (primary + two crossing sets) march across the surface at real deep-water speeds; crests light up toward the peak color and wave FACES get sun-lit/shadow shading, so the swell reads at any distance. 0.15 = lively lake chop, 0.4 = coastal sea, 0.7 = heavy weather. `0` (default) keeps the legacy calm look byte-identical |
+| `swellDirectionDeg` | `0` | compass direction the swell TRAVELS toward (0 = +z, 90 = +x) |
+| `swellWavelength` | `30` | primary swell wavelength, meters (≥ 2, load-time check); the crossing trains derive from it |
+| `whitecaps` | `0` | open-water whitecap foam on the tallest crests, 0–1 (fancy only; load-time check). Pairs with `swell` — the caps ride its crest lines and fade with distance so the horizon stays clean |
 | `underwater` | `true` | submerged-camera look: ONLY when the camera EYE is below this surface (inside its XZ footprint) — wading with the camera above the water never tints the view — the scene switches to short-range underwater fog + tint, the sky is hidden, and animated **caustics** (depth-aware, projected onto the submerged floor/props) play. `false` disables it; an object `{ color?, visibility?, caustics? }` overrides the murk hue / view distance (m, default 22) / caustics. `caustics` is `true` (default) \| `false` \| `{ color?, intensity?, scale?, speed? }`. The murk color defaults to a darkened shade of `color`. Works for both qualities (the caustics composite runs only while the camera is genuinely underwater) |
 
 Performance notes (fancy): beyond drawing the surface, each rendered frame

package/skills/incanto-node-reference.md

@@ -330,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`
@@ -362,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`
@@ -836,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`
@@ -953,6 +953,10 @@ Signals: `blocksChanged`
 | `absorption` | `0.15` | number |
 | `refraction` | `true` | boolean |
 | `underwater` | `true` | boolean |
+| `swell` | `0` | number |
+| `swellDirectionDeg` | `0` | number |
+| `swellWavelength` | `30` | number |
+| `whitecaps` | `0` | number |
 
 Signals: `entered(body)` · `exited(body)`
 

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

@@ -11,7 +11,7 @@
   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.
+- **Gliding**: hold JUMP while falling — capped descent; landing thumps a dust puff.
 - Keeper NPC tracks the player with `BoneLookAt3D`; shoreline rocks are one
   `InstancedMesh3D` draw call.
 

package/templates-app/beacon-isle-3d/generate-world.ts

@@ -101,7 +101,6 @@ for (let i = 0; i < 400 && grassPlaced < 14; i++) {
       position: [round2(x), round2(y), round2(z)],
       area: [34, 34],
       density: 10,
-      terrain: '../../Ground/Surface',
     },
   });
 }
@@ -119,7 +118,6 @@ for (let i = 0; i < 300 && flowersPlaced < 9; i++) {
       position: [round2(x), round2(y), round2(z)],
       area: [12, 12],
       seed: Math.floor(rand() * 1e9),
-      terrain: '../../Ground/Surface',
     },
   });
 }
@@ -180,7 +178,7 @@ const ward = (i: number, [x, y, z]: [number, number, number]): unknown => ({
           type: 'MeshInstance3D',
           props: {
             mesh: 'cylinder',
-            size: [1.6, 1.2, 1.6],
+            size: [0.8, 1.2, 0.8], // RADIUS (cylinder size[0]) = collider box half-extent
             material: { color: '#7d8494', roughness: 0.9 },
             castShadow: true,
             receiveShadow: true,
@@ -319,7 +317,7 @@ const scene = {
     fog: { near: 110, far: 560 },
     shadows: { mapSize: 2048, radius: 1.2 },
     exposure: 1.12,
-    ambient: { color: '#ffe8d4', intensity: 0.66 },
+    ambient: { color: '#ffe8d4', intensity: 0.85 },
     iblIntensity: 0.9,
     bloom: { threshold: 1.2, strength: 0.55 },
     post: { vignette: 0.28, saturation: 1.12, contrast: 1.02 },
@@ -382,7 +380,24 @@ const scene = {
         // must keep animating — auditScene flags exactly this mistake.
         children: (terrain.children ?? []).map((c) =>
           c.type === 'Water3D' || c.name === 'Clouds'
-            ? c
+            ? c.name === 'Sea'
+              ? {
+                  ...c,
+                  // the OPEN-OCEAN dial (0.15.0): directional swell trains +
+                  // whitecaps + deeper absorption — the sea moves, banded and
+                  // alive, instead of a flat noise sheet
+                  props: {
+                    ...(c.props ?? {}),
+                    swell: 0.55,
+                    swellWavelength: 42,
+                    swellDirectionDeg: 262,
+                    whitecaps: 0.45,
+                    absorption: 0.28,
+                    reflectionInterval: 400,
+                    colors: { trough: '#0c3d58', surface: '#1a7d9c', peak: '#9adfe0' },
+                  },
+                }
+              : c
             : { ...c, props: { ...(c.props ?? {}), static: true } },
         ),
       },
@@ -409,7 +424,7 @@ const scene = {
                 type: 'MeshInstance3D',
                 props: {
                   mesh: 'cylinder',
-                  size: [3, 11, 3],
+                  size: [1.5, 11, 1.5], // RADIUS = collider half-extent (was 3 → camera clipped inside the 1.5 m shell)
                   material: { color: '#e8e2d4', roughness: 0.8 },
                   castShadow: true,
                   receiveShadow: true,
@@ -420,7 +435,7 @@ const scene = {
                 type: 'MeshInstance3D',
                 props: {
                   mesh: 'cylinder',
-                  size: [3.06, 1.6, 3.06],
+                  size: [1.56, 1.6, 1.56],
                   position: [0, 1.2, 0],
                   material: { color: '#b8452e', roughness: 0.8 },
                 },
@@ -584,18 +599,6 @@ const scene = {
               },
             ],
           },
-          {
-            name: 'DashTrail',
-            type: 'Trail3D',
-            props: {
-              width: 0.5,
-              color: '#ffffff',
-              opacity: 0.28,
-              seconds: 0.45,
-              emitting: false,
-              position: [0, -0.4, 0],
-            },
-          },
           {
             name: 'SwingSfx',
             type: 'AudioPlayer',
@@ -609,7 +612,7 @@ const scene = {
         type: 'Node',
         script: {
           name: 'DayNight',
-          props: { paused: true, startHour: 17.5, nightDarkness: 0.42, maxSunElevationDeg: 48 },
+          props: { paused: true, startHour: 17.25, nightDarkness: 0.32, maxSunElevationDeg: 48 },
         },
       },
       {

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.13.0",
+    "incanto": "^0.15.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/src/behaviors.ts

@@ -21,7 +21,7 @@ import type {
   Voice,
 } from 'incanto';
 import { Behavior, findPath } from 'incanto';
-import type { MeshInstance3D, Node3D, Terrain3D, Trail3D } from 'incanto/3d';
+import type { Camera3D, MeshInstance3D, Node3D, Terrain3D, Trail3D } from 'incanto/3d';
 import { buildTerrainNav, Particles3D, type TerrainNav } from 'incanto/3d';
 import { type DayNight, goToScene } from 'incanto/gameplay';
 import gameJsonRaw from './game.scene.json';
@@ -54,6 +54,39 @@ const PATROL_SPEED = 2.6;
 const HUNT_SPEED = 3.6;
 const WARD_LIGHT_RANGE = 4;
 
+/** Sprint feel — see sprintFeel(): FOV kick + per-stride dust. */
+const FOV_BASE = 60;
+const FOV_SPRINT = 66.5;
+const STRIDE_SECONDS = 0.22;
+
+/**
+ * One kicked-up earth puff, world-anchored at the foot spot (one-shot,
+ * self-removing). Non-additive expanding dust — NOT a glow: it reads as
+ * dirt leaving the ground, then thins out.
+ */
+function spawnFootDust(root: Node, at: [number, number, number], scale = 1): void {
+  const puff = new Particles3D('FootDust');
+  puff.position = [at[0], at[1], at[2]];
+  puff.rate = 0;
+  puff.burst = Math.round(4 * scale);
+  puff.blend = 'normal';
+  puff.lifetime = [0.3, 0.5];
+  puff.speed = [8, 34];
+  puff.directionDeg = -90; // up out of the ground…
+  puff.spreadDeg = 75;
+  puff.gravity = [0, 30]; // …then settle back down
+  puff.drag = 2.5;
+  puff.sizeStart = 11 * scale;
+  puff.sizeEnd = 30 * scale; // dust EXPANDS as it dissipates
+  puff.colorStart = '#c2b394'; // dry peat kicked into the dusk light
+  puff.colorEnd = '#8a7c66';
+  puff.alphaStart = 0.24;
+  puff.alphaEnd = 0;
+  puff.maxParticles = 24;
+  puff.on('finished', () => puff.free());
+  root.addChild(puff);
+}
+
 export class IsleDirector extends Behavior {
   private wind: Voice | null = null;
   private nav: TerrainNav | null = null;
@@ -63,6 +96,9 @@ export class IsleDirector extends Behavior {
   private bobClock = 0;
   private fireworksIn = -1;
   private glideActive = false;
+  private strideClock = 0;
+  private wasAirborne = false;
+  private fov = FOV_BASE;
 
   private get dialogue(): UiDialogue {
     return this.node.getNode('HUD/Dialogue') as UiDialogue;
@@ -139,6 +175,37 @@ export class IsleDirector extends Behavior {
     }
   }
 
+  /**
+   * Sprint FEEL — speed you can see instead of a ribbon glued to the hips:
+   * - a soft camera FOV kick while at full sprint (eased both ways)
+   * - kicked-up earth at the feet, one puff per stride
+   * - a bigger thump-puff on landing after airtime (jump or glide)
+   */
+  private sprintFeel(dt: number, state: string): void {
+    const camera = this.node.getNodeOrNull('Camera') as Camera3D | null;
+    if (camera) {
+      const target = state === 'fastRun' ? FOV_SPRINT : FOV_BASE;
+      this.fov += (target - this.fov) * Math.min(1, dt * 6);
+      camera.fov = this.fov;
+    }
+    const player = this.node.getNodeOrNull('Player') as (Node3D & Positioned) | null;
+    if (!player) return;
+    const [px, py, pz] = player.position;
+    const feet: [number, number, number] = [px ?? 0, (py ?? 0) - 0.62, pz ?? 0];
+    const airborne = state === 'airborne';
+    if (this.wasAirborne && !airborne) spawnFootDust(this.node, feet, 1.7); // landing thump
+    this.wasAirborne = airborne;
+    if (state === 'fastRun') {
+      this.strideClock -= dt;
+      if (this.strideClock <= 0) {
+        this.strideClock = STRIDE_SECONDS;
+        spawnFootDust(this.node, feet);
+      }
+    } else {
+      this.strideClock = 0;
+    }
+  }
+
   private ambient(dt: number, engine: Engine | null | undefined): void {
     const controller = this.node.getNode('Player/Controller') as unknown as {
       state: string;
@@ -152,8 +219,7 @@ export class IsleDirector extends Behavior {
             : { pitch: 0.85, volume: 0.2 };
       this.wind.set(w);
     }
-    const dash = this.node.getNodeOrNull('Player/DashTrail') as Trail3D | null;
-    if (dash && controller) dash.emitting = controller.state === 'fastRun';
+    if (controller) this.sprintFeel(dt, controller.state);
     // shades hover-bob and face their travel
     this.bobClock += dt;
     for (const node of this.node.tree?.getNodesInGroup('shade') ?? []) {
@@ -241,7 +307,7 @@ export class IsleDirector extends Behavior {
         ? 8.7
         : quest.bossRisen
           ? 17.8 // sun ~+2 deg — deep red horizon, still lit (below 18 the sky dies)
-          : 17.5 - quest.lit.size * 0.35; // each ward buys back the light
+          : 17.25 - quest.lit.size * 0.4; // each ward buys back the light
     sky.hour += (targetHour - sky.hour) * Math.min(1, dt * 0.4);
   }