sindicate 0.13.0 → 0.16.0

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/design.js

@@ -0,0 +1,72 @@
+// THE DESIGN STAMPER (designer v3) — renders a World Designer layout (designs/<name>.json,
+// authored in /designer.html by hand or by an MCP-driven session) into the live world.
+// MACHINE-WRITTEN LAYOUTS ARE JSON: { name, prefabs: [{ file, dir, x, y?, z, ry?, s?, tex? }],
+// roads: [[{x,z}, ...], ...] }.
+//
+// Same shape as the kit stamper's prop path: prefabs batch per (file|tex) into ONE
+// InstancedMesh each, on the shared townMaterial pipeline (one material per atlas,
+// lamp-lit). Placement seats on the game's ground through the heightAt option unless the
+// entry pins its own y.
+//
+// COLLISION IS THE BAKE'S BUSINESS: batches are named `scatter:` (solid — the world BVH
+// bake picks them up by name) or `scatterDeco:` (walk-through) via opts.solid. Stamping
+// AFTER world.build's bake gives no collision until the next bake — fine for a dev-flag
+// preview; the production path stamps designs before the bake, exactly like the towns.
+//
+// ROADS: not rendered here. A designer road is a ROUTE, and routes belong to the game's
+// terrain survey (road networks bench the ground, paint the surface and re-cook) — the
+// designer's road polylines feed that pipeline game-side; a painted-on decal would lie
+// about where the carriageway really is.
+import * as THREE from 'three/webgpu';
+import { loadModel } from '../core/assets.js';
+import { flattenToGeometry } from './scatter.js';
+import { townMaterial } from './kit.js';
+
+export async function buildDesign(scene, design, { heightAt = () => 0, solid = true, defaultTex = null } = {}) {
+  const byFile = new Map();   // `${dir}/${file}|${tex}` -> { url, tex, mats: [] }
+  const _p = new THREE.Vector3(), _q = new THREE.Quaternion(), _s = new THREE.Vector3();
+  const _up = new THREE.Vector3(0, 1, 0);
+  for (const e of design.prefabs ?? []) {
+    const bare = e.file.replace(/\.(fbx|glb)$/i, '');
+    const ext = e.ext ?? (/\.glb$/i.test(e.file) ? 'glb' : 'fbx');
+    const url = `${e.dir}/${bare}`;
+    e._url = `${url}.${ext}`;
+    const tex = e.tex ?? defaultTex;
+    const key = `${e._url}|${tex}`;
+    if (!byFile.has(key)) byFile.set(key, { url: e._url, tex, mats: [] });
+    byFile.get(key).mats.push(new THREE.Matrix4().compose(
+      _p.set(e.x, e.y ?? heightAt(e.x, e.z), e.z),
+      _q.setFromAxisAngle(_up, e.ry ?? 0),
+      _s.setScalar(e.s ?? 1),
+    ));
+  }
+  const meshes = [];
+  let count = 0, failed = 0;
+  for (const { url, tex, mats } of byFile.values()) {
+    try {
+      const master = await loadModel(url, tex ? { texture: tex } : {});
+      const flat = flattenToGeometry(master);
+      if (!flat) { failed++; continue; }
+      // textured prefabs ride the shared town pipeline (one material per atlas, lamp-lit);
+      // an untextured one gets a plain slate rather than crashing the whole batch pass
+      const mat = tex ? await townMaterial(tex, url) : new THREE.MeshStandardMaterial({ color: 0x9a938a, roughness: 0.9 });
+      const mesh = new THREE.InstancedMesh(flat.geometry, mat, mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = mats.length < 12;
+      mesh.receiveShadow = true;
+      const file = url.split('/').pop();
+      mesh.name = `${solid ? 'scatter' : 'scatterDeco'}:${file}`;
+      mesh.matrixAutoUpdate = false;
+      mesh.updateMatrix();
+      scene.add(mesh);
+      meshes.push(mesh);
+      count += mats.length;
+    } catch (e) {
+      failed++;
+      console.warn(`[design] prefab batch ${url} failed`, e?.message ?? e);
+    }
+  }
+  console.log(`[design] '${design.name ?? 'unnamed'}': ${count} prefabs in ${meshes.length} batches${failed ? ` (${failed} files failed)` : ''}${design.roads?.length ? ` · ${design.roads.length} road route(s) carried for the survey` : ''}`);
+  return { meshes, count, roads: design.roads ?? [] };
+}

package/src/world/heightfield.js

@@ -0,0 +1,146 @@
+// THE HEIGHTFIELD BUILDER (world splits, step 4) — the chunked terrain mesh + cook harness
+// both games carried byte-identically around their own paint and material:
+//
+//   · ONE height lattice (every vertex computed exactly once), chunk meshes aligned to it,
+//     normals from lattice CENTRAL DIFFERENCES so chunk borders cannot seam
+//   · THE TERRAIN COOK — the lattice fill is ~1.74M heightAt calls and the paint pass as
+//     many again, all deterministic: cooked to ONE self-writing bin
+//     [u32 hlen][JSON {ver,N} pad4][H f32 N²][sand u8 N²][paint u8 4/vert rgba-as-rgbs]
+//     fetched by NAME (the game bakes its content fingerprints into cookName, so stale
+//     bins 404 and re-cook), recorded back through the dev middleware on a cold boot
+//   · the SAND LATTICE (u8 N²) — the game's paint writes it, other systems (grass blade
+//     fields) query exactly what the ground shows; returned for the game's sandAt()
+//
+// The GAME supplies: heightAt, the cook name + ver, the node material, and makePaint —
+// a factory receiving { hAt, step, N, sandLattice } and returning the per-vertex painter
+// (x, z, h, li, lj, colors, sands, k), the exact signature both counties already use.
+import * as THREE from 'three/webgpu';
+
+export async function buildHeightfield({
+  worldSize, segments, chunkTarget = 360,
+  heightAt, cookName, cookVer,
+  material, makePaint,
+  saveRoute = '/__save-cookbin', cookRoute = '/assets/cook',
+}) {
+  const CHUNKS = Math.max(1, Math.round(worldSize / chunkTarget));
+  if (segments % CHUNKS !== 0) throw new Error(`segments ${segments} not divisible by ${CHUNKS} chunks`);
+  const CSEG = segments / CHUNKS;                  // segments per chunk side
+  const CSIZE = worldSize / CHUNKS;                // metres per chunk side
+  const STEP = worldSize / segments;               // lattice spacing
+  const N = segments + 1;                          // lattice verts per side
+
+  let cook = null;
+  try {
+    const r = await fetch(`${cookRoute}/${cookName}`);
+    if (r.ok) {
+      const buf = await r.arrayBuffer();
+      const hlen = new DataView(buf).getUint32(0, true);
+      const head = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, 4, hlen)));
+      if (head.N === N) {
+        let o = 4 + hlen;
+        cook = { H: new Float32Array(buf.slice(o, o + N * N * 4)) };
+        o += N * N * 4;
+        cook.sand = new Uint8Array(buf.slice(o, o + N * N));
+        o += N * N;
+        cook.paint = new Uint8Array(buf.slice(o));
+        console.log(`[terrain] COOKED lattice+paint from ${cookName} — heightAt/paint compute skipped`);
+      }
+    }
+  } catch (e) { console.warn('[terrain] cook bin missing/unreadable — falling back to the SLOW compute path (first boot after a VER bump is expected; repeated boots are not)', e?.message ?? e); }
+
+  // ---- height lattice: every terrain vertex height, computed once ----
+  const H = cook ? cook.H : new Float32Array(N * N);
+  if (!cook) {
+    for (let j = 0; j < N; j++) {
+      const z = -worldSize / 2 + j * STEP;
+      for (let i = 0; i < N; i++) H[j * N + i] = heightAt(-worldSize / 2 + i * STEP, z);
+    }
+  }
+  const hAt = (i, j) => H[Math.min(N - 1, Math.max(0, j)) * N + Math.min(N - 1, Math.max(0, i))];
+  const sandLattice = cook ? cook.sand : new Uint8Array(N * N);
+  const paintVertex = cook ? null : makePaint({ hAt, step: STEP, N, sandLattice });
+
+  // ---- build the chunk grid ----
+  const group = new THREE.Group();
+  group.name = 'terrain';
+  let chunkIdx = 0, vertsPerChunk = 0;
+  const recChunks = cook ? null : [];
+  for (let cj = 0; cj < CHUNKS; cj++) {
+    for (let ci = 0; ci < CHUNKS; ci++) {
+      const geo = new THREE.PlaneGeometry(CSIZE, CSIZE, CSEG, CSEG);
+      geo.rotateX(-Math.PI / 2);
+      const cx = -worldSize / 2 + (ci + 0.5) * CSIZE;             // chunk centre (mesh position)
+      const cz = -worldSize / 2 + (cj + 0.5) * CSIZE;
+      const pos = geo.attributes.position;
+      const colors = new Float32Array(pos.count * 3);
+      const sands = new Float32Array(pos.count);
+      const normals = geo.attributes.normal;
+      vertsPerChunk = pos.count;
+      for (let k = 0; k < pos.count; k++) {
+        const x = pos.getX(k) + cx, z = pos.getZ(k) + cz;
+        // lattice indices — chunk grids align exactly to the global lattice
+        const li = Math.round((x + worldSize / 2) / STEP);
+        const lj = Math.round((z + worldSize / 2) / STEP);
+        const h = hAt(li, lj);
+        pos.setY(k, h);
+        // normal from lattice central differences — identical on both sides of
+        // a chunk border (computeVertexNormals would seam: edge verts lack
+        // neighbour faces from the adjacent chunk). Cheap H arithmetic — always live.
+        const nx = -(hAt(li + 1, lj) - hAt(li - 1, lj)) / (2 * STEP);
+        const nz = -(hAt(li, lj + 1) - hAt(li, lj - 1)) / (2 * STEP);
+        const inv = 1 / Math.hypot(nx, 1, nz);
+        normals.setXYZ(k, nx * inv, inv, nz * inv);
+        if (cook) {
+          // cooked paint: 4 bytes/vert (r,g,b,sand) in chunk build order
+          const po = (chunkIdx * pos.count + k) * 4;
+          colors[k * 3] = cook.paint[po] / 255;
+          colors[k * 3 + 1] = cook.paint[po + 1] / 255;
+          colors[k * 3 + 2] = cook.paint[po + 2] / 255;
+          sands[k] = cook.paint[po + 3] / 255;
+        } else {
+          paintVertex(x, z, h, li, lj, colors, sands, k);
+        }
+      }
+      geo.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+      geo.setAttribute('aSand', new THREE.BufferAttribute(sands, 1));
+      recChunks?.push({ colors, sands });
+      chunkIdx++;
+      const mesh = new THREE.Mesh(geo, material);
+      mesh.position.set(cx, 0, cz);
+      mesh.receiveShadow = true;
+      mesh.name = `terrain:${ci},${cj}`;
+      group.add(mesh);
+    }
+  }
+  console.log(`[terrain] ${CHUNKS}x${CHUNKS} chunks (${CSIZE}m, ${CSEG}x${CSEG} segs each) — frustum-culled${cook ? ' · cooked' : ''}`);
+
+  // record mode: persist lattice + paint for the next boot (dev middleware writes the file)
+  if (recChunks) {
+    try {
+      let head = JSON.stringify({ ver: cookVer, N });
+      while ((head.length + 4) % 4) head += ' '; // 4-byte-align the Float32 payload
+      const hb = new TextEncoder().encode(head);
+      const paint = new Uint8Array(chunkIdx * vertsPerChunk * 4);
+      recChunks.forEach(({ colors, sands }, cIdx) => {
+        for (let k = 0; k < sands.length; k++) {
+          const po = (cIdx * sands.length + k) * 4;
+          paint[po] = Math.min(255, Math.round(colors[k * 3] * 255));
+          paint[po + 1] = Math.min(255, Math.round(colors[k * 3 + 1] * 255));
+          paint[po + 2] = Math.min(255, Math.round(colors[k * 3 + 2] * 255));
+          paint[po + 3] = Math.min(255, Math.round(sands[k] * 255));
+        }
+      });
+      const out = new Uint8Array(4 + hb.length + H.byteLength + sandLattice.byteLength + paint.byteLength);
+      const dv = new DataView(out.buffer);
+      dv.setUint32(0, hb.length, true);
+      out.set(hb, 4);
+      let o = 4 + hb.length;
+      out.set(new Uint8Array(H.buffer), o); o += H.byteLength;
+      out.set(sandLattice, o); o += sandLattice.byteLength;
+      out.set(paint, o);
+      fetch(`${saveRoute}?name=${cookName}`, { method: 'POST', body: out });
+      console.log(`[terrain] cooked → ${cookName} (${(out.length / 1048576).toFixed(1)}MB)`);
+    } catch (e) { console.warn('[terrain] cook save failed', e); }
+  }
+  return { group, sandLattice, N, step: STEP, cooked: !!cook };
+}