sindicate 0.12.0 → 0.15.0

package/src/world/roadTerrain.js

@@ -0,0 +1,263 @@
+// ROAD TERRAIN — the ground has to agree with the roads.
+//
+// Two edits, both applied by wrapping a game's own heightAt:
+//   · PADS — a junction is a rigid prefab: it cannot follow a slope, so the ground under its
+//     footprint is levelled and blended back out to the natural terrain.
+//   · CORRIDORS — a link road carries its own solved profile; the ground is cut or filled to
+//     meet it across the carriageway, then blended out over the verge.
+//
+//   const heightAt = makeRoadTerrain(naturalHeightAt, { pads, corridors })
+//
+// Wrapping rather than baking means the terrain cook, collision, grass occupancy and
+// anything else that samples the ground all see the same edited surface for free.
+import { smoothstep } from './geo.js';
+
+// segment lookup on a uniform grid — a world's worth of road is far too many segments to
+// walk per lattice vertex, and the lattice is ~1.7M vertices
+function segmentIndex(corridors, cell) {
+  const buckets = new Map();
+  const key = (i, j) => `${i},${j}`;
+  const segs = [];
+  for (const c of corridors) {
+    const line = c.centreline;
+    // a batter can run a long way when the road crosses a deep valley, so the bucket reach
+    // has to cover the whole earthwork, not just the carriageway
+    const reach = (c.halfWidth ?? 5) + (c.maxEarthwork ?? 90);
+    for (let i = 0; i < line.length - 1; i++) {
+      const a = line[i], b = line[i + 1];
+      const s = {
+        ax: a[0], ay: a[1], az: a[2], bx: b[0], by: b[1], bz: b[2],
+        half: c.halfWidth ?? 5, drop: c.drop ?? 0, batter: c.batter ?? 0.5,
+      };
+      const id = segs.push(s) - 1;
+      const i0 = Math.floor((Math.min(a[0], b[0]) - reach) / cell), i1 = Math.floor((Math.max(a[0], b[0]) + reach) / cell);
+      const j0 = Math.floor((Math.min(a[2], b[2]) - reach) / cell), j1 = Math.floor((Math.max(a[2], b[2]) + reach) / cell);
+      for (let ii = i0; ii <= i1; ii++) for (let jj = j0; jj <= j1; jj++) {
+        const k = key(ii, jj);
+        if (!buckets.has(k)) buckets.set(k, []);
+        buckets.get(k).push(id);
+      }
+    }
+  }
+  return {
+    near(x, z) { return buckets.get(key(Math.floor(x / cell), Math.floor(z / cell))) ?? null; },
+    segs,
+  };
+}
+
+// How far outside a pad's footprint a point is (0 inside). A simple junction is a circle,
+// but an interchange is a long rectangle with slip roads and spurs down one axis — flatten a
+// circle under one of those and the arms stick out over thin air.
+function padDistance(p, x, z) {
+  const dx = x - p.x, dz = z - p.z;
+  if (p.halfX == null) return Math.max(Math.hypot(dx, dz) - (p.radius ?? 0), 0);
+  const c = Math.cos(p.yaw ?? 0), s = Math.sin(p.yaw ?? 0);
+  const lx = Math.abs(dx * c - dz * s) - p.halfX;      // into the pad's own frame
+  const lz = Math.abs(dx * s + dz * c) - p.halfZ;
+  return Math.hypot(Math.max(lx, 0), Math.max(lz, 0));
+}
+
+// THE GROUND UNDER A PIECE, TAKEN FROM THE PIECE ITSELF.
+//
+// The law: no road may fly with nothing under it — except a deck, which flies over the road
+// it crosses. Both follow from one rule: the ground tracks the LOWEST DRIVEABLE SURFACE at
+// each spot. Under a bridge the lowest surface is the carriageway below, so the ground is cut
+// to it and the deck spans the gap; everywhere else the lowest surface is the only surface,
+// so the ground comes up to meet it — slip roads included, wherever they curve.
+//
+// `points` must be DECK vertices only. Pillars, supports and retaining walls hang far below
+// the road they carry; let those in and the ground is dug out from under the whole junction.
+export function surfaceRaster(points, { x = 0, z = 0, yaw = 0, halfX, halfZ, res = 3, drop = 0.3, batter = 0.5 }) {
+  const nx = Math.max(1, Math.ceil((halfX * 2) / res));
+  const nz = Math.max(1, Math.ceil((halfZ * 2) / res));
+  const h = new Float32Array(nx * nz).fill(Infinity);
+  const c = Math.cos(yaw), s = Math.sin(yaw);
+  for (const p of points) {
+    const dx = p[0] - x, dz = p[2] - z;
+    const lx = dx * c - dz * s, lz = dx * s + dz * c;      // into the piece's own frame
+    const i = Math.floor((lx + halfX) / res), j = Math.floor((lz + halfZ) / res);
+    if (i < 0 || j < 0 || i >= nx || j >= nz) continue;
+    const k = j * nx + i;
+    if (p[1] < h[k]) h[k] = p[1];                          // LOWEST deck wins
+  }
+  // chamfer distance transform: every empty cell learns its nearest deck and how far away,
+  // so the batter can slope out of it in O(1) per query
+  const d = new Float32Array(nx * nz).fill(Infinity);
+  for (let k = 0; k < h.length; k++) if (h[k] < Infinity) d[k] = 0;
+  const relax = (k, k2, cost) => { if (d[k2] + cost < d[k]) { d[k] = d[k2] + cost; h[k] = h[k2]; } };
+  for (let j = 0; j < nz; j++) for (let i = 0; i < nx; i++) {
+    const k = j * nx + i;
+    if (i > 0) relax(k, k - 1, res);
+    if (j > 0) relax(k, k - nx, res);
+    if (i > 0 && j > 0) relax(k, k - nx - 1, res * 1.414);
+    if (i < nx - 1 && j > 0) relax(k, k - nx + 1, res * 1.414);
+  }
+  for (let j = nz - 1; j >= 0; j--) for (let i = nx - 1; i >= 0; i--) {
+    const k = j * nx + i;
+    if (i < nx - 1) relax(k, k + 1, res);
+    if (j < nz - 1) relax(k, k + nx, res);
+    if (i < nx - 1 && j < nz - 1) relax(k, k + nx + 1, res * 1.414);
+    if (i > 0 && j < nz - 1) relax(k, k + nx - 1, res * 1.414);
+  }
+  return { nx, nz, res, x, z, yaw, halfX, halfZ, h, d, drop, batter };
+}
+
+function rasterAt(r, x, z) {
+  const c = Math.cos(r.yaw), s = Math.sin(r.yaw);
+  const dx = x - r.x, dz = z - r.z;
+  const lx = dx * c - dz * s, lz = dx * s + dz * c;
+  const outX = Math.max(Math.abs(lx) - r.halfX, 0), outZ = Math.max(Math.abs(lz) - r.halfZ, 0);
+  const i = Math.min(Math.max(Math.floor((lx + r.halfX) / r.res), 0), r.nx - 1);
+  const j = Math.min(Math.max(Math.floor((lz + r.halfZ) / r.res), 0), r.nz - 1);
+  const k = j * r.nx + i;
+  if (!(r.h[k] < Infinity)) return null;
+  return { y: r.h[k], d: r.d[k] + Math.hypot(outX, outZ) };
+}
+
+export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfaces = [], cell = 32 } = {}) {
+  const index = corridors.length ? segmentIndex(corridors, cell) : null;
+
+  return function heightAt(x, z) {
+    let h = baseHeightAt(x, z);
+
+    // ── junction pads: level, because a prefab junction cannot bend ──
+    for (const p of pads) {
+      const d = padDistance(p, x, z);
+      // sit the dirt a little under the deck, or the two surfaces fight for the same pixels
+      const y = p.y - (p.drop ?? 0);
+      if (d <= 0) { h = y; continue; }                        // inside the footprint: level
+      const reach = d * (p.batter ?? 0.5);                    // same earthwork law as a link
+      h = Math.min(Math.max(h, y - reach), y + reach);
+    }
+
+    // ── piece decks: cut the plateau open wherever a deck runs BELOW it ──
+    // The pad above gives a junction the level ground it needs. This pass then digs out the
+    // parts that live under grade — the motorway through an overpass, the slip roads
+    // descending to it — so those are open to the sky and the deck above spans a real gap.
+    // It only ever lowers: raising here would make the ground follow every kerb and ramp,
+    // which turns a junction into a lumpy mess.
+    for (const r of surfaces) {
+      const hit = rasterAt(r, x, z);
+      if (!hit) continue;
+      const y = hit.y - r.drop;
+      // retaining-wall gradient out of the cut, so it stays tight to the road below
+      h = Math.min(h, y + hit.d * (r.wall ?? 3));
+    }
+
+    // ── link corridors: cut/fill the ground to the road's own profile ──
+    if (index) {
+      const ids = index.near(x, z);
+      if (ids) {
+        let best = null;
+        for (const id of ids) {
+          const s = index.segs[id];
+          const dx = s.bx - s.ax, dz = s.bz - s.az;
+          const len2 = dx * dx + dz * dz || 1e-6;
+          const t = Math.min(1, Math.max(0, ((x - s.ax) * dx + (z - s.az) * dz) / len2));
+          const px = s.ax + dx * t, pz = s.az + dz * t;
+          const d = Math.hypot(x - px, z - pz);
+          if (!best || d < best.d) best = { d, s, y: s.ay + (s.by - s.ay) * t };
+        }
+        if (best) {
+          const road = best.y - best.s.drop;
+          if (best.d <= best.s.half) h = road;                 // the bed itself
+          else {
+            // EMBANKMENT / CUTTING: outside the bed the ground may only climb away from the
+            // road at the batter slope (1:2 by default). Fill rises to meet a road above the
+            // valley, cutting falls away from a road below the hill, and natural ground
+            // further out is left alone — no fixed blend distance to get wrong.
+            const reach = (best.d - best.s.half) * best.s.batter;
+            h = Math.min(Math.max(h, road - reach), road + reach);
+          }
+        }
+      }
+    }
+
+    return h;
+  };
+}
+
+// The height a junction should sit at: the average ground across its footprint, so it is
+// neither buried on one side nor stilted on the other. `spread` is how much the ground
+// varies underneath — a site law: junctions go on the flats.
+export function seatHeight(heightAt, x, z, radius, rings = 3, spokes = 8) {
+  // `radius` may be a footprint {halfX, halfZ, yaw}; sample its own extent in that case
+  if (typeof radius === 'object' && radius) {
+    const { halfX, halfZ, yaw = 0 } = radius;
+    const c = Math.cos(yaw), sn = Math.sin(yaw);
+    let sum = 0, n = 0, lo = Infinity, hi = -Infinity;
+    for (let i = -rings; i <= rings; i++) {
+      for (let j = -rings; j <= rings; j++) {
+        const lx = (i / rings) * halfX, lz = (j / rings) * halfZ;
+        const h = heightAt(x + lx * c + lz * sn, z - lx * sn + lz * c);
+        sum += h; n++;
+        if (h < lo) lo = h;
+        if (h > hi) hi = h;
+      }
+    }
+    return { y: sum / n, spread: hi - lo };
+  }
+  let sum = heightAt(x, z), n = 1, lo = Infinity, hi = -Infinity;
+  for (let r = 1; r <= rings; r++) {
+    const rad = (radius * r) / rings;
+    for (let a = 0; a < spokes; a++) {
+      const th = (a / spokes) * Math.PI * 2;
+      const h = heightAt(x + Math.cos(th) * rad, z + Math.sin(th) * rad);
+      sum += h; n++;
+      if (h < lo) lo = h;
+      if (h > hi) hi = h;
+    }
+  }
+  return { y: sum / n, spread: hi - lo };
+}
+
+// Where should a junction go? Sample the map, keep the flat spots, and take the pair that is
+// both well separated and interestingly different in height — the "sites go on the flats"
+// law from the road plan, applied automatically.
+// Several sites at once, for a whole map: flat enough to stand a junction on, spread out
+// enough to be separate places. Greedy farthest-point selection keeps them from clumping.
+export function pickManySites(heightAt, { count = 5, half = 600, step = 90, radius = 60, minGap = 300 } = {}) {
+  const cands = [];
+  for (let x = -half; x <= half; x += step) {
+    for (let z = -half; z <= half; z += step) {
+      const seat = seatHeight(heightAt, x, z, radius);
+      if (seat.spread > radius * 0.3) continue;
+      cands.push({ x, z, y: seat.y, spread: seat.spread });
+    }
+  }
+  if (!cands.length) return [];
+  cands.sort((a, b) => a.spread - b.spread);       // flattest first
+  const chosen = [cands[0]];
+  for (const c of cands) {
+    if (chosen.length >= count) break;
+    if (chosen.every((s) => Math.hypot(s.x - c.x, s.z - c.z) >= minGap)) chosen.push(c);
+  }
+  return chosen;
+}
+
+export function pickSites(heightAt, { half = 600, step = 90, radius = 60, minGap = 340, maxGap = 760, maxGrade = 0.07 } = {}) {
+  const cands = [];
+  for (let x = -half; x <= half; x += step) {
+    for (let z = -half; z <= half; z += step) {
+      const seat = seatHeight(heightAt, x, z, radius);
+      if (seat.spread > radius * 0.28) continue;         // too lumpy to stand a junction on
+      cands.push({ x, z, y: seat.y, spread: seat.spread });
+    }
+  }
+  let best = null;
+  for (let i = 0; i < cands.length; i++) {
+    for (let j = i + 1; j < cands.length; j++) {
+      const a = cands[i], b = cands[j];
+      const gap = Math.hypot(a.x - b.x, a.z - b.z);
+      if (gap < minGap || gap > maxGap) continue;
+      // interesting relief, but only as much as a road can actually climb between them:
+      // pairing the highest peak with the deepest valley just guarantees an unbuildable link
+      const dy = Math.abs(a.y - b.y);
+      const climbable = gap * maxGrade * 0.55;
+      const relief = dy <= climbable ? dy : climbable - (dy - climbable) * 3;
+      const score = relief * 2 - (a.spread + b.spread) + gap * 0.02;
+      if (!best || score > best.score) best = { a, b, gap, score };
+    }
+  }
+  return best;
+}

