sindicate 0.13.0 → 0.15.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/roadKit.js

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