incanto 0.25.3 → 0.26.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-D4_I76v2.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.3",
+  "version": "0.26.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"
         }
@@ -6691,6 +6694,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

@@ -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

package/skills/incanto-gameplay-behaviors.md

@@ -471,8 +471,8 @@ all a raft, a buoy, a crate or a body needs to bob, settle and ride the swell.
 | Prop | Default | Meaning |
 |---|---|---|
 | `water` | `""` | Water3D node path; empty = the first Water3D in the tree (a wrong path fails hard) |
-| `draft` | `0.35` | how deep the hull sits at rest, in meters (its waterline below the body origin) |
-| `stiffness` | `14` | float stiffness (1/s²) — higher snaps to the surface, lower wallows |
+| `draft` | `0.35` | where the resting WATERLINE sits below the body origin, in meters — the hull floats with its origin that far above the water |
+| `stiffness` | `3` | how stiffly it returns to that waterline (extra g of lift per draft of submersion): 1 wallows, 3 is a firm dinghy, 8 is a cork |
 | `damping` | `3.5` | vertical damping (1/s) — how fast the bobbing settles |
 | `drift` | `0.6` | how hard wave SLOPES carry the body along (0 = bob on the spot) |
 | `drag` | `0.9` | horizontal drag while submerged (1/s) |
@@ -492,6 +492,22 @@ thing slides down it, so a raft left alone wanders with the swell instead of
 bobbing on the spot. The lift is capped at a few g — water pushes back, it
 never launches a body that has been dragged deep.
 
+**The lift cancels gravity AT the waterline**, so the hull holds that line
+instead of sinking until a spring happens to match its weight. That is what
+`draft` buys you: set it to the freeboard you want and the boat sits there.
+
+**Model the hull BELOW the floor.** A boat whose lowest surface is its interior
+floor cannot float dry — the sea closes over that floor and renders inside the
+hull. Give it something to displace with (a keel/hull box under the floor) and
+a `draft` that puts the waterline on it:
+
+```json
+{ "name": "Hull", "type": "MeshInstance3D",
+  "props": { "mesh": "box", "size": [3, 0.34, 1.06], "position": [0, -0.24, 0] } }
+// …with the body origin at the interior floor and "draft": 0.2 — the water
+// then rests 20 cm below the floor, on the hull, and the boat is dry inside.
+```
+
 For the water's own height anywhere (jetties, spawn heights, an AI deciding
 where the shore is), `Water3D.heightAt(x, z)` answers the same surface.
 

package/skills/incanto-node-reference.md

@@ -996,6 +996,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
@@ -1008,7 +1022,7 @@ wire their signals through scene `connections`. Full guide: `incanto-gameplay-be
 |---|---|---|
 | `water` | `""` | string |
 | `draft` | `0.35` | number |
-| `stiffness` | `14` | number |
+| `stiffness` | `3` | number |
 | `damping` | `3.5` | number |
 | `drift` | `0.6` | number |
 | `drag` | `0.9` | 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.25.3",
+    "incanto": "^0.26.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.3",
+    "incanto": "^0.26.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.3",
+    "incanto": "^0.26.0",
     "three": "^0.184.0"
   },
   "devDependencies": {