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

package/skills/incanto-environment.md

@@ -766,6 +766,28 @@ plane and samples it per fragment, so those things appear in the water:
 - Geometry below the waterline is clipped out of the mirror pass, and the whole
   pass is skipped while the camera is submerged.
 
+### Under the surface
+
+Swimming down is a different optical world, and the engine renders it as one:
+
+- **Light shafts** hang in the water column toward the sun — `underwater.rays`
+  (`true` by default, a number sets the strength, `false` turns them off). The
+  composite marches each view ray and, at every step, walks UP the sun direction
+  to the surface: the pattern sampled there is what that beam carries down, so
+  shafts converge with depth and shimmer with the same surface that makes the
+  caustics. They need DEPTH to read — a knee-deep pool has no column to light.
+- **Caustics** light what those beams land on (`underwater.caustics`).
+- **Snell's window**: light can only leave into the air inside a ~48.6° cone,
+  so from below the surface is a bright disc of sky ringed by a mirror of the
+  water you are in. That image is what everyone recognises as "underwater", and
+  the surface shader draws it whenever the camera eye is submerged.
+
+```json
+{ "type": "Water3D", "props": { "preset": "ocean",
+    "underwater": { "visibility": 26, "rays": 0.8,
+                    "caustics": { "intensity": 0.6 } } } }
+```
+
 ### Character interaction — `entered(body)` / `exited(body)`
 
 With `interaction: true` the water scans the tree each frame for

package/skills/incanto-gameplay-behaviors.md

@@ -1,6 +1,6 @@
 ---
 name: incanto-gameplay-behaviors
-description: The batteries-included game-logic library (incanto/gameplay) — ready-made Behaviors you wire from scene JSON with ZERO custom code. State & interaction: Health (hit points, i-frames, regen), Lifetime (self-destruct), ScoreKeeper (score/lives/win-lose hub), Pickup (collectibles), Collector (collect-N tally), DamageOnContact (projectiles/hazards), Interactable (press-to-use doors/levers/NPCs). Movement, AI, camera, spawning & juice: FollowCamera (camera tracks a target), Patrol (waypoint paths), Chase (homing enemy AI), Wander (seeded roaming), ZombieAI (wander-then-charge monster AI with proximity aggro), MoveTo (eased position tween), Oscillate (sine float/spin/pulse), Spawner (interval spawning), WaveSpawner (sequenced enemy waves), Projectile (straight-line motion). Use when a game needs health, score, pickups, damage, timers, interaction, enemy movement/AI, camera-follow, tweens, or spawning — BEFORE hand-rolling them as custom behaviors.
+description: The batteries-included game-logic library (incanto/gameplay) — ready-made Behaviors you wire from scene JSON with ZERO custom code. State & interaction: Health (hit points, i-frames, regen), Lifetime (self-destruct), ScoreKeeper (score/lives/win-lose hub), Pickup (collectibles), Collector (collect-N tally), DamageOnContact (projectiles/hazards), Interactable (press-to-use doors/levers/NPCs). Movement, AI, camera, spawning & juice: FollowCamera (camera tracks a target), Patrol (waypoint paths), Chase (homing enemy AI), Wander (seeded roaming), ZombieAI (wander-then-charge monster AI with proximity aggro), MoveTo (eased position tween), Oscillate (sine float/spin/pulse), Spawner (interval spawning), WaveSpawner (sequenced enemy waves), Projectile (straight-line motion), Buoyancy (float/bob/ride the swell on a Water3D). Use when a game needs health, score, pickups, damage, timers, interaction, enemy movement/AI, camera-follow, tweens, spawning, rafts/boats/floating objects — BEFORE hand-rolling them as custom behaviors.
 ---
 
 # Gameplay behaviors — the built-in logic library
@@ -460,6 +460,41 @@ pickups, spinning/pulsing coins. Drives one `axis` of `position`, `rotation`
   "script": { "name": "Oscillate", "props": { "axis": "z", "amplitude": 180, "frequency": 0.5, "mode": "rotation" } } }
 ```
 
+## Buoyancy
+
+Float on water. Hangs on a `RigidBody3D` and asks the water how high it is at
+each of the hull's sample points — the CPU twin of the surface the player is
+actually looking at, waves included — then pushes up by how deep each point
+sits, damped by how fast it is already rising. Archimedes plus drag, which is
+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 |
+| `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) |
+| `samples` | `4` | 1 = a buoy, 4 = a hull that reads the wave under it |
+| `size` | `[1, 1]` | hull footprint [x, z] in meters — where those samples sit |
+
+Signals: `submerged(node)` / `surfaced(node)` as it crosses the waterline —
+wire them to a splash `Particles3D`, a sound, or a "you dropped the cargo" rule.
+
+```json
+{ "name": "Raft", "type": "RigidBody3D", "props": { "mass": 120 },
+  "script": { "name": "Buoyancy", "props": { "draft": 0.25, "size": [2.4, 1.4], "drift": 0.8 } } }
+```
+
+`drift` is the part players notice: a wave face is a slope, and a floating
+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.
+
+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.
+
 ## Spawner
 
 Drip-feed clones of a TEMPLATE into the scene on a timer — enemy generators,

package/skills/incanto-node-reference.md

@@ -1001,6 +1001,21 @@ Ready-made `Behavior`s auto-registered by `createGame2D`/`createGame3D` (opt out
 with `gameplay: false`). Attach via `"script": {"name": "...", "props": {...}}` and
 wire their signals through scene `connections`. Full guide: `incanto-gameplay-behaviors.md`.
 
+### `Buoyancy`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `water` | `""` | string |
+| `draft` | `0.35` | number |
+| `stiffness` | `14` | number |
+| `damping` | `3.5` | number |
+| `drift` | `0.6` | number |
+| `drag` | `0.9` | number |
+| `samples` | `4` | number |
+| `size` | `[1,1]` | array |
+
+Signals: `submerged` · `surfaced`
+
 ### `CameraShake`
 
 | Prop | Default | Kind |

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