sindicate 0.15.0 → 0.17.0

package/src/world/roadAssert.js

@@ -0,0 +1,152 @@
+// WHAT MUST BE TRUE OF A ROAD WORLD.
+//
+// Every fault in this file was found by a person driving into it, one at a time, over an
+// afternoon. Each was silent: nothing threw, nothing logged, the world simply looked wrong in
+// one particular place. That is the argument for checking them at build — a road system has
+// no natural failure mode, so it needs assertions or it needs somebody's evening.
+//
+//   const report = auditRoadWorld(roads, { ground });
+//   if (report.failures.length) console.warn(report.summary);
+//
+// Cheap by design: it samples rather than proves, so a game can afford to run it on every
+// cold build and still boot.
+const NEAR = (a, b, tol) => Math.abs(a - b) <= tol;
+
+export function auditRoadWorld(roads, { ground, samples = 24, tolerance = 0.06 } = {}) {
+  const checks = [];
+  const fail = (rule, detail) => checks.push({ rule, ok: false, detail });
+  const pass = (rule, detail) => checks.push({ rule, ok: true, detail });
+  const { heightAt, links = [], placed = new Map() } = roads ?? {};
+  if (!heightAt || !links.length) return { failures: [], checks, summary: 'no roads to audit' };
+
+  // 1. NO DIRT ABOVE TARMAC. The ground is cut below every deck; if it is not, a wedge of
+  //    landscape lies across the carriageway.
+  let poke = 0, worstPoke = 0, pokeAt = null, n1 = 0;
+  for (const { link, from } of links) {
+    const half = from.width / 2;
+    const line = link.centreline;
+    for (let i = 2; i < line.length - 2; i += Math.max(1, Math.floor(line.length / samples))) {
+      const p = line[i], q = line[i + 1];
+      const fx = q[0] - p[0], fz = q[2] - p[2], L = Math.hypot(fx, fz) || 1;
+      const rx = -fz / L, rz = fx / L;
+      for (const off of [-half * 0.95, 0, half * 0.95]) {
+        const x = p[0] + rx * off, z = p[2] + rz * off;
+        n1++;
+        const over = heightAt(x, z) - p[1];
+        if (over > tolerance) {
+          poke++;
+          if (over > worstPoke) { worstPoke = over; pokeAt = [Math.round(x), Math.round(z)]; }
+        }
+      }
+    }
+  }
+  poke ? fail('no ground above a road', `${poke}/${n1} samples, worst ${worstPoke.toFixed(2)} m at ${pokeAt}`)
+       : pass('no ground above a road', `${n1} samples clean`);
+
+  // 2. NO FLOATING ROADS. Beside the tarmac the ground must come up to meet it — a road with
+  //    a gap of air under its edge exists nowhere in the world.
+  let float = 0, worstFloat = 0, floatAt = null, n2 = 0;
+  for (const { link, from } of links) {
+    const half = from.width / 2;
+    const line = link.centreline;
+    for (let i = 2; i < line.length - 2; i += Math.max(1, Math.floor(line.length / samples))) {
+      const p = line[i], q = line[i + 1];
+      const fx = q[0] - p[0], fz = q[2] - p[2], L = Math.hypot(fx, fz) || 1;
+      const rx = -fz / L, rz = fx / L;
+      for (const off of [-half - 1.5, half + 1.5]) {
+        const x = p[0] + rx * off, z = p[2] + rz * off;
+        // A CUTTING IS NOT A FLOATING ROAD. Where a lower carriageway runs alongside — the
+        // motorway beneath an interchange, say — the ground beside this road drops to meet
+        // it, held by a retaining wall. That is a road ON something, not over nothing.
+        // look a little wider than the sample itself: the wall of a cutting stands OUTSIDE
+        // the lower carriageway's bed, so asking only at this exact point misses it
+        let inCutting = false;
+        for (const probe of [0, 6, 12]) {
+          const b = heightAt.deck?.(x + rx * Math.sign(off) * probe, z + rz * Math.sign(off) * probe);
+          if (b != null && b < p[1] - 2) { inCutting = true; break; }
+        }
+        if (inCutting) continue;
+        n2++;
+        const under = p[1] - heightAt(x, z);
+        if (under > 1.0) {
+          float++;
+          if (under > worstFloat) { worstFloat = under; floatAt = [Math.round(x), Math.round(z)]; }
+        }
+      }
+    }
+  }
+  float ? fail('no road floating over a gap', `${float}/${n2} edge samples, worst ${worstFloat.toFixed(2)} m at ${floatAt}`)
+        : pass('no road floating over a gap', `${n2} edge samples clean`);
+
+  // 3. EVERY LINK MEETS ITS SOCKETS. A road that stops short of the junction it was built to
+  //    reach is the one fault a player cannot drive around.
+  let gaps = 0;
+  for (const { link, from, to } of links) {
+    const a = link.centreline[0], b = link.centreline[link.centreline.length - 1];
+    if (!NEAR(a[0], from.pos[0], 0.1) || !NEAR(a[2], from.pos[2], 0.1) || !NEAR(a[1], from.pos[1], 0.1)) gaps++;
+    if (!NEAR(b[0], to.pos[0], 0.1) || !NEAR(b[2], to.pos[2], 0.1) || !NEAR(b[1], to.pos[1], 0.1)) gaps++;
+  }
+  gaps ? fail('every link meets both sockets', `${gaps} loose ends`)
+       : pass('every link meets both sockets', `${links.length * 2} ends joined`);
+
+  // 4. NOTHING UNDRIVABLE. A link whose grade had to exceed what was asked for is a fact the
+  //    world should know about, not a surprise on the hill.
+  const steep = links.filter(({ link }) => link.feasible === false);
+  steep.length ? fail('every link is drivable at its grade', `${steep.length} link(s) needed more grade than allowed`)
+               : pass('every link is drivable at its grade', `${links.length} links within grade`);
+
+  // 5. NOTHING CLAIMS TARMAC IT HAS NOT GOT. A game that hides the ground under its roads —
+  //    the only cure for two surfaces a few centimetres apart fighting for the same pixels —
+  //    trusts `heightAt.deck` absolutely: wherever it answers, the terrain is thrown away.
+  //    So an answer past the end of a road does not make a small error, it makes a hole in
+  //    the world with the sky showing through it. This was reported from the driver's seat
+  //    as a black patch at the end of every road, twice.
+  let phantom = 0, phantomAt = null, n5 = 0;
+  for (const { link, from } of links) {
+    const line = link.centreline;
+    const half = from.width / 2;
+    for (const [p, q] of [[line[0], line[1]], [line[line.length - 1], line[line.length - 2]]]) {
+      if (!p || !q) continue;
+      const ax = p[0] - q[0], az = p[2] - q[2];
+      const L = Math.hypot(ax, az) || 1;                 // outward, away from the road
+      for (const past of [1.5, half, half * 2 + 4]) {
+        for (const side of [-0.8, 0, 0.8]) {
+          const x = p[0] + (ax / L) * past - (az / L) * side * half;
+          const z = p[2] + (az / L) * past + (ax / L) * side * half;
+          n5++;
+          if (heightAt.deck?.(x, z) != null) { phantom++; phantomAt ??= [Math.round(x), Math.round(z)]; }
+        }
+      }
+    }
+  }
+  phantom ? fail('no phantom tarmac past a road end', `${phantom}/${n5} probes claimed a deck, first at ${phantomAt}`)
+          : pass('no phantom tarmac past a road end', `${n5} probes beyond the ends clean`);
+
+  // 6. JUNCTIONS SIT ON THEIR OWN GROUND. A piece seated at the wrong level is the difference
+  //    between a slip road and a diving board.
+  let hanging = 0;
+  for (const [, p] of placed) {
+    if (!p.site) continue;
+    // sample ACROSS the footprint and take the median: a multi-level piece has a motorway
+    // running through its middle in a trench, so the ground at its exact centre is
+    // legitimately metres below grade. What matters is that the piece as a whole is seated.
+    const r = (p.piece?.size?.[0] ?? 60) * 0.35;
+    const around = [];
+    for (let k = 0; k < 8; k++) {
+      const th = (k / 8) * Math.PI * 2;
+      around.push(heightAt(p.site.x + Math.cos(th) * r, p.site.z + Math.sin(th) * r));
+    }
+    around.sort((x, y) => x - y);
+    const median = around[Math.floor(around.length / 2)];
+    if (Math.abs(median - p.site.y) > 1.5) hanging++;
+  }
+  hanging ? fail('junctions seated on their own ground', `${hanging} piece(s) more than 1.5 m off`)
+          : pass('junctions seated on their own ground', `${placed.size} pieces seated`);
+
+  const failures = checks.filter((c) => !c.ok);
+  const summary = [
+    `road audit: ${checks.length - failures.length}/${checks.length} passed`,
+    ...checks.map((c) => `  ${c.ok ? '✓' : '✗'} ${c.rule} — ${c.detail}`),
+  ].join('\n');
+  return { failures, checks, summary };
+}