package/src/world/waterLevels.js

@@ -0,0 +1,95 @@
+// THE WATER-LEVEL BAKE (world splits, step 3b) — R.wy, the per-vertex water surface every
+// carve, sheet, swimmer and bridge reads. Moved verbatim from the games (identical bodies;
+// western adds PASS 0 + the R.bd gates, which subsume fable's ungated loops — an unsolved
+// course simply runs the live passes).
+//
+//   PASS 0 — THE SURVEY GOVERNS (solved courses, R.bd present): wy = solved bed + baked
+//            reach depth, source/terminus lake pins, then strictly monotone — the uphill
+//            forgiveness below does not apply to a solved course.
+//   PASS 1 — raw level = lowest of the ±ww cross-section on the river-free ground, −1 m
+//            (cross-section reach capped at 10 m — the wide-trunk lesson: ±26 m banks
+//            reached distant low ground and PASS 2 dragged whole reaches to sea level).
+//   PASS 2 — terminus pin (end lake surface −0.8 / parent trunk's level at the join / the
+//            open sea), monotone-downhill, floor at sea level. Trunks must precede their
+//            tributaries in the array so a join reads a FINALIZED parent level.
+//   PASS 3 — riffle relief: water rides within riffleCut of the river-free ground (highest
+//            of centreline AND both banks at ±(ww+4)) so the monotone floor cannot gouge a
+//            slot-gorge across a rise ('rivers underground').
+//   PASS 4 — estuary descent: sea-reaching trunks ease to sea level anchored at the
+//            SHORELINE node (tails run out to sea), pin seaward, re-monotone the reach.
+//
+// groundFn(x, z) is the game's river-free pristine ground — rawHeight(x, z, true) in both
+// counties. Call this at the game's bake site (BELOW its rawHeight, per the TDZ law both
+// files document). Headless by law.
+import { lerp, smoothstep } from './geo.js';
+
+function riverWyAt(R, p) {                          // baked level of R nearest p — for confluences
+  let best = Infinity, wy = R.wy[0];
+  for (let i = 0; i < R.pts.length; i++) {
+    const d = Math.hypot(R.pts[i].x - p.x, R.pts[i].z - p.z);
+    if (d < best) { best = d; wy = R.wy[i]; }
+  }
+  return wy;
+}
+
+export function bakeWaterLevels(rivers, groundFn, { seaLevel, coastZ, riffleCut = 1.6 } = {}) {
+  // PASS 0
+  for (const R of rivers) {
+    if (!R.bd) continue;
+    const n = R.pts.length;
+    R.wy = R.bd.map((b, i) => b + R.wdep[i]);
+    if (R.srcLake) R.wy[0] = R.srcLake.level - 0.3;
+    if (R.endLake) R.wy[n - 1] = R.endLake.level - 0.8;
+    for (let i = 1; i < n; i++) R.wy[i] = Math.min(R.wy[i], R.wy[i - 1]);
+  }
+  // PASS 1
+  for (const R of rivers) {
+    if (R.bd) continue;
+    R.wy = R.pts.map((p, i, a) => {
+      const pa = a[Math.max(0, i - 1)], pb = a[Math.min(a.length - 1, i + 1)];
+      let tx = pb.x - pa.x, tz = pb.z - pa.z; const tl = Math.hypot(tx, tz) || 1; const nx = -tz / tl, nz = tx / tl;
+      const w = Math.min(R.ww[i], 10);
+      return Math.min(groundFn(p.x, p.z), groundFn(p.x + nx * w, p.z + nz * w), groundFn(p.x - nx * w, p.z - nz * w)) - 1.0;
+    });
+  }
+  // PASS 2
+  for (const R of rivers) {
+    if (R.bd) continue;
+    const n = R.wy.length;
+    R.wy[n - 1] = R.endLake ? R.endLake.level - 0.8
+               : R.parent != null ? riverWyAt(rivers[R.parent], R.pts[n - 1])
+               : seaLevel;
+    for (let i = 1; i < n; i++) R.wy[i] = Math.min(R.wy[i], R.wy[i - 1]);
+    for (let i = 0; i < n; i++) R.wy[i] = Math.max(R.wy[i], seaLevel);
+  }
+  // PASS 3
+  for (const R of rivers) {
+    if (R.bd) continue;
+    for (let i = 0; i < R.wy.length; i++) {
+      const p2 = R.pts[i], pa2 = R.pts[Math.max(0, i - 1)], pb2 = R.pts[Math.min(R.pts.length - 1, i + 1)];
+      let tx2 = pb2.x - pa2.x, tz2 = pb2.z - pa2.z; const tl2 = Math.hypot(tx2, tz2) || 1;
+      const nx2 = -tz2 / tl2, nz2 = tx2 / tl2, off2 = R.ww[i] + 4;
+      const gRef = Math.max(
+        groundFn(p2.x, p2.z),
+        groundFn(p2.x + nx2 * off2, p2.z + nz2 * off2),
+        groundFn(p2.x - nx2 * off2, p2.z - nz2 * off2),
+      );
+      R.wy[i] = Math.max(R.wy[i], gRef - riffleCut);
+    }
+  }
+  // PASS 4
+  for (const R of rivers) {
+    if (R.bd || R.parent != null || R.endLake) continue;
+    const n = R.wy.length;
+    if (R.pts[n - 1].z < coastZ) continue;
+    let iShore = n - 1;
+    while (iShore > 0 && groundFn(R.pts[iShore].x, R.pts[iShore].z) < seaLevel + 0.3) iShore--;
+    const K = Math.min(14, iShore);
+    for (let i = iShore - K; i <= iShore; i++) {
+      const t = smoothstep(iShore - K, iShore, i);
+      R.wy[i] = Math.max(seaLevel, lerp(R.wy[i], seaLevel, t));
+    }
+    for (let i = iShore + 1; i < n; i++) R.wy[i] = seaLevel;
+    for (let i = Math.max(1, iShore - Math.min(24, iShore)); i < n; i++) R.wy[i] = Math.min(R.wy[i], R.wy[i - 1]);
+  }
+}

