incanto 0.1.0

package/skills/incanto-environment.md

@@ -0,0 +1,743 @@
+---
+name: incanto-environment
+description: Generating game environments in Incanto — the deterministic `incanto-env` CLI and `incanto/env` library. EXACTLY three themed 3D generators (arena with boxes/ruins/garden, Terrain3D heightfield worlds with island/alpine/plains/desert/meadow/forest/savanna/snow/wetland/volcanic themes, maze with stone/hedge/canyon) plus 2D mazes, roguelike dungeons and platform courses; insertIntoScene, the GENERATORS catalog + runGenerator; and the environment nodes — Terrain3D (biome texture splatting, heightAt, heightfield collider), shader-water Water3D (FBM waves, anisotropic wind ripple, sparse sun glints, crystal shallows, refraction + depth absorption, reflections, shoreline foam, splash signals + ripples), shader-grass Foliage3D (real curved blade meshes, clumps, rolling wind, distance LOD, character bend), Flowers3D flower plants (lush/sparse/none density dial, daisy/cosmos/bellflower varieties, Voronoi patches, head-bob sway) and ez-tree Tree3D groves (branchy trunks, textured wind-swayed leaves, budget-checked tiers). Use when a game needs a level, stage, arena, terrain, heightfield, island, meadow, grass field, flowers, flower bed, forest, trees, mountain, desert, savanna, snow, tundra, swamp, wetland, marsh, volcano, lava field, maze, dungeon, platform course, scattered props, clouds, water, or a splash effect.
+---
+
+# Environment generation — levels from a seed
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Generators are PURE and DETERMINISTIC: all randomness flows through a seeded
+`Rng`, so the same `--seed` always emits byte-identical JSON. A generated
+level is reproducible from its seed alone — keep the seed in your scene
+notes/PROJECT docs, and change it (not the output) to reroll a layout.
+
+## CLI
+
+```bash
+bunx incanto-env --list                                           # every generator + params
+bunx incanto-env arena --seed 42 --theme ruins                    # print the NodeJson
+bunx incanto-env terrain --seed 42 --theme island --json
+bunx incanto-env terrain --seed 42 --theme meadow --size 120
+bunx incanto-env maze --seed 7 --theme hedge --width 10 --depth 10
+
+# Insert straight into a scene file (validates with incanto-check afterwards):
+bunx incanto-env terrain --seed 42 --theme forest --into src/game.scene.json --at Root/Level
+```
+
+- `--seed` is REQUIRED — determinism is the contract.
+- Subcommands and `--<param>` flags come from the `GENERATORS` metadata
+  (camelCase params become kebab-case flags: `wallHeight` → `--wall-height`;
+  boolean params are bare flags: `--water`). `--list` prints the full table.
+- Without `--into` the pretty-printed NodeJson goes to stdout (`--json`
+  silences the stderr summary for piping).
+- `--into <file>` reads the scene, appends the generated node under `--at`
+  (default: the scene root) and writes the file back pretty-printed.
+- `--at` is the '/'-joined chain of node NAMES from the root, root included:
+  `Root/Level` targets the root's child `Level`. A missing path is a hard
+  `NODE_NOT_FOUND` listing the children that DO exist.
+- `scatter` is library-only — its item templates don't fit CLI flags.
+- The scene editor (`bunx incanto-editor`) drives the same catalog visually:
+  the ✦ Generate dialog builds its param form from `GENERATORS` and inserts
+  under the selected node as one undoable step (see the incanto-editor skill).
+
+## The catalog: 3 themed 3D generators + 3 2D generators
+
+The 3D set is EXACTLY `arena`, `terrain`, `maze` — the `theme` param does
+the heavy lifting (one knob, big payoff). Every generator: same skeleton,
+themed palette/dressing, deterministic child names, sun/fill lighting.
+
+| generator | theme | what you get |
+|---|---|---|
+| `terrain` | `island` (default) | Terrain3D island splat (beach→grass→cliff→snow), edge-wrapped rim, a `Sea` Water3D at a COMPUTED drownable level, conifers on the grass band, a `Clouds` group |
+| `terrain` | `alpine` | rugged alpine splat (meadow valleys, stone, snow from 0.55), conifer treeline at mid heights, boulders in the snow band |
+| `terrain` | `plains` | rolling plains splat (grass + dirt patches), scattered broadleaf trees + boulders |
+| `terrain` | `desert` | dune splat (sand, gravel pans, stone mesas), dead trees + boulders |
+| `terrain` | `meadow` (잔디밭) | LOW grassland splat (ez-tree ground set, noise dirt patches), dense `Foliage3D` TUFT carpets + sparse `Flowers3D` beds at flat spots, broadleaf groves, boulders, a HIGH HOT sun (sunlit-meadow stage) |
+| `terrain` | `forest` | LAYERED woodland on a litter splat (ez-tree dark soil + noise moss patches): ~480 trees in 40 region-mixed groves (low-freq noise picks pine- vs broadleaf-dominant patches) + high-tier ELDERS, aspen/birch accent clumps and sapling fringes; bush undergrowth + FERN tuft beds near trunks; fallen logs (tipped dead trunks) near elders, stumps, mossy boulders; a meadow-treated central clearing (bright tuft carpets + sparse `Flowers3D`) |
+| `terrain` | `savanna` | dry GOLDEN plains on a dry-grass splat (grass + sand pans + dirt patches): sparse wide-LOW-canopy acacias (broadleaf, gold-green tint, 3.5–5 m), cured gold tuft carpets, dry-scrub bush clumps, scattered boulders; warm hazy low sun (exposure 1.05), no water |
+| `terrain` | `snow` | snow-dominant TUNDRA splat (snow at every height, rock on steep) — distinct from alpine's banded peaks: sparse cool-DARK conifers (snow-dusted tint), snow-dusted boulders, a LOW pale crisp sun (exposure 0.9), light fog, no water |
+| `terrain` | `wetland` | SWAMP on a mossy-grass + dark-mud splat near a HIGH water table: a STRUCTURAL broad `Swamp` Water3D (always shipped — `quality: 'simple'`, murky green, not the blue fancy sea), lush `Foliage3D` REED beds at the waterline, mossy ground tufts, dead snags + bush undergrowth, mossy boulders; soft overcast green-grey haze |
+| `terrain` | `volcanic` | dark basalt/ash splat (stone + gravel ash beds): bare DEAD snags, dark basalt boulders, 3 `Particles3D` smoke + ember vent pairs; ember-warm low sun + DENSE dark fog (the smoky read rides the fog + ember light — the atmosphere sky stays blue up high, see LEARNINGS), no water |
+| `arena` | `boxes` (default) | the classic FPS stage: floor, 4 walls, colorful random crate obstacles |
+| `arena` | `ruins` | stone palette, obstacles become broken colonnade rows (standing columns + toppled stumps) |
+| `arena` | `garden` | hedge-green walls/blocks, `Foliage3D` grass patches, lush `Flowers3D` beds, a calm `Water3D` pool at the center |
+| `maze` | `stone` (default) | brick-textured walls (`wall/blocks` color + normal maps) with coping caps, stone floor, west entrance → east exit |
+| `maze` | `hedge` | foliage-look walls (grass map) with trimmed `Foliage3D` grass strips along the wall tops, lawn floor, corridor grass patches |
+| `maze` | `canyon` | warm sandstone walls, sand floor, boulders perched on the wall rim |
+
+**`terrain`** (3D heightfield world): emits the canonical physics recipe —
+a `Ground` `StaticBody3D` with `collider: {shape: 'heightfield'}` and a
+`Surface` `Terrain3D` child — plus the theme dressing above, ALL placed by
+probing the exact heightmap the node rebuilds at runtime (`heightAt` for
+tree/rock/grass ground contact, slope + height-band rejection so trees skip
+sand/snow/steep cells). Options: `theme`, `size` (200 m square), `maxHeight`
+(0 = theme default: island 4.5, alpine 8, plains 4, desert 5, meadow 1.2,
+forest 2.5, savanna 3, snow 2.2, wetland 1.4, volcanic 4), `water` (adds a
+low valley `Lake` to non-island themes; the island ALWAYS ships its sea and
+the wetland ALWAYS ships its broad swamp water — see the sea-level math
+below). Islands
+auto-fit `maxHeight` DOWN when a seed realizes rim hills no drownable sea
+could cover. Live (conifer/broadleaf) trees get a per-grove SPECIES color
+drawn from the seed: conifers deep blue-green (pine/spruce/fir) with red-brown
+bark, broadleaf mid-warm-green oak/maple, lighter yellow-green aspen/birch
+(grey bark), plus a few autumnal gold/amber groves — grove-to-grove drift on
+top of Tree3D's per-instance jitter, so a forest reads varied, not one flat
+green. Same seed → byte-identical colors (deterministic); dead/bush keep their
+node defaults.
+
+**Themed atmosphere — `terrainEnvironment(theme, size?)`**: generators emit
+node trees, so the matching scene `environment` header ships as a separate
+one-liner. It composes the whole rendering stage per theme — physical `sky`
+(island: bright maritime; forest: low WARM sun raking dappled pools under a
+close green-grey haze, lifted ambient so shadowed floor stays readable; desert:
+warm dusty; alpine: crisp far fog + cooler sun + 0.92 exposure so the snow
+keeps texture; meadow/plains: pleasant mid-morning; savanna: warm hazy late
+afternoon over the gold grass; snow: low pale crisp cold-blue light + 0.9
+exposure; wetland: soft overcast green-grey humid haze + lifted ambient;
+volcanic: ember-warm low sun + DENSE dark fog + 0.86 exposure — the smoky
+mood rides the fog + ember light, NOT the sky dome, which stays Preetham-blue
+up high), size-scaled `fog`, `shadows: true`, a LOW ambient (0.18 — the sky's
+image-based ambience is the fill; the generator's `Sun` light runs at ~1.7
+against it so shadows stay visible under ACES; deep-haze themes lift it:
+forest/wetland 0.24–0.26, volcanic 0.22) and a per-theme `iblIntensity` (the
+`?scene=tree` stand's lit-FORM dial: cuts the physical-sky IBL below full so
+the hot sun carves each crown's lit-vs-shadow side instead of a flat-bright
+wash — volcanic 0.5, forest 0.55, plains 0.58, savanna/meadow 0.6–0.62,
+wetland 0.66, alpine/island/snow 0.72, desert 0.75; island stays mild so the
+deep cut never dulls its sea). Spread it into your scene:
+
+```ts
+import { runGenerator, terrainEnvironment } from 'incanto/env';
+const scene = {
+  …,
+  environment: { background: '#9bc4e2', ...terrainEnvironment('island') },
+  root: { …, children: [camera, runGenerator('terrain', { seed: 7, theme: 'island' })] },
+};
+```
+
+**`arena`** (3D FPS stage): a `StaticBody3D` floor, 4 perimeter walls and N
+obstacles — every body a box collider with a `MeshInstance3D` `Skin` child
+(the canonical visible+collidable composition) — plus `Sun`/`FillLight`/
+`Lamp` lights. Children are deterministically named (`Wall1`…`Wall4`,
+`Obstacle1`…`ObstacleN`). Options: `theme`, `width`, `depth` (meters,
+default 30), `wallHeight` (3), `obstacles` (8).
+
+**`maze`** (3D): a recursive-backtracker maze — entrance on the west edge,
+exit on the east, every cell reachable — as one-tile-thick `StaticBody3D`
+wall boxes (merged into runs) over a floor slab, with lights. Every theme
+textures its walls and floor (worldspace `repeat` tiling on the
+`MeshInstance3D` skins) and adds structure: junction `Pillar`s where runs
+meet, `Gate1`–`Gate4` posts framing the entrance/exit plus a tinted
+`EntrancePath`/`ExitPath` floor tile; 'stone' caps every run with coping
+trim, 'hedge' grows `HedgeTop` grass strips along the longest rims, 'canyon'
+keeps its rim boulders. All dressing is decorative `MeshInstance3D` — the
+COLLISION layout (walls only) is identical across themes, and the carved
+LAYOUT is identical across themes for the same seed. Options: `theme`,
+`width`/`depth` (corridor cells, default 8), `cellSize` (2 m), `wallHeight`
+(2.5 m). The boolean grid is also available in the library as
+`carveMaze(rng, cols, rows)` for pathing/item placement.
+
+**Maze mood — `mazeEnvironment(theme, span?)`**: the terrainEnvironment
+contract for mazes. Maze scenes should read MOODY at corridor level, not
+showroom-bright: every theme gets a LOW hazy sun, exposure 0.85–0.95, dim
+ambient (≤0.15) and a close fog window (scaled by `span` — pass
+`(2·width+1)·cellSize` if you changed the size, default 34). 'stone' is the
+coolest and foggiest (dungeon courtyard), 'hedge' an overcast garden,
+'canyon' a warm dusk raking the sandstone. The generator's `Sun`/`FillLight`
+are theme-graded to match — pair both halves:
+
+```ts
+import { mazeEnvironment, runGenerator } from 'incanto/env';
+const scene = {
+  …,
+  environment: { background: '#9bc4e2', ...mazeEnvironment('stone') },
+  root: { …, children: [camera, runGenerator('maze', { seed: 7, theme: 'stone' })] },
+};
+```
+
+**`maze2d`** (2D): the SAME algorithm as `ColorRect2D` floor +
+`StaticBody2D` wall tiles with `ColorRect2D` skins (px, y-down, centered).
+Options: `cols` (10), `rows` (8), `cellPx` (64).
+
+**`dungeon2d`** (2D roguelike): rectangular rooms joined by 1-tile
+L-corridors on a 32px tile grid — `ColorRect2D` floor rects (`Room1`…,
+`Corridor1H`/`1V`…) ringed by merged `StaticBody2D` wall segments with
+skins. Options: `rooms` (5), `size` (px; square number on the CLI,
+`[width, height]` via the library; default [960, 720]).
+
+**`platforms2d`** (2D course): `StaticBody2D` rect colliders with
+`ColorRect2D` skins, left to right. Spacing is caller-tunable — keep `gapX`
+and `stepY` inside your character's jump arc (px, y-DOWN: negative `stepY`
+steps UP).
+
+### Migrating from the removed generators
+
+`meadow`, `forest`, `island`, `rocks` and `clouds` left the catalog — they
+are terrain themes now (`runGenerator('meadow', …)` is a hard error that
+says so):
+
+| before | now |
+|---|---|
+| `incanto-env meadow --seed 42` | `incanto-env terrain --seed 42 --theme meadow` |
+| `incanto-env forest --seed 42` | `incanto-env terrain --seed 42 --theme forest` |
+| `incanto-env island --seed 42` | `incanto-env terrain --seed 42 --theme island` (smooth Terrain3D island, computed sea level, heightfield collider — no longer voxel) |
+| `incanto-env rocks` / `clouds` | themes scatter their own; the library still exports `generateRocks`/`generateClouds` (deprecated) for custom compositions |
+| `incanto-env terrain` (voxel) | library-only `generateVoxelTerrain` — see the voxel worlds note |
+
+The old functions stay exported from `incanto/env` (deprecated, see jsdoc)
+so library code keeps compiling.
+
+### Voxel worlds
+
+The old voxel terrain lives on as **`generateVoxelTerrain`** (library-only,
+NOT in the catalog, not deprecated): a `VoxelGrid3D` whose `voxels` prop
+carries the heightfield as `[x, y, z, tile]` tuples (value noise; grass
+top, dirt fill, bedrock base). Reach for it when BLOCKS are the point —
+digging, building, minecraft-style games on `VoxelGrid3D` (colliders are
+the game's job: chunk trimeshes near the player, see the minecraft
+template). Options: `seed`, `size` (32 blocks), `height` (8), `water`. The
+voxel `generateIsland` (radial dome falloff, sandy shore) also remains for
+the same use case.
+
+## Library
+
+```ts
+import {
+  generateArena, generateTerrain, generateMaze, generateMaze2D,
+  generateDungeon2D, generatePlatforms2D, generateScatter,
+  generateVoxelTerrain, GENERATORS, runGenerator, carveMaze, insertIntoScene,
+} from 'incanto/env';
+
+const world = generateTerrain({ seed: 42, theme: 'forest', size: 160 });
+
+// Every generator is also invokable uniformly by name — what the CLI and
+// editor use. Unknown names are a hard IncantoError listing the valid ones:
+const island = runGenerator('terrain', { seed: 7, theme: 'island' });
+
+// GENERATORS is the machine-readable catalog (description, dimension, typed
+// params with defaults/min/max/options) — render UIs and help from it. The
+// theme params carry options arrays that drive the editor dropdowns:
+console.log(GENERATORS.terrain.params.theme.options);
+// ['island','alpine','plains','desert','meadow','forest','savanna','snow','wetland','volcanic']
+
+// Scatter takes weighted node JSON templates — YOU say what to strew:
+const props = generateScatter({
+  seed: 42,
+  count: 30,
+  area: [36, 20],
+  items: [
+    { type: 'MeshInstance3D', props: { mesh: 'cylinder', size: [0.3, 2, 0.3],
+        material: { color: '#6b4a2b' } }, weight: 3 },                  // trees (3x as likely)
+    { type: 'MeshInstance3D', props: { mesh: 'sphere', size: [0.5, 0.5, 0.5],
+        material: { color: '#777777' } } },                             // rocks
+  ],
+});
+// Each instance gets a random position in `area`, y-rotation, and ±20% scale
+// jitter; the template's position[1] survives as the ground offset.
+
+// insertIntoScene is PURE — it returns a NEW scene, inputs untouched:
+let scene = JSON.parse(readFileSync('src/game.scene.json', 'utf-8'));
+scene = insertIntoScene(scene, meadow, 'Root/Level');
+scene = insertIntoScene(scene, props);          // default: under the root
+writeFileSync('src/game.scene.json', JSON.stringify(scene, null, 2));
+```
+
+Tune `generatePlatforms2D` spacing for reachability:
+
+```ts
+generatePlatforms2D({
+  seed: 3,
+  count: 14,
+  width: [80, 160],   // platform width range, px
+  gapX: [40, 120],    // edge-to-edge horizontal gap, px
+  stepY: [-80, 40],   // vertical step, px y-down — negative climbs
+  start: [0, 300],    // first platform center
+});
+```
+
+## Foliage3D
+
+An instanced vegetation field (in `incanto/3d`, registered by
+`registerNodes3D`): grass, flowers or reeds scattered over an XZ `area`.
+Placement is deterministic from the `seed` PROP (never the engine rng), so
+the same JSON grows the identical field on every machine.
+
+Four looks, picked by `style`:
+
+| style | what renders | when to pick it |
+|---|---|---|
+| `"tufts"` | ONE InstancedMesh of 3-crossed-quad CARDS (12 verts each) carrying a baked multi-blade alpha-cutout texture, per-instance clump-coherent green tints + dry patches, ported sin·cos sway — kind `grass` only | the dense 잔디밭 — the ez-tree demo's actual grass mechanism; overlapping textured fans read as a full meadow at a fraction of the instances. Layer a sparse `mesh` field on top for close-up blade silhouettes |
+| `"mesh"` (default) | ONE InstancedMesh where EVERY instance is a real tapered blade (7-vertex strip) curved along a vertex-shader quadratic bezier — kind `grass` only | real per-blade geometry — best up close; reads thin at field scale |
+| `"blades"` | TWO crossed quads per slot; the fragment shader draws 8 procedural SDF blades per quad — kind `grass` only; bends to the player (`interaction`) and receives scene `fog` (distant fields melt into the haze like the mesh grass / trees / water) | pinning the pre-mesh ported look |
+| `"simple"` | legacy crossed quads, per-instance colorA→colorB lerp, whole-field shear sway | `flowers`/`reeds` (their only look); ultra-cheap set dressing |
+
+What the **tufts** style does (the recon finding behind it: the famous
+ez-tree meadow is NOT per-blade geometry — its `grass.glb` is three crossed
+quads with one grayscale tall-grass cutout texture, instanced 5 000× with
+random green instance colors):
+
+- the card texture is **baked at runtime** (~80 tapered blade silhouettes
+  fanning from a clumped base, dark roots → bright tips) — no asset fetch,
+  headless-safe (no DOM → no texture, geometry still deterministic);
+- count is `⌊area·density/6⌋` (cards are BIG); cards stand ~2.2× `height`
+  and ride the same regional height / dry-patch / coverage noise as mesh;
+- per-tuft luminance varies ~2× (upstream-style) — that brightness
+  diversity is what carves depth into the canopy;
+- tufts skip the character bend (a card fan has no blade tops to push);
+  generators emit `style: "tufts"` for their carpets — meadow density ≈ 30.
+
+What the **mesh** style adds (all deterministic from `seed`):
+
+- **Real curved blades** — each blade bends along a quadratic bezier whose
+  tip is displaced by resting lean + wind + character bend; the root never
+  moves. Blades are fully opaque: no alpha sorting, no transparency cost.
+- **8× instances** — one blade per instance needs more instances to match
+  the SDF coverage, so mesh plants `⌊area·density·8⌋` (still capped at
+  `maxInstances`; past the cap the LOD keeps the NEAR field dense).
+- **Clumps** — a Voronoi-ish cell id from the placement position gives each
+  tuft a SHARED hue shift and lean direction, so the field grows patchy
+  like a real meadow instead of uniformly green.
+- **Regional height field** — low-frequency noise scales blade height
+  0.55–1.7× in ~6 m patches (tall meadow tufts beside short worn spots),
+  and tall blades lean/curve harder — they DROOP like real long grass.
+- **Dry-hue patches** — a second noise channel lerps blades toward a dry
+  yellow-green ramp, mixing cured-grass hues through the green.
+- **Coverage holes** — `coverage` < 1 (default 0.85) drops blades in
+  noise-carved patches so dirt breaks the carpet like a real field;
+  `coverage: 1` restores the wall-to-wall carpet (and the exact
+  `⌊area·density·8⌋` instance count).
+- **Flowers** — DEPRECATED: `flowers` (0–0.2, default 0) renders that
+  fraction of instances as cheap 5-vertex heads riding the canopy. They
+  read as confetti — use a **`Flowers3D` node** (real plants, below)
+  instead; the generators already do. The prop keeps working for existing
+  scenes.
+- **Base-to-tip ramp** — blades root in `groundColor` (soil, with DEEP
+  root occlusion — the inside of the volume reads near-black), pass through
+  `colorA` and tip out at `colorB`. **Pair `groundColor` with the ground
+  under the field** (the `MeshInstance3D` floor color or the Terrain3D
+  grass band) so roots melt into the terrain instead of floating on it.
+- **Sun sheen** — fake-cylinder normals across each blade feed a cheap
+  Blinn-Phong vs the fixed `sunDirection`; tips glint as they sway. Match
+  it to the scene's key light direction.
+- **Rolling wind** — 2-octave directional gusts (large rolling wave + slow
+  swell) plus per-blade flutter: waves visibly travel across the field.
+- **Distance LOD** — blades shrink to zero between `fadeStart`..`fadeEnd`
+  meters from the camera, and HALF the blades (instance-hash) bow out by
+  the midpoint, halving far-field work. Far blades also widen slightly so
+  the carpet stays closed instead of aliasing away.
+
+mesh + blades share the character bend: with `interaction: true` the
+nearest ≤4 moving bodies (`CharacterBody3D` / `RigidBody3D`) push blade
+tops radially away with a smooth falloff as a character wades through.
+
+```json
+{ "name": "Grass", "type": "Foliage3D",
+  "props": { "area": [30, 30], "density": 10, "seed": 7,
+             "groundColor": "#2e4a26" } }
+```
+
+| prop | default | meaning |
+|---|---|---|
+| `kind` | `"grass"` | `grass` \| `flowers` \| `reeds` — blade silhouette (load-time check) |
+| `style` | `"mesh"` | `mesh` (curved real blades) \| `tufts` (ez-tree textured cards — the dense 잔디밭) \| `blades` (SDF quads) \| `simple` (legacy quads) |
+| `tuftStyle` | `"grass"` | tufts only: `grass` (dense blade-fan bake) \| `fern` (fewer, wider, arching fronds with leaflet notches — forest undergrowth) |
+| `area` | `[20, 20]` | [x, z] extent in meters, centered on the node |
+| `density` | `12` | instances per m² (mesh plants 8× — total capped at `maxInstances`) |
+| `maxInstances` | `50000` | instance cap (hard ceiling 200000 — split bigger fields) |
+| `colorA` | `"#4d7232"` | bottom/body color (mesh/blades) / lerp start (simple) — warm sunlit meadow green |
+| `colorB` | `"#9aab55"` | tip color (mesh/blades) / lerp end (simple) |
+| `groundColor` | `"#1f3015"` | mesh: soil tint at the blade ROOT — match the ground/terrain color |
+| `sunDirection` | `[0.5, 0.8, 0.3]` | mesh: fixed sun for the specular sheen — match the key light (load-time check: non-zero [x,y,z]) |
+| `fadeStart` | `60` | mesh LOD: camera distance where blades start shrinking, meters |
+| `fadeEnd` | `90` | mesh LOD: gone by here (load-time check: > `fadeStart`) |
+| `height` | `0.25` | base blade height, meters (mesh scales it 0.55–1.7× regionally) |
+| `sway` | `0.6` | wind strength; 0 disables wind entirely |
+| `interaction` | `true` | mesh/blades styles: moving bodies bend nearby grass |
+| `coverage` | `0.85` | mesh: carpet fill in (0, 1] — below 1 noise carves dirt patches (load-time check) |
+| `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` | `false` | **drape each blade onto a Terrain3D's surface** so a field follows rolling ground instead of floating on a flat plane — one big field covers a whole terrain |
+| `terrain` | `""` | drape target node path; empty = **auto-find the first Terrain3D** in the tree (the zero-config default when `drape` is on) |
+
+> **Rolling terrain?** Set `drape: true` and the field's blades root on the
+> ground per-instance (it samples the Terrain3D's `heightAt`). Without draping a
+> Foliage3D/Flowers3D is a FLAT carpet at the node's Y, so on hills it
+> floats/sinks — either drape it, or place small patches at flat spots (the
+> generators still do the latter for backward-compatible output).
+
+## Flowers3D
+
+A first-class flower FIELD (in `incanto/3d`, registered by
+`registerNodes3D`): instanced procedural flower PLANTS — a curved stem,
+2-3 leaf blades low on the stem, a 5-8 petal head cupped around a
+contrasting center disc, 1-3 blooms per plant at staggered heights — not
+billboard confetti. Deterministic from the `seed` PROP.
+
+- **`density` is the vibe dial** — `'lush'` (풍성하게, 2.2 plants/m²),
+  `'sparse'` (듬성듬성, 0.35 — the default), `'none'` (없게, renders
+  nothing), or any number in plants/m². Load-time checks: valid
+  preset/number AND `area × density ≤ 10 000` plants (~1.3M tris budget).
+- **Varieties** — `varieties` picks a unique subset of
+  `daisy` (8 flat petals, 3 blooms), `cosmos` (8 cupped petals, 2 tall
+  blooms), `bellflower` (5 petals in a deep nodding bell, 3 blooms);
+  `[]` (default) = all three. Each variety is ONE merged template geometry,
+  instanced per plant as a green-structure mesh + a petal mesh —
+  **≤3 varieties → ≤6 draw calls**.
+- **Patches, not confetti** — placement gathers plants into jittered-Voronoi
+  patches (`clustering` 0 = uniform … 1 = tight patches, default 0.6), and
+  each patch blooms ONE variety in ONE palette color, like real meadows.
+- **`palette`** — head colors as `'#rrggbb'` strings; `[]` (default) = the
+  reference white/yellow/violet trio. The center disc keeps its contrasting
+  per-variety color.
+- **`height`** — plant height in meters (default 0.45, ±25% per-plant
+  jitter; petals scale along). Pick it ABOVE the surrounding grass canopy
+  (e.g. 0.6–0.7 over `height: 0.35` Foliage3D) so heads ride the grass.
+- **`sway`** — gentle vertex-shader head bob, phase-hashed per plant; roots
+  never move. 0 holds still.
+- Like Foliage3D the field is planar — on rolling terrain place small
+  patches at flat spots (the meadow/garden generators do this for you).
+
+```json
+{ "name": "Flowers", "type": "Flowers3D",
+  "props": { "area": [26, 26], "density": "sparse", "seed": 7,
+             "height": 0.7 } }
+```
+
+| prop | default | meaning |
+|---|---|---|
+| `density` | `"sparse"` | `lush` \| `sparse` \| `none` \| number (plants/m²) — budget-checked at load |
+| `area` | `[20, 20]` | [x, z] extent in meters, centered on the node |
+| `seed` | `1` | placement seed — identical field across runs/machines |
+| `varieties` | `[]` | unique subset of `daisy`/`cosmos`/`bellflower`; `[]` = all three (load-time check) |
+| `palette` | `[]` | head colors, `'#rrggbb'` each; `[]` = white/yellow/violet (load-time check) |
+| `height` | `0.45` | plant height, meters (±25% per-plant jitter) |
+| `clustering` | `0.6` | 0 uniform … 1 tight Voronoi patches (load-time check) |
+| `sway` | `0.5` | head-bob wind strength; 0 disables |
+| `drape` | `false` | drape each plant onto a Terrain3D's surface (rolling terrain) — see the Foliage3D drape note above |
+| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D |
+
+## Tree3D
+Procedural trees grown by the ported ez-tree generator (MIT, Dan Greenheck;
+in `incanto/3d`, registered by `registerNodes3D`) — recursive gnarled
+branches plus alpha-cutout leaf billboards sampling the packaged leaf
+textures. One node is a whole grove in ≤6 draw calls: up to 3 seed VARIANTS
+(differently-grown trees), each one branches-InstancedMesh + one
+leaves-InstancedMesh, `count` instances scattered over `area` and dealt
+round-robin among the variants. Construction is deterministic from the
+`seed` PROP: identical grove on every machine. Per-instance
+hue/scale/rotation jitter keeps a patch from reading as copies; `height`
+jitters ±20% per tree; leaves ride a ported simplex-wind vertex sway.
+
+**Crown shading (automatic):** leaf billboards do NOT light like flat
+quads — the generator bakes crown-VOLUME normals (deciduous crowns shade as
+an ellipsoid, conifers as a cone) plus per-leaf occlusion vertex colors
+(interior leaves darken toward 0.45) and per-cluster hue/value jitter, so
+canopies read as lit/shaded three-dimensional masses with a dark heart, not
+paper cut-outs. The leaf cutout threshold relaxes with camera distance
+(1.0× → 0.25× over 40–240 m) and edges ride MSAA alpha-to-coverage, so far
+groves keep solid crowns instead of mip-ghosting away (~300 m). Leaf albedo
+is calibrated for the atmosphere-sky + ACES stage; `canopyColor` still
+tints on top.
+
+**Bark** (medium/high tiers): trunks and branches sample the packaged
+ez-tree BARK sets — color + normal + roughness (1k, ambientcg CC0 packaged
+by ez-tree) — tiled over the generator's ring UVs with the upstream
+per-preset repeat, so trunks show ridged bark up close instead of smooth
+plastic. The mapping follows upstream: oak/ash → oak bark, aspen → birch,
+pine → pine; `dead` trees stay barkless weathered gray. Default texture
+source is the agent8 CDN (the only sanctioned external host, like leaves and
+the terrain splat); the same JPGs also ship in `incanto/assets/vegetation/bark/`
+for offline serving.
+
+**Tiers are a quality/cost dial** (ported preset → tris per tree):
+
+| tier | what grows | tris/tree |
+|---|---|---|
+| `simple` | the original primitive low-poly trees (cones/blobs) — cheapest, unchanged | ~0.1–0.5k |
+| `medium` (default) | light `*-forest` presets — use for FORESTS (many trees) | ≤3k |
+| `high` | full ez-tree presets (oak/ash rotation, airy pine whorls) — hero trees | 7–20k |
+
+**Perf budget (load-time check):** `count × tris-per-tree ≤ 1 500 000` —
+the error states the math and the max count for the tier. 500 medium trees
+fit; `high` caps at ~75 trees per node (worst variant ≈ 20k). Geometry
+grows lazily once (1–30 ms per variant), then scatter is matrix-only.
+```json
+{ "name": "Pines", "type": "Tree3D",
+  "props": { "type": "conifer", "tier": "medium",
+             "count": 24, "area": [40, 40], "seed": 11 } }
+```
+| prop | default | meaning |
+|---|---|---|
+| `tier` | `"medium"` | `simple` \| `medium` \| `high` — see the dial above (load-time check) |
+| `type` | `"conifer"` | `conifer` (pine whorls) \| `broadleaf` (oak/ash greens — autumn-gold aspen left out of the mix on purpose) \| `dead` (bare branches, no leaves) \| `bush` (ported bush_1 shrub — undergrowth; pair with height 2–4) |
+| `seed` | `1` | construction + scatter seed |
+| `height` | `6` | tree height, meters (±20% per-instance jitter) |
+| `count` | `1` | instances; > 1 scatters a forest patch (max 500, budget-checked) |
+| `area` | `[10, 10]` | [x, z] scatter extent when count > 1 |
+| `trunkColor` | `"#7a5a3a"` | bark tint — the DEFAULT hands color to the upstream preset tint (the bark maps carry it); a custom value keeps its hue, max-channel-normalized so it tints the map instead of darkening it. Headless / `dead`: flat untextured tint |
+| `canopyColor` | `"#4a7c3f"` | leaf tint — hue kept, value normalized over the leaf textures |
+
+Every instance in a grove also gets a deterministic per-instance color jitter (±~20° hue, ±0.11 lightness off the base canopy/trunk color) so neighbouring trees read varied, not a flat wall of one green — the `terrain` generator stacks per-grove SPECIES colors on top (see above).
+| `leafTexture` | `""` | leaf texture URL override; `""` = packaged per-type ez-tree texture (agent8 CDN — the only sanctioned external host; loads zero-setup). The same PNGs also ship in `incanto/assets/vegetation/` (`incanto-assets list`, kind `foliage`) — copy one next to your game and point here to serve offline |
+| `leafFadeStart` | `0` | **leaf LOD** — leaf cards begin collapsing toward their branch at this camera distance (m). `0`/`0` disables (full leaves at any range) |
+| `leafFadeEnd` | `0` | leaf LOD — cards fully collapsed (zero overdraw) by here; tune ≈ the scene `fog.far` so the thinning hides in fog (load-time check: `> leafFadeStart`) |
+| `leafShadows` | `true` | `false` keeps trunk/branch shadows but drops the expensive alpha-cutout LEAF shadow pass — big FPS in dense forests |
+| `drape` | `false` | **drape a scattered grove onto a Terrain3D**: each instance roots at the ground height under it instead of the node's single Y, so a `count > 1` patch on rolling/carved terrain never floats or buries |
+| `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (the zero-config default when `drape` is on) |
+
+> **Tree LOD / forest FPS.** Leaf overdraw + the leaf shadow pass dominate a
+> dense-forest frame (~90% in profiling). For big groves set `leafFadeStart`/
+> `leafFadeEnd` (e.g. `340`/`620` under fog far ~620) so far crowns shed their
+> leaf cards (branch silhouette stays), and `leafShadows: false` to drop the leaf
+> shadow pass. Both default off → existing scenes are unchanged.
+
+> **Floating trees?** A scattered grove (`count > 1`) places every instance at
+> the node's single Y, so on rolling or basin-carved terrain the far instances
+> float or sink. Set `drape: true` (auto-finds the Terrain3D) so each instance
+> roots on the ground under it. The drape is a pure heightAt lookup — no rng
+> draw, so the seed/grove layout is byte-identical, only the Y shifts.
+
+## Terrain3D
+Procedural heightfield terrain with biome texture splatting (in `incanto/3d`,
+registered by `registerNodes3D`), ported from the agent8 starter terrain:
+seeded simplex octaves displace a plane grid ONCE on the CPU, and a patched
+MeshStandardMaterial blends up to 4 biome textures by height and slope
+(per-vertex weights in vertex colors, world-UV sampling with fbm anti-tiling
+jitter — mip-correct: every sample passes the un-jittered UV's gradients via
+`textureGrad` — normal maps via a screen-space TBN). Same `seed` → identical
+terrain on every machine. Within 25 m of the camera every active layer is
+re-sampled at 10× repeat and added as zero-mean grain (colors AND normals,
+plus a crevice micro-AO), fading out by 60 m — the ground resolves into crisp
+grain up close instead of bilinear mush without shifting tone; textures load
+with anisotropy 8 so grazing angles stay sharp into the distance. All
+automatic, no props.
+{ "name": "Island", "type": "StaticBody3D",
+  "props": { "collider": { "shape": "heightfield" } },
+  "children": [
+    { "name": "Terrain", "type": "Terrain3D",
+      "props": { "size": [200, 200], "maxHeight": 6, "seed": 1, "theme": "island" } }
+  ] }
+That snippet is the canonical PHYSICS recipe: the `heightfield` collider has
+no params of its own — it pulls the height grid from its Terrain3D CHILD, so
+visuals and collision can never drift apart. It is static-only (load-time
+check) and hard-fails at physics start if the Terrain3D child is missing.
+Skip the StaticBody3D wrapper when the terrain is scenery-only.
+**Themes** preset the splat layers (and the island edge wrap) — load-time
+check lists them on a typo:
+| theme | layers (height × slope placement) | edge wrap |
+| `island` | sand beach 0–0.12 · grass 0.1–0.7 · stone on slopes >45° · snow 0.8–1 | ON — borders curl down a quarter-circle to −50 m (sea floor) |
+| `alpine` | grass valleys 0–0.45 · stone mid+high · gravel on slopes >36° · snow from 0.55 | off |
+| `plains` | grass everywhere · dirt patches 0.35–0.65 · gravel on slopes >45° | off |
+| `desert` | sand everywhere · gravel pans 0–0.15 · stone mesas on slopes >45° | off |
+| `grassland` | the ez-tree demo GROUND set (mossy grass + dense crisp dirt, 30 m tiling): grass at EVERY height · dirt on slopes >45° AND in noise-carved flat patches (the demo's exact 100 m simplex / 0.7 patchiness shaping). With a custom `textureBase` it falls back to the `<base>/grass.png` + `dirt.png` contract | off |
+| `forest` | grassland INVERTED — the LITTER floor: the ez-tree dark organic soil at every height/slope, moss-grass ONLY in noise-carved patches (55 m simplex, ~1/4 coverage). Custom `textureBase`: `<base>/dirt.png` + `grass.png` | off |
+| `savanna` | dry GOLDEN plains: grass at every height · sand pans 0–0.22 · dirt on slopes >45° AND in noise-carved patches (the warm sun does the golden tinting) | off |
+| `snow` | snow-dominant TUNDRA: snow at every height · stone (rock) on slopes >45° only — flat white field, distinct from alpine's banded peaks | off |
+| `wetland` | SWAMP floor: mossy grass at every height · dark dirt (mud) on slopes >45° AND in frequent noise patches (the soft overcast light reads it humid) | off |
+| `volcanic` | dark BASALT/ash: stone (basalt) at every height/slope · gravel (ash beds) pooling in the lows 0–0.28 | off |
+| `custom` | YOUR `layers` (1–4 entries, load-time checked) | off |
+Custom layers look like
+`{ "texture": "url.png", "normalMap": "url_normal.png", "heightRange": [0, 0.3], "slopeRange": [0, 0.8], "repeat": 2, "roughness": 0.9 }`
+— `heightRange` is normalized 0..1 over the realized height span, `slopeRange`
+is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
+(`textureBase` prop) — override it to self-host.
+| `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) |
+| `theme` | `"island"` | see table — `custom` requires `layers` |
+| `roughness` | `0.5` | detail-octave persistence (higher = more rugged) |
+| `detail` | `4` | detail octave count |
+| `flatThreshold` | `0.95` | snap-flatten heights within ±0.6 m of `maxHeight·flatThreshold` |
+| `islandEdge` | `null` | `null` = theme decides; force the rim wrap on/off with a boolean |
+| `layers` | `[]` | custom splat layers (theme `custom` only) |
+| `textureBase` | agent8 CDN | base URL: `<base>/<name>.png` + `<base>/<name>_normal.png` |
+| `basins` | `[]` | lake/pond bowls — `[{ x, z, radius, depth }]` (centered meters) carved into the surface (smooth, 0-slope rim); `heightAt`, the collider AND draped grass all see them |
+
+**Carving a lake.** A flat Water3D plane on rolling/dome terrain reads as a wet
+patch, not a lake. Carve a `basins` bowl so water fills a real depression with a
+shoreline, then drop a `Water3D` at the floor + a little:
+```ts
+// Terrain3D prop: a 9 m-radius, 3 m-deep bowl at the interior point (20, -15)
+"basins": [{ "x": 20, "z": -15, "radius": 9, "depth": 3 }]
+// then place water just above the carved floor (heightAt sees the bowl):
+const floor = terrain.heightAt(20, -15);          // ≈ surroundingGround - 3
+pond.position = [20, floor + 1.2, -15];            // ~60% of the bank submerged
+```
+Keep `radius`/`depth` gentle (depth/radius ≈ 0.3–0.5) so the bank stays walkable
+and the shore splat reads. Interior ponds/lakes are cheapest as `Water3D
+quality:'simple'` — the lake shader (fresnel sky tint + ripple normals + sun
+glint + soft edge fade) with ZERO scene re-renders, vs fancy's ~2 full-scene
+re-renders a frame. Give simple ponds a vivid water `color` (a muddy/dark hue
+reads grey, since the surface IS mostly that color plus a sky sheen) and a
+`sunDirection` matching the key light so the glint lands; its soft alpha edge
+melts the rectangular plane into the shore (no hard rim poking out of the bowl).
+**`heightAt(x, z)`** answers the surface height (world y) at WORLD x/z —
+bilinear over the displaced grid, works headless and before any render.
+Spawn points, prop placement, AI ground checks:
+```ts
+const terrain = scene.root.getNode('Island/Terrain') as Terrain3D;
+crate.position = [x, terrain.heightAt(x, z) + 0.5, z];
+```
+
+Splat bands follow the surface the eye sees: the island rim's wrap shoulder
+descends through the bands (snow → grass → sand) and every shoreline ends in
+the bottom layer, so beaches happen automatically at the waterline.
+
+**Island sea level is a TWO-sided constraint** — probe heights with
+`heightAt` (or `buildHeightmap`) instead of guessing:
+
+- the edge wrap only drops the rim 20 m before the vertical skirt to −50 m,
+  so the waterline must sit ABOVE `(highest border height − 20 m)` or bare
+  cliff walls with stretched stripes poke out of the sea;
+- it should also sit inside the sand band (bottom 12% of the realized span)
+  so the visible shore reads as beach.
+
+Both fit comfortably at `maxHeight ≈ 4–5` with `size: [200, 200]` (e.g.
+seed 1 → surface 10.4–32 m, cliffs top out at 12.0, sea at 12.8 works).
+Tall islands (`maxHeight ≥ 8` at that size) have rim heights no drownable
+sea level can cover — scale height with care, the wrap radius does not grow.
+
+`runGenerator('terrain', { seed, theme: 'island' })` does ALL of this math
+for you: it probes the border with `buildHeightmap`, places the sea above
+every rim cliff top and inside the sand band, and auto-fits `maxHeight`
+down for seeds whose rim is too tall. Hand-author only when you need a
+non-default composition.
+
+## Water3D
+
+A commercial-quality water surface (in `incanto/3d`, registered by
+`registerNodes3D`). The default `quality: 'fancy'` is a real water shader:
+9-iteration simplex-FBM wave displacement with analytic normals, THREE
+animated ANISOTROPIC detail-normal layers — wind-stretched (~2.8× along the
+wind), ridge-sharpened fine ripple in crossing directions, each layer
+distance-faded at its own range so the far field goes glassy instead of
+aliasing — sun glints as SPARSE micro-facet sparks (extreme shininess +
+noise-gated + weighted toward the sun's azimuth path and grazing views;
+the rest of the surface stays broad calm color fields), per-channel
+Beer's-law depth `absorption` (red dies first — turquoise shallows fade
+WIDE into deep teal-blue, like a real sea), CRYSTAL shallows (inside the
+first ~1.5 m of water the refracted bottom dominates, ripple-distorted —
+you see the sand through the surface), screen-space `refraction`
+(submerged geometry shimmers SOFTLY through the surface — the offset reads
+the smooth gloss normal, fades to zero at object waterlines, mip-blurs the
+grab pass and blends instead of snapping at above-water silhouettes, so
+contact lines stay clean with no comb-pattern streaks), always-on wispy
+noise-broken shoreline `foam` (the foam band's depth range scales with the
+water's extent: ponds get a contact kiss, open seas get whole shallow
+channels), a trough/surface/peak color ramp (teal sea-blue defaults),
+fresnel-mixed CubeCamera reflections re-rendered every `reflectionInterval`
+ms and an edge-fade ring. Fresnel/reflection read a SMOOTH long-wavelength
+normal (never the ridged ripple — that's what kept turning HDR sky
+reflections into white sequins), HDR-capped per sample. `quality: 'simple'`
+is the cheap LAKE shader — fresnel sky-tint reflection (a procedural
+horizon→zenith gradient, NO cube map), animated procedural ripple normals
+(`detailStrength`), a sun glint+sheen (`sunDirection`/`sunColor`/
+`sunIntensity`), a depth-free view-angle body tint (clearer looking down,
+deeper/more-reflective grazing) and a soft alpha edge fade that melts the
+plane's rim into the shore. It does ZERO scene re-renders (no CubeCamera, no
+depth/refraction pre-pass — the three things that drop fancy to ~30 fps at a
+pond), so it's the low-end/perf path AND the deterministic headless path. A
+lake reads as ONE hue derived from `color` (deep = darkened, surface =
+lifted, sky = mostly real sky-blue), so give it a vivid color — a dark/muddy
+hue reads grey.
+
+```json
+{ "name": "Water", "type": "Water3D",
+  "props": { "size": [40, 40], "position": [0, 3.2, 0] } }
+```
+
+| prop | default | meaning |
+|---|---|---|
+| `size` | `[40, 40]` | [width, depth] meters — must be positive (load-time check) |
+| `color` | `"#2a6fbe"` | THE lake hue for `simple` (deep/surface/sky derived from it — use a vivid color); if customized it also tints the fancy ramp |
+| `opacity` | `0.8` | water-body density: lower = clearer (scales how much the refracted scene shows through) |
+| `waveHeight` | `0.04` | wave intensity, meters-ish (0 = mirror-flat; 0.04 = calm sea; 0.08 = the older choppier look) |
+| `waveSpeed` | `1` | animation speed multiplier |
+| `quality` | `"fancy"` | `fancy` full shader water (CubeCamera + scene pre-pass) \| `simple` cheap lake shader, no scene re-renders (load-time check) |
+| `colors` | `{}` | fancy ramp overrides: `{"trough", "surface", "peak"}` hex strings |
+| `reflection` | `true` | live CubeCamera reflections (fancy only; needs a renderer) |
+| `reflectionInterval` | `1000` | ms between CubeCamera reflection re-renders |
+| `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`) |
+| `splash` | `true` | built-in splash WHITEWATER (needs `interaction`): the shaders paint expanding **surface foam** where bodies interact — a **"풍덩"** froth bloom when a body plunges in (bigger the faster it falls) and a **foam trail ("물살")** behind a body wading/running through. Real frothy whitewater on the surface, not flying droplets; works on both `fancy` and `simple` quality. `false` keeps the ripples/waves but paints no foam. No wiring needed; for an extra custom burst add your own `Particles3D` on the `entered` signal |
+| `sunDirection` | `[0.5, 0.8, 0.3]` | TOWARD the sun, for the specular glint — match the scene's key light (non-zero, load-time check) |
+| `sunColor` | `"#fff5d6"` | glint/sheen tint |
+| `sunIntensity` | `1` | glint/sheen strength (≥ 0; 0 = off) |
+| `detailStrength` | `0.3` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
+| `absorption` | `0.15` | Beer's-law constant per meter of water depth (≥ 0; lower = clearer/wider turquoise band; red absorbs ~3× faster than blue under the hood) |
+| `refraction` | `true` | screen-space refraction of the submerged scene |
+| `underwater` | `true` | submerged-camera look: ONLY when the camera EYE is below this surface (inside its XZ footprint) — wading with the camera above the water never tints the view — the scene switches to short-range underwater fog + tint, the sky is hidden, and animated **caustics** (depth-aware, projected onto the submerged floor/props) play. `false` disables it; an object `{ color?, visibility?, caustics? }` overrides the murk hue / view distance (m, default 22) / caustics. `caustics` is `true` (default) \| `false` \| `{ color?, intensity?, scale?, speed? }`. The murk color defaults to a darkened shade of `color`. Works for both qualities (the caustics composite runs only while the camera is genuinely underwater) |
+
+Performance notes (fancy): beyond drawing the surface, each rendered frame
+pays ONE half-resolution scene pre-pass (clamped at 1024px) that feeds the
+depth texture (absorption + foam + soft intersections) AND the refraction
+color grab; the CubeCamera reflection stays on its `reflectionInterval`
+throttle. Measured on the generated island (sea 1600×1600 m, ~206k tris):
+60 fps, frame times indistinguishable from the pre-v2 water. Headless runs
+never invoke any of it. Multiple fancy waters each pay their own pre-pass —
+prefer one large surface over many small ones.
+
+Two placement rules keep the surface artifact-free:
+
+- **Waves dip below the waterline.** Troughs reach ≈6.5× `waveHeight` meters
+  below `position.y` (the default 0.04 ≈ 0.26 m). Float the waterline at
+  least that far above any ground/terrain it overlaps — otherwise the ground
+  pokes through wave troughs as dark bites in the surface.
+- **Reflections mirror DISTANT content only.** The cube map renders from the
+  water's center with everything inside the footprint near-plane-culled (a
+  nearby mesh would smear across the whole surface as a giant false-color
+  patch). Shoreline, terrain, and sky reflect; a boat floating ON the water
+  intentionally does not — its submerged hull shows through `refraction`
+  instead.
+
+### Character interaction — `entered(body)` / `exited(body)`
+
+With `interaction: true` the water scans the tree each frame for
+`CharacterBody3D`/`RigidBody3D` inside its XZ footprint, compares their world
+y against the waterline at their xz (wave offset included), and:
+
+- emits `entered(body)` / `exited(body)` signals (the argument is the node),
+- pushes a ripple impulse into a fixed 8-slot ring buffer that the shader
+  turns into expanding ring waves (faster falls splash harder; floating
+  bodies feed gentle bob rings on an interval),
+- and (with `splash: true`, the default) paints expanding **surface FOAM** —
+  a **"풍덩"** froth bloom on entry whose size tracks the plunge speed, plus a
+  **foam trail ("물살")** behind a body wading/running through. This is real
+  whitewater on the water surface (driven by the same ripple buffer, in both
+  shaders), not flying droplets. Automatic; zero wiring. Set `splash: false`
+  to keep only the ripples/waves.
+
+The surface has no bottom — anything below the waterline inside the
+footprint counts as in-water. Keep using an `Area3D` for volumetric gameplay
+(swim zones, drowning); the signals are for SPLASH moments. The built-in
+`splash` particles already cover the common case — reach for a hand-wired
+emitter only when you want a specific custom burst:
+
+```json
+{
+  "root": { "name": "World", "type": "Node3D", "children": [
+    { "name": "Lake", "type": "Water3D",
+      "props": { "size": [60, 60], "position": [0, 2.8, 0] } },
+    { "name": "Splash", "type": "Particles3D",
+      "props": { "position": [0, 3, 0], "preset": "explosion", "emitting": false,
+                 "rate": 0, "burst": 40, "colorStart": "#dff3ff", "colorEnd": "#9bd8ff" } }
+  ] },
+  "connections": [
+    { "signal": "entered", "from": "Lake", "to": "Splash", "handler": "replay" }
+  ]
+}
+```
+
+(`replay` re-arms the one-shot burst; a small behavior can also move the
+emitter to the body first — the signal hands you the node:
+`onEntered(body) { splash.position = body.position; splash.replay(); }`.)
+
+## Determinism, verified
+
+`--seed` makes every run reproducible — keep the seed in your scene comments
+or PROJECT docs. Regenerating with the same seed after an engine upgrade is
+the cheap way to diff what changed; `bunx incanto-check` validates the scene
+after every insert.