incanto 0.19.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-B7gj1VII.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.19.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

@@ -277,6 +277,9 @@
         {
           "$ref": "#/$defs/RigidBody3D"
         },
+        {
+          "$ref": "#/$defs/River3D"
+        },
         {
           "$ref": "#/$defs/Sprite2D"
         },
@@ -4600,6 +4603,170 @@
       },
       "required": ["name", "type"]
     },
+    "River3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "River3D"
+        },
+        "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"
+            },
+            "path": {
+              "type": "array",
+              "default": []
+            },
+            "width": {
+              "type": "number",
+              "default": 6
+            },
+            "widths": {
+              "type": "array",
+              "default": []
+            },
+            "depth": {
+              "type": "number",
+              "default": 0.8
+            },
+            "flowSpeed": {
+              "type": "number",
+              "default": 1.6
+            },
+            "colors": {
+              "type": "object",
+              "default": {}
+            },
+            "absorption": {
+              "type": "number",
+              "default": 0.5
+            },
+            "opacity": {
+              "type": "number",
+              "default": 0.85
+            },
+            "foam": {
+              "type": "number",
+              "default": 1
+            },
+            "ripples": {
+              "type": "number",
+              "default": 1
+            },
+            "sunDirection": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0.5, 0.8, 0.3]
+            },
+            "sunColor": {
+              "type": "string",
+              "default": "#fff6e0"
+            },
+            "sunIntensity": {
+              "type": "number",
+              "default": 1
+            },
+            "terrain": {
+              "type": "string",
+              "default": ""
+            },
+            "flowForce": {
+              "type": "number",
+              "default": 1
+            },
+            "spray": {
+              "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"]
+    },
     "Sprite2D": {
       "type": "object",
       "properties": {
@@ -5198,6 +5365,10 @@
               "type": "array",
               "default": []
             },
+            "channels": {
+              "type": "array",
+              "default": []
+            },
             "wetline": {
               "default": null
             }
@@ -6408,6 +6579,14 @@
               "type": "number",
               "default": 1000
             },
