incanto 0.26.0 → 0.28.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-D4_I76v2.js"></script>
+    <script type="module" crossorigin src="./assets/index-D6RQgROR.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.26.0",
+  "version": "0.28.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -2379,6 +2379,10 @@
             "drape": {
               "default": null
             },
+            "avoidWater": {
+              "type": "boolean",
+              "default": true
+            },
             "terrain": {
               "type": "string",
               "default": ""
@@ -2566,6 +2570,10 @@
             "drape": {
               "default": null
             },
+            "avoidWater": {
+              "type": "boolean",
+              "default": true
+            },
             "terrain": {
               "type": "string",
               "default": ""
@@ -4735,6 +4743,10 @@
               "type": "string",
               "default": ""
             },
+            "carve": {
+              "type": "boolean",
+              "default": true
+            },
             "flowForce": {
               "type": "number",
               "default": 1

package/skills/incanto-environment.md

@@ -359,6 +359,7 @@ tops radially away with a smooth falloff as a character wades through.
 | `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` | `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) |
+| `avoidWater` | `true` | blades keep OUT of the water — any instance whose ground sits under a `Water3D` or `River3D` surface is dropped, so a creek that cuts its bed through a meadow gets banks instead of blades waving in the current. `false` plants reeds and paddy fields |
 | `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 just works.** Since 0.14 draping is on by default: with a
@@ -415,6 +416,7 @@ billboard confetti. Deterministic from the `seed` PROP.
 | `clustering` | `0.6` | 0 uniform … 1 tight Voronoi patches (load-time check) |
 | `sway` | `0.5` | head-bob wind strength; 0 disables |
 | `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 |
+| `avoidWater` | `true` | plants keep OUT of the water (see the Foliage3D note) — `false` for lilies and marsh planting |
 | `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 
 ## Tree3D
@@ -545,7 +547,7 @@ is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
 | `size` | `[200, 200]` | [width, depth] meters, centered on the node |
 | `maxHeight` | `28` | height SCALE — realized heights land at ~3.5–8× this (the ported pipeline sums positive noise octaves); read real numbers off `heightAt` |
 | `seed` | `1` | integer seed — deterministic terrain |
-| `resolution` | `128` | grid segments per side (2–128, load-time check) |
+| `resolution` | `128` | grid segments per side (2–256, load-time check). 128 ≈ 2 m cells on a 260 m map; raise to 256 when the map carries something finer, e.g. a creek bed |
 | `theme` | `"island"` | see table — `custom` requires `layers` |
 | `roughness` | `0.5` | detail-octave persistence (higher = more rugged) |
 | `detail` | `4` | detail octave count |
@@ -975,6 +977,7 @@ underneath decides everything else.
 | `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) |
+| `carve` | `true` | cut the bed. The river trenches its own channel into the terrain it drapes on — see below |
 | `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) |
@@ -990,24 +993,85 @@ underneath decides everything else.
   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.
+- **a dry bank**: `Foliage3D` and `Flowers3D` refuse to plant where a river
+  runs (`avoidWater`, on by default), so a creek cutting its bed through a
+  meadow gets bare wet ground at the edge instead of blades waving in the
+  current;
+- **what stands in the water**: drop boulders in the channel and the current
+  answers them — a cushion of white piled on the upstream face, a torn wake
+  opening downstream, and the surface sheen bending around the stone. Nothing
+  is wired: the node scans the tree for `MeshInstance3D` and `InstancedMesh3D`
+  footprints (a rock scatter is one node with fifty stones in it), keeps the
+  ones whose body actually intersects the water column — a footbridge deck
+  three metres up is not a boulder — and writes the eight nearest the camera
+  each frame, ramped in by distance so nothing pops. A drowned stone still
+  bends the flow; only one standing proud tears it white.
 
 It costs NO extra render passes (unlike fancy `Water3D`), so a map can carry a
 dozen rivers.
 
-### Cut the bed first
+### The bed digs itself, and the water can never hang in the air
 
-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:
+Two promises hold a river to the ground, and both are automatic:
+
+**1. It carves its own bed** (`carve`, on by default). Real water erodes a
+channel; a ribbon laid on raw ground has nothing holding it and reads as a
+strip of blue hovering over the grass. So the node cuts one — a trench per
+reach, as wide as the creek is there, with banks that stand above the water.
+`heightAt`, the heightfield collider, the splat and draped vegetation all see
+it, because it IS the terrain. The floor it cuts only ever FALLS: where the
+path crosses a rise the bed digs through it (up to 7 water columns deep) so the
+water keeps running instead of burying itself.
+
+```json
+{ "name": "Creek", "type": "River3D", "props": {
+    "path": [[-80, -30], [-20, 5], [30, 10], [90, -10]],
+    "widths": [2.4, 4.5, 7, 9], "depth": 1 } }
+```
+
+That is the whole scene. No `channels` on the terrain, no bank meshes.
+
+**2. Its surface is FITTED to the ground it finds.** Each station reads its own
+cross-section: the water stands no higher than the lowest rim holding it, ends
+where the ground comes up to meet it (so the ribbon is asymmetric on a sloping
+reach — a near bank and a far one), and where a bank has fallen away entirely
+the ribbon lies DOWN on the slope as a film instead of hanging off it. Authored
+width is how much water there is; the ground decides where it goes.
+
+Carve it yourself with `Terrain3D.channels` when you want a bed the river does
+not own — a stone aqueduct, a canal with masonry sides, a dry wash that only
+floods in a cutscene — and set `"carve": false`.
+
+**Terrain resolution is the one thing that can defeat this.** A trench thinner
+than a grid cell smooths away to nothing. 128 segments on a 260 m map is ~2 m
+per cell, so a 2.4 m headwater creek needs `"resolution": 256` (~1 m cells) on
+the Terrain3D. The node widens its cut to survive the grid rather than cutting
+nothing, so a too-coarse terrain shows up as a creek in a bed wider than it
+should be.
 
 ```ts
+// the classic setup: let the terrain choose the line, then pour water on it
 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
 ```
 
+**Placing things against a self-carved bed?** Ask the engine what the cut will
+be — never mirror it by hand. `riverCarveChannels` is the same function the node
+runs at load, so a generator that assigns its result to a scratch Terrain3D gets
+the EXACT ground the game will have; a hand-rolled approximation puts the player
+inside a hill.
+
+```ts
+const carved = new Terrain3D('probe');
+Object.assign(carved, terrainProps);
+carved.channels = riverCarveChannels({
+  path, widths, depth,
+  cell: size / resolution,   // the terrain's own grid
+  groundAt: (x, z) => rawTerrain.heightAt(x, z),
+});
+const groundAt = (x: number, z: number) => carved.heightAt(x, z); // place against THIS
+```
+
+
 ### Waterfalls happen — you do not author them
 
 Nothing in a scene says "waterfall". Where the ground gives way the surface

package/skills/incanto-node-reference.md

@@ -331,6 +331,7 @@ Signals: `movementStateChanged(state)`
 | `clustering` | `0.6` | number |
 | `sway` | `0.5` | number |
 | `drape` | `null` | null |
+| `avoidWater` | `true` | boolean |
 | `terrain` | `""` | string |
 
 ## `Foliage3D` — `incanto/3d`
@@ -363,6 +364,7 @@ Signals: `movementStateChanged(state)`
 | `flowers` | `0` | number |
 | `seed` | `1` | number |
 | `drape` | `null` | null |
+| `avoidWater` | `true` | boolean |
 | `terrain` | `""` | string |
 
 ## `HudLayer` — `incanto`
@@ -695,6 +697,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `sunColor` | `"#fff6e0"` | string |
 | `sunIntensity` | `1` | number |
 | `terrain` | `""` | string |
+| `carve` | `true` | boolean |
 | `flowForce` | `1` | number |
 | `spray` | `1` | number |
 

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