incanto 0.25.4 → 0.27.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-BGtXxzJn.js"></script>
+    <script type="module" crossorigin src="./assets/index-BrneVqN0.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.25.4",
+  "version": "0.27.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -331,6 +331,9 @@
         {
           "$ref": "#/$defs/Water3D"
         },
+        {
+          "$ref": "#/$defs/WaterCutout3D"
+        },
         {
           "$ref": "#/$defs/_instance"
         }
@@ -4732,6 +4735,10 @@
               "type": "string",
               "default": ""
             },
+            "carve": {
+              "type": "boolean",
+              "default": true
+            },
             "flowForce": {
               "type": "number",
               "default": 1
@@ -6691,6 +6698,114 @@
         }
       },
       "required": ["name", "type"]
+    },
+    "WaterCutout3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "WaterCutout3D"
+        },
+        "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"
+            },
+            "size": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [2, 1, 1]
+            },
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            }
+          },
+          "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"]
     }
   }
 }

package/skills/incanto-environment.md

@@ -545,7 +545,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 |
@@ -789,6 +789,44 @@ Swimming down is a different optical world, and the engine renders it as one:
                     "caustics": { "intensity": 0.6 } } } }
 ```
 
+### `WaterCutout3D` — the thing that holds the water back
+
+Water is ONE surface; it has no idea a boat has an inside. Float an open hull
+and every crest that rises above its floor renders as sea sloshing through the
+deck. Freeboard cannot promise otherwise — a big enough swell always wins for a
+frame. So name the geometry that keeps the water out:
+
+```json
+{ "name": "Rowboat", "type": "RigidBody3D",
+  "script": { "name": "Buoyancy", "props": { "draft": 0.2 } },
+  "children": [
+    { "name": "DryInside", "type": "WaterCutout3D",
+      "props": { "size": [2.55, 1.2, 0.95], "position": [-0.1, 0.4, 0] } },
+    … hull, seats, oars …
+  ] }
+```
+
+It MUST be a CHILD of what it belongs to — a hull, a diving bell, a well under a
+dock, a cave mouth. That parent is the mechanism, not a convenience: the water
+re-draws it (the part inside the box) into the depth pre-pass at the near plane,
+and then hides itself behind it exactly as it hides behind any solid thing. At
+the scene root a cutout has nothing to stand in for, and the loader says so.
+
+| prop | default | meaning |
+|---|---|---|
+| `size` | `[2, 1, 1]` | box extent in meters, centered on the node — which PART of the parent holds water back |
+| `enabled` | `true` | live toggle — a scuttled hull can start letting the sea in |
+
+**A cutout cannot punch a hole in open water**, because nothing is ever cut out
+of the water. The mask is the parent's own silhouette, so water can only be
+hidden behind geometry the player is already looking at. Overshoot the box and
+more of that hull holds water back; undershoot and water stands in the bow. Size
+it to the interior and err large.
+
+Needs the depth pre-pass, so `"quality": "fancy"` (the default). Four cutouts per
+water surface; each costs one extra draw of its parent in that pass. Skinned and
+instanced meshes re-draw at their rest pose — hang cutouts on ordinary geometry.
+
 ### Where water meets ground
 
 The waterline is the thing that gives game water away. Incanto fades it in
@@ -937,6 +975,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) |
@@ -952,24 +991,64 @@ 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.
+- **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
+
+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.
 
-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:
+**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
 ```
 
+
 ### 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

@@ -695,6 +695,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `sunColor` | `"#fff6e0"` | string |
 | `sunIntensity` | `1` | number |
 | `terrain` | `""` | string |
+| `carve` | `true` | boolean |
 | `flowForce` | `1` | number |
 | `spray` | `1` | number |
 
@@ -996,6 +997,20 @@ Signals: `blocksChanged`
 
 Signals: `entered(body)` · `exited(body)`
 
+## `WaterCutout3D` — `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` |
+| `size` | `[2,1,1]` | array |
+| `enabled` | `true` | boolean |
+
 ## Gameplay behaviors — `incanto/gameplay`
 
 Ready-made `Behavior`s auto-registered by `createGame2D`/`createGame3D` (opt out

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