sindicate 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.16.0 — driving on it
+
+### A car (new: `vehicle/`)
+
+- `vehicle/car.js` — a wheel at each corner asking the world for its own ground, so pitch,
+  roll and hanging a wheel over an edge all fall out of it. Spring-damped suspension, a
+  power-limited engine (0–60 in 4.6 s, not 0–123 in three), brakes, and a handbrake that
+  genuinely breaks grip: the body points one way and travels another when it slides. It also
+  owns where to probe for obstacles and what to do about a hit — the game only answers a ray.
+- `vehicle/carAudio.js` — the classic four-loop engine: acceleration and deceleration at low
+  and high revs, crossfaded by revs and throttle, with tyres that protest in proportion to
+  the slide.
+
+The header of `car.js` lists the faults it exists to prevent, each found the hard way: a body
+snapped to the ground is glued to it; an airborne test against one frame of gravity flickers
+on contact noise and sags the car to a crawl; one ray down the nose lets the body pass through
+anything not hit head-on; a rail alongside must never bleed speed.
+
+### Roads as a world-build step
+
+- `world/roadWorld.js` — one call that runs the road build in the only order that works and
+  hands back a `heightAt` for `buildHeightfield`, geometry to stamp before the BVH bake, and
+  the solved network. Site, seat each piece at ITS grade, wrap the ground with pads, THEN
+  generate links over that padded ground, then wrap again with their corridors.
+- `world/roadAssert.js` — what must be true of a road world: no ground above a road, no road
+  floating over a gap, every link meeting both sockets, every link drivable at its grade,
+  every junction seated on its own ground. Cheap enough for every cold build. It found three
+  real faults on its first run.
+- `world/roadNetwork.js` — `planLoop`/`loopTangents` for closed circuits.
+- `world/roadLink.js` — `buildDeck`, and rail lines (median and shoulders) reported with the
+  pitch of the ground they sit on.
+- `world/roadTerrain.js` — the ground now guarantees it never sits above a road, pads fade
+  into the landscape rather than ending at a rim, `heightAt.road`/`heightAt.deck` answer where
+  the driveable surface is, and the whole wrapper is bucketed (25× → 10.7× over bare terrain
+  across a 1.7 M-vertex lattice).
+
+### Tools
+
+- `tools/unityPackageExtract.mjs` — pull named assets out of a `.unitypackage` without staging
+  the whole thing.
+- `tools/fbxToGlb.mjs`, `tools/roadKitAnalyze.mjs`, `tools/buildKiwiRoadsPack.mjs`.
+
+### Fixed
+
+- **Trains ran beside the track, not on it.** `train.js` still reached for a county's railway
+  data through `import.meta.glob`, which inside the engine resolves against the engine's own
+  folder and finds nothing — so the fleet silently graded its own polyline. The solved survey
+  goes in through `setTrainContent`.
+
 ## 0.15.0 — the world-building release
 
 Everything between the last published version (0.13.0) and here. 0.14.0 was bumped in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",

package/src/systems/train.js

