sindicate 0.12.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/railFormation.js

@@ -0,0 +1,185 @@
+// THE RAIL FORMATION SOLVER (world splits, step 2) — the embankment IS the terrain.
+// Moved verbatim from western's terrainData: the navvy's algorithm that turns a centreline
+// over raw ground into a buildable formation, and the corridor index heightAt interrogates
+// 1.74M times per cold cook. Everything here is PURE MACHINERY — the county supplies the
+// nodes, the surveyed ground, the ruling grade and the weave (its applyRail composition
+// stays game-side, where the river guard and road bench live).
+//
+// HOW A LINE IS SOLVED, at every node of the centreline (~1 m apart):
+//   1. the game SURVEYS the ground into g[] (its own choice of surface — pads in, benches out)
+//   2. LEVEL THE YARDS — each contiguous `flat` run pulled to its own mean
+//   3. THE RULING GRADE — ceil/floor Lipschitz envelopes at maxGrade; their midpoint splits
+//      every obstacle evenly between a cutting and an embankment
+//   4. VERTICAL CURVES — a diffusion pass is a curve and cannot break the ruling grade
+//   5. optional WELD onto an already-solved line (one bed through the turnout, no seam)
+//   6. e[] — earthworks weight: 1 = full bench, 0 = past fillMax, flying on a trestle
+//
+// HEADLESS BY LAW, like geo.js: no three imports at all.
+import { clamp, lerp, smoothstep } from './geo.js';
+
+// Nearest point on a solved line: how far, and how high the formation is there.
+export function nearestOnLine(nodes, Y, x, z) {
+  let bd = Infinity, by = 0;
+  for (let i = 0; i < nodes.length - 1; i++) {
+    const a = nodes[i], b = nodes[i + 1];
+    const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+    const t = clamp(((x - a.x) * dx + (z - a.z) * dz) / len2, 0, 1);
+    const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+    if (d < bd) { bd = d; by = lerp(Y[i], Y[i + 1], t); }
+  }
+  return { d: bd, y: by };
+}
+
+// nodes: [{x, z, s, w, flat}] — s = arc length, w = bed half-width, flat = yard node.
+// g: Float64Array of surveyed ground per node (the game samples its own surface).
+// mergeWith: { nodes, y } of an already-solved line to weld through the shared bed.
+// Returns { y, g, e }.
+export function solveFormation(nodes, g, { maxGrade, smooth = 90, mergeIn = 7, mergeOut = 32, fillMax, mergeWith = null }) {
+  const n = nodes.length;
+  g = Float64Array.from(g);
+
+  // ONE BED THROUGH THE TURNOUT: where this line is still in the other's bed, the ground
+  // it is surveyed on IS the other line's formation.
+  if (mergeWith) {
+    for (let i = 0; i < n; i++) {
+      const m = nearestOnLine(mergeWith.nodes, mergeWith.y, nodes[i].x, nodes[i].z);
+      g[i] = lerp(m.y, g[i], smoothstep(mergeIn, mergeOut, m.d));
+    }
+  }
+
+  // LEVEL THE YARDS — each contiguous run of `flat` nodes pulled to its own mean.
+  for (let i = 0; i < n; i++) {
+    if (!nodes[i].flat) continue;
+    let j = i; while (j < n && nodes[j].flat) j++;
+    let sum = 0; for (let k = i; k < j; k++) sum += g[k];
+    const mean = sum / (j - i);
+    for (let k = i; k < j; k++) g[k] = mean;
+    i = j;
+  }
+
+  // THE RULING GRADE — the two Lipschitz envelopes, and their midpoint.
+  const ceil = Float64Array.from(g), floor = Float64Array.from(g);
+  for (let i = 1; i < n; i++) {
+    const d = maxGrade * (nodes[i].s - nodes[i - 1].s);
+    ceil[i] = Math.max(ceil[i], ceil[i - 1] - d);      // may only FALL at the ruling grade
+    floor[i] = Math.min(floor[i], floor[i - 1] + d);   // may only RISE at it
+  }
+  for (let i = n - 2; i >= 0; i--) {
+    const d = maxGrade * (nodes[i + 1].s - nodes[i].s);
+    ceil[i] = Math.max(ceil[i], ceil[i + 1] - d);
+    floor[i] = Math.min(floor[i], floor[i + 1] + d);
+  }
+  const y = new Float64Array(n);
+  for (let i = 0; i < n; i++) y[i] = 0.5 * (ceil[i] + floor[i]);
+
+  // THE VERTICAL CURVES.
+  const tmp = new Float64Array(n);
+  for (let p = 0; p < smooth; p++) {
+    tmp.set(y);
+    for (let i = 1; i < n - 1; i++) y[i] = 0.25 * tmp[i - 1] + 0.5 * tmp[i] + 0.25 * tmp[i + 1];
+  }
+
+  // …and weld the result back onto the line it left — bit-identical through the shared bed.
+  if (mergeWith) {
+    for (let i = 0; i < n; i++) {
+      const m = nearestOnLine(mergeWith.nodes, mergeWith.y, nodes[i].x, nodes[i].z);
+      y[i] = lerp(m.y, y[i], smoothstep(mergeIn, mergeOut, m.d));
+    }
+  }
+
+  // HOW MUCH EARTH TO MOVE. Past fillMax the bank would be a wall — stop building and fly.
+  const e = new Float64Array(n);
+  for (let i = 0; i < n; i++) e[i] = 1 - smoothstep(fillMax, fillMax + 1.5, y[i] - g[i]);
+  return { y, g, e };
+}
+
+// THE CORRIDOR INDEX — chunked AABBs per line plus ONE box round the whole railway, because
+// the county is huge, the railway is a ribbon, and the common answer must cost four compares.
+// lines: { name: { nodes, y, e } }. Returns { railInfo, railDistance, records } — records is
+// the fixed scratch array (one record per line, rewritten in place, zero allocation per call)
+// the game's own corridor blend iterates.
+export function makeRailIndex(lines, { near, chunk = 32 } = {}) {
+  const chunks = [];
+  const box = { minX: Infinity, maxX: -Infinity, minZ: Infinity, maxZ: -Infinity };
+  const rl = {};
+  for (const name of Object.keys(lines)) {
+    rl[name] = { d: Infinity, y: 0, w: 0, e: 1 };
+    const { nodes: N, y: Y, e: E } = lines[name];
+    for (let i = 0; i < N.length - 1; i += chunk) {
+      const end = Math.min(i + chunk, N.length - 1);
+      let minX = Infinity, maxX = -Infinity, minZ = Infinity, maxZ = -Infinity;
+      for (let j = i; j <= end; j++) {
+        const p = N[j];
+        if (p.x < minX) minX = p.x; if (p.x > maxX) maxX = p.x;
+        if (p.z < minZ) minZ = p.z; if (p.z > maxZ) maxZ = p.z;
+      }
+      chunks.push({ name, N, Y, E, i0: i, i1: end, minX: minX - near, maxX: maxX + near, minZ: minZ - near, maxZ: maxZ + near });
+      box.minX = Math.min(box.minX, minX - near); box.maxX = Math.max(box.maxX, maxX + near);
+      box.minZ = Math.min(box.minZ, minZ - near); box.maxZ = Math.max(box.maxZ, maxZ + near);
+    }
+  }
+  const records = Object.values(rl);
+
+  function railInfo(x, z) {
+    for (const r of records) r.d = Infinity;
+    if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ) return rl;
+    for (const c of chunks) {
+      if (x < c.minX || x > c.maxX || z < c.minZ || z > c.maxZ) continue;
+      const R = rl[c.name], N = c.N, Y = c.Y, E = c.E;
+      for (let i = c.i0; i < c.i1; i++) {
+        const a = N[i], b = N[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+        const t = clamp(((x - a.x) * dx + (z - a.z) * dz) / len2, 0, 1);
+        const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+        if (d < R.d) {
+          R.d = d;
+          R.y = lerp(Y[i], Y[i + 1], t);
+          R.w = lerp(a.w, b.w, t);
+          R.e = lerp(E[i], E[i + 1], t);
+        }
+      }
+    }
+    return rl;
+  }
+
+  function railDistance(x, z) {
+    const r = railInfo(x, z);
+    let d = Infinity;
+    for (const name in r) if (r[name].d < d) d = r[name].d;
+    return d;
+  }
+
+  return { railInfo, railDistance, records };
+}
+
+// WHERE THE ROADS CROSS THE RAILS — found, not assumed: every road segment against every
+// rail segment. Returns [{x, z, y, tx, tz}] with y = the formation there and (tx,tz) the
+// rail's unit tangent (the axis the deck is measured along).
+export function findCrossings(roads, lines, { minSpacing = 30 } = {}) {
+  const xings = [];
+  const hit = (a, b, c, d) => {
+    const rx = b.x - a.x, rz = b.z - a.z, sx = d.x - c.x, sz = d.z - c.z;
+    const den = rx * sz - rz * sx;
+    if (Math.abs(den) < 1e-9) return null;
+    const t = ((c.x - a.x) * sz - (c.z - a.z) * sx) / den;
+    const u = ((c.x - a.x) * rz - (c.z - a.z) * rx) / den;
+    if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+    return { x: a.x + rx * t, z: a.z + rz * t };
+  };
+  for (const road of roads) {
+    for (let i = 0; i < road.length - 1; i++) {
+      for (const name of Object.keys(lines)) {
+        const { nodes: N, y: Y } = lines[name];
+        for (let j = 0; j < N.length - 1; j++) {
+          const p = hit(road[i], road[i + 1], N[j], N[j + 1]);
+          if (p && !xings.some((q) => Math.hypot(q.x - p.x, q.z - p.z) < minSpacing)) {
+            const tx0 = N[j + 1].x - N[j].x, tz0 = N[j + 1].z - N[j].z;
+            const tl = Math.hypot(tx0, tz0) || 1;
+            xings.push({ x: p.x, z: p.z, y: nearestOnLine(N, Y, p.x, p.z).y, tx: tx0 / tl, tz: tz0 / tl });
+          }
+        }
+      }
+    }
+  }
+  return xings;
+}