sindicate 0.13.0 → 0.16.0

package/src/world/roadTerrain.js

@@ -0,0 +1,377 @@
+// 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) };
+}
+
+// Pads get a bucket grid too. A world has tens of junctions and the lattice asks this
+// function ~1.7 million times for a cold cook: scanning every pad per call is 40 million
+// distance tests nobody needs, and it showed up as a 25x cost over the bare terrain.
+function padIndex(pads, cell) {
+  const buckets = new Map();
+  pads.forEach((p, id) => {
+    const reach = (p.halfX != null ? Math.hypot(p.halfX, p.halfZ) : (p.radius ?? 0))
+      + Math.max(p.fade ?? 0, p.maxEarthwork ?? 120);
+    const i0 = Math.floor((p.x - reach) / cell), i1 = Math.floor((p.x + reach) / cell);
+    const j0 = Math.floor((p.z - reach) / cell), j1 = Math.floor((p.z + reach) / cell);
+    for (let i = i0; i <= i1; i++) for (let j = j0; j <= j1; j++) {
+      const k = `${i},${j}`;
+      if (!buckets.has(k)) buckets.set(k, []);
+      buckets.get(k).push(id);
+    }
+  });
+  return (x, z) => buckets.get(`${Math.floor(x / cell)},${Math.floor(z / cell)}`) ?? null;
+}
+
+export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfaces = [], cell = 32, clearance = 0.08 } = {}) {
+  const index = corridors.length ? segmentIndex(corridors, cell) : null;
+  const nearPads = pads.length ? padIndex(pads, cell) : null;
+
+  // WHERE THE DRIVEABLE SURFACE IS. The ground is deliberately cut a little below the road so
+  // the two do not fight for the same pixels, which means anything that drives — the player's
+  // car, traffic, a pedestrian on a bridge — must ask for the road, not the dirt.
+  // Returns null away from any road, so the caller falls back to the ground.
+  heightAt.road = function roadAt(x, z, preferY = null) {
+    const found = [];
+    // pads are driveable too: a junction's deck is where its own roads sit
+    for (const pid of nearPads?.(x, z) ?? []) {
+      const p = pads[pid];
+      if (padDistance(p, x, z) <= 0) found.push(p.y);
+    }
+    if (index) {
+      const ids = index.near(x, z);
+      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));
+        if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half) continue;
+        found.push(s.ay + (s.by - s.ay) * t);
+      }
+    }
+    if (!found.length) return null;
+    // MULTI-LEVEL: where a bridge crosses a cutting, or a link overlaps an interchange's
+    // trench, several surfaces cover the same spot. Answer with the one nearest the height
+    // the caller is already at — you stay on the deck you are driving on, you do not fall
+    // through it onto the road below.
+    if (preferY == null) return Math.max(...found);
+    // 'low' / 'high' ask for a level outright. (A non-finite preference cannot do this by
+    // arithmetic: |y - -Infinity| is Infinity for EVERY candidate, so the nearest-wins
+    // comparison is always false and the first deck found is returned regardless.)
+    if (preferY === 'low' || preferY === -Infinity) return Math.min(...found);
+    if (preferY === 'high' || preferY === Infinity) return Math.max(...found);
+    return found.reduce((best, y) => (Math.abs(y - preferY) < Math.abs(best - preferY) ? y : best));
+  };
+
+  // JUST THE CARRIAGEWAYS — no pads. A pad is a levelled area a junction stands on, not a
+  // road deck: anything asking "is this ground hidden under tarmac?" must not be told yes
+  // for the whole footprint of an interchange, or it will remove ground you can plainly see.
+  // `shrink` narrows the corridor before answering. A corridor's bed is deliberately wider
+  // than its tarmac (the road needs level ground beside it), so anything using this to decide
+  // "is the ground hidden here?" must ask about the ROAD, not the bed — or it cuts away a
+  // strip of terrain along both edges that nothing is covering, leaving a gap at the kerb.
+  heightAt.deck = function deckAt(x, z, shrink = 0) {
+    if (!index) return null;
+    const ids = index.near(x, z);
+    if (!ids) return null;
+    let lowest = 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));
+      if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half - shrink) continue;
+      const y = s.ay + (s.by - s.ay) * t;
+      if (lowest == null || y < lowest) lowest = y;
+    }
+    return lowest;
+  };
+
+  function heightAt(x, z) {
+    let h = baseHeightAt(x, z);
+
+    // ── junction pads: level, because a prefab junction cannot bend ──
+    for (const pid of nearPads?.(x, z) ?? []) {
+      const p = pads[pid];
+      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
+      // A FADE, NOT A CUT. An embankment batter is right for a road crossing a valley and
+      // wrong for the ground around a junction: it leaves a visible rim, and the eye reads
+      // the whole pad as a platform someone dropped on the landscape. Kiwi's answer, and
+      // the right one, is to ease back to the ORIGINAL height over a generous distance —
+      // far enough that you cannot tell the ground was levelled at all.
+      const fade = p.fade ?? 0;
+      if (fade > 0) {
+        if (d >= fade) continue;                              // beyond the fade: natural ground
+        const t = smoothstep(0, 1, d / fade);
+        h = y + (h - y) * t;
+      } else {
+        const reach = d * (p.batter ?? 0.5);                  // the old earthwork law
+        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);
+          }
+        }
+      }
+    }
+
+    // THE GUARANTEE: ground never sits above a road. The clearance is a hair — just enough
+    // that the two surfaces do not fight for the same pixels. It was much larger while this
+    // clamp was silently broken, and that showed as a step along every road edge: the ground
+    // beside a kerb sitting half a metre below the tarmac it should meet. Corridor and pad bookkeeping alone
+    // cannot promise it — a terrain lattice is metres wide, so a vertex just outside a
+    // road's flat bed drags its triangle up across the carriageway and lays a wedge of dirt
+    // over the tarmac. Every consumer of this function (the mesh, the cook, collision,
+    // grass) gets the same promise, in every game, without having to know the rule exists.
+    const deck = heightAt.road(x, z, 'low');
+    if (deck != null && h > deck - clearance) h = deck - clearance;
+    return h;
+  }
+
+  return heightAt;
+}
+
+// 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, maxGrade = 0 } = {}) {
+  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;
+    const ok = chosen.every((s) => {
+      const gap = Math.hypot(s.x - c.x, s.z - c.z);
+      if (gap < minGap) return false;
+      // AND A ROAD MUST BE ABLE TO REACH IT. Picking the flattest spots regardless of each
+      // other's height cheerfully pairs a hilltop with a valley floor, and no road between
+      // them can be built at a sane grade — the link then quietly exceeds it.
+      if (maxGrade > 0 && Math.abs(s.y - c.y) > gap * maxGrade * 0.55) return false;
+      return true;
+    });
+    if (ok) 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/roadWorld.js

