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

package/schemas/scene.schema.json

@@ -6583,6 +6583,10 @@
               "type": "boolean",
               "default": false
             },
+            "mirrorInterval": {
+              "type": "number",
+              "default": 33
+            },
             "swellSteepness": {
               "type": "number",
               "default": 0.35

package/skills/incanto-environment.md

@@ -699,6 +699,7 @@ hue reads grey.
 | `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 |
+| `mirrorInterval` | `33` | ms between planar-mirror re-renders. A reflection seen through a rippling surface does not need 60 Hz; 33 halves the pass's cost. 0 = every 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`) |
@@ -788,6 +789,51 @@ Swimming down is a different optical world, and the engine renders it as one:
                     "caustics": { "intensity": 0.6 } } } }
 ```
 
+### What water COSTS, and every dial that lowers it
+
+Fancy water is not one draw — it is extra SCENE RENDERS, and each one
+re-submits the world. Measured on the lake template (1600×900, one Water3D
+with grass, trees and a mirror):
+
+| pass | when | size | scene submissions |
+|---|---|---|---|
+| refraction/depth grab | `quality: 'fancy'` | ½ buffer, ≤1024 | 2 (colour + depth completion) |
+| planar mirror | `mirror: true` | ⅓ buffer, ≤640 | 1, throttled by `mirrorInterval` |
+| cube reflection | `reflection: true` | 256² × 6 faces | 6, every `reflectionInterval` ms (≥2 s while `mirror` is on — it is only the off-screen fallback then) |
+| the surface itself | always | — | a ~1.5 quads/m grid, capped 160² |
+
+Grass, flowers, particles and trails are dropped from the side passes: they are
+most of a meadow's triangles and none of what anyone reads in a reflection or a
+depth mask.
+
+**The dials, cheapest first.** Each is a normal prop, so a scene can trade look
+for frames per water body:
+
+| dial | effect |
+|---|---|
+| `quality: 'simple'` | ZERO extra passes — sine waves, fresnel sky tint, edge fade. The low-end/mobile answer |
+| `mirror: false` | −1 scene render (the default) |
+| `mirrorInterval` | ms between mirror re-renders (default 33 ≈ 30 Hz — halves the pass; 100 is still convincing on rippled water) |
+| `reflection: false` | −6 cube faces; the surface falls back to its colour ramp |
+| `reflectionInterval` | ms between cube refreshes (default 1000) |
+| `refraction: false` | the grab colour is ignored (depth still drives absorption/foam) |
+| `foam: false` | drops the shoreline foam work |
+| `interaction: false` | stops the per-frame body scan |
+
+Two more, outside water: `createGame3D({ pixelRatio: 1.5 })` — a retina display
+renders **4× the pixels**, and water is fragment-heavy, so capping the ratio is
+usually the single biggest win on a Mac; and `environment.bloom`, which adds a
+full-resolution HDR pass of its own.
+
+If a scene feels heavy, measure before guessing — the browser console has the
+whole story:
+
+```js
+const gl = game.renderer.webgl;
+gl.info.autoReset = false; gl.info.reset();
+requestAnimationFrame(() => console.log(gl.info.render)); // calls + triangles for ONE frame
+```
+
 ### Character interaction — `entered(body)` / `exited(body)`
 
 With `interaction: true` the water scans the tree each frame for

package/skills/incanto-node-reference.md

@@ -974,6 +974,7 @@ Signals: `blocksChanged`
 | `reflection` | `true` | boolean |
 | `reflectionInterval` | `1000` | number |
 | `mirror` | `false` | boolean |
+| `mirrorInterval` | `33` | number |
 | `swellSteepness` | `0.35` | number |
 | `foam` | `true` | boolean |
 | `interaction` | `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.22.0",
+    "incanto": "^0.23.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.22.0",
+    "incanto": "^0.23.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.22.0",
+    "incanto": "^0.23.0",
     "three": "^0.184.0"
   },
   "devDependencies": {