package/src/world/waterMeshes.js

@@ -0,0 +1,168 @@
+// THE WATER MESHES (world splits, step 6) — river ribbons, lake sheets and the sea plane,
+// moved verbatim from western's zones.js. All geometry + per-vertex hydraulic bakes; the
+// MATERIALS stay the game's choice (one shared waterMaterial across lakes, one shared
+// riverMaterial across courses — each distinct refracting material pays its own viewport
+// copy per frame, so sharing collapses the copies however many bodies the county gains).
+import * as THREE from 'three/webgpu';
+
+// A river ribbon: walk the path in ~2m steps, emit left/right cross-section verts at ±w,
+// bake the still-water depth (level − bed) + downstream UVs per vertex, strip the quads.
+// Emitted as ~200 m CHUNKS (each its own geometry + bounding sphere) rather than one
+// course-long mesh: a 3.6 km course has a county-sized bounding sphere, so frustumCulled
+// never actually culled, and refraction pays a viewport copy per DRAW. Boundary
+// cross-section rows are duplicated into both neighbouring chunks — identical baked values
+// from identical inputs, so the strip has no seam.
+export function buildRiverMesh(scene, R, mat, { heightAt }) {
+  const L = THREE.MathUtils.lerp, pts = [];
+  // Reference half-width for the flow bake: the course's own source→mouth hydraulic ramp,
+  // PER STATION — not one course-wide constant. The solved widths are that ramp ±25 %
+  // pool/riffle modulation, and it is the MODULATION continuity should answer to: against a
+  // constant reference, a narrow upstream pool computes faster than a wide downstream riffle
+  // (measured: pools averaged 0.50 m/s to the riffles' 0.44), which is backwards. Against
+  // the local ramp, wide-for-here runs slow and narrow-for-here runs quick, the whole course over.
+  const wEnd = R.pts.length - 1 || 1;
+  const wrefAt = (f) => L(R.wsrc ?? R.w, R.w, f);
+  for (let i = 0; i < R.pts.length - 1; i++) {
+    const a = R.pts[i], b = R.pts[i + 1], steps = Math.max(1, Math.round(Math.hypot(b.x - a.x, b.z - a.z) / 2));
+    for (let s = 0; s < steps; s++) { const t = s / steps; pts.push({ x: L(a.x, b.x, t), z: L(a.z, b.z, t), wy: L(R.wy[i], R.wy[i + 1], t), ww: L(R.ww[i], R.ww[i + 1], t), wr: wrefAt((i + t) / wEnd) }); }
+  }
+  const e = R.pts.length - 1; pts.push({ x: R.pts[e].x, z: R.pts[e].z, wy: R.wy[e], ww: R.ww[e], wr: wrefAt(1) });
+
+  // cross-section resolution scales with the river's width — ~2.4m across (odd → centreline)
+  const K = Math.max(9, Math.min(41, 2 * Math.round(Math.max(...R.ww) / 2.4) + 1));
+  const CHUNK_LEN = 200;   // m of course per geometry
+  const meshes = [];
+  const newChunk = () => ({ verts: [], depths: [], uvs: [], flows: [], drops: [], bWy: [], bX: [], bZ: [], rows: 0 });
+  const pushRow = (c, row) => {
+    for (const [dst, src] of [[c.verts, row.verts], [c.depths, row.depths], [c.uvs, row.uvs],
+      [c.flows, row.flows], [c.drops, row.drops], [c.bWy, row.bWy], [c.bX, row.bX], [c.bZ, row.bZ]]) dst.push(...src);
+    c.rows++;
+  };
+  const flush = (c) => {
+    const idx = [];
+    for (let i = 0; i < c.rows - 1; i++) for (let k = 0; k < K - 1; k++) {
+      const a = i * K + k, b = a + 1, q = (i + 1) * K + k, d = q + 1;
+      idx.push(a, q, b, b, q, d);
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.Float32BufferAttribute(c.verts, 3));
+    geo.setAttribute('aDepth', new THREE.Float32BufferAttribute(c.depths, 1));
+    geo.setAttribute('uv', new THREE.Float32BufferAttribute(c.uvs, 2));
+    geo.setAttribute('aFlow', new THREE.Float32BufferAttribute(c.flows, 2));
+    geo.setAttribute('aDrop', new THREE.Float32BufferAttribute(c.drops, 1));
+    geo.setIndex(idx);
+    const mesh = new THREE.Mesh(geo, mat);
+    // per-chunk bake data — refreshRiverDepths already iterates N meshes, so each chunk
+    // re-derives its own aDepth after the terrain pads mutate heightAt
+    mesh.userData.riverVerts = { wy: Float32Array.from(c.bWy), x: Float32Array.from(c.bX), z: Float32Array.from(c.bZ) };
+    geo.computeBoundingSphere();
+    mesh.frustumCulled = true; // refraction pays a viewport copy per DRAW — never draw off-screen chunks
+    scene.add(mesh);
+    meshes.push(mesh);
+  };
+  let cur = newChunk(), chunkStart = 0, along = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i], pa = pts[Math.max(0, i - 1)], pb = pts[Math.min(pts.length - 1, i + 1)];
+    let tx = pb.x - pa.x, tz = pb.z - pa.z; const tl = Math.hypot(tx, tz) || 1; tx /= tl; tz /= tl;
+    const nx = -tz, nz = tx;                                    // perpendicular in the XZ plane
+    if (i > 0) along += Math.hypot(p.x - pts[i - 1].x, p.z - pts[i - 1].z);
+    // rapids strength: how fast the water level DROPS just downstream of here (per metre)
+    const pd = pts[Math.min(pts.length - 1, i + 3)];
+    const dDist = Math.hypot(pd.x - p.x, pd.z - p.z) || 1;
+    const drop = Math.max(0, (p.wy - pd.wy) / dDist);
+    const row = newChunk();                                     // one cross-section, built once…
+    for (let k = 0; k < K; k++) {
+      const side = (k / (K - 1)) * 2 - 1;                       // -1 (left bank) … 0 (centre) … 1 (right bank)
+      const vx = p.x + nx * p.ww * side, vz = p.z + nz * p.ww * side;
+      const g = heightAt(vx, vz);
+      // wet verts sit at water level; DRY verts dive a fixed metre BELOW the surface, so the
+      // sheet submerges and the waterline is the smooth surface/terrain intersection
+      row.verts.push(vx, g < p.wy ? p.wy : p.wy - 1.0, vz);
+      row.depths.push(p.wy - g);                                // ≤0 on dry verts → transparent + bank foam at the line
+      row.bWy.push(p.wy); row.bX.push(vx); row.bZ.push(vz);
+      row.uvs.push((side + 1) * 0.5, along * 0.1);              // V runs down the WHOLE course — seamless across chunks
+      // downstream velocity (m/s), BAKED FROM THE HYDRAULICS instead of a universal
+      // constant (every reach of every course at the same speed — a pool as fast as a
+      // rapid). Slope sets the pace (drop is already per-metre, from the reach-baked wy
+      // three nodes downstream), width modulates it by continuity against the local ramp
+      // (wr above): the solved courses run ±25 % pool/riffle width, so a narrow riffle
+      // visibly quickens and a wide pool slows to a crawl.
+      const v = THREE.MathUtils.clamp(0.4 + 10 * drop, 0.3, 2.4) * (p.wr / p.ww);
+      row.flows.push(tx * v, tz * v);
+      row.drops.push(drop);
+    }
+    pushRow(cur, row);
+    if (along - chunkStart >= CHUNK_LEN && i < pts.length - 1) {
+      flush(cur);
+      cur = newChunk(); chunkStart = along;
+      pushRow(cur, row);                                        // …and shared by both sides of the cut
+    }
+  }
+  flush(cur);
+  return meshes;
+}
+
+// A lake sheet: one plane per body at the survey level − drop, per-vertex aDepth bake, dry
+// verts dived below the surface, per-vertex aRClip so ONE shared material keeps per-lake
+// sprawl clip. The shared material is the game's (waterMaterial({ rClip: 'attribute' })).
+export function buildLake(scene, Lk, mat, { heightAt, drop = 0.8 }) {
+  const rClip = Lk.rClip ?? Lk.r * 0.85;
+  const wr = rClip + 4;
+  const wseg = THREE.MathUtils.clamp(Math.round((wr * 2) / 1.8), 16, 64);    // ~1.8m facets
+  const wgeo = new THREE.PlaneGeometry(wr * 2, wr * 2, wseg, wseg);
+  const waterY = Lk.level - drop;
+  const dp = wgeo.attributes.position, aDepth = new Float32Array(dp.count);
+  const aRClip = new Float32Array(dp.count).fill(rClip);     // per-vertex so the shared shader keeps per-lake sprawl clip
+  for (let i = 0; i < dp.count; i++) {
+    const g = heightAt(Lk.x + dp.getX(i), Lk.z - dp.getY(i));
+    aDepth[i] = waterY - g;
+    if (g >= waterY) dp.setZ(i, -drop); // dry verts dive below the surface (plane local +z is world up)
+  }
+  wgeo.setAttribute('aDepth', new THREE.BufferAttribute(aDepth, 1));
+  wgeo.setAttribute('aRClip', new THREE.BufferAttribute(aRClip, 1));
+  const lake = new THREE.Mesh(wgeo, mat);
+  lake.rotation.x = -Math.PI / 2;
+  lake.position.set(Lk.x, waterY, Lk.z);
+  scene.add(lake);
+  return lake;
+}
+
+// The sea: a flat ocean plane at seaLevel, shown only where land dips below it past coastZ.
+export function buildSea(scene, mat, { worldSize, seaLevel, coastZ, heightAt }) {
+  const SEG = 256;
+  const geo = new THREE.PlaneGeometry(worldSize, worldSize, SEG, SEG);
+  const pos = geo.attributes.position, aDepth = new Float32Array(pos.count);
+  for (let i = 0; i < pos.count; i++) {
+    const X = pos.getX(i), Z = -pos.getY(i);
+    aDepth[i] = Z > coastZ ? Math.max(0, seaLevel - heightAt(X, Z)) : 0;
+  }
+  geo.setAttribute('aDepth', new THREE.BufferAttribute(aDepth, 1));
+  const mesh = new THREE.Mesh(geo, mat);
+  mesh.rotation.x = -Math.PI / 2;
+  mesh.position.y = seaLevel;
+  mesh.frustumCulled = false;
+  scene.add(mesh);
+  return mesh;
+}
+
+// Rivers v2: re-derive every river vert's depth from the CURRENT terrain — pads that
+// register during world.build mutate heightAt AFTER the ribbons bake, leaving stale aDepth.
+// Called at the END of world.build; re-runnable whenever terrain changes.
+export function refreshRiverDepths(waters, { heightAt }) {
+  let fixed = 0;
+  for (const m of waters ?? []) {
+    const rb = m.userData?.riverVerts;
+    if (!rb) continue;
+    const pos = m.geometry.attributes.position, aD = m.geometry.attributes.aDepth;
+    for (let i = 0; i < aD.count; i++) {
+      const g = heightAt(rb.x[i], rb.z[i]);
+      const d = rb.wy[i] - g;
+      if (Math.abs(d - aD.getX(i)) > 0.02) fixed++;
+      aD.setX(i, d);
+      pos.setY(i, g < rb.wy[i] ? rb.wy[i] : rb.wy[i] - 1.0);
+    }
+    aD.needsUpdate = true; pos.needsUpdate = true;
+    m.geometry.computeBoundingSphere();
+  }
+  if (fixed) console.log(`[rivers] depth refresh: ${fixed} verts re-derived after terrain pads`);
+}