+            "mirror": {
+              "type": "boolean",
+              "default": false
+            },
+            "swellSteepness": {
+              "type": "number",
+              "default": 0.35
+            },
             "foam": {
               "type": "boolean",
               "default": true

package/skills/incanto-environment.md

@@ -1,6 +1,6 @@
 ---
 name: incanto-environment
-description: Generating game environments in Incanto — the deterministic `incanto-env` CLI and `incanto/env` library. EXACTLY three themed 3D generators (arena with boxes/ruins/garden, Terrain3D heightfield worlds with island/alpine/plains/desert/meadow/forest/savanna/snow/wetland/volcanic themes, maze with stone/hedge/canyon) plus 2D mazes, roguelike dungeons and platform courses; insertIntoScene, the GENERATORS catalog + runGenerator; and the environment nodes — Terrain3D (biome texture splatting, heightAt, heightfield collider), shader-water Water3D (FBM waves, anisotropic wind ripple, sparse sun glints, crystal shallows, refraction + depth absorption, reflections, shoreline foam, splash signals + ripples), shader-grass Foliage3D (real curved blade meshes, clumps, rolling wind, distance LOD, character bend), Flowers3D flower plants (lush/sparse/none density dial, daisy/cosmos/bellflower varieties, Voronoi patches, head-bob sway) and ez-tree Tree3D groves (branchy trunks, textured wind-swayed leaves, budget-checked tiers). Use when a game needs a level, stage, arena, terrain, heightfield, island, meadow, grass field, flowers, flower bed, forest, trees, mountain, desert, savanna, snow, tundra, swamp, wetland, marsh, volcano, lava field, maze, dungeon, platform course, scattered props, clouds, water, or a splash effect.
+description: Generating game environments in Incanto — the deterministic `incanto-env` CLI and `incanto/env` library. EXACTLY three themed 3D generators (arena with boxes/ruins/garden, Terrain3D heightfield worlds with island/alpine/plains/desert/meadow/forest/savanna/snow/wetland/volcanic themes, maze with stone/hedge/canyon) plus 2D mazes, roguelike dungeons and platform courses; insertIntoScene, the GENERATORS catalog + runGenerator; and the environment nodes — Terrain3D (biome texture splatting, heightAt, heightfield collider), shader-water Water3D (FBM waves, anisotropic wind ripple, sparse sun glints, crystal shallows, refraction + depth absorption, reflections, shoreline foam, splash signals + ripples), River3D running water (path-derived course, terrain-cut banks, derived rapids/riffles, a current that sweeps bodies), shader-grass Foliage3D (real curved blade meshes, clumps, rolling wind, distance LOD, character bend), Flowers3D flower plants (lush/sparse/none density dial, daisy/cosmos/bellflower varieties, Voronoi patches, head-bob sway) and ez-tree Tree3D groves (branchy trunks, textured wind-swayed leaves, budget-checked tiers). Use when a game needs a level, stage, arena, terrain, heightfield, island, meadow, grass field, flowers, flower bed, forest, trees, mountain, desert, savanna, snow, tundra, swamp, wetland, marsh, volcano, lava field, maze, dungeon, platform course, scattered props, clouds, water, a river, stream, creek, brook, rapids, a ford, or a splash effect.
 ---
 
 # Environment generation — levels from a seed
@@ -554,6 +554,7 @@ is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
 | `layers` | `[]` | custom splat layers (theme `custom` only) |
 | `textureBase` | agent8 CDN | base URL: `<base>/<name>.png` + `<base>/<name>_normal.png` |
 | `basins` | `[]` | lake/pond bowls — `[{ x, z, radius, depth }]` (centered meters) carved into the surface (smooth, 0-slope rim); **negative `depth` RAISES a smooth dome mound instead** (a hill, an islet); `heightAt`, the collider AND draped grass all see them |
+| `channels` | `[]` | river/road TRENCHES carved along polylines — `[{ path, width, depth, taper? }]` (the line counterpart of `basins`). This is what gives a `River3D` a bed to sit in; `heightAt`, the collider and draped vegetation all see it |
 | `wetline` | `null` | WET SAND band — `{ y, band? }` darkens + glosses the splat in a noisy, breathing band just above height `y` (a waterline): the trace of the last swash runup. `band` (default `1.1` m) caps how high above `y` reads wet. `null` = off |
 
 **Wet sand at a shoreline.** Set `wetline.y` to the SAME world height as the
@@ -697,6 +698,8 @@ hue reads grey.
 | `colors` | `{}` | fancy ramp overrides: `{"trough", "surface", "peak"}` hex strings |
 | `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 |
@@ -737,6 +740,32 @@ Two placement rules keep the surface artifact-free:
   intentionally does not — its submerged hull shows through `refraction`
   instead.
 
+### `mirror` — a TRUE planar reflection
+
+The default reflection is a CubeCamera env map: it carries the sky and the far
+shore, and it deliberately near-clips everything inside the water's own
+footprint (a nearby crate sampled as an infinite environment smears across the
+whole surface). So the boat, the dock, the pier lamp and the player standing at
+the edge are exactly what it CANNOT show.
+
+`mirror: true` re-renders the scene from the camera mirrored across the water
+plane and samples it per fragment, so those things appear in the water:
+
+```json
+{ "type": "Water3D", "props": { "preset": "lake", "mirror": true,
+    "waveHeight": 0.012, "detailStrength": 0.07 } }
+```
+
+- Costs **one extra scene render per frame** (half the drawing buffer, clamped)
+  — off by default; a still lake or a pool earns it, open ocean rarely does.
+- A mirror needs a CALM surface to read: chop that shatters the reflection is
+  what makes game lakes look like blue plastic. Pair it with a low `waveHeight`
+  and a gentle `detailStrength`.
+- Rays that leave the screen have no planar sample; those fragments fall back to
+  the cube map (keep `reflection: true`), so there is no hard cut at the edges.
+- Geometry below the waterline is clipped out of the mirror pass, and the whole
+  pass is skipped while the camera is submerged.
+
 ### Character interaction — `entered(body)` / `exited(body)`
 
 With `interaction: true` the water scans the tree each frame for
@@ -779,6 +808,132 @@ emitter only when you want a specific custom burst:
 emitter to the body first — the signal hands you the node:
 `onEntered(body) { splash.position = body.position; splash.replay(); }`.)
 
+## River3D — running water
+
+`Water3D` is a *surface*; `River3D` is a *current*. A river is authored as a
+line, not a shape: give it a centerline `path` and a width, and the terrain
+underneath decides everything else.
+
+```json
+{ "name": "Creek", "type": "River3D", "props": {
+    "path": [[-80, -30], [-20, 5], [30, 10], [90, -10]],
+    "widths": [2.5, 5, 9],
+    "depth": 1,
+    "flowSpeed": 1.6,
+    "colors": { "shallow": "#79b6a4", "deep": "#103c49", "bank": "#39472f" }
+} }
+```
+
+| prop | default | meaning |
+|---|---|---|
+| `path` | `[]` | centerline `[[x, z], …]` in NODE-LOCAL meters, Catmull-Rom smoothed (2+ points) |
+| `width` | `6` | channel width in meters |
+| `widths` | `[]` | width profile lerped source→mouth (e.g. `[2.5, 5, 9]`); empty = constant `width` |
+| `depth` | `0.8` | water column at the centerline — also the scale foam thresholds read as "shallow" |
+| `flowSpeed` | `1.6` | reference current in m/s (the mean; reaches speed up and slow down) |
+| `colors` | `{}` | `{ shallow, deep, sky, horizon, bank }` — the body ramp plus what the surface mirrors |
+| `absorption` | `0.5` | how fast the water hides its bed (Beer's law) |
+| `opacity` | `0.85` | upper bound on the body's opacity |
+| `foam` | `1` | whitewater dial — 0 = a glassy canal, 2 = raging |
+| `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:
+
+- a surface that follows the bed's DESCENDING envelope — water pours over a lip
+  and never climbs one (a rising bed dams it into a still pool);
+- **the visible width**: every vertex carries its own water column
+  (`surfaceY − bed`) and the shader stops drawing where that runs out, so
+  banks, gravel bars and half-drowned boulders cut the ribbon;
+- **the current**: continuity (a pinched channel runs faster) × grade (a chute
+  runs faster), which is what puts rapids where a real river has them;
+- **whitewater**: grade × speed makes rapids, the bank shear line makes edge
+  froth, a thinning column riffles over rock. Foam then rides downstream.
+
+It costs NO extra render passes (unlike fancy `Water3D`), so a map can carry a
+dozen rivers.
+
+### Cut the bed first
+
+Water needs somewhere to be. Give the same path to the terrain as a `channels`
+carve, or the creek will lie on top of the ground as a thin film and read as
+riffle everywhere:
+
+```ts
+const path = traceDownhillPath(terrain.heightAt, { x: peakX, z: peakZ, step: 7 });
+// terrain prop — the trench (collider + heightAt + drape all see it)
+"channels": [{ "path": path, "width": 7, "depth": 2.2, "taper": 9 }]
+// river prop — the water in it
+"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
+import { traceDownhillPath } from 'incanto/3d';
+const path = traceDownhillPath((x, z) => terrain.heightAt(x, z), {
+  x: sourceX, z: sourceZ,   // start high
+  step: 7,                  // meters per step (also the gradient probe radius)
+  bounds: 100,              // stay inside ±100 m
+  maxPoints: 46,
+});
+```
+
+Steepest descent with momentum and a thalweg snap, so the line follows the
+valley floor instead of rattling between its walls. It ends in a pool, at the
+map edge or at `maxPoints`; `[]` means the start was flat.
+
+### The current is gameplay
+
+`flowForce` drags bodies toward the water's own velocity — drag, never thrust,
+so a raft accelerates until it matches the current and then coasts, and a
+character can fight across a slow ford but loses ground in a fast one. For
+scripts, `sampleAt(x, z)` (WORLD coords) answers where a point sits:
+
+```ts
+const hit = creek.sampleAt(player.position[0], player.position[2]);
+if (hit?.inside && hit.speed > 3) hud.warn('too fast to ford here');
+// hit: { inside, across (±1 = banks), along, surfaceY, dirX, dirZ, speed, halfWidth }
+```
+
+The course is derived on the CPU in `update()`, so `sampleAt` works headlessly
+(servers, `bun verify.ts`) before anything has ever been rendered.
+
 ## Determinism, verified
 
 `--seed` makes every run reproducible — keep the seed in your scene comments

package/skills/incanto-node-reference.md

@@ -670,6 +670,34 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
+## `River3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `path` | `[]` | array |
+| `width` | `6` | number |
+| `widths` | `[]` | array |
+| `depth` | `0.8` | number |
+| `flowSpeed` | `1.6` | number |
+| `colors` | `{}` | object |
+| `absorption` | `0.5` | number |
+| `opacity` | `0.85` | number |
+| `foam` | `1` | number |
+| `ripples` | `1` | number |
+| `sunDirection` | `[0.5,0.8,0.3]` | array |
+| `sunColor` | `"#fff6e0"` | string |
+| `sunIntensity` | `1` | number |
+| `terrain` | `""` | string |
+| `flowForce` | `1` | number |
+| `spray` | `1` | number |
+
 ## `Sprite2D` — `incanto/2d`
 
 | Prop | Default | Kind |
@@ -764,6 +792,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `layers` | `[]` | array |
 | `textureBase` | `"https://agent8-games.verse8.io/assets/3D/default/textures/terrain"` | string |
 | `basins` | `[]` | array |
+| `channels` | `[]` | array |
 | `wetline` | `null` | null |
 
 ## `TileMap2D` — `incanto/2d`
@@ -944,6 +973,8 @@ Signals: `blocksChanged`
 | `colors` | `{}` | object |
 | `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.19.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.19.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.19.0",
+    "incanto": "^0.21.0",
     "three": "^0.184.0"
   },
   "devDependencies": {