incanto 0.14.0 → 0.16.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-7qOYg7t8.js"></script>
+    <script type="module" crossorigin src="./assets/index-N3Hnrv0w.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.14.0",
+  "version": "0.16.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -6449,6 +6449,31 @@
             "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
+            },
+            "preset": {
+              "type": "string",
+              "enum": ["custom", "ocean", "pool", "lake", "pond"],
+              "default": "custom"
+            },
+            "causticsAbove": {
+              "type": "number",
+              "default": 0
             }
           },
           "additionalProperties": false

package/skills/incanto-environment.md

@@ -608,8 +608,14 @@ non-default composition.
 ## Water3D
 
 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
+`registerNodes3D`). **Four curated water types are one prop away:**
+`preset: 'ocean' | 'pool' | 'lake' | 'pond'` — see the prop table; the four
+`examples/water-*-3d` templates stage one each (cove pier, resort pool,
+mirror-lake dock, walled garden pond). The default `quality: 'fancy'` is a
+real water shader:
+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
@@ -668,6 +674,12 @@ 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 |
+| `preset` | `"custom"` | **THE one-choice water type** (0.16.0): `ocean` \| `pool` \| `lake` \| `pond` bundles every wave/color/clarity/caustics knob into a hand-tuned sea state. A preset value applies ONLY where a prop still sits at its schema default — pick the type, then override any detail prop and your value wins. ocean = traveling swell + whitecaps + wide turquoise→deep absorption · pool = near-flat crystal water + strong above-water caustics · lake = calm high-reflectivity mirror, green-teal murk · pond = still, mossy, opaque quickly. `custom` (default) changes nothing |
+| `causticsAbove` | `0` | above-water CAUSTICS intensity 0–3 (fancy + `refraction` only): the dancing light web on the submerged bottom seen THROUGH the surface — the pool / tropical-shallows look. Reconstructed on the real refracted bottom position, strongest through the first meters of water, distance-faded. Presets set it (pool 1.0); override freely |
+| `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

@@ -953,6 +953,12 @@ Signals: `blocksChanged`
 | `absorption` | `0.15` | number |
 | `refraction` | `true` | boolean |
 | `underwater` | `true` | boolean |
+| `swell` | `0` | number |
+| `swellDirectionDeg` | `0` | number |
+| `swellWavelength` | `30` | number |
+| `whitecaps` | `0` | number |
+| `preset` | `"custom"` | one of: `custom` `ocean` `pool` `lake` `pond` |
+| `causticsAbove` | `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

@@ -178,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,
@@ -317,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 },
@@ -380,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 } },
         ),
       },
@@ -407,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,
@@ -418,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 },
                 },
@@ -582,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',
@@ -607,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.14.0",
+    "incanto": "^0.16.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);
   }
 

package/templates-app/beacon-isle-3d/src/game.scene.json

