sindicate 0.15.0 → 0.17.0

package/src/world/roadWorld.js

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

package/src/world/settlement.js

@@ -0,0 +1,254 @@
+// SETTLEMENTS — buildings along the roads that already exist.
+//
+// A town is not a scatter of houses; it is frontage. Buildings stand back from a kerb by a
+// consistent distance, face the road, sit shoulder to shoulder without overlapping, and stop
+// short of a junction so they do not block sightlines or stand in the carriageway. Give this
+// the roads and a catalogue of what you own, and it returns where each building goes.
+//
+//   const plots = planFrontage({ links, catalogue, groundAt });
+//   for (const p of plots) place(p.model, p);      // { model, x, y, z, yaw }
+//
+// It places nothing and loads nothing: a game owns its assets, and a designer may take this
+// list, edit it, and save it as a layout.
+import { lcgRng } from './permanentWay.js';
+
+const EPS = 0.01;
+
+export const FRONTAGE_DEFAULTS = {
+  setback: 6,               // metres from the kerb to the front wall
+  gap: 2.5,                 // between neighbours
+  junctionClear: 45,        // no frontage within this of a link's end
+  depthClear: 4,            // keep this much behind a building free of the next road
+  maxSlope: 0.18,           // a plot steeper than this is not built on
+  maxBuilding: 60,          // the widest thing that may stand on a frontage
+  seed: 1,
+};
+
+// Every plot along one side of one road. Walks the centreline, and for each step chooses a
+// building from the catalogue that fits the gap it has left.
+function frontageOf(link, side, catalogue, cfg, groundAt, taken) {
+  const line = link.centreline;
+  if (line.length < 4) return [];
+  const half = link.width / 2;
+  const plots = [];
+
+  // arc positions along the line, so buildings are spaced by distance rather than by index
+  const seg = [];
+  let total = 0;
+  for (let i = 1; i < line.length; i++) {
+    const d = Math.hypot(line[i][0] - line[i - 1][0], line[i][2] - line[i - 1][2]);
+    seg.push({ i, s: total, d });
+    total += d;
+  }
+  const at = (s) => {
+    let k = 0;
+    while (k < seg.length - 1 && seg[k].s + seg[k].d < s) k++;
+    const a = line[seg[k].i - 1], b = line[seg[k].i];
+    const t = Math.min(1, Math.max(0, (s - seg[k].s) / (seg[k].d || 1)));
+    const p = [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+    const fx = b[0] - a[0], fz = b[2] - a[2];
+    const L = Math.hypot(fx, fz) || 1;
+    return { p, fwd: [fx / L, fz / L], right: [-fz / L, fx / L] };
+  };
+
+  const rng = lcgRng(cfg.seed * 7919 + (side > 0 ? 13 : 31) + Math.round(total));
+  const models = Object.entries(catalogue);
+  if (!models.length) return [];
+
+  let s = cfg.junctionClear;
+  const end = total - cfg.junctionClear;
+  let guard = 0;
+  while (s < end && guard++ < 500) {
+    const { p, fwd, right } = at(s);
+    // pick something that fits the road it faces: nothing enormous on a country lane
+    const room = end - s;
+    const fits = models.filter(([, m]) => Math.max(m.size[0], m.size[2]) <= Math.min(room, 26));
+    if (!fits.length) break;
+    const [model, m] = fits[Math.floor(rng() * fits.length)];
+    const width = Math.max(m.size[0], m.size[2]);
+    const depth = Math.min(m.size[0], m.size[2]);
+
+    // stand it back from the kerb, centred on its own frontage
+    const off = side * (half + cfg.setback + depth / 2);
+    const cx = p[0] + right[0] * off + fwd[0] * (width / 2);
+    const cz = p[2] + right[1] * off + fwd[1] * (width / 2);
+
+    // refuse a plot the ground will not take, and one already spoken for
+    const g = groundAt(cx, cz);
+    const corner = groundAt(cx + right[0] * depth / 2, cz + right[1] * depth / 2);
+    const slope = Math.abs(corner - g) / Math.max(depth / 2, 1);
+    const clash = taken.some((t) => Math.hypot(t.x - cx, t.z - cz) < (t.r + width / 2) * 0.85);
+    if (slope <= cfg.maxSlope && !clash) {
+      // face the road: the building's back is to the outside, its front to the kerb
+      const yaw = Math.atan2(-right[0] * side, -right[1] * side);
+      plots.push({ model, x: +cx.toFixed(2), y: +g.toFixed(2), z: +cz.toFixed(2), yaw: +yaw.toFixed(4), width, depth });
+      taken.push({ x: cx, z: cz, r: width / 2 });
+      s += width + cfg.gap;
+    } else {
+      s += 8;                                    // step past a plot that will not do
+    }
+  }
+  return plots;
+}
+
+// WHICH ROADS HAVE FRONTAGE AT ALL. Houses face a street, a lane, a high road through a
+// village. NOTHING fronts a motorway or a dual carriageway — no door opens onto one anywhere
+// in the world, because you cannot stop, turn across, or walk out of it. A planner handed
+// every road in the network will happily line a motorway with offices, and it looks exactly
+// as wrong as it is.
+//
+// Judged on what the road IS, in this order: what the kit called the socket, then how many
+// lanes it carries, then how wide it is — so a road that arrives with no classification at
+// all is still caught by its size.
+export const FRONTAGE_KINDS = new Set(['road', 'street', 'lane', undefined, null]);
+
+export function hasFrontage(entry, maxWidth = 16) {
+  const kind = entry?.from?.kind ?? entry?.kind ?? entry?.link?.kind;
+  if (kind && !FRONTAGE_KINDS.has(kind)) return false;
+  const lanes = entry?.from?.lanes?.length ?? 0;
+  if (lanes > 2) return false;                      // more than one each way is a through route
+  const width = entry?.from?.width ?? entry?.width ?? entry?.link?.width ?? 10;
+  return width <= maxWidth;
+}
+
+export function planFrontage({ links = [], catalogue = {}, groundAt = () => 0, ...opts } = {}) {
+  const cfg = { ...FRONTAGE_DEFAULTS, ...opts };
+  const taken = [];
+  const plots = [];
+  let refused = 0;
+  for (const entry of links) {
+    if (!hasFrontage(entry, cfg.maxFrontageWidth ?? 16)) { refused++; continue; }
+    // accept either a roadWorld link or a plain { centreline, width }
+    const link = entry.link ?? entry;
+    const width = entry.from?.width ?? entry.width ?? link.width ?? 10;
+    for (const side of [-1, 1]) {
+      plots.push(...frontageOf({ centreline: link.centreline, width }, side, catalogue, cfg, groundAt, taken));
+    }
+  }
+  plots.refused = refused;                          // say so rather than silently building none
+  return plots;
+}
+
+// WHAT BELONGS WHERE. A tower block on a country lane and a barn in the financial district
+// are the same mistake. Kiwi zoned its blocks and stopped; this is what the zone is FOR.
+// Names are the only signal a pack gives us, so read them, and fall back on height — a thing
+// thirty metres tall is downtown wherever it was filed.
+export const ZONE_RULES = {
+  downtown: /office|tower|skyscraper|bank|hall|corporate/i,
+  commercial: /shop|store|market|mall|retail|cafe|restaurant|hotel|station|cinema/i,
+  residential: /house|home|apartment|flat|residential|villa|cottage|terrace/i,
+  industrial: /factory|warehouse|depot|industrial|workshop|garage|silo/i,
+};
+
+export function zoneOf(model, entry) {
+  for (const [zone, re] of Object.entries(ZONE_RULES)) if (re.test(model)) return zone;
+  const h = entry?.size?.[1] ?? 0;
+  return h > 24 ? 'downtown' : h > 14 ? 'commercial' : 'residential';
+}
+
+// The models a zone will accept, widest choice first. A zone with nothing of its own takes
+// whatever fits rather than leaving the block bare — an empty plot reads as a bug.
+function catalogueFor(catalogue, zone, maxWidth) {
+  const all = Object.entries(catalogue).filter(([, m]) => Math.max(m.size[0], m.size[2]) <= maxWidth);
+  if (zone === 'park') return [];
+  const mine = all.filter(([n, m]) => zoneOf(n, m) === zone);
+  return mine.length >= 3 ? mine : all;
+}
+
+// BUILDINGS FILL A BLOCK FROM ITS EDGES INWARD. They stand along the block's boundary with
+// their fronts to the street and their backs to the middle, which is how a city block is
+// built and why its interior is yards and car parks rather than more buildings.
+export function planBlockFrontage({ blocks = [], catalogue = {}, groundAt = () => 0, ...opts } = {}) {
+  const cfg = { ...FRONTAGE_DEFAULTS, ...opts };
+  const plots = [];
+  const taken = [];
+  const used = new Map();              // model -> how many are up, so variety spreads itself
+  let b = 0;
+  for (const block of blocks) {
+    const poly = block.polygon;
+    const rng = lcgRng(cfg.seed * 7919 + (b++) * 131);
+    const cx = poly.reduce((a, p) => a + p[0], 0) / poly.length;
+    const cz = poly.reduce((a, p) => a + p[1], 0) / poly.length;
+    for (let e = 0; e < poly.length; e++) {
+      const A = poly[e], B = poly[(e + 1) % poly.length];
+      const ex = B[0] - A[0], ez = B[1] - A[1];
+      const len = Math.hypot(ex, ez);
+      if (len < 8) continue;
+      const fx = ex / len, fz = ez / len;
+      // outward: away from the block's middle, i.e. toward the street this edge faces
+      let nx = -fz, nz = fx;
+      if ((A[0] + fx * len / 2 - cx) * nx + (A[1] + fz * len / 2 - cz) * nz < 0) { nx = -nx; nz = -nz; }
+      // NOTHING SO WIDE IT EATS A WHOLE FRONTAGE, and nothing so deep it meets the building
+      // backing onto it from the far side. The ceiling belongs to the pack, not to this file:
+      // a kit whose smallest building is thirty metres across needs bigger blocks, and a cap
+      // of twenty-six would silently place none of them.
+      const edgeCap = Math.min(len * 0.55, cfg.maxBuilding ?? 60, (block.depth ?? Infinity));
+
+      // leave the corners clear so two frontages do not meet at right angles inside a wall
+      let s = cfg.gap;
+      const end = len - cfg.gap;
+      let guard = 0;
+      while (s < end && guard++ < 80) {
+        const room = end - s;
+        // PICK SOMETHING THAT FILLS THE RUN, WITHOUT BUILDING THE SAME STREET TWICE.
+        // Choosing at random from everything that fits leaves a block mostly empty, because a
+        // small building drawn early strands a gap nothing else wants. Choosing only from the
+        // widest few — as this did — fills the run and turns a city into four repeated towers,
+        // since the widest few are the same four every time.
+        //
+        // So weight by width rather than truncating by it — and DECAY THE WEIGHT AS A TYPE
+        // GETS USED, or the widest still wins nearly every roll and a sixteen-building pack
+        // reads as five. Dividing by how often a model has already gone up makes the
+        // distribution spread itself: the first roll favours the big ones, and by the tenth
+        // the ones that have not been built yet are the likeliest.
+        const fits = catalogueFor(catalogue, block.zone, Math.min(room, edgeCap));
+        if (!fits.length) break;
+        const weights = fits.map(([n, m]) =>
+          Math.max(m.size[0], m.size[2]) / (1 + (used.get(n) ?? 0) * 2));
+        const total = weights.reduce((a, b) => a + b, 0);
+        let pick = rng() * total, k = 0;
+        while (k < weights.length - 1 && (pick -= weights[k]) > 0) k++;
+        const [model, m] = fits[k];
+        const width = Math.max(m.size[0], m.size[2]);
+        const depth = Math.min(m.size[0], m.size[2]);
+        // FRONT WALL ON THE BLOCK EDGE. Set back by half its own depth and no more: a
+        // building pushed further in leaves a bald strip along every street and, with a
+        // deep enough model, ends up standing in the middle of the block instead of on it.
+        const px = A[0] + fx * (s + width / 2) - nx * (depth / 2);
+        const pz = A[1] + fz * (s + width / 2) - nz * (depth / 2);
+
+        // AND CLASH ON THE FOOTPRINT, NOT ON A CIRCLE ROUND IT. A circle big enough to hold
+        // a 22 m tower keeps the next building 20 m away in every direction, so a block
+        // fits three of them and looks abandoned. The blocks are axis-aligned and so are
+        // their frontages, so the real footprints compare directly.
+        const along = Math.abs(fx) > Math.abs(fz);
+        const hw = (along ? width : depth) / 2, hd = (along ? depth : width) / 2;
+        const box = { x0: px - hw, x1: px + hw, z0: pz - hd, z1: pz + hd };
+        const clash = taken.some((t) =>
+          box.x0 < t.x1 - EPS && box.x1 > t.x0 + EPS && box.z0 < t.z1 - EPS && box.z1 > t.z0 + EPS);
+        if (!clash) {
+          used.set(model, (used.get(model) ?? 0) + 1);
+          plots.push({
+            model, x: +px.toFixed(2), y: +groundAt(px, pz).toFixed(2), z: +pz.toFixed(2),
+            yaw: +Math.atan2(nx, nz).toFixed(4), width, depth, zone: block.zone,
+          });
+          taken.push({ x0: box.x0 - cfg.gap / 2, x1: box.x1 + cfg.gap / 2, z0: box.z0 - cfg.gap / 2, z1: box.z1 + cfg.gap / 2 });
+          s += width + cfg.gap;
+        } else {
+          s += 4;
+        }
+      }
+    }
+  }
+  return plots;
+}
+
+// A town is frontage plus a name and a middle. Handy for a map, and for deciding which
+// buildings belong where — a bank downtown, a barn on a lane.
+export function summariseSettlement(plots) {
+  if (!plots.length) return null;
+  const x = plots.reduce((a, p) => a + p.x, 0) / plots.length;
+  const z = plots.reduce((a, p) => a + p.z, 0) / plots.length;
+  const spread = Math.max(...plots.map((p) => Math.hypot(p.x - x, p.z - z)));
+  return { x: +x.toFixed(1), z: +z.toFixed(1), radius: +spread.toFixed(1), buildings: plots.length };
+}

package/src/world/walkHumps.js

@@ -22,6 +22,10 @@
 
 // Footprint half-extents (x, z) and bbox apex, measured off the GLBs (probe: gltf-transform bbox).
 // The apex rides above the −0.08 m seat placementField sinks every pile by.
+// THE MOUNDS THIS ENGINE HAPPENS TO KNOW. Five Dustwater dust piles, measured off their GLBs.
+// A game with its own mounds — sandbags, rubble, a spoil heap — is not doing anything wrong by
+// having them, so `resHump()` must not crash the world build over one. Games add their own with
+// setHumpDims(); anything still unknown is placed as ordinary scenery and said so once.
 const DIMS = {
   SM_Env_DustPile_Large_01: [5.66, 5.66, 0.82],
   SM_Env_DustPile_Small_02: [1.35, 1.41, 0.82],
@@ -34,9 +38,26 @@ const CELL = 16, HALF = 512;
 const key = (cx, cz) => (cx + HALF) * 4096 + (cz + HALF);
 const _grid = new Map();    // int key → flat rows [x, z, cos, sin, 1/rx, 1/rz, apex] × n
 
+// A game declares the footprint of its own mounds: { file: [radiusX, radiusZ, height] } in
+// metres at scale 1, measured off the GLB. Merged over the built-in table, never replacing it.
+export function setHumpDims(dims = {}) { Object.assign(DIMS, dims); }
+
+const UNKNOWN = new Set();
+
 export function registerHumps(file, placements) {
   const dims = DIMS[file];
-  if (!dims) throw new Error(`[walkHumps] no dome dims for ${file} — measure the GLB and add it to DIMS`);
+  if (!dims) {
+    // NOT AN ERROR. Throwing from a registration API means a game whose props differ from
+    // western's cannot build its world at all; the honest outcome is that this prop is scenery
+    // you walk past rather than a mound you walk over.
+    if (!UNKNOWN.has(file)) {
+      UNKNOWN.add(file);
+      console.warn(`[walkHumps] no dome dimensions for ${file} — placed as flat scenery. `
+        + 'Measure the GLB and register it with setHumpDims({ [file]: [rx, rz, height] }) '
+        + 'to make it walkable-over.');
+    }
+    return;
+  }
   for (const p of placements) {
     const rx = dims[0] * p.s, rz = dims[1] * p.s, h = dims[2] * p.s - SEAT;
     if (h <= 0.05) continue;                     // a 5 cm mound is texture, not terrain

package/tools/modelCatalogue.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// MODEL CATALOGUE — measure a pack's GLBs so a placer knows what it is putting down.
+//
+//   node tools/modelCatalogue.mjs <packDir> [filterRegex]
+//
+// Writes <packDir>/catalogue.json: for each model, its size and where its origin sits within
+// it. Placing a building without knowing its footprint means either guessing (and overlapping
+// its neighbour) or measuring it at load in every game that uses it.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [packDir, filter = '.', exclude = null] = process.argv.slice(2);
+if (!packDir) { console.error('usage: modelCatalogue.mjs <packDir> [filterRegex] [excludeRegex]'); process.exit(1); }
+const re = new RegExp(filter, 'i');
+// Synty ships COMPONENTS as well as whole things — a roof, a floor slab, a length of pipe.
+// A placer handed those puts a chimney on a grass verge, so a catalogue meant for placement
+// needs to exclude them (the assembled versions live in the pack's prefabs).
+const ex = exclude ? new RegExp(exclude, 'i') : null;
+const modelsDir = path.join(packDir, 'models');
+
+function bounds(file) {
+  const buf = fs.readFileSync(path.join(modelsDir, file));
+  const jsonLen = buf.readUInt32LE(12);
+  const gltf = JSON.parse(buf.slice(20, 20 + jsonLen).toString('utf8'));
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+  for (const mesh of gltf.meshes ?? []) {
+    for (const prim of mesh.primitives ?? []) {
+      const acc = gltf.accessors[prim.attributes.POSITION];
+      if (!acc?.min) continue;
+      for (let d = 0; d < 3; d++) {
+        if (acc.min[d] < min[d]) min[d] = acc.min[d];
+        if (acc.max[d] > max[d]) max[d] = acc.max[d];
+      }
+    }
+  }
+  return Number.isFinite(min[0]) ? { min, max } : null;
+}
+
+const out = {};
+let n = 0;
+for (const f of fs.readdirSync(modelsDir)) {
+  if (!f.endsWith('.glb') || !re.test(f) || (ex && ex.test(f))) continue;
+  const b = bounds(f);
+  if (!b) continue;
+  // and nothing that is obviously not a building in its own right
+  const sz = [0, 1, 2].map((d) => b.max[d] - b.min[d]);
+  if (sz[1] < 5 || Math.max(sz[0], sz[2]) < 5) continue;
+  out[f] = {
+    size: [0, 1, 2].map((d) => +(b.max[d] - b.min[d]).toFixed(2)),
+    // where the model's own origin sits in its footprint — a building modelled around its
+    // centre and one modelled from a corner need different treatment to stand on a plot
+    centre: [0, 1, 2].map((d) => +((b.max[d] + b.min[d]) / 2).toFixed(2)),
+    base: +b.min[1].toFixed(2),
+  };
+  n++;
+}
+fs.writeFileSync(path.join(packDir, 'catalogue.json'), JSON.stringify(out, null, 0));
+const sizes = Object.values(out).map((v) => Math.max(v.size[0], v.size[2]));
+console.log(`${n} models catalogued · footprints ${Math.min(...sizes).toFixed(1)}–${Math.max(...sizes).toFixed(1)} m`);

package/tools/unityPackageExtract.mjs

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