incanto 0.26.0 → 0.28.0

package/dist/{register-CeWtdiCw.js → register-6R75AC7-.js}

@@ -4,7 +4,7 @@ import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-Ddk13pQ6.js";
+import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-DEG-TP7D.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
@@ -898,8 +898,15 @@ function themePatchTransfer(theme) {
 }
 //#endregion
 //#region src/3d/nodes/terrain-3d.ts
-/** Hard cap on grid segments per side (129×129 vertices ≈ the CPU budget). */
-const MAX_RESOLUTION = 128;
+/**
+* Hard cap on grid segments per side. 128 is the default and the right answer
+* for most maps; 256 (66k vertices) exists for terrain that has to hold
+* features finer than a cell — a 2 m creek bed on a 260 m map needs ~1 m
+* cells or the trench smooths away. The cost is CPU at build time (noise
+* octaves + carving per vertex), paid once per shaping change, so raise it
+* deliberately rather than by default.
+*/
+const MAX_RESOLUTION = 256;
 /**
 * Procedural heightfield terrain with biome texture splatting — seeded
 * simplex octaves displace a PlaneGeometry once on the CPU, per-vertex
@@ -982,6 +989,14 @@ var Terrain3D = class extends Node3D {
 	* bed to sit in, and the collider/heightAt/drape all see it. */
 	channels = [];
 	/**
+	* Trenches other NODES cut in this terrain — a `River3D` carving its own bed.
+	* Keyed by the node that owns each, so a moving or re-pathed river replaces
+	* its cut instead of stacking a new one. Runtime state, never serialized:
+	* the scene file says "there is a river here", not "here is the ditch it
+	* dug", and re-loading the scene digs it again.
+	*/
+	externalChannels = /* @__PURE__ */ new Map();
+	/**
 	* WET SAND band: `{ y, band? }` darkens + glosses the splat in a noisy,
 	* breathing band just above height `y` (a waterline) — the trace of the
 	* last swash runup. `band` is the max height above `y` that reads wet
@@ -1061,6 +1076,20 @@ var Terrain3D = class extends Node3D {
 		}
 		return this._heightmap().heightAt(x - ox, z - oz) + oy;
 	}
+	/**
+	* @internal Cut (spec) or release (null) a trench another node owns. A
+	* `River3D` calls this to dig its own bed; the heightmap, the collider,
+	* `heightAt`, the drape and the mesh all pick it up on their next rebuild.
+	*/
+	_setExternalChannel(owner, specs) {
+		if (specs === null || specs.length === 0) this.externalChannels.delete(owner);
+		else this.externalChannels.set(owner, specs);
+	}
+	/** Authored trenches plus the ones other nodes cut. */
+	allChannels() {
+		if (this.externalChannels.size === 0) return this.channels;
+		return [...this.channels, ...[...this.externalChannels.values()].flat()];
+	}
 	/** @internal The pure heightfield (lazily built — physics pulls this). */
 	_heightmap() {
 		const segs = this.segments();
@@ -1074,7 +1103,7 @@ var Terrain3D = class extends Node3D {
 			this.flatThreshold,
 			this.effectiveIslandEdge(),
 			this.basins,
-			this.channels
+			this.allChannels()
 		]);
 		if (!this.heightmap || key !== this.heightmapKey) {
 			this.heightmap = buildHeightmap({
@@ -1089,7 +1118,7 @@ var Terrain3D = class extends Node3D {
 				flatThreshold: this.flatThreshold,
 				islandEdge: this.effectiveIslandEdge(),
 				basins: this.basins,
-				channels: this.channels
+				channels: this.allChannels()
 			});
 			this.heightmapKey = key;
 		}
@@ -1124,7 +1153,8 @@ var Terrain3D = class extends Node3D {
 			this.islandEdge,
 			this.layers,
 			this.textureBase,
-			this.basins
+			this.basins,
+			this.allChannels()
 		]);
 		if (key === this.builtKey) return;
 		this.builtKey = key;
@@ -2802,6 +2832,37 @@ function firstTerrain(node) {
 	return null;
 }
 //#endregion