@@ -38,6 +38,13 @@ export function setTrainContent(c = {}) {
   if (c.colliders) colliders = c.colliders;
   if (c.dropItemsFor) dropItemsFor = c.dropItemsFor;
   if (c.railPaths) SURVEY_PATHS = c.railPaths;
+  // THE TRACK AUTHOR'S OWN SURVEY. Without it the fleet grades its own polyline and runs
+  // beside the rails the county actually laid.
+  if (c.railLines) LINES_IN = c.railLines;
+  if (c.railLineStops) STOPS_IN = c.railLineStops;
+  if (c.levelCrossing) XING_IN = c.levelCrossing;
+  if (c.junction) JUNC_IN = c.junction;
+  if (c.railTop != null) { RAIL_TOP = c.railTop; RAIL_Y = RAIL_TOP - FLANGE; }
   if (c.railStops) SURVEY_STOPS = c.railStops;
   if (c.crossing !== undefined) SURVEY_CROSSING = c.crossing;
   if (c.halts) RAIL_HALTS = c.halts;
@@ -89,18 +96,21 @@ import { attachTrainCamera } from './trainCamera.js';
 const _mods = import.meta.glob(['../world/railway.js', '../world/data/railway.js'], { eager: true });
 const RD = _mods['../world/data/railway.js'] ?? {};
 
-const LINES_IN = RD.RAIL_LINES ?? null;         // { main: {nodes,len}, spur: {nodes,len} }
-const STOPS_IN = RD.RAIL_STOPS ?? null;         // [{ id, name, line, s, platformSide, wait }]
-const XING_IN = RD.LEVEL_CROSSING ?? null;      // { line, s, x, z }
-const JUNC_IN = RD.JUNCTION ?? null;            // { line, s, x, z }
+// ...and inside the ENGINE that glob resolves against the engine's own folder, where no
+// county's railway data lives — so these MUST be injectable. A game hands its solved survey
+// to setTrainContent; the glob remains for a game that still keeps train.js's neighbours.
+let LINES_IN = RD.RAIL_LINES ?? null;           // { main: {nodes,len}, spur: {nodes,len} }
+let STOPS_IN = RD.RAIL_STOPS ?? null;           // [{ id, name, line, s, platformSide, wait }]
+let XING_IN = RD.LEVEL_CROSSING ?? null;        // { line, s, x, z }
+let JUNC_IN = RD.JUNCTION ?? null;              // { line, s, x, z }
 
 // The railhead above the formation — his number, not mine. A car's origin sits at RAILHEAD CONTACT
 // (measured: min.y = 0 on all four models), so this is exactly how high off the ballast it rides,
 // less a flange: the wheel's lowest point is its flange, not its tread, and standing the tread ON
 // the rail is what closes the hairline of daylight under a stationary loco.
-const RAIL_TOP = RD.RAIL_TOP ?? 0.3285;
+let RAIL_TOP = RD.RAIL_TOP ?? 0.3285;
 const FLANGE = 0.06;
-const RAIL_Y = RAIL_TOP - FLANGE;
+let RAIL_Y = RAIL_TOP - FLANGE;
 
 // ── THE FALLBACK ROUTE (only if data/railway.js has not landed) ───────────────────────────────
 const FALLBACK_PATHS = [

package/src/vehicle/car.js

@@ -0,0 +1,321 @@
+// A CAR — suspension, wheels, brakes, grip.
+//
+// Deliberately not a rigid-body solver: a planar body with a wheel at each corner, which is
+// what an open-world game actually needs and what can be reasoned about when it misbehaves.
+// The car owns its physics; a game owns its model, its sounds and its camera.
+//
+//   const car = createCar({ surfaceAt });
+//   car.update(dt, { throttle, brake, handbrake, steer });
+//   // then pose the model from car.pose() and the wheels from car.wheels
+//
+// `surfaceAt(x, z, fromY)` returns the height of whatever is driveable under a point, or
+// null for thin air — a raycast against the road meshes, typically. Each wheel asks
+// separately, which is what gives pitch, roll and the ability to hang a wheel over an edge.
+//
+// `obstacleAt(from, dir, reach)` answers what is standing in the way: { normal, distance } or
+// null. The GAME decides how to answer a ray; the CAR decides where to ask and what to do
+// about the answer, because that is the part with all the traps in it — which is why it
+// belongs here and not in a game's page.
+//
+// The four faults this module exists to prevent, all of them found the hard way:
+//   · a body snapped to the ground every frame is glued to it and can never leave a ramp;
+//   · an airborne test that compares one frame against gravity flickers on contact noise,
+//     and if landing costs speed the car sags to a crawl with the throttle held;
+//   · a single collision ray down the nose lets the whole body pass through anything it did
+//     not drive at head-on;
+//   · a "wall" that is really a rail alongside must never bleed speed.
+const G = 9.81;
+
+const wrapPi = (a) => Math.atan2(Math.sin(a), Math.cos(a));
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+
+export const CAR_DEFAULTS = {
+  // measured off the Synty sedan; a game passes its own model's numbers
+  wheelbase: 2.88,          // front axle to rear axle
+  track: 1.66,              // left wheel to right wheel
+  wheelRadius: 0.36,
+  rideHeight: 0.34,         // body origin above the contact patch at rest
+  mass: 1300,
+
+  suspension: {
+    travel: 0.22,           // how far a wheel may move before it tops or bottoms out
+    stiffness: 26,          // rad/s² per metre of compression — how hard it pushes back
+    damping: 7.5,           // how quickly it stops oscillating
+  },
+
+  engine: {
+    // A CAR IS POWER-LIMITED, not force-limited. A constant acceleration means it pulls as
+    // hard at 120 mph as at walking pace — 0 to 123 mph in three seconds, which is madness.
+    // Tyres cap what you can put down low; above that it is power over speed, so the pull
+    // fades as the car gains speed and top speed is approached slowly, as it should be.
+    traction: 6.5,          // m/s² — all the grip will take from a standing start
+    power: 152,             // m²/s³ — acceleration = power / speed once rolling
+    drive: 14,              // m/s² — legacy name, still honoured if a game sets it
+    topSpeed: 55,           // ~200 km/h
+    reverseSpeed: 12,
+    // COASTING. A single per-second decay is not drag: at 90 km/h a 0.55 decay takes
+    // 13.75 m/s² out of the car — harder than most braking — so lifting off felt like
+    // standing on the pedal. Real resistance is a near-constant rolling term plus air that
+    // only bites at speed, and top speed is held by the limiter rather than by drag.
+    rollingResistance: 0.35,  // m/s², roughly constant
+    airDrag: 0.0008,          // m/s² per (m/s)² — about 0.5 m/s² at 90 km/h
+  },
+
+  brakes: {
+    force: 22,              // m/s² on the pedal
+    handbrake: 9,           // the rear locking up
+  },
+
+  grip: {
+    normal: 7.5,            // how fast travel direction is dragged round to face the car
+    handbrake: 1.1,         // ...and how completely it lets go when the rear locks
+    steerRate: 1.5,         // radians/s of yaw at speed
+    steerHandbrake: 2.6,
+    steerBite: 12,          // m/s at which steering reaches full authority
+  },
+
+  // A GUARDRAIL IS A THIN BAR ON POSTS. One ray at one height slips under the rail or
+  // through the gap between two posts, so whether a fence stops you depends on the angle you
+  // happened to approach it at. Feeling for it at several heights catches the bar, the post
+  // and the kerb alike.
+  body: { halfWidth: 1.0, halfLength: 2.4, probeHeights: [0.25, 0.55, 0.9] },
+  maxLean: 0.6,             // ~35 deg: no contact reading may tip the body further than this
+  launchMargin: 3.5,        // the ground must fall away this much faster than gravity to fly
+  landingHit: 6,            // vertical speed below which a landing costs nothing
+  maxStep: 0.45,            // the tallest thing a wheel may climb onto in one go
+};
+
+// TWO DIFFERENT QUESTIONS, and conflating them is what makes a car crawl: something AHEAD
+// obstructs travel, something ALONGSIDE only stops the body moving sideways into it. A rail
+// you are driving down must never bleed speed. Probes cover the whole body, nose to tail —
+// one ray down the middle lets a back end swing clean through a barrier on a turn.
+function resolveObstacles(car, dt, obstacleAt) {
+  const { halfWidth, halfLength } = car.cfg.body;
+  const heights = car.cfg.body.probeHeights ?? [car.cfg.body.probeHeight ?? 0.4];
+  const fx = Math.sin(car.travel), fz = Math.cos(car.travel);
+  const rx = -fz, rz = fx;                                  // the car's right, in world terms
+  const ask = (ox, oz, dx, dz, reach) => {
+    let best = null;
+    for (const h of heights) {
+      const hit = obstacleAt({ x: car.pos.x + ox, y: car.pos.y + h, z: car.pos.z + oz }, { x: dx, z: dz }, reach);
+      if (hit && (!best || hit.distance < best.distance)) best = hit;
+    }
+    return best;
+  };
+
+  // AHEAD (or behind, in reverse) — only as far as the car will actually travel this frame,
+  // or every curve reads as a collision with the barrier running alongside it
+  if (Math.abs(car.speed) > 0.4) {
+    const sgn = Math.sign(car.speed);
+    const dx = fx * sgn, dz = fz * sgn;
+    const nose = halfLength * sgn;
+    const reach = 0.2 + Math.abs(car.speed) * dt;
+    for (const off of [-halfWidth, 0, halfWidth]) {
+      const hit = ask(fx * nose + rx * off, fz * nose + rz * off, dx, dz, reach);
+      if (!hit) continue;
+      const n = hit.normal;
+      // slide along it rather than stopping dead, and only scrub speed for a square hit
+      const headOn = clamp(-(n.x * dx + n.z * dz), 0, 1);
+      car.pos.x += n.x * (reach - hit.distance);
+      car.pos.z += n.z * (reach - hit.distance);
+      // square-on stops you quickly; a glancing scrape barely costs anything
+      car.speed *= 1 - 6 * headOn * Math.min(dt, 0.05);
+      // deflect where the car is GOING, not where it is pointing. Turning the facing leaves
+      // it crabbing down the road at the angle of whatever it brushed, long after the
+      // contact has gone; grip brings the nose round on its own.
+      let alongX = -n.z, alongZ = n.x;
+      if (alongX * fx + alongZ * fz < 0) { alongX = -alongX; alongZ = -alongZ; }
+      car.travel += wrapPi(Math.atan2(alongX, alongZ) - car.travel) * Math.min(1, dt * 6);
+      break;
+    }
+  }
+
+  // ALONGSIDE — push the body out, never touch its speed
+  for (const s of [-1, 1]) {
+    for (const along of [halfLength * 0.92, halfLength * 0.3, -halfLength * 0.3, -halfLength * 0.92]) {
+      const hit = ask(fx * along + rx * s * halfWidth, fz * along + rz * s * halfWidth, rx * s, rz * s, 0.35);
+      if (!hit) continue;
+      car.pos.x += hit.normal.x * (0.35 - hit.distance);
+      car.pos.z += hit.normal.z * (0.35 - hit.distance);
+    }
+  }
+}
+
+export function createCar({ surfaceAt, obstacleAt = null, x = 0, y = 0, z = 0, heading = 0, ...opts } = {}) {
+  const cfg = {
+    ...CAR_DEFAULTS, ...opts,
+    body: { ...CAR_DEFAULTS.body, ...(opts.body ?? {}) },
+    suspension: { ...CAR_DEFAULTS.suspension, ...(opts.suspension ?? {}) },
+    engine: { ...CAR_DEFAULTS.engine, ...(opts.engine ?? {}) },
+    brakes: { ...CAR_DEFAULTS.brakes, ...(opts.brakes ?? {}) },
+    grip: { ...CAR_DEFAULTS.grip, ...(opts.grip ?? {}) },
+  };
+  const halfL = cfg.wheelbase / 2, halfT = cfg.track / 2;
+
+  // wheel order: front-left, front-right, rear-left, rear-right
+  const CORNERS = [
+    { id: 'fl', along: halfL, across: -halfT, front: true },
+    { id: 'fr', along: halfL, across: halfT, front: true },
+    { id: 'rl', along: -halfL, across: -halfT, front: false },
+    { id: 'rr', along: -halfL, across: halfT, front: false },
+  ];
+
+  // seat the car ON the ground it was placed over, so it never starts by falling into place
+  const seatY = surfaceAt?.(x, z, y);
+  const car = {
+    cfg,
+    pos: { x, y: (seatY ?? y) + CAR_DEFAULTS.rideHeight, z },
+    heading,                 // where the car POINTS
+    travel: heading,         // where it is actually GOING — the two differ when it slides
+    speed: 0,
+    vy: 0,
+    airborne: false,
+    pitch: 0,
+    roll: 0,
+    slip: 0,
+    steer: 0,
+    spin: 0,                 // wheel rotation, radians
+    wheels: CORNERS.map((c) => ({ ...c, compression: 0, grounded: true, contactY: y })),
+
+    // where each wheel sits in world space right now
+    wheelPoints() {
+      const s = Math.sin(car.heading), c = Math.cos(car.heading);
+      return car.wheels.map((w) => ({
+        wheel: w,
+        x: car.pos.x + s * w.along - c * w.across,
+        z: car.pos.z + c * w.along + s * w.across,
+      }));
+    },
+
+    // the body's pose, for whatever is drawing it
+    pose() {
+      return {
+        x: car.pos.x, y: car.pos.y, z: car.pos.z,
+        heading: car.heading, pitch: car.pitch, roll: car.roll,
+      };
+    },
+
+    update(dt, input = {}) {
+      const { throttle = 0, brake = false, handbrake = false, steer = 0 } = input;
+      const { engine, brakes, grip, suspension } = cfg;
+      dt = Math.min(dt, 0.05);
+
+      // ── engine, brakes, drag ──
+      if (throttle > 0) {
+        const pull = Math.min(engine.traction, engine.power / Math.max(Math.abs(car.speed), 3));
+        car.speed += throttle * pull * dt;
+      } else if (throttle < 0) {
+        car.speed += throttle * engine.traction * 1.3 * dt;      // reverse, and engine braking
+      }
+      if (brake) {
+        // a brake stops you; it does not reverse you
+        const b = brakes.force * dt;
+        car.speed = Math.abs(car.speed) <= b ? 0 : car.speed - Math.sign(car.speed) * b;
+      }
+      if (handbrake) car.speed -= Math.sign(car.speed) * brakes.handbrake * dt;
+      const resist = (engine.rollingResistance + engine.airDrag * car.speed * car.speed) * dt;
+      car.speed = Math.abs(car.speed) <= resist ? 0 : car.speed - Math.sign(car.speed) * resist;
+      car.speed = clamp(car.speed, -engine.reverseSpeed, engine.topSpeed);
+
+      // ── steering, and the slide it can provoke ──
+      const authority = Math.min(1, Math.abs(car.speed) / grip.steerBite) * Math.sign(car.speed || 1);
+      car.heading += steer * dt * (handbrake ? grip.steerHandbrake : grip.steerRate) * authority;
+      const g = handbrake ? grip.handbrake : grip.normal;
+      car.slip = wrapPi(car.heading - car.travel);
+      car.travel += car.slip * Math.min(1, g * dt);
+
+      // ── travel across the ground ──
+      const fx = Math.sin(car.travel), fz = Math.cos(car.travel);
+      const step = { x: fx * car.speed * dt, z: fz * car.speed * dt };
+      const next = { x: car.pos.x + step.x, z: car.pos.z + step.z };
+
+      // ── each wheel finds its own ground ──
+      const sh = Math.sin(car.heading), ch = Math.cos(car.heading);
+      let sum = 0, grounded = 0;
+      const contacts = car.wheels.map((w) => {
+        const wx = next.x + sh * w.along - ch * w.across;
+        const wz = next.z + ch * w.along + sh * w.across;
+        let y = surfaceAt(wx, wz, car.pos.y);
+        // A WHEEL CANNOT CLIMB A GUARDRAIL — but the test must be against where the CAR is
+        // now, not where this wheel last touched. Measured against a stale per-wheel value,
+        // a single missed contact on a ramp (a seam between two deck meshes, say) leaves the
+        // wheel's memory metres below the road, and every real contact after that looks like
+        // an unclimbable wall: the car can never get back onto the ramp it is driving up.
+        // And while airborne there is no limit at all — you may land on anything.
+        const wheelLevel = car.pos.y - cfg.rideHeight;
+        if (!car.airborne && y != null && y > wheelLevel + cfg.maxStep) y = null;
+        w.grounded = y != null;
+        if (y != null) { sum += y; grounded++; w.contactY = y; }
+        return y ?? w.contactY;
+      });
+      // NOTHING UNDER ANY WHEEL means falling, not hovering. Holding the car at its current
+      // height when every wheel misses leaves it hanging in mid-air indefinitely.
+      if (!grounded) car.airborne = true;
+      const targetY = (grounded ? sum / grounded : -Infinity) + cfg.rideHeight;
+
+      // ── airborne or held down ──
+      // NOT a fixed threshold: while the wheels are down the ground dictates our vertical
+      // speed, and only when it falls away faster than gravity could take us — by a real
+      // margin, or contact noise alone will do it — do the wheels have nothing to push on.
+      const rate = grounded ? clamp((targetY - car.pos.y) / Math.max(dt, 1e-4), -30, 30) : -30;
+      // vy follows the surface rate rather than being set to it: a single settling frame
+      // (a car created below its ride height, a wheel finding a new deck) otherwise leaves a
+      // large stale value in vy, and every frame after that reads as a launch.
+      if (!car.airborne && rate < car.vy - G * dt - cfg.launchMargin) car.airborne = true;
+      else if (!car.airborne) car.vy += (rate - car.vy) * Math.min(1, 20 * dt);
+
+      car.pos.x = next.x;
+      car.pos.z = next.z;
+      if (car.airborne) {
+        car.vy -= G * dt;
+        car.pos.y += car.vy * dt;
+        if (car.pos.y <= targetY) {
+          const hit = car.vy;
+          car.pos.y = targetY;
+          car.vy = 0;
+          car.airborne = false;
+          if (hit < -cfg.landingHit) car.speed *= 0.93;   // only a real drop costs you
+        }
+      } else {
+        car.pos.y = targetY;
+      }
+
+      // ── suspension: each wheel's compression, and the lean that comes out of it ──
+      for (let i = 0; i < car.wheels.length; i++) {
+        const w = car.wheels[i];
+        const rest = car.pos.y - cfg.rideHeight;
+        const want = clamp(rest - contacts[i], -suspension.travel, suspension.travel);
+        w.compression += (want - w.compression) * Math.min(1, suspension.damping * dt);
+      }
+      // LEAN ONLY FROM WHEELS THAT ARE ACTUALLY ON SOMETHING. A wheel over an edge keeps the
+      // last height it touched, and averaging that stale value in tips the car onto a
+      // permanent angle it can never recover from — the body ends up leaning at rest.
+      const mean = (a, b) => {
+        const A = car.wheels[a], B = car.wheels[b];
+        if (A.grounded && B.grounded) return (A.contactY + B.contactY) / 2;
+        if (A.grounded) return A.contactY;
+        if (B.grounded) return B.contactY;
+        return null;
+      };
+      const f = mean(0, 1), r = mean(2, 3), l = mean(0, 2), rt = mean(1, 3);
+      const targetPitch = car.airborne || f == null || r == null
+        ? Math.atan2(car.vy, Math.max(Math.abs(car.speed), 4))
+        : Math.atan2(f - r, cfg.wheelbase);
+      const targetRoll = car.airborne || l == null || rt == null ? 0 : Math.atan2(l - rt, cfg.track);
+      const k = Math.min(1, dt * (car.airborne ? 2 : 9));
+      // whatever the ground says, a car does not lie on its side. A cap here means no
+      // contact reading, however odd, can ever leave the body at an impossible angle.
+      car.pitch = clamp(car.pitch + (targetPitch - car.pitch) * k, -cfg.maxLean, cfg.maxLean);
+      car.roll = clamp(car.roll + (targetRoll - car.roll) * k, -cfg.maxLean, cfg.maxLean);
+
+      // ── what is standing in the road ──
+      if (obstacleAt) resolveObstacles(car, dt, obstacleAt);
+
+      // ── the wheels themselves ──
+      car.spin -= (car.speed * dt) / cfg.wheelRadius * (handbrake ? 0.15 : 1);
+      car.steer += (steer * 0.5 - car.steer) * Math.min(1, dt * 8);
+      return car;
+    },
+  };
+  return car;
+}

package/src/vehicle/carAudio.js

@@ -0,0 +1,124 @@
+// CAR AUDIO — the engine you hear is four loops and a crossfade.
+//
+// The classic arrangement, and the one Kiwi used: acceleration and deceleration recorded at
+// low and high revs. Load rises with throttle, revs rise with speed, and the four are mixed
+// so that pulling away sounds like pulling away and lifting off sounds like lifting off.
+// Playback rate stretches each loop between its samples so the pitch tracks the revs
+// continuously rather than in steps.
+//
+//   const audio = createCarAudio({ listener, clips });   // clips: AudioBuffers
+//   audio.update(dt, { speed, topSpeed, throttle, slip, airborne });
+//
+// A game supplies the buffers, because a game owns its content. Everything here is Web Audio:
+// no three.js, so it can be tested and reasoned about on its own.
+
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+
+export const CAR_AUDIO_DEFAULTS = {
+  idleRevs: 0.12,           // revs at a standstill — an engine is never silent
+  revSmoothing: 4,          // how fast the revs chase the wheels (per second)
+  loadSmoothing: 6,         // ...and how fast the engine loads up under throttle
+  pitchLow: 0.75,           // playback rate for a clip at the bottom of its range
+  pitchHigh: 1.55,          // ...and at the top
+  crossover: 0.55,          // revs at which the high clips take over from the low
+  crossWidth: 0.28,         // how broad that handover is
+  skidSlip: 0.28,           // radians of slide before the tyres start to protest
+  masterGain: 0.8,
+};
+
+export function createCarAudio({ context, destination, clips = {}, ...opts } = {}) {
+  const cfg = { ...CAR_AUDIO_DEFAULTS, ...opts };
+  const ctx = context ?? new (globalThis.AudioContext ?? globalThis.webkitAudioContext)();
+  const out = ctx.createGain();
+  out.gain.value = cfg.masterGain;
+  out.connect(destination ?? ctx.destination);
+
+  // one looping voice per clip; they all run all the time and are mixed by gain, because
+  // starting and stopping sources is what makes engine audio stutter
+  const voice = (buffer) => {
+    if (!buffer) return null;
+    const src = ctx.createBufferSource();
+    const gain = ctx.createGain();
+    src.buffer = buffer;
+    src.loop = true;
+    gain.gain.value = 0;
+    src.connect(gain).connect(out);
+    src.start();
+    return { src, gain };
+  };
+  const voices = {
+    accelLow: voice(clips.accelLow),
+    accelHigh: voice(clips.accelHigh),
+    decelLow: voice(clips.decelLow),
+    decelHigh: voice(clips.decelHigh),
+    skid: voice(clips.skid),
+  };
+
+  const state = { revs: cfg.idleRevs, load: 0 };
+
+  const set = (v, value, dt) => {
+    if (!v) return;
+    // ramp rather than assign: a stepped gain is an audible click at 60 fps
+    v.gain.gain.setTargetAtTime(value, ctx.currentTime, Math.max(dt, 0.02));
+  };
+
+  return {
+    context: ctx,
+    state,
+
+    update(dt, { speed = 0, topSpeed = 55, throttle = 0, slip = 0, airborne = false } = {}) {
+      const wheelRevs = clamp01(Math.abs(speed) / Math.max(topSpeed, 1e-3));
+      // revs chase the wheels but never fall to silence, and a car in the air revs freely
+      const targetRevs = airborne ? Math.max(wheelRevs, 0.7) : Math.max(wheelRevs, cfg.idleRevs);
+      state.revs += (targetRevs - state.revs) * Math.min(1, cfg.revSmoothing * dt);
+      state.load += (clamp01(throttle) - state.load) * Math.min(1, cfg.loadSmoothing * dt);
+
+      // low clips hand over to high across a band, so there is no seam at one rev value
+      const high = clamp01((state.revs - cfg.crossover) / cfg.crossWidth + 0.5);
+      const low = 1 - high;
+      const onPower = state.load;                 // accelerating vs coasting
+      const rate = cfg.pitchLow + (cfg.pitchHigh - cfg.pitchLow) * state.revs;
+      for (const v of Object.values(voices)) {
+        if (v && v !== voices.skid) v.src.playbackRate.setTargetAtTime(rate, ctx.currentTime, 0.05);
+      }
+      set(voices.accelLow, low * onPower, dt);
+      set(voices.accelHigh, high * onPower, dt);
+      set(voices.decelLow, low * (1 - onPower), dt);
+      set(voices.decelHigh, high * (1 - onPower), dt);
+
+      // tyres complain in proportion to how far the car is sliding, and not at all in the air
+      const squeal = airborne ? 0 : clamp01((Math.abs(slip) - cfg.skidSlip) / 0.6) * clamp01(Math.abs(speed) / 8);
+      set(voices.skid, squeal, dt);
+      return state;
+    },
+
+    // a one-shot, for the horn or a collision
+    play(buffer, gain = 1) {
+      if (!buffer) return;
+      const src = ctx.createBufferSource();
+      const g = ctx.createGain();
+      src.buffer = buffer;
+      g.gain.value = gain;
+      src.connect(g).connect(out);
+      src.start();
+    },
+
+    stop() {
+      for (const v of Object.values(voices)) v?.src.stop();
+    },
+  };
+}
+
+// Load a set of clips by URL. Returns whatever decoded, so a missing file silences one voice
+// instead of taking the whole car with it.
+export async function loadCarClips(context, urls = {}) {
+  const clips = {};
+  await Promise.all(Object.entries(urls).map(async ([name, url]) => {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) return;
+      clips[name] = await context.decodeAudioData(await res.arrayBuffer());
+    } catch { /* a car with no sound still drives */ }
+  }));
+  return clips;
+}

