sindicate 0.13.0 → 0.16.0

package/src/world/roadKit.js

@@ -0,0 +1,110 @@
+// ROAD KIT — reading the measured kit a pack ships (roadkit.json from tools/roadKitAnalyze).
+//
+// The kit stores geometry only. Which side of the road traffic drives on is a RUNTIME
+// choice: a game may ship left-hand-drive, a designer may flip a map mid-edit to see how it
+// reads, and neither should require re-analysing a single mesh. So every lane records the
+// SIDE of the centre line it sits on ('L' or 'R', looking outward along its socket) and the
+// direction of travel is derived here.
+//
+//   const kit = await loadRoadKit('/assets/packs/KiwiRoads');
+//   kit.driveOnLeft = false;                 // flip the whole world, instantly
+//   for (const lane of kit.lanesOf(socket)) console.log(lane.flow);   // 'out' | 'in'
+
+export const laneFlow = (side, driveOnLeft) => ((side === 'L') === !!driveOnLeft ? 'out' : 'in');
+
+export function makeRoadKit(data, { driveOnLeft = data.driveOnLeft ?? true } = {}) {
+  const kit = {
+    pieces: data.pieces ?? {},
+    laneWidth: data.laneWidth ?? 5,
+    driveOnLeft,
+    piece(name) { return kit.pieces[name] ?? null; },
+    // lanes with their direction of travel resolved against the current hand of the road
+    lanesOf(socket) {
+      return (socket?.lanes ?? []).map((l) => ({ ...l, flow: laneFlow(l.side, kit.driveOnLeft) }));
+    },
+    // the lanes leaving / arriving at a socket, in kerb-to-median order
+    outboundOf(socket) { return kit.lanesOf(socket).filter((l) => l.flow === 'out'); },
+    inboundOf(socket) { return kit.lanesOf(socket).filter((l) => l.flow === 'in'); },
+    // sockets a given socket may legally join: same kind, compatible width
+    compatible(a, b, tol = 0.25) {
+      if (!a || !b) return false;
+      if ((a.kind ?? 'road') !== (b.kind ?? 'road')) return false;
+      return Math.abs(a.width - b.width) <= Math.max(a.width, b.width) * tol;
+    },
+    // every socket in the kit of a given kind, as { piece, socket } pairs
+    socketsOfKind(kind = 'road') {
+      const out = [];
+      for (const [name, p] of Object.entries(kit.pieces)) {
+        for (const s of p.sockets ?? []) if ((s.kind ?? 'road') === kind) out.push({ piece: name, socket: s });
+      }
+      return out;
+    },
+  };
+  return kit;
+}
+
+export async function loadRoadKit(packDir, opts) {
+  const data = await fetch(`${packDir}/roadkit.json`, { cache: 'no-store' }).then((r) => r.json());
+  return makeRoadKit(data, opts);
+}
+
+// WHICH LEVEL OF A PIECE MEETS THE GROUND.
+//
+// Multi-level pieces are authored around their own origin, not around grade: an overpass
+// interchange carries its local roads 10 m above origin and its motorway at origin; a
+// dumbbell carries the motorway 20 m up. Seat either by its origin and the parts that should
+// be at ground level hang in the air. Kiwi's answer was to sink the junction until the roads
+// that meet the outside world are at grade — so the level to seat by is the level of the
+// LOCAL road sockets when a piece has them, and the motorway's otherwise.
+export function gradeLevel(piece) {
+  const sockets = piece?.sockets ?? [];
+  if (!sockets.length) return 0;
+  const local = sockets.filter((s) => (s.kind ?? 'road') === 'road');
+  const use = local.length ? local : sockets;
+  return use.reduce((a, s) => a + s.pos[1], 0) / use.length;
+}
+
+// The y to place a piece at so its grade level lands on the given ground height.
+export const seatY = (piece, groundY) => groundY - gradeLevel(piece);
+
+// Any part of a piece that sits BELOW its grade level needs a trench: the motorway running
+// under an overpass roundabout, for instance. Returns corridors (in the piece's own frame)
+// that carve it, ready to be transformed with the piece.
+export function cuttings(piece, { margin = 3 } = {}) {
+  const grade = gradeLevel(piece);
+  const low = (piece?.sockets ?? []).filter((s) => s.pos[1] < grade - 1.5);
+  const out = [];
+  // pair opposite sockets: a motorway runs through, so its two ends define the alignment
+  for (let i = 0; i < low.length; i++) {
+    for (let j = i + 1; j < low.length; j++) {
+      const a = low[i], b = low[j];
+      if (a.dir[0] * b.dir[0] + a.dir[1] * b.dir[1] > -0.8) continue;   // not opposite ends
+      out.push({
+        from: a.pos, to: b.pos,
+        halfWidth: Math.max(a.width, b.width) / 2 + margin,
+      });
+    }
+  }
+  return out;
+}
+
+// Place a piece in the world and get its sockets in world space. Junction pieces are rigid:
+// they translate and yaw, never bend, so this is the whole transform.
+export function placeSockets(piece, { x = 0, y = 0, z = 0, yaw = 0 } = {}) {
+  const cos = Math.cos(yaw), sin = Math.sin(yaw);
+  const xf = (p) => [x + p[0] * cos + p[2] * sin, y + p[1], z - p[0] * sin + p[2] * cos];
+  return (piece?.sockets ?? []).map((s) => ({
+    ...s,
+    pos: xf(s.pos),
+    dir: [s.dir[0] * cos + s.dir[1] * sin, -s.dir[0] * sin + s.dir[1] * cos],
+    lanes: (s.lanes ?? []).map((l) => ({ ...l, centre: xf(l.centre) })),
+  }));
+}
+
+// The yaw that turns a piece's socket to face a target point — how a junction is aimed at
+// the thing it is about to be connected to.
+export function yawToFace(socket, tx, tz, { x = 0, z = 0 } = {}) {
+  const want = Math.atan2(tx - x, tz - z);
+  const have = Math.atan2(socket.dir[0], socket.dir[1]);
+  return want - have;
+}

