sindicate 0.13.0 → 0.15.0

package/src/world/roadLink.js

@@ -0,0 +1,270 @@
+// ROAD LINK — the road BETWEEN two junctions.
+//
+// Junctions are fixed prefab pieces (instanced, never deformed). The road joining two of
+// their sockets has to curve, climb and match each socket's width exactly, so it is
+// generated: a cubic Bezier through both socket tangents, a smooth vertical profile, and
+// the same cross-section the junction arms are built from (asphalt + edge lines + centre
+// dashes on a palette atlas). This is how Kiwi joined its junctions too — its
+// Generated/RoadMeshes tree is thousands of exactly these.
+//
+//   const link = buildRoadLink({ from: socketA, to: socketB, heights: [0, 12, 30, 22, 38] })
+//   scene.add(new THREE.Mesh(link.geometry, roadMaterial))
+//
+// `from`/`to` are kit sockets: { pos:[x,y,z], dir:[dx,dz], width } with dir pointing OUT of
+// its junction. The link leaves `from` along +dir and arrives at `to` against its +dir, so
+// both ends meet their arms tangentially — no kink at the seam.
+import * as THREE from 'three';
+
+const PALETTE = {           // texels in the Simpligon atlas (flat sampling, no tiling)
+  asphalt: [0.2871, 0.0361],
+  line: [0.2871, 0.1105],
+};
+const MARK_Y = 0.02;        // paint sits this far above the asphalt
+const EDGE_W = 0.1;         // edge-line width
+const DASH_W = 0.1;         // centre-line width
+const DASH_ON = 2.5, DASH_OFF = 2.5;
+
+const catmull = (p, t) => {
+  // smooth interpolation through the given heights (duplicated ends = flat entry/exit)
+  const n = p.length;
+  if (n === 1) return p[0];
+  const x = t * (n - 1);
+  const i = Math.min(Math.floor(x), n - 2);
+  const f = x - i;
+  const p0 = p[Math.max(i - 1, 0)], p1 = p[i], p2 = p[i + 1], p3 = p[Math.min(i + 2, n - 1)];
+  return 0.5 * ((2 * p1) + (-p0 + p2) * f + (2 * p0 - 5 * p1 + 4 * p2 - p3) * f * f + (-p0 + 3 * p1 - 3 * p2 + p3) * f * f * f);
+};
+
+// A road may only climb so fast. Whatever profile is asked for, squeeze it into the envelope
+// that is actually reachable from both ends at `g`, then relax the kinks out of it — the same
+// idea as the rail solver's Lipschitz envelope + vertical curves, which is why Sindicate can
+// do grades at all (Kiwi could only bench them into the ground).
+function limitGrade(samples, gWanted, yStart, yEnd) {
+  const n = samples.length;
+  if (n < 3 || !(gWanted > 0)) return { grade: gWanted, feasible: true };
+  const s = samples.map((sm) => sm.s);
+  const L = s[n - 1] || 1;
+  // CONNECTING IS NON-NEGOTIABLE. If the two sockets simply cannot be joined at the wanted
+  // grade, the road still meets both ends and reports the grade it actually needed — a
+  // steep road is a fact the caller can act on; a road that stops in mid-air is a bug.
+  const needed = Math.abs(yEnd - yStart) / L;
+  const g = Math.max(gWanted, needed * 1.0001);
+  const y = samples.map((sm) => sm.p.y);
+  y[0] = yStart; y[n - 1] = yEnd;
+  for (let i = 1; i < n - 1; i++) {
+    const hi = Math.min(yStart + g * s[i], yEnd + g * (L - s[i]));
+    const lo = Math.max(yStart - g * s[i], yEnd - g * (L - s[i]));
+    y[i] = Math.min(Math.max(y[i], Math.min(lo, hi)), Math.max(lo, hi));
+  }
+  // vertical curves: average neighbours, re-clamping so the envelope still holds
+  for (let pass = 0; pass < 24; pass++) {
+    for (let i = 1; i < n - 1; i++) {
+      const avg = (y[i - 1] + y[i + 1]) / 2;
+      const step = y[i] + (avg - y[i]) * 0.5;
+      const hi = Math.min(yStart + g * s[i], yEnd + g * (L - s[i]));
+      const lo = Math.max(yStart - g * s[i], yEnd - g * (L - s[i]));
+      y[i] = Math.min(Math.max(step, Math.min(lo, hi)), Math.max(lo, hi));
+    }
+  }
+  // final safety: no single step may exceed the grade — interior points only, so the pass
+  // can never drag the far end off its socket
+  for (let i = 1; i < n - 1; i++) {
+    const ds = s[i] - s[i - 1] || 1e-3;
+    y[i] = Math.min(Math.max(y[i], y[i - 1] - g * ds), y[i - 1] + g * ds);
+  }
+  const dsLast = s[n - 1] - s[n - 2] || 1e-3;
+  y[n - 2] = Math.min(Math.max(y[n - 2], yEnd - g * dsLast), yEnd + g * dsLast);
+  y[n - 1] = yEnd;
+  for (let i = 0; i < n; i++) samples[i].p.y = y[i];
+  return { grade: g, feasible: g <= gWanted * 1.001 };
+}
+
+export function buildRoadLink({
+  from, to,
+  heights = null,            // extra height control points between the two sockets
+  groundAt = null,           // sample the terrain instead: the road follows the land it crosses
+  step = 3,                  // metres between cross-sections
+  handleScale = 0.42,        // Bezier handle length as a fraction of the gap — how gentle the curve is
+  maxGrade = 0.08,           // 8% — steep but drivable; motorways want ~0.06
+  skirt = 0.5,               // vertical apron under the road edges (0 = paper-thin)
+  palette = PALETTE,
+} = {}) {
+  const P0 = new THREE.Vector3(...from.pos);
+  const P3 = new THREE.Vector3(...to.pos);
+  const gap = P0.distanceTo(P3);
+  const k = gap * handleScale;
+  const P1 = P0.clone().add(new THREE.Vector3(from.dir[0], 0, from.dir[1]).multiplyScalar(k));
+  const P2 = P3.clone().add(new THREE.Vector3(to.dir[0], 0, to.dir[1]).multiplyScalar(k));
+
+  const at = (t) => {
+    const u = 1 - t;
+    return new THREE.Vector3()
+      .addScaledVector(P0, u * u * u).addScaledVector(P1, 3 * u * u * t)
+      .addScaledVector(P2, 3 * u * t * t).addScaledVector(P3, t * t * t);
+  };
+  // arc length first, so cross-sections are evenly spaced no matter how the handles bunch
+  const probe = 200;
+  const cum = [0];
+  let prev = at(0);
+  for (let i = 1; i <= probe; i++) { const p = at(i / probe); cum.push(cum[i - 1] + p.distanceTo(prev)); prev = p; }
+  const length = cum[probe];
+  const tAt = (s) => {
+    let i = 1;
+    while (i < probe && cum[i] < s) i++;
+    const span = cum[i] - cum[i - 1] || 1;
+    return (i - 1 + (s - cum[i - 1]) / span) / probe;
+  };
+
+  const rows = Math.max(2, Math.round(length / step) + 1);
+  const halfA = from.width / 2, halfB = to.width / 2;
+  // where the joined arms carry their edge lines — usually inset from the asphalt edge by
+  // the verge, so painting at the deck edge would kink the lines at the seam
+  const paintA = from.paint?.half ?? halfA - EDGE_W;
+  const paintB = to.paint?.half ?? halfB - EDGE_W;
+  const lineW = from.paint?.lineWidth ?? EDGE_W;
+  const pos = [], nrm = [], uv = [], idx = [];
+  const vert = (p, n, t) => { pos.push(p.x, p.y, p.z); nrm.push(n[0], n[1], n[2]); uv.push(t[0], t[1]); return pos.length / 3 - 1; };
+  const UP = [0, 1, 0];
+
+  // one cross-section anywhere along the road: position, right vector, half-width
+  const profile = heights?.length ? [from.pos[1], ...heights, to.pos[1]] : null;
+  const sampleAt = (s) => {
+    const f = Math.min(Math.max(s / length, 0), 1);
+    const t = tAt(s);
+    const p = at(t);
+    const fwd = at(Math.min(t + 0.001, 1)).sub(at(Math.max(t - 0.001, 0)));
+    fwd.y = 0; fwd.normalize();
+    // vertical profile: follow the land if we were given it, else the sockets' own heights
+    // plus any crests asked for between them. Either way limitGrade has the last word.
+    if (groundAt) p.y = groundAt(p.x, p.z);
+    else if (profile) p.y = catmull(profile, f);
+    return {
+      p, right: new THREE.Vector3(-fwd.z, 0, fwd.x),
+      half: halfA + (halfB - halfA) * f,
+      paintHalf: paintA + (paintB - paintA) * f,
+      s,
+    };
+  };
+  const samples = [];
+  for (let i = 0; i < rows; i++) samples.push(sampleAt((i / (rows - 1)) * length));
+  const gradeFit = limitGrade(samples, maxGrade, from.pos[1], to.pos[1]);
+  // EVERYTHING after this point must read the road from `samples`, never from sampleAt():
+  // the deck follows the grade-limited profile, and paint that re-sampled the raw curve
+  // would float off the ribbon wherever the limiter did its work.
+  const along = (s) => {
+    const f = Math.min(Math.max(s / length, 0), 1) * (rows - 1);
+    const i = Math.min(Math.floor(f), rows - 2);
+    const t = f - i;
+    const a = samples[i], b = samples[i + 1];
+    return {
+      p: a.p.clone().lerp(b.p, t),
+      right: a.right.clone().lerp(b.right, t).normalize(),
+      half: a.half + (b.half - a.half) * t,
+      paintHalf: a.paintHalf + (b.paintHalf - a.paintHalf) * t,
+      s,
+    };
+  };
+
+  // ── asphalt deck ──
+  const deck = [];
+  for (const { p, right, half } of samples) {
+    const l = p.clone().addScaledVector(right, -half);
+    const r = p.clone().addScaledVector(right, half);
+    deck.push([vert(l, UP, palette.asphalt), vert(r, UP, palette.asphalt)]);
+  }
+  for (let i = 0; i < deck.length - 1; i++) {
+    const [a, b] = deck[i], [c, d] = deck[i + 1];
+    idx.push(a, b, c, b, d, c);
+  }
+
+  // ── painted strips: a run of cross-sections at fixed lateral offsets ──
+  const paint = (rowsIn, offsetFn, texel) => {
+    const row = rowsIn.map((sm) => {
+      const [o0, o1] = offsetFn(sm);
+      const y = sm.p.clone(); y.y += MARK_Y;
+      return [
+        vert(y.clone().addScaledVector(sm.right, o0), UP, texel),
+        vert(y.clone().addScaledVector(sm.right, o1), UP, texel),
+      ];
+    });
+    for (let i = 0; i < row.length - 1; i++) {
+      const [a, b] = row[i], [c, d] = row[i + 1];
+      idx.push(a, b, c, b, d, c);
+    }
+  };
+  // A MOTORWAY carries its own measured paint — two carriageways, a median and however many
+  // lane divisions the piece was generated with — so a link between two motorway sockets is
+  // marked out exactly like the interchange it leaves. Anything else gets the plain
+  // two-way treatment: an edge line each side and a dashed middle.
+  const section = from.section ?? null;
+  if (section?.lines?.length) {
+    const lerpBands = (a, b) => (b?.length === a.length
+      ? a.map((band, i) => ({ at0: band.at, at1: b[i].at, width: Math.max(band.width, b[i].width, 0.12) }))
+      : a.map((band) => ({ at0: band.at, at1: band.at, width: Math.max(band.width, 0.12) })));
+    for (const b of lerpBands(section.lines, to.section?.lines)) {
+      paint(samples, (sm) => {
+        const at = b.at0 + (b.at1 - b.at0) * (sm.s / length);
+        return [at - b.width / 2, at + b.width / 2];
+      }, palette.line);
+    }
+    for (const b of lerpBands(section.dashes ?? [], to.section?.dashes)) {
+      for (let s = DASH_OFF / 2; s + DASH_ON < length; s += DASH_ON + DASH_OFF) {
+        const dash = [along(s), along(s + DASH_ON * 0.5), along(s + DASH_ON)];
+        paint(dash, (sm) => {
+          const at = b.at0 + (b.at1 - b.at0) * (sm.s / length);
+          return [at - b.width / 2, at + b.width / 2];
+        }, palette.line);
+      }
+    }
+  } else {
+    paint(samples, (sm) => [-sm.paintHalf, -sm.paintHalf + lineW], palette.line);   // left edge line
+    paint(samples, (sm) => [sm.paintHalf - lineW, sm.paintHalf], palette.line);     // right edge line
+    // centre dashes walk their own cycle so they stay crisp regardless of `step`
+    const centreOff = from.paint?.centre ?? 0;
+    for (let s = DASH_OFF / 2; s + DASH_ON < length; s += DASH_ON + DASH_OFF) {
+      const dash = [along(s), along(s + DASH_ON * 0.5), along(s + DASH_ON)];
+      paint(dash, () => [centreOff - DASH_W / 2, centreOff + DASH_W / 2], palette.line);
+    }
+  }
+
+  // ── side apron so an elevated road is not a floating sheet ──
+  if (skirt > 0) {
+    for (const side of [-1, 1]) {
+      const wall = [];
+      for (const { p, right, half } of samples) {
+        const top = p.clone().addScaledVector(right, side * half);
+        const bot = top.clone(); bot.y -= skirt;
+        const n = [right.x * side, 0, right.z * side];
+        wall.push([vert(top, n, palette.asphalt), vert(bot, n, palette.asphalt)]);
+      }
+      for (let i = 0; i < wall.length - 1; i++) {
+        const [a, b] = wall[i], [c, d] = wall[i + 1];
+        if (side > 0) idx.push(a, b, c, b, d, c);
+        else idx.push(a, c, b, b, c, d);
+      }
+    }
+  }
+
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3));
+  geometry.setAttribute('normal', new THREE.Float32BufferAttribute(nrm, 3));
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uv, 2));
+  geometry.setIndex(idx);
+  geometry.computeBoundingSphere();
+
+  // the centreline is what traffic, benching and the minimap all consume
+  const centreline = samples.map(({ p }) => [+p.x.toFixed(3), +p.y.toFixed(3), +p.z.toFixed(3)]);
+  const grades = [];
+  for (let i = 1; i < samples.length; i++) {
+    const dy = samples[i].p.y - samples[i - 1].p.y;
+    const dxz = Math.hypot(samples[i].p.x - samples[i - 1].p.x, samples[i].p.z - samples[i - 1].p.z) || 1;
+    grades.push(dy / dxz);
+  }
+  return {
+    geometry, centreline, length,
+    maxGrade: grades.length ? Math.max(...grades.map(Math.abs)) : 0,
+    // false when the two sockets could not be joined within the requested grade: the road
+    // still connects, but the caller should re-site, re-pair, or accept the climb
+    feasible: gradeFit?.feasible ?? true,
+  };
+}

