sindicate 0.16.0 → 0.17.0

package/src/world/roadLink.js

@@ -15,14 +15,26 @@
 // both ends meet their arms tangentially — no kink at the seam.
 import * as THREE from 'three';
 
-const PALETTE = {           // texels in the Simpligon atlas (flat sampling, no tiling)
+// TEXELS IN THE SIMPLIGON ATLAS, flat-sampled — Kiwi's own coordinates, from
+// CurvedRoadMeshGenerator: UV_ROAD (0.2871, 0.0361), UV_WHITE (0.2871, 0.1105),
+// UV_CONCRETE top (0.2993, 0.1396) and edge (0.2993, 0.1133).
+//
+// The concrete pair was missing here, so anything that was not tarmac got painted with the
+// WHITE LINE texel — which is why the pavements came out looking like road markings rather
+// than like pavements.
+const PALETTE = {
   asphalt: [0.2871, 0.0361],
   line: [0.2871, 0.1105],
+  concrete: [0.2993, 0.1396],       // footway top
+  kerb: [0.2993, 0.1133],           // its edge, and the gutter face
 };
 const MARK_Y = 0.02;        // paint sits this far above the asphalt
 const EDGE_W = 0.1;         // edge-line width
-const DASH_W = 0.1;         // centre-line width
-const DASH_ON = 2.5, DASH_OFF = 2.5;
+// KIWI'S OWN FIGURES (CurvedRoadMeshGenerator: DASH_LENGTH 1, DASH_GAP 1.5, DASH_WIDTH
+// 0.15, MARKING_HEIGHT 0.02). Mine were 2.5 on and 2.5 off, which reads as a lane divider on
+// a motorway and as sleepers on a street.
+const DASH_W = 0.15;        // centre-line width
+const DASH_ON = 1.0, DASH_OFF = 1.5;
 
 const catmull = (p, t) => {
   // smooth interpolation through the given heights (duplicated ends = flat entry/exit)
@@ -196,16 +208,70 @@ export function buildRoadLink({
     };
   };
 
-  // ── asphalt deck ──
-  const deck = [];
-  for (const { p, right, half } of samples) {
-    const l = p.clone().addScaledVector(right, -half);
-    const r = p.clone().addScaledVector(right, half);
-    deck.push([vert(l, UP, palette.asphalt), vert(r, UP, palette.asphalt)]);
-  }
-  for (let i = 0; i < deck.length - 1; i++) {
-    const [a, b] = deck[i], [c, d] = deck[i + 1];
-    idx.push(a, b, c, b, d, c);
+  // ── the deck ──
+  //
+  // A CROSS-SECTION WITH HEIGHT IN IT, when the socket carries one. A city street is not a
+  // flat ribbon with paint on it: it has a kerb, a gutter that drops below the carriageway,
+  // and a footway raised above it. Kiwi builds these by taking a road prefab's front-edge
+  // vertices as a profile and extruding that along the spline (CurvedRoadMeshGenerator.
+  // ExtractRoadProfile), which is why its streets have kerbs and mine, tiled by hand, did
+  // not. `profile` is that list of [lateral, height] pairs; without one the deck is the flat
+  // ribbon a motorway wants, where the kerbs are somebody else's barrier props.
+  //
+  // Lateral offsets scale with the socket width so one profile serves a narrow lane and a
+  // wide street, and heights do NOT — a kerb is 125 mm whatever the road.
+  const xsec = from.profile ?? to.profile ?? null;
+  let refHalfOut = 1;
+  if (xsec?.length >= 2) {
+    // SCALE AGAINST THE CARRIAGEWAY, NOT THE WHOLE SECTION. A socket's `width` is the
+    // driveable width; the profile is wider than that because it includes the kerb, the
+    // footway and the verge behind it. Scaling by the outermost point squeezes the entire
+    // 20 m section into the 10 m carriageway — every kerb and pavement at half size.
+    // The carriageway ends at its OWN outermost vertex, not at the first kerb vertex beyond
+    // it. Those are different points — the kerb face begins a few centimetres outside the
+    // tarmac edge — and taking the kerb's makes every road that fraction narrow: a 10 m
+    // street came out 9.84 m, and every kerb, footway and lane marking with it.
+    const kerbAt = xsec.filter(([, y]) => y < -0.01).map(([x]) => Math.abs(x));
+    const innerKerb = kerbAt.length ? Math.min(...kerbAt) : Infinity;
+    const flat = xsec.filter(([x, y]) => Math.abs(y) <= 0.01 && Math.abs(x) <= innerKerb).map(([x]) => Math.abs(x));
+    const refHalf = (flat.length ? Math.max(...flat)
+      : Number.isFinite(innerKerb) ? innerKerb
+      : Math.max(...xsec.map(([x]) => Math.abs(x)))) || 1;
+    refHalfOut = refHalf;
+    // WHICH SIDE OF THE KERB IS IT ON? Height alone is not enough, and this is the rule
+    // Kiwi's GetSimpligonUV actually uses: cast from the centre line toward the vertex, and
+    // if a kerb lies between them, the vertex is footway — even where it is flat. A pavement
+    // is mostly level ground BEHIND a kerb, so judging by height alone paints the 0.35 m
+    // raised lip as pavement and the four metres of actual footway behind it as tarmac.
+    const kerbs = xsec.filter(([, y]) => y < -0.01).map(([x]) => x);
+    const pastKerb = (lx) => kerbs.some((k) => (lx > 0 && k > 0 && k < lx) || (lx < 0 && k < 0 && k > lx));
+    const rows = samples.map(({ p, right, half }) => xsec.map(([lx, ly]) => {
+      const q = p.clone().addScaledVector(right, (lx / refHalf) * half);
+      q.y += ly;
+      // the same three-way split Kiwi makes: below grade is the kerb face, raised or behind
+      // a kerb is footway, everything else is carriageway
+      const tex = ly < -0.01 ? palette.kerb
+        : (ly > 0.05 || pastKerb(lx)) ? palette.concrete
+        : palette.asphalt;
+      return vert(q, UP, tex);
+    }));
+    for (let i = 0; i < rows.length - 1; i++) {
+      for (let k = 0; k < xsec.length - 1; k++) {
+        const a = rows[i][k], b = rows[i][k + 1], c = rows[i + 1][k], d = rows[i + 1][k + 1];
+        idx.push(a, b, c, b, d, c);
+      }
+    }
+  } else {
+    const deck = [];
+    for (const { p, right, half } of samples) {
+      const l = p.clone().addScaledVector(right, -half);
+      const r = p.clone().addScaledVector(right, half);
+      deck.push([vert(l, UP, palette.asphalt), vert(r, UP, palette.asphalt)]);
+    }
+    for (let i = 0; i < deck.length - 1; i++) {
+      const [a, b] = deck[i], [c, d] = deck[i + 1];
+      idx.push(a, b, c, b, d, c);
+    }
   }
 
   // ── painted strips: a run of cross-sections at fixed lateral offsets ──
@@ -260,13 +326,20 @@ export function buildRoadLink({
 
   // ── side apron so an elevated road is not a floating sheet ──
   if (skirt > 0) {
+    // AT THE OUTSIDE OF THE SECTION, not at the carriageway edge. `half` is the driveable
+    // half-width, which with a profile is the middle of the ribbon, not its edge — so the
+    // apron came down as a wall right where the kerb is, a grey strip alongside the tarmac
+    // that reads as part of the road instead of the side of the pavement.
+    const outer = xsec?.length ? Math.max(...xsec.map(([x]) => Math.abs(x))) / (refHalfOut || 1) : 1;
     for (const side of [-1, 1]) {
       const wall = [];
       for (const { p, right, half } of samples) {
-        const top = p.clone().addScaledVector(right, side * half);
+        const top = p.clone().addScaledVector(right, side * half * outer);
         const bot = top.clone(); bot.y -= skirt;
         const n = [right.x * side, 0, right.z * side];
-        wall.push([vert(top, n, palette.asphalt), vert(bot, n, palette.asphalt)]);
+        // and it is the side of the PAVEMENT out here, not the side of the road
+        const tex = xsec?.length ? palette.kerb : palette.asphalt;
+        wall.push([vert(top, n, tex), vert(bot, n, tex)]);
       }
       for (let i = 0; i < wall.length - 1; i++) {
         const [a, b] = wall[i], [c, d] = wall[i + 1];

package/src/world/roadTerrain.js

@@ -14,6 +14,24 @@ import { smoothstep } from './geo.js';
 
 // segment lookup on a uniform grid — a world's worth of road is far too many segments to
 // walk per lattice vertex, and the lattice is ~1.7M vertices
+// HOW FAR ALONG A SEGMENT A POINT SITS, or null if the segment does not cover it. The two
+// callers below both used to inline this and both got the ends wrong in the same way; the
+// terrain went missing in a rounded blob past the end of every road, because a point out
+// there was told it had tarmac over it and its triangles were dropped as invisible.
+//
+// `narrow` pulls the edges in: a corridor's BED is wider than its carriageway, so anything
+// asking "is the ground hidden here?" must ask about the road, not the earthwork.
+function along(s, x, z, narrow = 0) {
+  const dx = s.bx - s.ax, dz = s.bz - s.az;
+  const len2 = dx * dx + dz * dz || 1e-6;
+  const raw = ((x - s.ax) * dx + (z - s.az) * dz) / len2;
+  // past either END of the whole line there is no road, however close the last vertex is
+  if (raw < 0 && s.first) return null;
+  if (raw > 1 && s.last) return null;
+  const t = Math.min(1, Math.max(0, raw));
+  return Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) <= s.half - narrow ? t : null;
+}
+
 function segmentIndex(corridors, cell) {
   const buckets = new Map();
   const key = (i, j) => `${i},${j}`;
@@ -28,6 +46,19 @@ function segmentIndex(corridors, cell) {
       const s = {
         ax: a[0], ay: a[1], az: a[2], bx: b[0], by: b[1], bz: b[2],
         half: c.halfWidth ?? 5, drop: c.drop ?? 0, batter: c.batter ?? 0.5,
+        // DOES THIS CORRIDOR CARRY TARMAC? Most do — a corridor is normally the cut and fill
+        // under a road. Some are pure earthwork: the trench that opens the ground under an
+        // interchange's lower carriageway is shaped like a road and is not one, and it runs
+        // on past the sockets at either end so the batter has somewhere to go. Told that was
+        // tarmac, the "don't draw ground you cannot see" pass threw away the terrain over the
+        // whole trench and left a hole in the world past the end of the road.
+        carries: c.deck !== false,
+        // WHERE THE ROAD STOPS. A segment answers questions about points near it by
+        // clamping the projection to its own span, which turns each end of a polyline into
+        // a half-disc of phantom road reaching a full half-width past the last vertex.
+        // Harmless in the middle of a line — the next segment covers that ground anyway —
+        // and wrong at the two ends, where it claims tarmac over open country.
+        first: i === 0, last: i === line.length - 2,
       };
       const id = segs.push(s) - 1;
       const i0 = Math.floor((Math.min(a[0], b[0]) - reach) / cell), i1 = Math.floor((Math.max(a[0], b[0]) + reach) / cell);
@@ -152,10 +183,8 @@ export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfa
       const ids = index.near(x, z);
       for (const id of ids ?? []) {
         const s = index.segs[id];
-        const dx = s.bx - s.ax, dz = s.bz - s.az;
-        const len2 = dx * dx + dz * dz || 1e-6;
-        const t = Math.min(1, Math.max(0, ((x - s.ax) * dx + (z - s.az) * dz) / len2));
-        if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half) continue;
+        const t = along(s, x, z);
+        if (t == null) continue;
         found.push(s.ay + (s.by - s.ay) * t);
       }
     }
@@ -187,10 +216,9 @@ export function makeRoadTerrain(baseHeightAt, { pads = [], corridors = [], surfa
     let lowest = null;
     for (const id of ids) {
       const s = index.segs[id];
-      const dx = s.bx - s.ax, dz = s.bz - s.az;
-      const len2 = dx * dx + dz * dz || 1e-6;
-      const t = Math.min(1, Math.max(0, ((x - s.ax) * dx + (z - s.az) * dz) / len2));
-      if (Math.hypot(x - (s.ax + dx * t), z - (s.az + dz * t)) > s.half - shrink) continue;
+      if (!s.carries) continue;                        // an earthwork is not a road surface
+      const t = along(s, x, z, shrink);
+      if (t == null) continue;
       const y = s.ay + (s.by - s.ay) * t;
       if (lowest == null || y < lowest) lowest = y;
     }

package/src/world/roadWorld.js

@@ -176,6 +176,11 @@ export async function buildRoadWorld({
         [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,
     });
   }
 

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`);