package/src/world/roadLink.js

@@ -0,0 +1,343 @@
+// 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 };
+}
+
+// A PLAIN DECK between two points — no markings, no rails. A junction's two carriageways are
+// separate meshes with a gap down the middle, so the ground shows through under the central
+// reservation and drops away beneath the concrete. A generated link has no such gap because
+// it is one deck across its whole width; this closes the same gap inside a junction.
+export function buildDeck({ from, to, width, y = null, palette = PALETTE }) {
+  const ax = from[0], az = from[2], bx = to[0], bz = to[2];
+  const dx = bx - ax, dz = bz - az;
+  const len = Math.hypot(dx, dz) || 1;
+  const rx = -dz / len * (width / 2), rz = dx / len * (width / 2);
+  const ay = y ?? from[1], by = y ?? to[1];
+  const pos = new Float32Array([
+    ax - rx, ay, az - rz, ax + rx, ay, az + rz,
+    bx - rx, by, bz - rz, bx + rx, by, bz + rz,
+  ]);
+  const nrm = new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]);
+  const uv = new Float32Array([
+    palette.asphalt[0], palette.asphalt[1], palette.asphalt[0], palette.asphalt[1],
+    palette.asphalt[0], palette.asphalt[1], palette.asphalt[0], palette.asphalt[1],
+  ]);
+  const g = new THREE.BufferGeometry();
+  g.setAttribute('position', new THREE.BufferAttribute(pos, 3));
+  g.setAttribute('normal', new THREE.BufferAttribute(nrm, 3));
+  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2));
+  g.setIndex([0, 1, 2, 1, 3, 2]);
+  g.computeBoundingSphere();
+  return g;
+}
+
+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)
+  railStep = 5,              // spacing of the shoulder rail sections
+  medianStep = 2,            // spacing of the median's blocks
+  railInset = 0.55,          // how far inside the deck edge the shoulder rail stands
+  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();
+
+  // WHERE THE BARRIERS GO. A motorway's median is the gap between its two innermost solid
+  // lines; its shoulders are outside the outermost. Returned as posts a game can instance
+  // its own guardrail along — the generator lays road, not other people's props.
+  const railings = { median: [], left: [], right: [] };
+  if (section?.lines?.length >= 4) {
+    const byInner = section.lines.map((b) => b.at).sort((a, b) => Math.abs(a) - Math.abs(b));
+    const medianHalf = Math.abs(byInner[0]);
+    const outer = Math.max(...section.lines.map((b) => Math.abs(b.at)));
+    // each line is sampled at ITS OWN prop's length — a concrete median block is not a
+    // steel rail section, and posting them at the same spacing leaves gaps or overlaps
+    const lay = (into, spacing, offsetOf) => {
+      const out = [];
+      for (let s = spacing / 2; s <= length - spacing / 2; s += spacing) {
+        const sm = along(s);
+        const off = offsetOf(sm);
+        // PITCH. A rail section is a rigid bar: leave it level on a graded road and each
+        // one steps down from the last, which reads as a gap at every joint. Tilt it to the
+        // local slope and consecutive sections meet end to end.
+        const back = along(Math.max(s - spacing / 2, 0));
+        const fore = along(Math.min(s + spacing / 2, length));
+        const rise = fore.p.y - back.p.y;
+        const run = Math.hypot(fore.p.x - back.p.x, fore.p.z - back.p.z) || 1e-3;
+        out.push({
+          pos: [
+            +(sm.p.x + sm.right.x * off).toFixed(3), +sm.p.y.toFixed(3),
+            +(sm.p.z + sm.right.z * off).toFixed(3),
+          ],
+          // a prop modelled along its own X lies along the road at this yaw
+          yaw: Math.atan2(sm.right.x, sm.right.z) + (into ? Math.PI : 0),
+          pitch: +(Math.atan2(rise, run) * (into ? -1 : 1)).toFixed(5),
+        });
+      }
+      return out;
+    };
+    if (medianHalf > 0.5) railings.median = lay(false, medianStep, () => 0);
+    // ON THE SHOULDER, not off it. A rail set beyond the deck edge stands in the grass and
+    // wanders off the road wherever the carriageway narrows; it belongs on the grey strip
+    // outside the outer line, which is still road.
+    railings.left = lay(false, railStep, (sm) => -(sm.half - railInset));
+    railings.right = lay(true, railStep, (sm) => sm.half - railInset);
+  }
+
+  // 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, railings,
+    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,158 @@
+// 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;
+}
+
+// A CLOSED CIRCUIT through every site — a ring road or an orbital motorway. Nearest-neighbour
+// tour, then 2-opt until no crossing pair remains, which is enough to stop a small loop from
+// doubling back on itself. Returns the sites in travel order.
+export function planLoop(sites) {
+  const n = sites.length;
+  if (n < 3) return sites.map((_, i) => i);
+  const d = (a, b) => Math.hypot(sites[a].x - sites[b].x, sites[a].z - sites[b].z);
+  const tour = [0];
+  const left = new Set(sites.map((_, i) => i).slice(1));
+  while (left.size) {
+    const from = tour[tour.length - 1];
+    let best = null;
+    for (const i of left) { const dd = d(from, i); if (!best || dd < best.d) best = { i, d: dd }; }
+    tour.push(best.i);
+    left.delete(best.i);
+  }
+  const tourLen = (t) => t.reduce((a, _, i) => a + d(t[i], t[(i + 1) % n]), 0);
+  for (let pass = 0; pass < 40; pass++) {
+    let improved = false;
+    for (let i = 1; i < n - 1; i++) {
+      for (let j = i + 1; j < n; j++) {
+        const cand = [...tour.slice(0, i), ...tour.slice(i, j + 1).reverse(), ...tour.slice(j + 1)];
+        if (tourLen(cand) < tourLen(tour) - 1e-6) { tour.splice(0, n, ...cand); improved = true; }
+      }
+    }
+    if (!improved) break;
+  }
+  return tour;
+}
+
+// Where a piece must face to sit ON a loop: along the local tangent, so its through-
+// carriageway continues the circuit rather than pointing across it.
+export function loopTangents(sites, order) {
+  const n = order.length;
+  return order.map((idx, k) => {
+    const prev = sites[order[(k - 1 + n) % n]], next = sites[order[(k + 1) % n]];
+    return { index: idx, yaw: Math.atan2(next.x - prev.x, next.z - prev.z) };
+  });
+}
+
+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 };
+}