package/src/world/roadNetwork.js

@@ -0,0 +1,118 @@
+// ROAD NETWORK — turning a handful of places into a road system.
+//
+// The map is authored as SITES (towns, cities, interchanges) and the network between them is
+// solved: which places are joined, what junction each one needs, and which way it faces.
+//
+//   const net = solveNetwork({ sites, kit, pieces: { 4: '...', 3: '...' } });
+//   for (const node of net.nodes) place(node.piece, node);      // junctions
+//   for (const edge of net.edges) buildRoadLink(edge.from, edge.to);   // roads between them
+//
+// Kiwi resolved a junction from its link count and snapped the piece to 90°; the same idea
+// generalises here — pick the piece whose arms best match the bearings a site actually needs,
+// then rotate it to face them.
+
+// Every site joined to the network at least once (a spanning tree), plus a few extra short
+// links so the map has loops in it — a pure tree gives a road system with no alternate
+// routes, which reads as a diagram rather than a country.
+export function planEdges(sites, { extra = 0.35, maxLength = Infinity } = {}) {
+  const n = sites.length;
+  if (n < 2) return [];
+  const dist = (a, b) => Math.hypot(sites[a].x - sites[b].x, sites[a].z - sites[b].z);
+  const inTree = new Set([0]);
+  const edges = [];
+  while (inTree.size < n) {
+    let best = null;
+    for (const a of inTree) {
+      for (let b = 0; b < n; b++) {
+        if (inTree.has(b)) continue;
+        const d = dist(a, b);
+        if (!best || d < best.d) best = { a, b, d };
+      }
+    }
+    if (!best) break;
+    inTree.add(best.b);
+    edges.push({ a: best.a, b: best.b, length: best.d });
+  }
+  // candidate extras, shortest first, skipping pairs already joined
+  const have = new Set(edges.map((e) => `${Math.min(e.a, e.b)}-${Math.max(e.a, e.b)}`));
+  const cands = [];
+  for (let a = 0; a < n; a++) {
+    for (let b = a + 1; b < n; b++) {
+      const key = `${a}-${b}`;
+      if (have.has(key)) continue;
+      const d = dist(a, b);
+      if (d > maxLength) continue;
+      cands.push({ a, b, length: d });
+    }
+  }
+  cands.sort((p, q) => p.length - q.length);
+  for (const c of cands.slice(0, Math.round(edges.length * extra))) edges.push(c);
+  return edges;
+}
+
+const TAU = Math.PI * 2;
+const wrap = (a) => ((a % TAU) + TAU) % TAU;
+const angleGap = (a, b) => { const d = Math.abs(wrap(a) - wrap(b)); return Math.min(d, TAU - d); };
+
+// How well a piece, turned by `yaw`, presents an arm to each bearing it must serve.
+// Returns the total mismatch in radians, and which socket answers which bearing.
+export function fitJunction(piece, bearings, yaw, { kinds = null } = {}) {
+  const sockets = (piece.sockets ?? []).filter((s) => !kinds || kinds.includes(s.kind ?? 'road'));
+  if (sockets.length < bearings.length) return null;
+  const used = new Set();
+  let cost = 0;
+  const assign = [];
+  for (const want of bearings) {
+    let best = null;
+    for (let i = 0; i < sockets.length; i++) {
+      if (used.has(i)) continue;
+      const have = Math.atan2(sockets[i].dir[0], sockets[i].dir[1]) + yaw;
+      const gap = angleGap(want, have);
+      if (!best || gap < best.gap) best = { i, gap };
+    }
+    if (!best) return null;
+    used.add(best.i);
+    cost += best.gap;
+    assign.push({ socket: sockets[best.i], bearing: want, gap: best.gap });
+  }
+  return { cost, assign };
+}
+
+// Choose the piece and rotation that best serves a site's bearings. `candidates` is a list of
+// piece names; the kit supplies their sockets.
+export function chooseJunction(kit, candidates, bearings, { steps = 72, kinds = null } = {}) {
+  let best = null;
+  for (const name of candidates) {
+    const piece = kit.piece ? kit.piece(name) : kit.pieces?.[name];
+    if (!piece) continue;
+    const arms = (piece.sockets ?? []).filter((s) => !kinds || kinds.includes(s.kind ?? 'road')).length;
+    if (arms < bearings.length) continue;
+    for (let k = 0; k < steps; k++) {
+      const yaw = (k / steps) * TAU;
+      const fit = fitJunction(piece, bearings, yaw, { kinds });
+      if (!fit) continue;
+      // prefer a piece with no arms left over — a crossroads standing in for a corner
+      // leaves two stubs pointing at nothing
+      const score = fit.cost + (arms - bearings.length) * 0.25;
+      if (!best || score < best.score) best = { name, piece, yaw, score, assign: fit.assign };
+    }
+  }
+  return best;
+}
+
+// The whole plan: which sites join to which, and what junction each site needs.
+export function solveNetwork({ sites, kit, candidates, extra = 0.35, maxLength = Infinity, kinds = null }) {
+  const edges = planEdges(sites, { extra, maxLength });
+  const bearingsOf = (i) => edges
+    .filter((e) => e.a === i || e.b === i)
+    .map((e) => {
+      const o = sites[e.a === i ? e.b : e.a];
+      return Math.atan2(o.x - sites[i].x, o.z - sites[i].z);
+    });
+  const nodes = sites.map((s, i) => {
+    const bearings = bearingsOf(i);
+    const choice = chooseJunction(kit, candidates, bearings, { kinds });
+    return { ...s, index: i, degree: bearings.length, bearings, ...(choice ?? {}) };
+  });
+  return { nodes, edges };
+}

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