sindicate 0.13.0 → 0.16.0

package/src/world/permanentWay.js

@@ -0,0 +1,161 @@
+// THE PERMANENT WAY's MACHINERY (world splits, step 8) — the generic half of laying
+// track as geometry, moved verbatim from western's railway.js. The GAME keeps the
+// railway itself: which castings, which gauge mates to which, where the line runs,
+// portal art direction, station areas. The engine keeps the laws:
+//
+//   · THE PERF LAW: a hundred track pieces as a hundred meshes is not acceptable.
+//     Panels batch per file into an InstancedMesh whose instance matrix carries the full
+//     transform — position, YAW, PITCH and a Z-SCALE — which is what makes the adaptive
+//     panel length free: a 9.6 m panel on a curve and a 10.0 m panel on the straight
+//     ride in the same batch.
+//   · YOU MUST BE ABLE TO WALK OVER IT: panel batches are named `scatterDeco:` (visual
+//     only) — track is 20 cm of rail, not a wall; the formation under it is terrain and
+//     the terrain is already in the BVH.
+//   · a deck is A FLOOR, NOT A PICTURE OF ONE: the trestle builder hands its deck batch
+//     back as an instance group for a side BVH.
+import * as THREE from 'three/webgpu';
+import { loadModel, loadTexture, resolveModelUrl } from '../core/assets.js';
+import { flattenToGeometry } from './scatter.js';
+
+// A raw FBX carries the default UV flip; a .glb twin carries glTF-convention UVs
+// (flipY:false). Kits whose castings HAVE twins genuinely need two textures — mixing
+// them is the white-roofs bug, and at a junction it paints the turnout in somebody
+// else's colours.
+export async function railMaterial(texUrl, modelUrl) {
+  const resolved = await resolveModelUrl(modelUrl, { texture: texUrl });
+  const tex = await loadTexture(texUrl, /\.glb$/i.test(resolved) ? { flipY: false } : {});
+  return new THREE.MeshStandardMaterial({ map: tex, roughness: 0.95, metalness: 0 });
+}
+
+// THE FOUNDRY MIRRORS THE PATTERN. A casting that throws its diverging road to its own
+// LEFT when the yard is on the RIGHT is reflected in x. A negative scale would do it in
+// one line and get it wrong in three ways (winding reversed → the mesh renders
+// inside-out; normals still pointing the old way → lit from the wrong side; and three's
+// frustum/shadow maths quietly disagreeing about the determinant). So the reflection is
+// baked into the geometry properly: negate x on the positions, negate x on the normals,
+// and reverse the winding to put the faces back the right way out.
+export function mirrorX(src) {
+  const g = src.clone();
+  const p = g.attributes.position, n = g.attributes.normal;
+  for (let i = 0; i < p.count; i++) p.setX(i, -p.getX(i));
+  if (n) for (let i = 0; i < n.count; i++) n.setX(i, -n.getX(i));
+  if (g.index) {
+    const a = g.index.array;
+    for (let i = 0; i < a.length; i += 3) { const t = a[i]; a[i] = a[i + 2]; a[i + 2] = t; }
+    g.index.needsUpdate = true;
+  } else {
+    // non-indexed: swap the 1st and 3rd vertex of every triangle, across every attribute
+    for (const key of Object.keys(g.attributes)) {
+      const at = g.attributes[key], w = at.itemSize, arr = at.array;
+      for (let t = 0; t < at.count; t += 3) {
+        for (let c = 0; c < w; c++) {
+          const i = (t + 0) * w + c, j = (t + 2) * w + c;
+          const tmp = arr[i]; arr[i] = arr[j]; arr[j] = tmp;
+        }
+      }
+      at.needsUpdate = true;
+    }
+  }
+  p.needsUpdate = true;
+  if (n) n.needsUpdate = true;
+  return g;
+}
+
+// Euler YXZ: yaw first, then pitch about the piece's OWN lateral axis. Applied to the
+// piece's local +Z it gives (cosθ·sin ry, sinθ, cosθ·cos ry) — a chord with heading `ry`
+// climbing at θ — which is exactly the chord a panel is cut to. Any other order tilts
+// the sleepers. Returns a fresh matrixFor with its own scratch objects.
+export function makeChordMatrix() {
+  const _e = new THREE.Euler();
+  const _q = new THREE.Quaternion();
+  const _p = new THREE.Vector3();
+  const _s = new THREE.Vector3();
+  const matrixFor = (p) => {
+    _e.set(p.pitch, p.ry, 0, 'YXZ');
+    _q.setFromEuler(_e);
+    _p.set(p.x, p.y, p.z);
+    _s.set(1, 1, p.sz ?? 1);            // the chord's own length over the casting's native length
+    return new THREE.Matrix4().compose(_p, _q, _s);
+  };
+  matrixFor.yawOnly = (p) => {
+    _e.set(0, p.ry, 0, 'YXZ');
+    _q.setFromEuler(_e);
+    return new THREE.Matrix4().compose(_p.set(p.x, p.y, p.z), _q, _s.set(1, 1, 1));
+  };
+  return matrixFor;
+}
+
+// One InstancedMesh per (file) panel batch. `scatterDeco:` by default — see the header;
+// pass a `scatter:` name yourself when the batch is genuinely SOLID (a ridge of rock).
+// frustumCulled false: a kilometres-long line has a county-sized bounding sphere, so
+// culling on it is a coin toss that always comes up "visible" — not worth the test.
+export function panelBatch(scene, geo, material, mats, file) {
+  if (!geo || !mats.length) return null;
+  const mesh = new THREE.InstancedMesh(geo, material, mats.length);
+  mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+  mesh.instanceMatrix.needsUpdate = true;
+  mesh.castShadow = false;      // hundreds of low bars of rail cast nothing worth a shadow pass
+  mesh.receiveShadow = true;
+  mesh.name = `scatterDeco:${file}`;
+  mesh.matrixAutoUpdate = false;
+  mesh.updateMatrix();
+  mesh.frustumCulled = false;
+  scene.add(mesh);
+  return mesh;
+}
+
+// One-off casting placer: turnouts, buffer stops, portals. Position + YXZ yaw/pitch +
+// uniform scale, optional mirrorX. `scatterDeco:` — a buffer stop you cannot walk past
+// is a buffer stop that traps you at the end of the spur; give the mesh real collision
+// yourself (buildingObjects push) when the casting is genuinely solid.
+export async function placeCasting(scene, { url, tex, place, name, mirror = false }) {
+  try {
+    const m = await loadModel(url, { texture: tex });
+    const f = flattenToGeometry(m);
+    if (!f) throw new Error('no geometry');
+    const geo = mirror ? mirrorX(f.geometry) : f.geometry;
+    const mesh = new THREE.Mesh(geo, await railMaterial(tex, url));
+    mesh.position.set(place.x, place.y, place.z);
+    mesh.rotation.order = 'YXZ';
+    mesh.rotation.set(place.pitch, place.ry, 0);
+    mesh.scale.setScalar(place.scale);
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    mesh.name = `scatterDeco:${name}`;
+    scene.add(mesh);
+    return mesh;
+  } catch (err) { console.error(`[railway] ${name} failed`, err); }
+}
+
+// Seeded LCG — an unseeded Math.random reshuffles a dressed ridge every boot: one boot
+// frames the portal beautifully, the next drops a boulder in front of it. Same rocks
+// every time.
+export function lcgRng(seed = 0xC0FFEE) {
+  let _seed = seed >>> 0;
+  return () => { _seed = (_seed * 1664525 + 1013904223) >>> 0; return _seed / 4294967296; };
+}
+
+// THE TRESTLE, BUILT. Where the line flies it rides timber, not air: a flying panel
+// KEEPS its rails and gains the kit's deck casting UNDER them (deck-only planking, same
+// chord convention); the ballast is skipped by the caller (dirt does not float), and a
+// bent goes under every deck joint, standing on (and into) whatever is below. `seat`
+// lifts the deck so its top plane meets the panel origin — the plane the sleepers rest
+// on — measured off the casting. Returns { deckMesh, bentCount, walkable } — the deck
+// IS A FLOOR: bake `walkable` into a side BVH or someone rides onto the trestle and
+// falls straight through the planks.
+export async function buildTrestle(scene, { deckPanels, deckUrl, bentUrl, tex, material, seat = 0, matrixFor }) {
+  if (!deckPanels.length) return null;
+  const deckMaster = await loadModel(deckUrl, { texture: tex });
+  const bentMaster = await loadModel(bentUrl, { texture: tex });
+  const deckFlat = flattenToGeometry(deckMaster);
+  const bentFlat = flattenToGeometry(bentMaster);
+  const deckMats = [], bentMats = [];
+  for (const p of deckPanels) {
+    deckMats.push(matrixFor({ ...p, y: p.y + seat }));
+    bentMats.push(matrixFor.yawOnly({ x: p.x, y: p.y + seat, z: p.z, ry: p.ry }));   // square to the track
+  }
+  const deckMesh = panelBatch(scene, deckFlat.geometry, material, deckMats, deckUrl.split('/').pop());
+  panelBatch(scene, bentFlat.geometry, material, bentMats, bentUrl.split('/').pop());
+  const walkable = deckMesh ? { geometry: deckMesh.geometry, count: deckMesh.count, matrices: deckMesh.instanceMatrix.array } : null;
+  return { deckMesh, bentCount: bentMats.length, walkable };
+}