package/src/world/roadAssert.js

@@ -0,0 +1,125 @@
+// 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. 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

@@ -79,6 +79,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 +115,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);
@@ -252,6 +283,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 +334,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

@@ -114,20 +114,113 @@ 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;
+
+  // WHERE THE DRIVEABLE SURFACE IS. The ground is deliberately cut a little below the road so
+  // the two do not fight for the same pixels, which means anything that drives — the player's
+  // car, traffic, a pedestrian on a bridge — must ask for the road, not the dirt.
+  // Returns null away from any road, so the caller falls back to the ground.
+  heightAt.road = function roadAt(x, z, preferY = null) {
+    const found = [];
+    // pads are driveable too: a junction's deck is where its own roads sit
+    for (const pid of nearPads?.(x, z) ?? []) {
+      const p = pads[pid];
+      if (padDistance(p, x, z) <= 0) found.push(p.y);
+    }
+    if (index) {
+      const ids = index.near(x, z);
+      for (const id of ids ?? []) {
+        const s = index.segs[id];
+        const dx = s.bx - s.ax, dz = s.bz - s.az;
+        const len2 = dx * dx + dz * dz || 1e-6;
+        const t = Math.min(1, Math.max(0, ((x - s.ax) * dx + (z - s.az) * dz) / len2));
+        if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half) continue;
+        found.push(s.ay + (s.by - s.ay) * t);
+      }
+    }
+    if (!found.length) return null;
+    // MULTI-LEVEL: where a bridge crosses a cutting, or a link overlaps an interchange's
+    // trench, several surfaces cover the same spot. Answer with the one nearest the height
+    // the caller is already at — you stay on the deck you are driving on, you do not fall
+    // through it onto the road below.
+    if (preferY == null) return Math.max(...found);
+    // 'low' / 'high' ask for a level outright. (A non-finite preference cannot do this by
+    // arithmetic: |y - -Infinity| is Infinity for EVERY candidate, so the nearest-wins
+    // comparison is always false and the first deck found is returned regardless.)
+    if (preferY === 'low' || preferY === -Infinity) return Math.min(...found);
+    if (preferY === 'high' || preferY === Infinity) return Math.max(...found);
+    return found.reduce((best, y) => (Math.abs(y - preferY) < Math.abs(best - preferY) ? y : best));
+  };
+
+  // JUST THE CARRIAGEWAYS — no pads. A pad is a levelled area a junction stands on, not a
+  // road deck: anything asking "is this ground hidden under tarmac?" must not be told yes
+  // for the whole footprint of an interchange, or it will remove ground you can plainly see.
+  // `shrink` narrows the corridor before answering. A corridor's bed is deliberately wider
+  // than its tarmac (the road needs level ground beside it), so anything using this to decide
+  // "is the ground hidden here?" must ask about the ROAD, not the bed — or it cuts away a
+  // strip of terrain along both edges that nothing is covering, leaving a gap at the kerb.
+  heightAt.deck = function deckAt(x, z, shrink = 0) {
+    if (!index) return null;
+    const ids = index.near(x, z);
+    if (!ids) return null;
+    let lowest = null;
+    for (const id of ids) {
+      const s = index.segs[id];
+      const dx = s.bx - s.ax, dz = s.bz - s.az;
+      const len2 = dx * dx + dz * dz || 1e-6;
+      const t = Math.min(1, Math.max(0, ((x - s.ax) * dx + (z - s.az) * dz) / len2));
+      if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half - shrink) continue;
+      const y = s.ay + (s.by - s.ay) * t;
+      if (lowest == null || y < lowest) lowest = y;
+    }
+    return lowest;
+  };
 