@@ -22,7 +22,7 @@
     "exposure": 1.12,
     "ambient": {
       "color": "#ffe8d4",
-      "intensity": 0.66
+      "intensity": 0.85
     },
     "iblIntensity": 0.9,
     "bloom": {
@@ -138,7 +138,18 @@
             "props": {
               "size": [1920, 1920],
               "position": [0, 9.19, 0],
-              "opacity": 1
+              "opacity": 1,
+              "swell": 0.55,
+              "swellWavelength": 42,
+              "swellDirectionDeg": 262,
+              "whitecaps": 0.45,
+              "absorption": 0.28,
+              "reflectionInterval": 400,
+              "colors": {
+                "trough": "#0c3d58",
+                "surface": "#1a7d9c",
+                "peak": "#9adfe0"
+              }
             }
           },
           {
@@ -1451,7 +1462,7 @@
                 "type": "MeshInstance3D",
                 "props": {
                   "mesh": "cylinder",
-                  "size": [3, 11, 3],
+                  "size": [1.5, 11, 1.5],
                   "material": {
                     "color": "#e8e2d4",
                     "roughness": 0.8
@@ -1465,7 +1476,7 @@
                 "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",
@@ -1602,7 +1613,7 @@
                 "type": "MeshInstance3D",
                 "props": {
                   "mesh": "cylinder",
-                  "size": [1.6, 1.2, 1.6],
+                  "size": [0.8, 1.2, 0.8],
                   "material": {
                     "color": "#7d8494",
                     "roughness": 0.9
@@ -1690,7 +1701,7 @@
                 "type": "MeshInstance3D",
                 "props": {
                   "mesh": "cylinder",
-                  "size": [1.6, 1.2, 1.6],
+                  "size": [0.8, 1.2, 0.8],
                   "material": {
                     "color": "#7d8494",
                     "roughness": 0.9
@@ -1778,7 +1789,7 @@
                 "type": "MeshInstance3D",
                 "props": {
                   "mesh": "cylinder",
-                  "size": [1.6, 1.2, 1.6],
+                  "size": [0.8, 1.2, 0.8],
                   "material": {
                     "color": "#7d8494",
                     "roughness": 0.9
@@ -2667,18 +2678,6 @@
               }
             ]
           },
-          {
-            "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",
@@ -2705,8 +2704,8 @@
           "name": "DayNight",
           "props": {
             "paused": true,
-            "startHour": 17.5,
-            "nightDarkness": 0.42,
+            "startHour": 17.25,
+            "nightDarkness": 0.32,
             "maxSunElevationDeg": 48
           }
         }

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.14.0",
+    "incanto": "^0.16.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/PROJECT/Context.md

@@ -19,7 +19,7 @@ again button.
 | `UiDialogue` + choices | the Elder conversation IS the quest state machine |
 | `UiButton` | the play-again button |
 | `findPath` + `PathFollow` | wolf patrol rings through the hedge maze |
-| `Trail3D` | sword arc + sprint dash trail |
+| `Trail3D` | sword arc |
 | `engine.sfx.startVoice('wind')` | live ambience that rises as you run |
 | `goToScene` | village ⇄ grove, with the black fade |
 | controller `animations` map | idle/walk/run/sprint/jump — zero animation code |

package/templates-app/village-quest-3d/PROJECT/Requirements.md

@@ -26,7 +26,7 @@
 ## Feel
 
 - Wind ambience always present, louder + higher while sprinting.
-- Dash trail only while sprinting.
+- Sprint FEEL: per-stride foot-dust puffs + a soft camera FOV kick (no body ribbon).
 - Village = warm sunset; grove = cold dusk, denser fog, moonlight.
 
 ## Verification (must stay green)

package/templates-app/village-quest-3d/PROJECT/Structure.md

@@ -4,11 +4,16 @@
 index.html               canvas + loading bar
 src/main.ts              preload GLB/anim assets → createGame3D (village)
 src/village.scene.json   sunset village: Elder (Interactable), gate Area3D,
-                         player rig (controller `animations` map, Trail3D ×2),
+                         player rig (controller `animations` map, sword Trail3D),
                          HUD (UiText/UiBanner/UiDialogue/UiButton)
 src/grove.scene.json     dusk grove: 3 wolves (PathFollow), return portal,
                          empty `Maze` holder (hedges are built at runtime)
 src/behaviors.ts         GROVE_GRID + VillageDirector / GroveDirector / SwordStrike
+generate-dressing.ts     VILLAGE dressing generator: rebuilds environment + the
+                         visual `Village` subtree (timber cottages, fences,
+                         lanterns, stall, grass/flowers, treelines) — edit
+                         numbers, `bun generate-dressing.ts`, reload. Gameplay
+                         nodes (Elder/Player/HUD/GroveGate) are preserved.
 src/quest.ts             cross-scene quest flags (module singleton)
 verify.ts                audit + headless quest E2E + replay determinism
 ```