package/src/world/placement.js

@@ -0,0 +1,309 @@
+// THE PLACEMENT MACHINERY (world splits, step 6) — the deterministic scatter samplers, the
+// placement-manifest COOK, the resident-spec wrappers and the grass OCCUPANCY grid, moved
+// verbatim from western's zones.js. The game keeps its manifest (species rows, counts,
+// biome accepts, crop tables) and calls these; the engine keeps the laws:
+//
+//   · the whole placement stream is deterministic — a seeded rng with space-hashed accepts
+//     — so it round-trips to ONE binary file per quality preset. On a cook hit the
+//     generators return recorded slices and never touch the rng OR heightAt.
+//   · slice arrays are the editor-override address space (slice:index), applied AFTER the
+//     pristine cook save and BEFORE anything consumes them.
+//   · collision-by-name: circle colliders register per tile WRITE (never at ensure()), so
+//     a failed asset fetch can't leave an invisible blocker; ground dressing declares a
+//     `scatterGround:` collider name and is skipped by the tile BVH bake; humps feed the
+//     analytic walk lift identically on cooked and computed paths.
+import * as THREE from 'three/webgpu';
+import { scatterResident } from './scatter.js';
+import { registerHumps } from './walkHumps.js';
+import { colliders } from './kit.js';
+
+// ── the placement context — the game's terrain and sampling extent ──
+let PC = { heightAt: () => 0, seaLevel: -Infinity, scatterSize: 2000, saveRoute: '/__save-cookbin', cookRoute: '/assets/cook' };
+export function setPlacementContext(c = {}) { Object.assign(PC, c); }
+
+// generic FNV table fingerprint — hash any nested table of numbers/booleans into the cook
+// filename, so a tuned table with an unbumped version counter renames the bin and re-cooks
+// (the only outcome that was ever correct)
+export function fnvSig(table) {
+  let h = 2166136261 >>> 0;
+  const walk = (v) => {
+    if (typeof v === 'number') { h = Math.imul((h ^ (Math.round(v * 1000) >>> 0)) >>> 0, 16777619) >>> 0; }
+    else if (typeof v === 'boolean') walk(v ? 1 : 0);
+    else if (v && typeof v === 'object') for (const k of Object.keys(v).sort()) walk(v[k]);
+  };
+  walk(table);
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+// ── the determinism probe + the editor-override address space ──
+let _plHash = 0, _plCount = 0;
+let _sliceRefs = [];                 // every slice array in stream order — the editor-override address space
+const _hashPl = (out) => {
+  for (const p of out) {
+    for (const v of [p.x, p.y, p.z, p.ry, p.s]) {
+      _plHash = (_plHash ^ ((Math.round((v ?? 0) * 1000)) >>> 0)) >>> 0;
+      _plHash = Math.imul(_plHash, 16777619) >>> 0;
+    }
+    _plCount++;
+  }
+  _sliceRefs.push(out);
+  return out;
+};
+export const placementStats = () => ({ hash: _plHash >>> 0, count: _plCount });
+export const sliceRefs = () => _sliceRefs;
+
+// ── the cook state machine ──
+let _cookSlices = null, _cookAt = 0, _cookRec = null;
+const _rec = (out) => { if (_cookRec) _cookRec.push(out); return out; };
+const _cookNext = () => {
+  const a = _cookSlices[_cookAt++];
+  if (!a) { throw new Error('[manifest] cook has fewer slices than the code has generators — bump the zones cook version or delete the cook dir'); }
+  const out = new Array(a.length / 6);
+  for (let i = 0; i < out.length; i++) {
+    const o = i * 6;
+    out[i] = { x: a[o], y: a[o + 1], z: a[o + 2], ry: a[o + 3], s: a[o + 4], cr: a[o + 5] };
+  }
+  return _rec(_hashPl(out)); // the determinism probe still tallies cooked placements
+};
+
+// Try the recorded placement stream. The bin is only trusted if it was cooked for THIS
+// county at THIS scale — a scale mismatch is not a cosmetic problem: it is a whole world of
+// props replayed at the wrong coordinates. Resets the probe + override address space for
+// the build either way; on a miss, record mode arms.
+export async function loadPlacementCook({ name, ver, scale }) {
+  _plHash = 2166136261 >>> 0; _plCount = 0;
+  _cookSlices = null; _cookAt = 0; _cookRec = null; _sliceRefs = [];
+  try {
+    const r = await fetch(`${PC.cookRoute}/${name}`);
+    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.ver !== ver || head.scale !== scale) {
+        console.warn(`[manifest] ${name} is v${head.ver}/x${head.scale}, this build wants v${ver}/x${scale} — IGNORING it and re-placing from scratch`);
+      } else {
+        const f32 = new Float32Array(buf, 4 + hlen);
+        const slices = []; let off = 0;
+        for (const len of head.lens) { slices.push(f32.subarray(off, off + len * 6)); off += len * 6; }
+        _cookSlices = slices;
+        console.log(`[manifest] COOKED: ${head.count} placements from ${name} — placement compute skipped`);
+      }
+    }
+  } catch (e) { console.warn('[zones] 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); }
+  if (!_cookSlices) _cookRec = [];
+  return !!_cookSlices;
+}
+
+// record mode: persist the whole placement stream for the next boot (dev middleware writes
+// the cook dir — the same self-writing scheme as the VAT bins). On a cooked boot, checks
+// the slice count instead (a generator added/removed without a version bump is loud).
+export function savePlacementCook({ name, ver, scale, quality }) {
+  if (_cookRec) {
+    try {
+      const lens = _cookRec.map((a) => a.length);
+      const total = lens.reduce((s, l) => s + l, 0);
+      const f32 = new Float32Array(total * 6);
+      let o = 0;
+      for (const arr of _cookRec) for (const p of arr) { f32[o++] = p.x; f32[o++] = p.y; f32[o++] = p.z; f32[o++] = p.ry; f32[o++] = p.s; f32[o++] = p.cr ?? 0; }
+      const srcs = _cookRec.map((a) => a._src ?? null); // slice source models — the editor renders real meshes from these
+      let head = JSON.stringify({ ver, scale, quality, hash: (_plHash >>> 0).toString(16), count: _plCount, lens, srcs });
+      while ((head.length + 4) % 4) head += ' '; // pad so the Float32Array view lands 4-byte aligned
+      const hb = new TextEncoder().encode(head);
+      const out = new Uint8Array(4 + hb.length + f32.byteLength);
+      new DataView(out.buffer).setUint32(0, hb.length, true);
+      out.set(hb, 4);
+      out.set(new Uint8Array(f32.buffer), 4 + hb.length);
+      fetch(`${PC.saveRoute}?name=${name}`, { method: 'POST', body: out });
+      console.log(`[manifest] cooked → ${name} (${(out.length / 1024).toFixed(0)}KB, ${lens.length} slices)`);
+    } catch (e) { console.warn('[manifest] cook save failed', e); }
+    _cookRec = null;
+  } else if (_cookSlices && _cookAt !== _cookSlices.length) {
+    console.warn(`[manifest] cook slice-count mismatch (${_cookAt} used of ${_cookSlices.length}) — a generator was added/removed; bump the zones cook version`);
+  }
+}
+
+// MAP-EDITOR OVERRIDES: hand edits addressed as slice:index against the PRISTINE stream,
+// applied to the shared pl arrays AFTER the cook save (the recorded bin stays pristine) and
+// BEFORE the grass occupancy/TileField consume them. Same behaviour cooked/computed.
+export async function applyPlacementOverrides({ url = '/assets/cook/overrides.json', ver }) {
+  try {
+    const r = await fetch(url);
+    if (r.ok) {
+      const ov = await r.json();
+      if (ov.ver != null && ov.ver !== ver) {
+        console.warn(`[manifest] editor overrides were recorded against zones v${ov.ver} (now v${ver}) — indices would corrupt; SKIPPED.`);
+        throw 0; // into the catch — pristine world
+      }
+      let applied = 0;
+      for (const [k, m] of Object.entries(ov.move ?? {})) {
+        const [si, i] = k.split(':').map(Number);
+        const p = _sliceRefs[si]?.[i];
+        if (p) { p.x = m[0]; p.y = m[1]; p.z = m[2]; p.ry = m[3]; p.s = m[4]; applied++; }
+      }
+      const dels = (ov.del ?? []).map((k) => k.split(':').map(Number)).sort((a, b) => b[1] - a[1]); // splice high→low keeps indices coherent
+      for (const [si, i] of dels) { if (_sliceRefs[si]?.[i] !== undefined) { _sliceRefs[si].splice(i, 1); applied++; } }
+      for (const a of ov.add ?? []) {
+        const s = _sliceRefs[a.slice];
+        if (s) { s.push({ x: a.x, y: a.y ?? PC.heightAt(a.x, a.z) - 0.08, z: a.z, ry: a.ry ?? 0, s: a.s ?? 1, cr: a.cr ?? 0 }); applied++; }
+      }
+      if (applied) console.log(`[manifest] ${applied} editor overrides applied`);
+    }
+  } catch (e) { /* no overrides — pristine world */ }
+}
+
+// ── the samplers ──
+export function placementField(rng, count, accept, { sMin = 0.85, sMax = 1.3, sPow = 1, collider = 0, bvhOwned = false, box = null, fitY = 0 } = {}) {
+  if (_cookSlices) return _cookNext(); // cooked boot: recorded placements, zero rng/heightAt
+  const out = [];
+  let guard = 0;
+  while (out.length < count && guard++ < count * 40) {
+    const x = box ? box[0] + rng() * (box[2] - box[0]) : (rng() - 0.5) * PC.scatterSize * 0.94;
+    const z = box ? box[1] + rng() * (box[3] - box[1]) : (rng() - 0.5) * PC.scatterSize * 0.94;
+    if (!accept(x, z)) continue;
+    const y = PC.heightAt(x, z);
+    // sPow > 1 biases sizes small (many modest plants, few giants)
+    let s = sMin + Math.pow(rng(), sPow) * (sMax - sMin);
+    let py = y - 0.08;
+    if (fitY) { // span from a sunk base up toward nearby high ground (cliff-fit)
+      let hi = y;
+      for (const [dx, dz] of [[16, 0], [-16, 0], [0, 16], [0, -16], [12, 12], [-12, -12], [12, -12], [-12, 12]]) { const hh = PC.heightAt(x + dx, z + dz); if (hh > hi) hi = hh; }
+      py = PC.seaLevel - 3;
+      s = Math.max(0.4, Math.min(2.6, (hi - py) / fitY));
+    }
+    const p = { x, y: py, z, ry: rng() * Math.PI * 2, s };
+    // circle colliders are registered into `colliders` ONLY once the mesh's tile actually
+    // writes (see residentSpec), so a failed asset fetch can't leave an invisible blocker
+    p.cr = (collider && !bvhOwned) ? collider : 0;
+    out.push(p);
+  }
+  return _rec(_hashPl(out));
+}
+
+// A generator that is NOT rejection-sampled. A crop row walks a GRID and a fence panel walks
+// a PERIMETER; throwing darts at a rectangle to find them would be absurd. Same cook contract
+// as placementField, and it must be: on a cook hit it returns the recorded slice and never
+// runs the builder. It consumes no rng, which is fine — the seeded stream's order is only
+// required to be the same on two COLD boots, and this generator is the same no-op on both.
+export function listField(build) {
+  if (_cookSlices) return _cookNext();
+  return _rec(_hashPl(build()));
+}
+
+// ── the resident kit — per-build wrappers encoding the collision-by-name contract ──
+// Tree/cactus circle colliders are registered into `colliders` ONLY after a tile writes —
+// a failed asset fetch must not leave an invisible blocker. `occluders` records the same
+// circles synchronously so the grass occupancy grid can still dodge trunks.
+export function makeResidentKit() {
+  const occluders = [];
+  const noteOcc = (pl) => { for (const p of pl) if (p.cr) occluders.push(p); };
+  const regCol = (pl, sink) => { for (const p of pl) if (p.cr) { const c = { x: p.x, z: p.z, r: p.cr * p.s }; colliders.push(c); if (sink) sink(c); } };
+  // Each helper returns a RESIDENT SPEC: the game collects these into a MANIFEST and the
+  // TileField streams the world from it. ensure(cap) builds the spec's resident mesh set ONCE
+  // (empty, capacity-sized); write(k, sub, sink)/free(k) stream one tile's placements in/out.
+  // CONTRACT (collision determinism): ensure() must NOT register circle colliders — regCol
+  // runs per WRITE, so circles register with their tile and are spliced back out on dispose.
+  const residentSpec = (pl, makeResident) => {
+    const spec = {
+      pl,
+      ensure: (cap) => (spec._hp ||= makeResident(cap)
+        .then((h) => (spec._h = h))
+        .catch((e) => { console.warn('[resident] spec build failed', e); return (spec._h = null); })),
+      write: async (key, sub, sink) => {
+        const h = spec._hp ? await spec._hp : null;   // resolved after boot — a runtime write never suspends
+        if (!h) return null;
+        const res = h.write(key, sub);
+        if (res) regCol(sub, sink);
+        return res;
+      },
+      free: (key) => { spec._h?.free(key); },
+      handle: () => spec._h,
+    };
+    return spec;
+  };
+  // tag(): stamp each slice array with its source model+atlas — the cook header ships
+  // these names so the map editor can render REAL meshes (not marker cones)
+  const tag = (pl, url, tex) => { pl._src = { url, tex }; return pl; };
+  // res(): SIMPLE resident scatter — one mesh set per species, no impostor/LOD tiers
+  const res = (dir, atlas, file, pl, opts = {}) => { noteOcc(tag(pl, `${dir}/${file}.fbx`, atlas)); return residentSpec(pl, (cap) => scatterResident(`${dir}/${file}.fbx`, atlas, cap, pl, opts)); };
+  // resFlat(): the same, but the instances NEVER collide. Collision membership is decided by
+  // NAME — tileManager/the world facade drop any collider whose name matches /fence|flower|
+  // path|brick|ground|floor|grass/i — so ground dressing declares itself with a
+  // `scatterGround:` collider name and is skipped by the tile BVH bake. You walk OVER flat
+  // ground dressing; a 20cm pebble that stops a horse is a bug, not a feature.
+  const resFlat = (dir, atlas, file, pl, opts = {}) => {
+    noteOcc(tag(pl, `${dir}/${file}.fbx`, atlas));
+    return residentSpec(pl, async (cap) => {
+      const h = await scatterResident(`${dir}/${file}.fbx`, atlas, cap, pl, { castShadow: false, ...opts });
+      h.colliderName = `scatterGround:${file}.fbx`;
+      h.group.name = h.colliderName;   // and out of the `^scatter:` BVH scan too
+      return h;
+    });
+  };
+  // resHump(): resFlat for dressing TALL enough to read as ground. Same no-BVH rule (a lump
+  // of dirt must never STOP anything), but the placements ALSO feed walkHumps' analytic
+  // lift, so everything that walks rides OVER the mound instead of clipping through it.
+  // Registration happens here, at declaration, identically on the cooked and computed paths
+  // (`pl` is the final rows on both), so collision truth can never drift from the renderer.
+  const resHump = (dir, atlas, file, pl, opts = {}) => {
+    registerHumps(file, pl);
+    return resFlat(dir, atlas, file, pl, opts);
+  };
+  return { occluders, residentSpec, tag, res, resFlat, resHump };
+}
+
+// ── the grass OCCUPANCY GRID — every cell covered by a placed object, O(1) per blade ──
+export function makeOccupancy({ cell = 0.5 } = {}) {
+  const keyOf = (gx, gz) => gx * 100003 + gz;
+  const occ = new Set();
+  const mark = (x, z, r) => {
+    const r2 = r * r, gx = Math.round(x / cell), gz = Math.round(z / cell), c = Math.ceil(r / cell);
+    for (let i = -c; i <= c; i++) for (let j = -c; j <= c; j++) {
+      if ((i * cell) ** 2 + (j * cell) ** 2 <= r2) occ.add(keyOf(gx + i, gz + j)); // circle, not square
+    }
+  };
+  // Rectangular (rotated) footprint — buildings aren't round; marks cells inside the oriented box.
+  const markRect = (cx, cz, hx, hz, ang) => {
+    const ca = Math.cos(ang), sa = Math.sin(ang), gx = Math.round(cx / cell), gz = Math.round(cz / cell);
+    const c = Math.ceil(Math.hypot(hx, hz) / cell);
+    for (let i = -c; i <= c; i++) for (let j = -c; j <= c; j++) {
+      const wx = (gx + i) * cell - cx, wz = (gz + j) * cell - cz;
+      const lx = wx * ca + wz * sa, lz = -wx * sa + wz * ca; // into the box's local frame
+      if (Math.abs(lx) <= hx && Math.abs(lz) <= hz) occ.add(keyOf(gx + i, gz + j));
+    }
+  };
+  const rasterTri = (x0, z0, x1, z1, x2, z2) => {
+    const gx0 = Math.floor(Math.min(x0, x1, x2) / cell), gx1 = Math.ceil(Math.max(x0, x1, x2) / cell);
+    const gz0 = Math.floor(Math.min(z0, z1, z2) / cell), gz1 = Math.ceil(Math.max(z0, z1, z2) / cell);
+    for (let gx = gx0; gx <= gx1; gx++) for (let gz = gz0; gz <= gz1; gz++) {
+      const px = gx * cell, pz = gz * cell;
+      const d1 = (px - x1) * (z0 - z1) - (x0 - x1) * (pz - z1);
+      const d2 = (px - x2) * (z1 - z2) - (x1 - x2) * (pz - z2);
+      const d3 = (px - x0) * (z2 - z0) - (x2 - x0) * (pz - z0);
+      if (!(((d1 < 0) || (d2 < 0) || (d3 < 0)) && ((d1 > 0) || (d2 > 0) || (d3 > 0)))) occ.add(keyOf(gx, gz));
+    }
+  };
+  // Buildings: stamp each one's REAL ground footprint (floor + low-wall faces) into the
+  // grid, so grass meets every wall flush — works for any building shape.
+  const _va = new THREE.Vector3(), _vb = new THREE.Vector3(), _vc = new THREE.Vector3();
+  const stampBuildings = (objects, wallBand = 1.5) => {
+    for (const obj of objects) {
+      obj.updateMatrixWorld(true);
+      const floorTop = new THREE.Box3().setFromObject(obj).min.y + wallBand; // floor slab + lower walls only
+      obj.traverse((o) => {
+        if (!o.isMesh || !o.geometry?.attributes.position) return;
+        const pos = o.geometry.attributes.position, idx = o.geometry.index, mw = o.matrixWorld;
+        const stamp = (i0, i1, i2) => {
+          _va.fromBufferAttribute(pos, i0).applyMatrix4(mw);
+          _vb.fromBufferAttribute(pos, i1).applyMatrix4(mw);
+          _vc.fromBufferAttribute(pos, i2).applyMatrix4(mw);
+          if (_va.y > floorTop && _vb.y > floorTop && _vc.y > floorTop) return; // skip roof/upper walls
+          rasterTri(_va.x, _va.z, _vb.x, _vb.z, _vc.x, _vc.z);
+        };
+        if (idx) for (let i = 0; i < idx.count; i += 3) stamp(idx.getX(i), idx.getX(i + 1), idx.getX(i + 2));
+        else for (let i = 0; i < pos.count; i += 3) stamp(i, i + 1, i + 2);
+      });
+    }
+  };
+  const occupied = (x, z) => occ.has(keyOf(Math.round(x / cell), Math.round(z / cell)));
+  return { mark, markRect, rasterTri, stampBuildings, occupied };
+}

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