-  return function heightAt(x, z) {
+  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 +266,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 +321,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 +335,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;
 }

package/src/world/roadWorld.js

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

package/tools/unityPackageExtract.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// UNITYPACKAGE EXTRACT — pull NAMED assets out of a .unitypackage.
+//
+// The dev-server importer takes a whole pack; this is for when you want a handful of things
+// out of a 90 MB archive (the cars from POLYGON City, say) without staging the other 2,000
+// assets. A .unitypackage is a gzip tar of GUID directories, each holding `pathname`,
+// `asset` and `asset.meta`; this rebuilds the real filenames for whatever matches.
+//
+//   node tools/unityPackageExtract.mjs <pkg.unitypackage> <outDir> <regex> [--list]
+//
+// The .meta travels with each asset because Unity keeps the FBX import scale there, and
+// Synty packs mix metre- and centimetre-authored models (see tools/fbxToGlb.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+const [pkg, outDir, pattern, ...rest] = process.argv.slice(2);
+if (!pkg || !outDir || !pattern) {
+  console.error('usage: unityPackageExtract.mjs <pkg.unitypackage> <outDir> <regex> [--list]');
+  process.exit(1);
+}
+const listOnly = rest.includes('--list');
+const re = new RegExp(pattern, 'i');
+
+const work = fs.mkdtempSync(path.join(os.tmpdir(), 'unitypkg-'));
+try {
+  execFileSync('tar', ['xzf', pkg, '-C', work], { stdio: ['ignore', 'ignore', 'pipe'] });
+  const hits = [];
+  for (const dir of fs.readdirSync(work)) {
+    const base = path.join(work, dir);
+    const pnFile = path.join(base, 'pathname');
+    if (!fs.existsSync(pnFile)) continue;
+    const assetPath = fs.readFileSync(pnFile, 'utf8').split('\n')[0].trim();
+    if (!re.test(assetPath)) continue;
+    if (!fs.existsSync(path.join(base, 'asset'))) continue;    // a folder entry, not a file
+    hits.push({ dir: base, assetPath });
+  }
+  hits.sort((a, b) => a.assetPath.localeCompare(b.assetPath));
+  if (listOnly) {
+    for (const h of hits) console.log(h.assetPath);
+    console.log(`\n${hits.length} matching assets`);
+  } else {
+    fs.mkdirSync(outDir, { recursive: true });
+    for (const h of hits) {
+      const name = path.basename(h.assetPath);
+      fs.copyFileSync(path.join(h.dir, 'asset'), path.join(outDir, name));
+      const meta = path.join(h.dir, 'asset.meta');
+      if (fs.existsSync(meta)) fs.copyFileSync(meta, path.join(outDir, `${name}.meta`));
+      console.log(`${name}  ←  ${h.assetPath}`);
+    }
+    console.log(`\n${hits.length} assets extracted to ${outDir}`);
+  }
+} finally {
+  fs.rmSync(work, { recursive: true, force: true });
+}