+//#region src/3d/water/wet-ground.ts
+function isWetSurface(node) {
+	return typeof node?._waterYAt === "function";
+}
+/** Every water surface in the tree the node belongs to. */
+function collectWetSurfaces(from) {
+	let root = from;
+	while (root.parent) root = root.parent;
+	const out = [];
+	const walk = (node) => {
+		if (node.visible !== false && isWetSurface(node)) out.push(node);
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	return out;
+}
+/**
+* Is this spot under water deep enough to drown a plant?
+*
+* `margin` is the depth a blade tolerates — a wet edge is still a bank, and
+* culling everything the water so much as touches leaves a bald halo around
+* every stream.
+*/
+function isUnderWater(surfaces, x, z, groundY, margin = .06) {
+	for (let i = 0; i < surfaces.length; i++) {
+		const y = surfaces[i]?._waterYAt(x, z);
+		if (y !== null && y !== void 0 && y - groundY > margin) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/3d/nodes/flowers-3d.ts
 /** Named density presets, plants per m² — the vibe-coding dial (풍성하게 /
 * 듬성듬성 / 없게). Numbers are accepted too. */
@@ -2870,6 +2931,7 @@ var Flowers3D = class extends Node3D {
 		clustering: { default: .6 },
 		sway: { default: .5 },
 		drape: { default: null },
+		avoidWater: { default: true },
 		terrain: { default: "" }
 	};
 	/** 'lush' | 'sparse' | 'none' | plants per m² (load-time check + budget). */
@@ -2897,6 +2959,12 @@ var Flowers3D = class extends Node3D {
 	* draping entirely.
 	*/
 	drape = null;
+	/**
+	* Keep plants out of standing and running water (default true) — a meadow a
+	* stream runs through has a bank of flowers, not flowers in the current.
+	* Set false for water lilies and marsh planting.
+	*/
+	avoidWater = true;
 	/** Drape target: a node path to the Terrain3D. Empty = auto-find the first
 	* Terrain3D in the tree (the zero-config default when `drape` is on). */
 	terrain = "";
@@ -2996,13 +3064,20 @@ var Flowers3D = class extends Node3D {
 		const density = resolveFlowerDensity(this.density);
 		const count = Math.min(Math.floor((this.area[0] ?? 0) * (this.area[1] ?? 0) * density), MAX_PLANTS);
 		if (count <= 0) return;
-		const placements = placeFlowerPlants({
+		let placements = placeFlowerPlants({
 			seed: this.seed,
 			areaX: this.area[0] ?? 0,
 			areaZ: this.area[1] ?? 0,
 			count,
 			clustering: this.clustering
 		});
+		if (this.avoidWater) {
+			const surfaces = collectWetSurfaces(this);
+			if (surfaces.length > 0) {
+				const [ox, oy, oz] = worldXZY(this);
+				placements = placements.filter((p) => !isUnderWater(surfaces, p.x + ox, p.z + oz, this.bedY(p.x, p.z) + oy));
+			}
+		}
 		const varieties = this.varieties.length > 0 ? this.varieties : FLOWER_VARIETIES;
 		const buckets = varieties.map(() => []);
 		for (const p of placements) buckets[Math.min(Math.floor(p.variety01 * varieties.length), varieties.length - 1)].push(p);
@@ -4257,6 +4332,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 		flowers: { default: 0 },
 		seed: { default: 1 },
 		drape: { default: null },
+		avoidWater: { default: true },
 		terrain: { default: "" },
 		renderOrder: { default: 2 }
 	};
@@ -4323,6 +4399,14 @@ var Foliage3D = class Foliage3D extends Node3D {
 	* a terrain appears), false disables draping entirely.
 	*/
 	drape = null;
+	/**
+	* Keep blades out of standing and running water (default true). Grass does
+	* not grow in a stream: any instance whose ground sits under a `Water3D` or
+	* `River3D` surface is dropped, which is what stops a creek that cut its bed
+	* through a meadow from filling with waving blades. Set false for reeds and
+	* paddy fields, where the plant IS in the water.
+	*/
+	avoidWater = true;
 	/** Drape target: a node path to the Terrain3D. Empty = auto-find the first
 	* Terrain3D in the tree (the zero-config default when `drape` is on). */
 	terrain = "";
@@ -4552,6 +4636,22 @@ var Foliage3D = class Foliage3D extends Node3D {
 	* fraction of instances into a SECOND InstancedMesh of 5-vertex flower
 	* heads (white/yellow/violet per instance).
 	*/
+	/**
+	* Drop the instances standing in water. The ground each blade drapes onto is
+	* already known here, so the test is one question per candidate — and only
+	* the ones a water surface actually covers pay for it.
+	*/
+	dryOnly(placements) {
+		if (!this.avoidWater) return placements;
+		const surfaces = collectWetSurfaces(this);
+		if (surfaces.length === 0) return placements;
+		const [ox, , oz] = worldXZY(this);
+		return placements.filter((p) => !isUnderWater(surfaces, p.x + ox, p.z + oz, this.bedY(p.x, p.z) + this.worldY()));
+	}
+	/** This field's own world height (the bed sampler works in local Y). */
+	worldY() {
+		return worldXZY(this)[1];
+	}
 	buildMeshField(count) {
 		const placements = placeGrass({
 			seed: this.seed,
@@ -4560,7 +4660,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 			count,
 			density: this.density * MESH_DENSITY_MULT
 		});
-		const kept = this.coverage >= 1 ? placements : placements.filter((p) => coverageNoiseAt(p.x, p.z, this.seed) <= this.coverage);
+		const kept = this.dryOnly(this.coverage >= 1 ? placements : placements.filter((p) => coverageNoiseAt(p.x, p.z, this.seed) <= this.coverage));
 		const flowerCount = this.flowers > 0 ? Math.floor(kept.length * this.flowers) : 0;
 		const flowerSlots = /* @__PURE__ */ new Set();
 		for (let k = 0; k < flowerCount; k++) flowerSlots.add(Math.floor((k + .5) * kept.length / flowerCount));
@@ -4670,7 +4770,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 			count,
 			density: this.density * TUFT_DENSITY_MULT
 		});
-		const kept = this.coverage >= 1 ? placements : placements.filter((p) => coverageNoiseAt(p.x, p.z, this.seed) <= this.coverage);
+		const kept = this.dryOnly(this.coverage >= 1 ? placements : placements.filter((p) => coverageNoiseAt(p.x, p.z, this.seed) <= this.coverage));
 		this.tuftTime = { value: this.time };
 		this.tuftStrength = { value: this.sway * TUFT_SWAY_TO_WIND };
 		const material = new MeshStandardMaterial({
@@ -4773,23 +4873,32 @@ var Foliage3D = class Foliage3D extends Node3D {
 			roughness: 1
 		});
 		const mesh = new InstancedMesh(buildBladeGeometry(BLADE_WIDTH[this.kind] ?? .08), material, Math.max(count, 1));
-		mesh.count = count;
 		mesh.receiveShadow = true;
 		const rng = new Rng(this.seed);
 		const halfX = (this.area[0] ?? 0) / 2;
 		const halfZ = (this.area[1] ?? 0) / 2;
 		const colorA = colorScratchA$1.set(this.colorA);
 		const colorB = colorScratchB$1.set(this.colorB);
+		const wet = this.avoidWater ? collectWetSurfaces(this) : [];
+		const [ox, oy, oz] = worldXZY(this);
+		let placed = 0;
 		for (let i = 0; i < count; i++) {
 			const sx = rng.range(-halfX, halfX);
 			const sz = rng.range(-halfZ, halfZ);
-			positionScratch$1.set(sx, this.bedY(sx, sz), sz);
-			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, rng.range(0, Math.PI * 2));
-			scaleScratch$2.set(1, this.height * rng.range(HEIGHT_JITTER$1[0], HEIGHT_JITTER$1[1]), 1);
+			const rotY = rng.range(0, Math.PI * 2);
+			const jitter = rng.range(HEIGHT_JITTER$1[0], HEIGHT_JITTER$1[1]);
+			const tint = rng.next();
+			const bed = this.bedY(sx, sz);
+			if (wet.length > 0 && isUnderWater(wet, sx + ox, sz + oz, bed + oy)) continue;
+			positionScratch$1.set(sx, bed, sz);
+			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, rotY);
+			scaleScratch$2.set(1, this.height * jitter, 1);
 			matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2);
-			mesh.setMatrixAt(i, matrixScratch$1);
-			mesh.setColorAt(i, colorScratchC$1.copy(colorA).lerp(colorB, rng.next()));
+			mesh.setMatrixAt(placed, matrixScratch$1);
+			mesh.setColorAt(placed, colorScratchC$1.copy(colorA).lerp(colorB, tint));
+			placed++;
 		}
+		mesh.count = placed;
 		mesh.instanceMatrix.needsUpdate = true;
 		if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
 		this.meshes = [mesh];
@@ -6422,6 +6531,81 @@ function softSprite() {
 }
 //#endregion
 //#region src/3d/water/river.ts
+/**
+* Self-carved bed. Sized off the WATER COLUMN, never off the width: a channel's
+* banks are as steep as banks are, and a taper scaled to width turns a wide
+* river into a shallow saucer the water floods far past its edge.
+*/
+/** Trench depth, in water columns. */
+const CARVE_DEPTH = 2.2;
+/** Bank blend beyond the flat bed, in water columns. */
+const CARVE_BANK = 2;
+/** Where the waterline crosses that blend — smoothstep(t) = 1 − 1/CARVE_DEPTH.
+* Knowing it is what lets the floor be narrowed so the WATER ends up the
+* authored width instead of the bed doing so. */
+const CARVE_WATERLINE_T = .52;
+/** Never cut the floor away entirely, however steep the bank works out. */
+const CARVE_FLOOR_MIN = .3;
+/** A trench thinner than this many terrain cells cannot survive the grid it is
+* sampled on — it smooths away to nothing and the creek is back on raw ground.
+* Widening it is the honest failure: better a bed too wide than no bed. */
+const CARVE_MIN_CELLS = 1.5;
+/** Deepest the bed may be cut, in water columns — the budget for digging
+* THROUGH a rise so the water keeps flowing, before it reads as a canyon. */
+const CARVE_MAX_DEPTH = 7;
+/** The fall the carved floor keeps even where the ground does not (m per m). */
+const CARVE_MIN_GRADE = .004;
+/**
+* The trench a river digs for itself, as {@link ChannelSpec}s for Terrain3D.
+*
+* Shared on purpose: `River3D` cuts this at load, and anything that has to
+* PLACE things against the result — a scene generator putting a player, a
+* bridge and a boulder field on the ground — computes the identical cut
+* instead of approximating it. A generator that guesses differently spawns the
+* player inside a hill.
+*
+* The floor only ever FALLS. Water does not climb, so a bed that climbs is a
+* river that stops and buries itself; carrying the running minimum downstream
+* digs through a rise instead, and the cap keeps that from turning a hill into
+* a canyon.
+*/
+function riverCarveChannels(opts) {
+	if (opts.path.length < 2) return [];
+	const line = resamplePath(opts.path, Math.max(opts.cell, opts.depth));
+	if (line.length < 2) return [];
+	const total = line[line.length - 1].along || 1;
+	const ground = line.map((s) => opts.groundAt(s.x, s.z));
+	const baseCut = opts.depth * CARVE_DEPTH;
+	const maxCut = opts.depth * CARVE_MAX_DEPTH;
+	const floor = new Array(line.length);
+	for (let i = 0; i < line.length; i++) {
+		const wanted = ground[i] - baseCut;
+		if (i === 0) {
+			floor[i] = wanted;
+			continue;
+		}
+		const run = line[i].along - line[i - 1].along;
+		const carried = floor[i - 1] - run * CARVE_MIN_GRADE;
+		floor[i] = Math.max(Math.min(wanted, carried), ground[i] - maxCut);
+	}
+	const out = [];
+	for (let i = 1; i < line.length; i++) {
+		const a = line[i - 1];
+		const b = line[i];
+		const cut = Math.max((ground[i - 1] + ground[i]) / 2 - (floor[i - 1] + floor[i]) / 2, 0);
+		if (cut <= .001) continue;
+		const half = widthAlong(opts.widths, a.along / total) / 2;
+		const bank = Math.max(opts.depth * CARVE_BANK, opts.cell * CARVE_MIN_CELLS);
+		const floorHalf = Math.max(half - bank * CARVE_WATERLINE_T, half * CARVE_FLOOR_MIN, opts.cell * .5);
+		out.push({
+			path: [[a.x, a.z], [b.x, b.z]],
+			width: floorHalf * 2,
+			depth: cut,
+			taper: bank
+		});
+	}
+	return out;
+}
 /** Dense Catmull-Rom taps per control segment before arc-length resampling. */
 const SPLINE_TAPS = 24;
 /** Box-filter half-window (samples) that irons kinks out of the bed profile. */
@@ -6430,6 +6614,22 @@ const PROFILE_SMOOTH = 3;
 const SLOPE_GAIN = 4;
 const SPEED_MIN = .05;
 const SPEED_MAX = 12;
+/** Taps per side when reading the cross-section (rim height, wetted edge). */
+const SECTION_TAPS = 14;
+/** How far out a station looks for the bank that holds it, as a multiple of
+* its half-width and of its depth. Wider than the water on purpose: a river
+* running down the middle of a broad channel is held by walls it never
+* touches, and a scan that stopped at the waterline would call that a spill. */
+const SCAN_WIDTHS = 3;
+const SCAN_DEPTHS = 5;
+/** Thinnest water a reach keeps when the ground refuses to hold any (m). */
+const MIN_FILM = .04;
+/** Half-window (stations) the wetted widths are box-smoothed over. */
+const WIDTH_SMOOTH = 2;
+/** How far a station looks sideways for the bank that holds its water. */
+function scanReach(halfWidth, depth) {
+	return Math.max(halfWidth * SCAN_WIDTHS, halfWidth + depth * SCAN_DEPTHS);
+}
 /**
 * Smooth the control path and walk it at even arc-length steps. The step is
 * nudged so the last sample lands exactly on the mouth — an odd short segment
@@ -6549,26 +6749,102 @@ function buildRiverRings(opts) {
 		const s = smoothed[i];
 		profile[i] = i === 0 ? s : Math.min(s, profile[i - 1]);
 	}
+	const fit = opts.fit === true;
+	const levels = new Array(samples.length);
+	const rims = new Array(samples.length);
+	for (let i = 0; i < samples.length; i++) {
+		const s = samples[i];
+		const wanted = profile[i] + opts.depth;
+		if (!fit) {
+			rims[i] = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+			levels[i] = wanted;
+			continue;
+		}
+		const reach = scanReach(halfWidths[i], opts.depth);
+		const px = -s.tz;
+		const pz = s.tx;
+		let rimL = Number.NEGATIVE_INFINITY;
+		let rimR = Number.NEGATIVE_INFINITY;
+		for (let k = 1; k <= SECTION_TAPS; k++) {
+			const d = k / SECTION_TAPS * reach;
+			rimL = Math.max(rimL, opts.bedAt(s.x + px * d, s.z + pz * d));
+			rimR = Math.max(rimR, opts.bedAt(s.x - px * d, s.z - pz * d));
+		}
+		rims[i] = [rimL, rimR];
+		levels[i] = Math.min(wanted, rimL, rimR);
+	}
+	for (let i = 0; i < levels.length; i++) {
+		let v = levels[i];
+		if (fit) v = Math.max(v, bed[i] + MIN_FILM);
+		if (i > 0) v = Math.min(v, levels[i - 1]);
+		const rim = rims[i];
+		v = Math.min(v, Math.max(Math.min(rim[0], rim[1]), bed[i] + MIN_FILM));
+		levels[i] = v;
+	}
+	const wetted = samples.map((s, i) => {
+		const half = halfWidths[i];
+		if (!fit) return [half, half];
+		const reach = scanReach(half, opts.depth);
+		const level = levels[i];
+		const px = -s.tz;
+		const pz = s.tx;
+		const edge = (side) => {
+			for (let k = 1; k <= SECTION_TAPS; k++) {
+				const d = k / SECTION_TAPS * reach;
+				if (opts.bedAt(s.x + px * d * side, s.z + pz * d * side) >= level) return d;
+			}
+			return -half;
+		};
+		return [edge(1), edge(-1)];
+	});
+	const smoothWetted = wetted.map((_, i) => {
+		let l = 0;
+		let r = 0;
+		let n = 0;
+		for (let k = -2; k <= WIDTH_SMOOTH; k++) {
+			const w = wetted[Math.min(Math.max(i + k, 0), wetted.length - 1)];
+			l += Math.abs(w[0]);
+			r += Math.abs(w[1]);
+			n++;
+		}
+		const raw = wetted[i];
+		return [Math.min(l / n, Math.abs(raw[0])), Math.min(r / n, Math.abs(raw[1]))];
+	});
 	const meanHalf = halfWidths.reduce((a, b) => a + b, 0) / halfWidths.length || 1;
 	return samples.map((s, i) => {
-		const surfaceY = profile[i] + opts.depth;
+		const surfaceY = levels[i];
 		const prev = Math.max(0, i - 1);
 		const next = Math.min(samples.length - 1, i + 1);
 		const run = samples[next].along - samples[prev].along;
-		const drop = (profile[prev] + opts.depth - (profile[next] + opts.depth)) / (run || 1);
+		const drop = (levels[prev] - levels[next]) / (run || 1);
 		const slope = Math.max(0, drop);
 		const halfWidth = halfWidths[i];
+		const wet = smoothWetted[i];
 		const speed = Math.min(Math.max(opts.flowSpeed * Math.sqrt(meanHalf / halfWidth) * (1 + SLOPE_GAIN * slope), SPEED_MIN), SPEED_MAX);
+		const rawWet = wetted[i];
 		return {
 			...s,
 			halfWidth,
+			halfLeft: Math.max(wet[0], .05),
+			halfRight: Math.max(wet[1], .05),
+			spillLeft: rawWet[0] < 0,
+			spillRight: rawWet[1] < 0,
 			surfaceY,
 			slope,
 			speed
 		};
 	});
 }
-/** Ribbon mesh for the stations — flat across, draped along, attribute-rich. */
+/**
+* Ribbon mesh for the stations: level across the channel, draped along it, and
+* attribute-rich.
+*
+* Level across ONLY while the ground holds it. Where a bank has fallen away —
+* the outside of a bend, a reach traversing a hillside, the lip above a fall —
+* a level ribbon would hang in the air, so those vertices drop to follow the
+* ground down instead. Water pouring over a lip is a sheet on the rock; it is
+* never a slab of blue floating over the grass.
+*/
 function buildRiverGeometry(rings, opts) {
 	const across = Math.max(1, Math.round(opts.acrossSegments));
 	const perRing = across + 1;
@@ -6582,6 +6858,7 @@ function buildRiverGeometry(rings, opts) {
 	const indices = new Uint32Array(quads * 6);
 	for (let r = 0; r < rings.length; r++) {
 		const ring = rings[r];
+		const columnCap = Math.max(ring.surfaceY - sampleBed(opts, ring.x, ring.z), MIN_FILM);
 		const px = -ring.tz;
 		const pz = ring.tx;
 		const nLen = Math.hypot(ring.slope, 1);
@@ -6590,12 +6867,15 @@ function buildRiverGeometry(rings, opts) {
 		const nz = ring.tz * ring.slope / nLen;
 		for (let c = 0; c <= across; c++) {
 			const t = c / across * 2 - 1;
-			const offset = t * ring.halfWidth * opts.bankOvershoot;
+			const offset = t * (t < 0 ? ring.halfRight : ring.halfLeft) * opts.bankOvershoot;
 			const x = ring.x + px * offset;
 			const z = ring.z + pz * offset;
 			const i = r * perRing + c;
+			const bed = sampleBed(opts, x, z);
+			const cap = (t < 0 ? ring.spillRight : ring.spillLeft) ? columnCap + (MIN_FILM - columnCap) * Math.abs(t) : columnCap;
+			const y = Math.min(ring.surfaceY, bed + cap);
 			positions[i * 3] = x;
-			positions[i * 3 + 1] = ring.surfaceY;
+			positions[i * 3 + 1] = y;
 			positions[i * 3 + 2] = z;
 			normals[i * 3] = nx;
 			normals[i * 3 + 1] = ny;
@@ -6605,7 +6885,7 @@ function buildRiverGeometry(rings, opts) {
 			flow[i * 2] = ring.tx;
 			flow[i * 2 + 1] = ring.tz;
 			river[i * 4] = ring.speed;
-			river[i * 4 + 1] = Math.max(0, ring.surfaceY - sampleBed(opts, x, z));
+			river[i * 4 + 1] = Math.max(0, y - bed);
 			river[i * 4 + 2] = ring.slope;
 			river[i * 4 + 3] = t * opts.bankOvershoot;
 		}
@@ -6689,8 +6969,10 @@ function hitFrom(a, b, t, x, z, capped) {
 	const tl = Math.hypot(tx, tz) || 1;
 	tx /= tl;
 	tz /= tl;
-	const halfWidth = a.halfWidth + (b.halfWidth - a.halfWidth) * t;
-	const across = ((x - cx) * -tz + (z - cz) * tx) / (halfWidth || 1);
+	const signed = (x - cx) * -tz + (z - cz) * tx;
+	const lerp = (u, v) => u + (v - u) * t;
+	const halfWidth = signed < 0 ? lerp(a.halfRight, b.halfRight) : lerp(a.halfLeft, b.halfLeft);
+	const across = signed / (halfWidth || 1);
 	return {
 		inside: !capped && Math.abs(across) <= 1,
 		across,
@@ -6726,7 +7008,7 @@ function detectFalls(rings, opts = {}) {
 			topY: lip.surfaceY,
 			baseY: base.surfaceY,
 			drop,
-			halfWidth: base.halfWidth,
+			halfWidth: (base.halfLeft + base.halfRight) / 2,
 			dirX: base.tx,
 			dirZ: base.tz,
 			speed: base.speed
@@ -6930,6 +7212,15 @@ uniform float uRippleStrength;
 uniform float uFlowRate;
 uniform float uSparkle;
 uniform float uFresnelScale;
+/**
+ * Rocks standing in the current: xz = centre, z = radius, w = how much of the
+ * water they break (0 = drowned and quiet, 1 = the crest stands proud).
+ * The water does not flow AROUND them in any simulated sense — it is told
+ * where they are and paints what a current does when it meets one: a bow
+ * cushion upstream, a broken wake downstream, and a bent surface between.
+ */
+uniform int uRockCount;
+uniform vec4 uRocks[8];
 
 varying vec3 vWorldPosition;
 varying vec3 vSurfaceNormal;
@@ -6970,6 +7261,53 @@ void main() {
   float across = vRiver.w;
 
   vec2 dir = normalize(vFlow + vec2(1e-5, 0.0));
+
+  // ── rocks in the current ────────────────────────────────────────────────
+  // Three things happen where a stream meets a boulder, and all three are
+  // read off the same geometry: the flow BENDS around it (a doublet, the
+  // textbook potential flow past a cylinder), it piles into a bow cushion on
+  // the upstream face, and it tears into a broken wake behind. Everything is
+  // in flow space, so a rock in a bend behaves like a rock in a straight.
+  vec2 bend = vec2(0.0);
+  float bow = 0.0;
+  float wake = 0.0;
+  float shed = 0.0;
+  for (int i = 0; i < 8; i++) {
+    if (i >= uRockCount) break;
+    vec4 rock = uRocks[i];
+    float R = max(rock.z, 0.02);
+    vec2 rel = vWorldPosition.xz - rock.xy;
+    float d = length(rel);
+    if (d > R * 6.0) continue;
+    float breaks = rock.w;
+    // flow-space: +s downstream of the rock, t across it
+    float s = dot(rel, dir);
+    float t = dot(rel, vec2(-dir.y, dir.x));
+    // the doublet: strength falls as 1/r², and inside the rock it is capped
+    // so the field never explodes at the centre
+    float rr = max(d, R);
+    // the BEND is not whitewater: even a drowned stone turns the sheen
+    // around itself, so it never fades out with how proud the rock stands
+    bend += (rel / rr) * (R * R / (rr * rr)) * max(breaks, 0.55);
+    // BOW: a cushion of piled water on the upstream face, brightest dead
+    // ahead of the stone and gone by its shoulders
+    float upstream = smoothstep(0.0, -R * 1.1, s);
+    bow += upstream * (1.0 - smoothstep(R * 0.9, R * 2.0, d)) *
+           (1.0 - smoothstep(R * 0.7, R * 1.6, abs(t))) * breaks;
+    // WAKE: a V opening downstream, fading over a few radii
+    float len = R * 5.0;
+    float along = clamp(s / len, 0.0, 1.0);
+    float halfWake = R * (0.5 + 1.3 * along);
+    wake += step(0.0, s) * (1.0 - along) * (1.0 - along) *
+            (1.0 - smoothstep(halfWake * 0.45, halfWake, abs(t))) * breaks;
+    // the SHOULDERS shed water fastest — that is where the white tears off
+    shed += (1.0 - smoothstep(R * 0.8, R * 1.7, d)) *
+            smoothstep(R * 0.35, R * 0.95, abs(t)) * step(-R * 0.6, s) * breaks;
+  }
+  // a bent surface, not a bent texture: rotating the frame the ripple normal
+  // is built in is what makes the sheen sweep around a stone
+  dir = normalize(dir + clamp(bend, vec2(-1.2), vec2(1.2)));
+
   vec3 dir3 = vec3(dir.x, 0.0, dir.y);
   vec3 perp3 = vec3(-dir.y, 0.0, dir.x);
 
@@ -7036,6 +7374,17 @@ void main() {
   float foam = smoothstep(0.74 - 0.45 * drive, 1.02 - 0.24 * drive, streak) * min(drive, 1.0);
   // crest froth: the tops of standing waves in a real rapid always carry white
   foam = max(foam, smoothstep(0.68, 0.96, ripple.x) * smoothstep(0.4, 1.0, rapids) * uFoam * 0.5);
+
+  // rock whitewater: the cushion is a smooth pile (white but soft-edged), the
+  // wake and the shoulders are TORN, so they ride the advected noise and boil
+  // instead of sitting there as a painted decal
+  float boil = 0.5 + 0.5 * sin(uTime * 3.1 + vFlowUv.x * 2.7);
+  float rockFoam = clamp(bow * 1.6, 0.0, 1.0) * (0.62 + 0.38 * boil);
+  rockFoam = max(rockFoam, clamp(wake * 1.5, 0.0, 1.0) * smoothstep(0.24, 0.72, streak) * 1.3);
+  rockFoam = max(rockFoam, clamp(shed * 1.5, 0.0, 1.0) * smoothstep(0.32, 0.8, streak));
+  // a boulder in a millpond barely whitens; the same boulder in a chute tears
+  foam = max(foam, clamp(rockFoam, 0.0, 1.0) * smoothstep(0.15, 0.9, speed) * uFoam);
+
   // froth can never be more present than the water carrying it
   foam = clamp(foam, 0.0, 1.0) * smoothstep(0.02, 0.14, column);
 
@@ -7132,6 +7481,14 @@ const METERS_PER_ACROSS_SEGMENT = 1.5;
 * flow over it, wide enough that terrain grain does not fizz the whole river. */
 const COLUMN_BLUR_PER_HALF_WIDTH = .35;
 const COLUMN_BLUR_MAX = 1.2;
+/** Rocks the shader can carry at once (the nearest ones win). */
+const ROCK_SLOTS = 8;
+/** How often the tree is re-scanned for things standing in the water (s). */
+const ROCK_RESCAN = .5;
+/** A rock stops mattering past this many of its own radii from the camera —
+* never sooner than ROCK_FADE_MIN, or a pebble would blink out at arm's reach. */
+const ROCK_FADE_RADII = 42;
+const ROCK_FADE_MIN = 26;
 /** How hard the current drags a body toward the water's own velocity (1/s at
 * `flowForce: 1`). Drag, not thrust: nothing ever outruns the river. Tuned
 * against CharacterController3D, whose stand-still damping fights it — at this
@@ -7150,6 +7507,8 @@ const DEFAULT_COLORS = {
 	bank: "#465447"
 };
 const FOAM_COLOR = "#e9f2ef";
+/** Per-frame scratch (no allocation in the render path). */
+const rockCamScratch = new Vector3();
 /** Fixed look constants — the props stay intent-level, these carry the craft. */
 const LOOK = {
 	/** Pattern units per meter of flow space. */
@@ -7205,6 +7564,7 @@ var River3D = class River3D extends Node3D {
 		sunColor: { default: "#fff6e0" },
 		sunIntensity: { default: 1 },
 		terrain: { default: "" },
+		carve: { default: true },
 		flowForce: { default: 1 },
 		spray: { default: 1 }
 	};
@@ -7240,6 +7600,18 @@ var River3D = class River3D extends Node3D {
 	sunIntensity = 1;
 	/** Drape target path; empty = auto-find the first Terrain3D in the tree. */
 	terrain = "";
+	/**
+	* Cut the bed. Real water arrives on a hillside and erodes itself a channel;
+	* a ribbon laid on raw ground has nothing holding it and reads as a strip of
+	* blue hovering over the grass. With this on, the river trenches its own
+	* course into the terrain it drapes on — banks the player can walk into, a
+	* collider and `heightAt` that agree with it, and splat that paints the cut.
+	*
+	* Off means you carve it yourself with `Terrain3D.channels` (or the reach is
+	* genuinely a flat flood plain). Either way the surface is FITTED to
+	* whatever ground it finds: it can never stand above its own banks.
+	*/
+	carve = true;
 	/** How hard the current sweeps bodies downstream (0 = visual only). */
 	flowForce = 1;
 	/**
@@ -7255,6 +7627,11 @@ var River3D = class River3D extends Node3D {
 	sprayKey = "";
 	courseKey = "";
 	bedAt = null;
+	/** Whether the last course was fitted to real ground (see buildRiverRings). */
+	fitted = false;
+	/** Everything standing in the current, rescanned on a slow timer. */
+	rocks = [];
+	rockScanAt = -1;
 	world = [
 		0,
 		0,
@@ -7295,6 +7672,12 @@ var River3D = class River3D extends Node3D {
 	_createObject3D() {
 		return new Mesh(new BufferGeometry(), this.buildMaterial());
 	}
+	onReady() {
+		this.ensureCourse();
+	}
+	onExitTree() {
+		findDrapeTerrain(this, this.terrain)?._setExternalChannel(this, null);
+	}
 	update(dt) {
 		this.time += dt;
 		this.ensureCourse();
@@ -7307,6 +7690,27 @@ var River3D = class River3D extends Node3D {
 		this.rebuildIfNeeded(mesh);
 		this.syncUniforms(mesh);
 	}
+	/** Rocks are picked per FRAME (nearest to the eye), scanned on a timer. */
+	_onRender3D(ctx) {
+		if (this.rings.length === 0) return;
+		if (this.rockScanAt < 0 || this.time - this.rockScanAt > ROCK_RESCAN) {
+			this.rockScanAt = this.time;
+			this.scanRocks();
+		}
+		const u = this._ensureObject3D().material.uniforms;
+		this.syncRocks(u, ctx.camera.getWorldPosition(rockCamScratch));
+	}
+	/**
+	* @internal Water surface height over a world point, or null where this
+	* river does not run — the question scattered vegetation asks before it
+	* plants a blade (see {@link WetSurface}).
+	*/
+	_waterYAt(x, z) {
+		if (this.rings.length === 0) return null;
+		const [wx, wy, wz] = this.world;
+		const hit = projectToRiver(this.rings, x - wx, z - wz);
+		return hit?.inside ? hit.surfaceY + wy : null;
+	}
 	/**
 	* Where a WORLD point sits in the channel — the query gameplay scripts run
 	* (steer a raft, drown a torch, decide a ford is too fast to cross). `null`
@@ -7359,6 +7763,31 @@ var River3D = class River3D extends Node3D {
 	widthProfile() {
 		return this.widths.length > 0 ? this.widths : [this.width];
 	}
+	/**
+	* Cut (or release) this river's trench in the terrain it drapes on.
+	*
+	* Runs at ready as well as on every course rebuild: the heightfield collider
+	* is built before the first render sync, so a bed cut only at draw time
+	* would leave the player walking on ground that is no longer there.
+	*/
+	applyCarve(terrain) {
+		if (!terrain) return;
+		if (!this.carve || this.path.length < 2) {
+			terrain._setExternalChannel(this, null);
+			return;
+		}
+		terrain._setExternalChannel(this, null);
+		const [wx, , wz] = worldXZY(this);
+		const [tx, , tz] = worldXZY(terrain);
+		const hm = terrain._heightmap();
+		terrain._setExternalChannel(this, riverCarveChannels({
+			path: this.path.map((p) => [(p[0] ?? 0) + wx - tx, (p[1] ?? 0) + wz - tz]),
+			widths: this.widthProfile(),
+			depth: this.depth,
+			cell: (terrain.size[0] ?? 1) / Math.max(1, hm.segsX),
+			groundAt: (x, z) => hm.heightAt(x, z)
+		}));
+	}
 	/** Resolve the drape terrain; an explicit path that misses is a hard error. */
 	resolveTerrain() {
 		const terrain = findDrapeTerrain(this, this.terrain);
@@ -7378,6 +7807,7 @@ var River3D = class River3D extends Node3D {
 			this.widths,
 			this.depth,
 			this.flowSpeed,
+			this.carve,
 			terrain ? terrain.name : "",
 			world
 		]);
@@ -7385,6 +7815,7 @@ var River3D = class River3D extends Node3D {
 		this.courseKey = key;
 		this.world = world;
 		this.bedAt = null;
+		this.applyCarve(terrain);
 		if (this.path.length < 2) {
 			this.rings = [];
 			this.falls = [];
@@ -7392,6 +7823,7 @@ var River3D = class River3D extends Node3D {
 		}
 		const [wx, wy, wz] = world;
 		this.bedAt = terrain ? (lx, lz) => terrain.heightAt(lx + wx, lz + wz) - wy : () => -this.depth;
+		this.fitted = terrain !== null;
 		const widths = this.widthProfile();
 		const narrow = Math.min(...widths);
 		this.rings = buildRiverRings({
@@ -7400,7 +7832,8 @@ var River3D = class River3D extends Node3D {
 			depth: this.depth,
 			flowSpeed: this.flowSpeed,
 			step: Math.min(Math.max(narrow * STEP_PER_WIDTH, STEP_MIN), STEP_MAX),
-			bedAt: this.bedAt
+			bedAt: this.bedAt,
+			fit: this.fitted
 		});
 		this.falls = detectFalls(this.rings);
 		return true;
@@ -7419,7 +7852,7 @@ var River3D = class River3D extends Node3D {
 		const wide = Math.max(...widths);
 		const data = buildRiverGeometry(this.rings, {
 			acrossSegments: Math.min(ACROSS_MAX, Math.max(ACROSS_MIN, Math.round(wide / METERS_PER_ACROSS_SEGMENT))),
-			bankOvershoot: BANK_OVERSHOOT,
+			bankOvershoot: this.fitted ? 1 : BANK_OVERSHOOT,
 			bedBlur: Math.min(narrow / 2 * COLUMN_BLUR_PER_HALF_WIDTH, COLUMN_BLUR_MAX),
 			bedAt: this.bedAt
 		});
@@ -7462,6 +7895,8 @@ var River3D = class River3D extends Node3D {
 				uRippleStrength: { value: LOOK.rippleStrength * this.ripples },
 				uFlowRate: { value: LOOK.flowRate },
 				uSparkle: { value: this.ripples },
+				uRockCount: { value: 0 },
+				uRocks: { value: Array.from({ length: ROCK_SLOTS }, () => new Vector4()) },
 				uFresnelScale: { value: LOOK.fresnelScale },
 				uStandingAmp: { value: LOOK.standingAmp },
 				uGlideAmp: { value: LOOK.glideAmp }
@@ -7472,6 +7907,88 @@ var River3D = class River3D extends Node3D {
 			side: DoubleSide
 		});
 	}
+	/**
+	* Find everything standing in the current.
+	*
+	* A boulder in a creek is not a physics problem — it is a thing the water
+	* has to be TOLD about, or the stream runs through it as if it were painted
+	* on. Any mesh whose footprint lands inside the wetted channel and whose top
+	* reaches near the surface counts, `InstancedMesh3D` rows included (a rock
+	* scatter is one node with fifty stones in it).
+	*
+	* Scanned on a slow timer rather than per frame: rocks do not move often,
+	* and a river with a hundred of them still writes only the nearest few.
+	*/
+	scanRocks() {
+		const found = [];
+		const [wx, wy, wz] = this.world;
+		/** Keep a candidate if it actually stands IN the water column. */
+		const consider = (x, z, radius, bottom, top) => {
+			if (radius <= .02) return;
+			const hit = projectToRiver(this.rings, x - wx, z - wz);
+			if (!hit || !hit.inside) return;
+			const surface = hit.surfaceY + wy;
+			if (bottom > surface) return;
+			const bed = surface - this.depth;
+			if (top < bed) return;
+			const breaks = Math.min(Math.max((top - bed) / Math.max(this.depth, .05), .2), 1);
+			found.push({
+				x,
+				z,
+				radius,
+				breaks
+			});
+		};
+		let root = this;
+		while (root.parent) root = root.parent;
+		const walk = (node) => {
+			if (node instanceof InstancedMesh3D) {
+				const [sx, sy, sz] = node.size;
+				const [ox, oy, oz] = worldXZY(node);
+				for (const row of node.transforms) {
+					const scale = row[4] ?? 1;
+					const x = ox + (row[0] ?? 0);
+					const y = oy + (row[1] ?? 0);
+					const z = oz + (row[2] ?? 0);
+					const half = (sy ?? 1) * scale / 2;
+					consider(x, z, Math.max(sx, sz) * scale / 2, y - half, y + half);
+				}
+			} else if (node instanceof MeshInstance3D) {
+				const [sx, sy, sz] = node.size;
+				const [x, y, z] = worldXZY(node);
+				const half = (sy ?? 1) / 2;
+				consider(x, z, Math.max(sx, sz) / 2, y - half, y + half);
+			}
+			for (const child of node.children) walk(child);
+		};
+		walk(root);
+		this.rocks = found;
+	}
+	/** Write the nearest rocks into the shader, faded in by distance. */
+	syncRocks(u, camera) {
+		const slots = u.uRocks?.value;
+		const count = u.uRockCount;
+		if (!slots || !count) return;
+		if (this.rocks.length === 0) {
+			count.value = 0;
+			return;
+		}
+		const near = [...this.rocks].map((r) => ({
+			r,
+			d: (r.x - camera.x) ** 2 + (r.z - camera.z) ** 2
+		})).sort((a, b) => a.d - b.d).slice(0, ROCK_SLOTS);
+		let n = 0;
+		for (const { r, d } of near) {
+			const far = Math.max(r.radius * ROCK_FADE_RADII, ROCK_FADE_MIN);
+			const t = Math.min(Math.sqrt(d) / far, 1);
+			const k = Math.min(Math.max((t - .6) / .4, 0), 1);
+			const fade = 1 - k * k * (3 - 2 * k);
+			if (fade <= .01) continue;
+			slots[n]?.set(r.x, r.z, r.radius, r.breaks * fade);
+			n++;
+		}
+		count.value = n;
+	}
 	syncUniforms(mesh) {
 		const u = mesh.material.uniforms;
 		const set = (key, value) => {
@@ -10884,4 +11401,4 @@ function registerNodes3D() {
 	registerNode(CharacterBody3D);
 }
 //#endregion
-export { QUARTER_PITCH as A, BoneAttachment3D as C, TERRAIN_THEMES as D, DEFAULT_TERRAIN_TEXTURE_BASE as E, keyboardIntensity as M, movementState as N, terrainThemeLayers as O, rigPose as P, BoneLookAt3D as S, Terrain3D as T, Flowers3D as _, Trail3D as a, CharacterController3D as b, Particles3D as c, DirectionalLight3D as d, OmniLight3D as f, DENSITY_PRESETS as g, Foliage3D as h, Tree3D as i, cameraRelative as j, Joint3D as k, ModelInstance3D as l, MeshInstance3D as m, VOXEL_PALETTE as n, River3D as o, InstancedMesh3D as p, VoxelGrid3D as r, traceDownhillPath as s, registerNodes3D as t, LoftMesh3D as u, resolveFlowerDensity as v, Billboard3D as w, Camera3D as x, FLOWER_VARIETIES as y };
+export { Joint3D as A, BoneLookAt3D as C, DEFAULT_TERRAIN_TEXTURE_BASE as D, Terrain3D as E, rigPose as F, cameraRelative as M, keyboardIntensity as N, TERRAIN_THEMES as O, movementState as P, Camera3D as S, Billboard3D as T, DENSITY_PRESETS as _, Trail3D as a, FLOWER_VARIETIES as b, traceDownhillPath as c, LoftMesh3D as d, DirectionalLight3D as f, Foliage3D as g, MeshInstance3D as h, Tree3D as i, QUARTER_PITCH as j, terrainThemeLayers as k, Particles3D as l, InstancedMesh3D as m, VOXEL_PALETTE as n, River3D as o, OmniLight3D as p, VoxelGrid3D as r, riverCarveChannels as s, registerNodes3D as t, ModelInstance3D as u, Flowers3D as v, BoneAttachment3D as w, CharacterController3D as x, resolveFlowerDensity as y };