@@ -0,0 +1,200 @@
+// ROADS AS A WORLD-BUILD STEP.
+//
+// The pieces exist — a kit to read, a network to solve, links to generate, earthworks to cut.
+// This is the one call that runs them in the right order and hands back everything a world
+// needs, so a game does not have to know that order (and cannot get it wrong):
+//
+//   const roads = await buildRoadWorld({ sites, kit, candidates, ground, placePiece });
+//   const heightAt = roads.heightAt;        // ← give THIS to buildHeightfield
+//   scene.add(...roads.meshes);             // ← and stamp these BEFORE the BVH bake
+//   for (const m of roads.colliders) bvhSources.push(m);
+//
+// THE ORDER IS THE POINT, and it is not obvious:
+//   1. site the junctions on flat ground        — before anything is placed
+//   2. seat each piece at ITS grade level       — multi-level pieces are authored high
+//   3. wrap the ground with the pads            — so links can follow a padded surface
+//   4. solve and generate the links             — they read that padded ground
+//   5. wrap again with pads AND corridors       — the final heightAt the world uses
+// Do 4 before 3 and links follow raw terrain into the sides of junctions; do 5 before 4 and
+// there are no corridors to add yet.
+//
+// `placePiece(name, { x, y, z, yaw })` is the game's: it loads the assembly, adds it to the
+// scene and returns `{ object, sockets, deckPoints }`. The engine never loads assets.
+import { makeRoadTerrain, seatHeight, pickManySites } from './roadTerrain.js';
+import { solveNetwork, planLoop, loopTangents } from './roadNetwork.js';
+import { buildRoadLink, buildDeck } from './roadLink.js';
+import { seatY, gradeLevel } from './roadKit.js';
+
+const footprintOf = (piece, margin = 6) => ({
+  halfX: (piece.bbox.max[0] - piece.bbox.min[0]) / 2 + margin,
+  halfZ: (piece.bbox.max[2] - piece.bbox.min[2]) / 2 + margin,
+  cx: (piece.bbox.max[0] + piece.bbox.min[0]) / 2,
+  cz: (piece.bbox.max[2] + piece.bbox.min[2]) / 2,
+});
+
+export async function buildRoadWorld({
+  kit,                       // from makeRoadKit
+  ground,                    // the game's natural heightAt
+  placePiece,                // (name, transform) => { object, sockets, deckPoints }
+  sites = null,              // explicit sites, or let pickManySites choose
+  candidates = [],           // junction piece names the solver may use
+  count = 6,                 // how many places, when choosing them
+  half = 600, minGap = 420,  // where they may go
+  loop = false,              // a closed circuit rather than a network
+  maxGrade = 0.07,
+  fade = 90,                 // how far a junction pad eases back into the landscape
+  drop = 0.12,               // ground below a deck: a hair, so they do not z-fight
+  linkStep = 3,
+  handleScale = 0.4,
+} = {}) {
+  const pieceOf = (n) => (kit.piece ? kit.piece(n) : kit.pieces?.[n]);
+  const pad = Math.max(...candidates.map((n) => pieceOf(n)?.size?.[0] ?? 100)) * 0.55;
+
+  // 1. WHERE THE PLACES GO — flat enough to stand a junction on, far enough apart to be
+  //    separate places
+  const chosen = sites ?? pickManySites(ground, { count, half, step: 70, radius: pad, minGap, maxGrade });
+  if (chosen.length < 2) return { heightAt: ground, meshes: [], colliders: [], network: null, sites: chosen };
+
+  // 2. THE NETWORK — who joins whom, and what junction each place needs
+  const order = loop ? planLoop(chosen) : null;
+  const facing = loop ? loopTangents(chosen, order) : null;
+  const net = loop ? null : solveNetwork({ sites: chosen, kit, candidates, kinds: ['road'] });
+
+  // 3. PLACE EACH JUNCTION, seated at its own grade level
+  const placed = new Map();
+  const pads = [];
+  const placeOne = async (index, name, yaw) => {
+    const piece = pieceOf(name);
+    if (!piece) return;
+    const st = chosen[index];
+    const p = await placePiece(name, { x: st.x, y: seatY(piece, st.y), z: st.z, yaw });
+    if (!p) return;
+    const foot = footprintOf(piece);
+    const c = Math.cos(yaw), s = Math.sin(yaw);
+    pads.push({
+      x: st.x + foot.cx * c + foot.cz * s, z: st.z - foot.cx * s + foot.cz * c,
+      y: st.y, yaw, halfX: foot.halfX, halfZ: foot.halfZ, drop, fade,
+    });
+    placed.set(index, { ...p, site: st, yaw, name, piece });
+  };
+  if (loop) for (const { index, yaw } of facing) await placeOne(index, candidates[0], yaw);
+  else for (const node of net.nodes) if (node.name) await placeOne(node.index, node.name, node.yaw);
+
+  // 4. THE LINKS — generated over ground that already knows about the pads, so a road
+  //    approaches a junction over its own levelled apron rather than raw hillside
+  const padded = makeRoadTerrain(ground, { pads });
+  const kinds = loop ? ['motorway'] : ['road'];
+  const facingSocket = (p, tx, tz) => (p.sockets ?? [])
+    .filter((s) => kinds.includes(s.kind ?? 'road'))
+    .reduce((best, s) => {
+      const v = [tx - s.pos[0], tz - s.pos[2]];
+      const len = Math.hypot(...v) || 1;
+      const sc = (s.dir[0] * v[0] + s.dir[1] * v[1]) / len;
+      return !best || sc > best.sc ? { s, sc } : best;
+    }, null)?.s ?? null;
+
+  // IN A LOOP THE TWO ENDS ARE ASSIGNED, not chosen independently. A through-piece has
+  // exactly two motorway sockets and exactly two neighbours; picking the best-facing socket
+  // for each neighbour separately lets both pick the SAME end on a turn, and the second road
+  // is then dropped for want of an arm — a circuit with holes in it.
+  const assigned = new Map();
+  if (loop) {
+    for (let k = 0; k < order.length; k++) {
+      const me = placed.get(order[k]);
+      if (!me) continue;
+      const prev = placed.get(order[(k - 1 + order.length) % order.length]);
+      const next = placed.get(order[(k + 1) % order.length]);
+      const mw = (me.sockets ?? []).filter((sk) => sk.kind === 'motorway');
+      if (mw.length < 2 || !prev || !next) continue;
+      const toward = (sk, t) => {
+        const v = [t.site.x - sk.pos[0], t.site.z - sk.pos[2]];
+        const len = Math.hypot(...v) || 1;
+        return (sk.dir[0] * v[0] + sk.dir[1] * v[1]) / len;
+      };
+      // take whichever pairing serves both neighbours better overall
+      const straight = toward(mw[0], prev) + toward(mw[1], next);
+      const swapped = toward(mw[1], prev) + toward(mw[0], next);
+      assigned.set(order[k], straight >= swapped
+        ? { prev: mw[0], next: mw[1] }
+        : { prev: mw[1], next: mw[0] });
+    }
+  }
+
+  const links = [];
+  const pairs = loop
+    ? order.map((a, k) => [a, order[(k + 1) % order.length]])
+    : net.edges.map((e) => [e.a, e.b]);
+  const used = new Set();
+  for (const [ia, ib] of pairs) {
+    const A = placed.get(ia), B = placed.get(ib);
+    if (!A || !B) continue;
+    const from = assigned.get(ia)?.next ?? facingSocket(A, B.site.x, B.site.z);
+    const to = assigned.get(ib)?.prev ?? facingSocket(B, A.site.x, A.site.z);
+    if (!from || !to) continue;
+    const ka = `${ia}:${from.id}`, kb = `${ib}:${to.id}`;
+    if (used.has(ka) || used.has(kb)) continue;          // one road per arm
+    used.add(ka); used.add(kb);
+    links.push({
+      a: ia, b: ib, from, to,
+      link: buildRoadLink({
+        from, to, groundAt: (x, z) => padded(x, z) + 0.15,
+        handleScale, step: linkStep, maxGrade,
+      }),
+    });
+  }
+
+  // 5. THE EARTHWORKS the world actually uses: pads AND the corridors those links carry,
+  //    plus a trench for anything a piece keeps below its own grade
+  const corridors = links.map(({ link, from }) => ({
+    centreline: link.centreline, halfWidth: from.width / 2 + 5, drop, batter: 0.5,
+  }));
+  for (const [, p] of placed) {
+    const mw = (p.sockets ?? []).filter((s) => s.kind === 'motorway');
+    if (mw.length < 2 || !p.deckPoints?.length) continue;
+    const a = mw[0].pos, b = mw[1].pos;
+    const ax = [b[0] - a[0], b[2] - a[2]];
+    const al = Math.hypot(...ax) || 1;
+    ax[0] /= al; ax[1] /= al;
+    const perp = [-ax[1], ax[0]];
+    const grade = p.site.y;
+    let wide = 0, lowest = Infinity;
+    for (const q of p.deckPoints) {
+      if (q[1] > grade - 1.5) continue;
+      const lat = Math.abs((q[0] - p.site.x) * perp[0] + (q[2] - p.site.z) * perp[1]);
+      if (lat > wide) wide = lat;
+      if (q[1] < lowest) lowest = q[1];
+    }
+    if (!(wide > 0)) continue;
+    // KEEP THE TRENCH TIGHT TO THE CARRIAGEWAY. Sizing it from everything below grade lets
+    // the slip roads — which sweep far out to either side as they climb — widen the cut until
+    // it swallows the whole junction, dropping the entire pad to motorway level and leaving
+    // every piece standing 10 m above its own ground.
+    const bed = Math.min(wide, Math.max(mw[0].width, mw[1].width) / 2 + 18) + 5;
+    corridors.push({
+      centreline: [
+        [a[0] - ax[0] * 30, Math.min(a[1], lowest), a[2] - ax[1] * 30],
+        [b[0] + ax[0] * 30, Math.min(b[1], lowest), b[2] + ax[1] * 30],
+      ],
+      halfWidth: bed, drop, batter: 4,
+    });
+  }
+
+  return {
+    heightAt: makeRoadTerrain(ground, { pads, corridors }),
+    links,
+    pads,
+    corridors,
+    placed,
+    sites: chosen,
+    network: net,
+    order,
+    // the median strip through each junction: its two carriageways are separate meshes, and
+    // the ground would otherwise be visible dropping away between them
+    medianDecks: [...placed.values()].flatMap((p) => {
+      const mw = (p.sockets ?? []).filter((s) => s.kind === 'motorway');
+      if (mw.length < 2) return [];
+      const inner = (mw[0].section?.lines ?? []).map((b) => Math.abs(b.at)).sort((x, y) => x - y)[0] ?? 1.1;
+      return [buildDeck({ from: mw[0].pos, to: mw[1].pos, width: inner * 2 + 0.6 })];
+    }),
+  };
+}

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]);
+  }
+}