incanto 0.20.0 → 0.21.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-CXdpxO_B.js"></script>
+    <script type="module" crossorigin src="./assets/index-Dt44Z9ka.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.20.0",
+  "version": "0.21.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -4735,6 +4735,10 @@
             "flowForce": {
               "type": "number",
               "default": 1
+            },
+            "spray": {
+              "type": "number",
+              "default": 1
             }
           },
           "additionalProperties": false
@@ -6579,6 +6583,10 @@
               "type": "boolean",
               "default": false
             },
+            "swellSteepness": {
+              "type": "number",
+              "default": 0.35
+            },
             "foam": {
               "type": "boolean",
               "default": true

package/skills/incanto-environment.md

@@ -699,6 +699,7 @@ hue reads grey.
 | `reflection` | `true` | live CubeCamera reflections (fancy only; needs a renderer) |
 | `reflectionInterval` | `1000` | ms between CubeCamera reflection re-renders |
 | `mirror` | `false` | TRUE planar reflection (see below) — the only way the dock, the boat and the player appear IN the water. One extra scene render per frame |
+| `swellSteepness` | `0.35` | GERSTNER pinch on the swell: 0 = height-only trains, 1 = maximum trochoid (crests narrow to a peak, troughs broaden). It also decides where whitecaps break — the surface's Jacobian collapses on a folding crest, and that is where foam belongs |
 | `foam` | `true` | noise-broken shoreline foam band + crest foam near shores |
 | `interaction` | `true` | character interaction: bodies (CharacterBody3D/RigidBody3D) inside the XZ footprint whose FEET dip below the surface count as in-water — so a WADING character (origin above water, feet below, sized from its collider) splashes, not only a fully-submerged one. Entry/exit emit `entered`/`exited` + a splash ripple; striding through water trails a WAKE (a ripple every ~0.45 m); floating bodies bob gently. Ripples drive both shaders' `uRipples[8]` (fancy) and CPU-displace the mesh (`simple`) |
 | `splash` | `true` | built-in splash WHITEWATER (needs `interaction`): the shaders paint expanding **surface foam** where bodies interact — a **"풍덩"** froth bloom when a body plunges in (bigger the faster it falls) and a **foam trail ("물살")** behind a body wading/running through. Real frothy whitewater on the surface, not flying droplets; works on both `fancy` and `simple` quality. `false` keeps the ripples/waves but paints no foam. No wiring needed; for an extra custom burst add your own `Particles3D` on the `entered` signal |
@@ -837,6 +838,7 @@ underneath decides everything else.
 | `ripples` | `1` | surface-detail dial (ripple relief + glitter) |
 | `terrain` | `''` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 | `flowForce` | `1` | how hard the current sweeps bodies downstream (0 = visual only) |
+| `spray` | `1` | mist at the foot of every waterfall the course turns out to contain — the node finds the drops and hangs a Particles3D plume on each (0 = off) |
 | `sunDirection` / `sunColor` / `sunIntensity` | sky / `#fff6e0` / `1` | glint (the environment sun wins while `sunDirection` is default) |
 
 **What the node derives for you**, all from `path` + the ground:
@@ -868,6 +870,38 @@ const path = traceDownhillPath(terrain.heightAt, { x: peakX, z: peakZ, step: 7 }
 "path": path, "widths": [2.4, 4.5, 7, 9], "depth": 1
 ```
 
+### Waterfalls happen — you do not author them
+
+Nothing in a scene says "waterfall". Where the ground gives way the surface
+profile falls with it, and past ~20° of grade the shader stops treating the
+sheet as flowing water: it aerates (white, diffuse, no sky reflection), its
+pattern stretches into strands, the standing waves of a rapid switch off, and
+the lip goes glassy-dark for the moment before it breaks. `spray` then hangs a
+mist plume at the foot of each drop, sized by how far the water fell.
+
+The cheapest way to put one in a scene is to take the ground away — a
+`basins` pocket on the course, no wider than the creek's own reach:
+
+```ts
+const plungeAt = path[Math.round(path.length * 0.82)];
+"basins": [{ "x": plungeAt[0], "z": plungeAt[1], "radius": 7, "depth": 4.5 }]
+```
+
+Keep it a POCKET: a wide shallow bowl reads as a crater with a puddle, and the
+drop has to be short and sharp for the curtain to read at all. For your own
+effects (sound, a rainbow, a cave behind the water), `river.fallsAt()` returns
+every drop with its plunge point in WORLD coordinates and its height:
+
+```ts
+for (const fall of creek.fallsAt()) {
+  if (fall.drop > 4) playAt('$sfx/falls', fall.worldX, fall.worldY, fall.worldZ);
+}
+```
+
+A step shallower than the water's own `depth` is deliberately NOT a fall — the
+surface profile treats it as bed grain, which is what stops every riffle in a
+creek from spawning a spray plume.
+
 ### Let the terrain choose the course — `traceDownhillPath`
 
 ```ts

package/skills/incanto-node-reference.md

@@ -696,6 +696,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `sunIntensity` | `1` | number |
 | `terrain` | `""` | string |
 | `flowForce` | `1` | number |
+| `spray` | `1` | number |
 
 ## `Sprite2D` — `incanto/2d`
 
@@ -973,6 +974,7 @@ Signals: `blocksChanged`
 | `reflection` | `true` | boolean |
 | `reflectionInterval` | `1000` | number |
 | `mirror` | `false` | boolean |
+| `swellSteepness` | `0.35` | number |
 | `foam` | `true` | boolean |
 | `interaction` | `true` | boolean |
 | `splash` | `true` | boolean |

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.20.0",
+    "incanto": "^0.21.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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.20.0",
+    "incanto": "^0.21.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-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.20.0",
+    "incanto": "^0.21.0",
     "three": "^0.184.0"
   },
   "devDependencies": {