package/src/world/roadLink.js

@@ -15,14 +15,26 @@
 // 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)
+// TEXELS IN THE SIMPLIGON ATLAS, flat-sampled — Kiwi's own coordinates, from
+// CurvedRoadMeshGenerator: UV_ROAD (0.2871, 0.0361), UV_WHITE (0.2871, 0.1105),
+// UV_CONCRETE top (0.2993, 0.1396) and edge (0.2993, 0.1133).
+//
+// The concrete pair was missing here, so anything that was not tarmac got painted with the
+// WHITE LINE texel — which is why the pavements came out looking like road markings rather
+// than like pavements.
+const PALETTE = {
   asphalt: [0.2871, 0.0361],
   line: [0.2871, 0.1105],
+  concrete: [0.2993, 0.1396],       // footway top
+  kerb: [0.2993, 0.1133],           // its edge, and the gutter face
 };
 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;
+// KIWI'S OWN FIGURES (CurvedRoadMeshGenerator: DASH_LENGTH 1, DASH_GAP 1.5, DASH_WIDTH
+// 0.15, MARKING_HEIGHT 0.02). Mine were 2.5 on and 2.5 off, which reads as a lane divider on
+// a motorway and as sleepers on a street.
+const DASH_W = 0.15;        // centre-line width
+const DASH_ON = 1.0, DASH_OFF = 1.5;
 
 const catmull = (p, t) => {
   // smooth interpolation through the given heights (duplicated ends = flat entry/exit)
@@ -79,6 +91,34 @@ function limitGrade(samples, gWanted, yStart, yEnd) {
   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
@@ -87,6 +127,9 @@ export function buildRoadLink({
   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);
@@ -165,16 +208,70 @@ export function buildRoadLink({
     };
   };
 
-  // ── 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);
+  // ── the deck ──
+  //
+  // A CROSS-SECTION WITH HEIGHT IN IT, when the socket carries one. A city street is not a
+  // flat ribbon with paint on it: it has a kerb, a gutter that drops below the carriageway,
+  // and a footway raised above it. Kiwi builds these by taking a road prefab's front-edge
+  // vertices as a profile and extruding that along the spline (CurvedRoadMeshGenerator.
+  // ExtractRoadProfile), which is why its streets have kerbs and mine, tiled by hand, did
+  // not. `profile` is that list of [lateral, height] pairs; without one the deck is the flat
+  // ribbon a motorway wants, where the kerbs are somebody else's barrier props.
+  //
+  // Lateral offsets scale with the socket width so one profile serves a narrow lane and a
+  // wide street, and heights do NOT — a kerb is 125 mm whatever the road.
+  const xsec = from.profile ?? to.profile ?? null;
+  let refHalfOut = 1;
+  if (xsec?.length >= 2) {
+    // SCALE AGAINST THE CARRIAGEWAY, NOT THE WHOLE SECTION. A socket's `width` is the
+    // driveable width; the profile is wider than that because it includes the kerb, the
+    // footway and the verge behind it. Scaling by the outermost point squeezes the entire
+    // 20 m section into the 10 m carriageway — every kerb and pavement at half size.
+    // The carriageway ends at its OWN outermost vertex, not at the first kerb vertex beyond
+    // it. Those are different points — the kerb face begins a few centimetres outside the
+    // tarmac edge — and taking the kerb's makes every road that fraction narrow: a 10 m
+    // street came out 9.84 m, and every kerb, footway and lane marking with it.
+    const kerbAt = xsec.filter(([, y]) => y < -0.01).map(([x]) => Math.abs(x));
+    const innerKerb = kerbAt.length ? Math.min(...kerbAt) : Infinity;
+    const flat = xsec.filter(([x, y]) => Math.abs(y) <= 0.01 && Math.abs(x) <= innerKerb).map(([x]) => Math.abs(x));
+    const refHalf = (flat.length ? Math.max(...flat)
+      : Number.isFinite(innerKerb) ? innerKerb
+      : Math.max(...xsec.map(([x]) => Math.abs(x)))) || 1;
+    refHalfOut = refHalf;
+    // WHICH SIDE OF THE KERB IS IT ON? Height alone is not enough, and this is the rule
+    // Kiwi's GetSimpligonUV actually uses: cast from the centre line toward the vertex, and
+    // if a kerb lies between them, the vertex is footway — even where it is flat. A pavement
+    // is mostly level ground BEHIND a kerb, so judging by height alone paints the 0.35 m
+    // raised lip as pavement and the four metres of actual footway behind it as tarmac.
+    const kerbs = xsec.filter(([, y]) => y < -0.01).map(([x]) => x);
+    const pastKerb = (lx) => kerbs.some((k) => (lx > 0 && k > 0 && k < lx) || (lx < 0 && k < 0 && k > lx));
+    const rows = samples.map(({ p, right, half }) => xsec.map(([lx, ly]) => {
+      const q = p.clone().addScaledVector(right, (lx / refHalf) * half);
+      q.y += ly;
+      // the same three-way split Kiwi makes: below grade is the kerb face, raised or behind
+      // a kerb is footway, everything else is carriageway
+      const tex = ly < -0.01 ? palette.kerb
+        : (ly > 0.05 || pastKerb(lx)) ? palette.concrete
+        : palette.asphalt;
+      return vert(q, UP, tex);
+    }));
+    for (let i = 0; i < rows.length - 1; i++) {
+      for (let k = 0; k < xsec.length - 1; k++) {
+        const a = rows[i][k], b = rows[i][k + 1], c = rows[i + 1][k], d = rows[i + 1][k + 1];
+        idx.push(a, b, c, b, d, c);
+      }
+    }
+  } else {
+    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 ──
@@ -229,13 +326,20 @@ export function buildRoadLink({
 
   // ── side apron so an elevated road is not a floating sheet ──
   if (skirt > 0) {
+    // AT THE OUTSIDE OF THE SECTION, not at the carriageway edge. `half` is the driveable
+    // half-width, which with a profile is the middle of the ribbon, not its edge — so the
+    // apron came down as a wall right where the kerb is, a grey strip alongside the tarmac
+    // that reads as part of the road instead of the side of the pavement.
+    const outer = xsec?.length ? Math.max(...xsec.map(([x]) => Math.abs(x))) / (refHalfOut || 1) : 1;
     for (const side of [-1, 1]) {
       const wall = [];
       for (const { p, right, half } of samples) {
-        const top = p.clone().addScaledVector(right, side * half);
+        const top = p.clone().addScaledVector(right, side * half * outer);
         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)]);
+        // and it is the side of the PAVEMENT out here, not the side of the road
+        const tex = xsec?.length ? palette.kerb : palette.asphalt;
+        wall.push([vert(top, n, tex), vert(bot, n, tex)]);
       }
       for (let i = 0; i < wall.length - 1; i++) {
         const [a, b] = wall[i], [c, d] = wall[i + 1];
@@ -252,6 +356,48 @@ export function buildRoadLink({
   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 = [];
@@ -261,7 +407,7 @@ export function buildRoadLink({
     grades.push(dy / dxz);
   }
   return {
-    geometry, centreline, length,
+    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

package/src/world/roadNetwork.js

@@ -50,6 +50,46 @@ export function planEdges(sites, { extra = 0.35, maxLength = Infinity } = {}) {
   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); };

package/src/world/roadTerrain.js

@@ -14,6 +14,24 @@ 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
+// HOW FAR ALONG A SEGMENT A POINT SITS, or null if the segment does not cover it. The two
+// callers below both used to inline this and both got the ends wrong in the same way; the
+// terrain went missing in a rounded blob past the end of every road, because a point out
+// there was told it had tarmac over it and its triangles were dropped as invisible.
+//
+// `narrow` pulls the edges in: a corridor's BED is wider than its carriageway, so anything
+// asking "is the ground hidden here?" must ask about the road, not the earthwork.
+function along(s, x, z, narrow = 0) {
+  const dx = s.bx - s.ax, dz = s.bz - s.az;
+  const len2 = dx * dx + dz * dz || 1e-6;
+  const raw = ((x - s.ax) * dx + (z - s.az) * dz) / len2;
+  // past either END of the whole line there is no road, however close the last vertex is
+  if (raw < 0 && s.first) return null;
+  if (raw > 1 && s.last) return null;
+  const t = Math.min(1, Math.max(0, raw));
+  return Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) <= s.half - narrow ? t : null;
+}
+
 function segmentIndex(corridors, cell) {
   const buckets = new Map();
   const key = (i, j) => `${i},${j}`;
@@ -28,6 +46,19 @@ function segmentIndex(corridors, cell) {
       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,
+        // DOES THIS CORRIDOR CARRY TARMAC? Most do — a corridor is normally the cut and fill
+        // under a road. Some are pure earthwork: the trench that opens the ground under an
+        // interchange's lower carriageway is shaped like a road and is not one, and it runs
+        // on past the sockets at either end so the batter has somewhere to go. Told that was
+        // tarmac, the "don't draw ground you cannot see" pass threw away the terrain over the
+        // whole trench and left a hole in the world past the end of the road.
+        carries: c.deck !== false,
+        // WHERE THE ROAD STOPS. A segment answers questions about points near it by
+        // clamping the projection to its own span, which turns each end of a polyline into
+        // a half-disc of phantom road reaching a full half-width past the last vertex.
+        // Harmless in the middle of a line — the next segment covers that ground anyway —
+        // and wrong at the two ends, where it claims tarmac over open country.
+        first: i === 0, last: i === line.length - 2,
       };
       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);
@@ -114,20 +145,110 @@ function rasterAt(r, x, z) {
   return { y: r.h[k], d: r.d[k] + Math.hypot(outX, outZ) };
 }
 
-export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfaces = [], cell = 32 } = {}) {
+// 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;
 
-  return function heightAt(x, z) {
+  // 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 t = along(s, x, z);
+        if (t == null) 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];
+      if (!s.carries) continue;                        // an earthwork is not a road surface
+      const t = along(s, x, z, shrink);
+      if (t == null) 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 p of pads) {
+    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
-      const reach = d * (p.batter ?? 0.5);                    // same earthwork law as a link
-      h = Math.min(Math.max(h, y - reach), y + reach);
+      // 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 ──
@@ -173,8 +294,20 @@ export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfa
       }
     }
 
+    // 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
@@ -216,7 +349,7 @@ export function seatHeight(heightAt, x, z, radius, rings = 3, spokes = 8) {
 // 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 } = {}) {
+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) {
@@ -230,7 +363,16 @@ export function pickManySites(heightAt, { count = 5, half = 600, step = 90, radi
   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);
+    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;
 }