sindicate 0.13.0 → 0.15.0

package/src/world/kit.js

@@ -0,0 +1,924 @@
+// THE KIT REGISTRIES + DOOR/LADDER MECHANISM (world splits, step 5a) — the live shared
+// state of a stamped world and the machinery that animates it, moved verbatim from
+// western's town.js. Identity is the contract: the coach/train systems, the TileField,
+// the weather shelter closure and the region streamer all hold these ARRAYS by reference
+// — one module instance, ever. The stamper itself (buildTown/buildArea + the content
+// regexes) follows in 5b; games re-export these from their town module so every existing
+// importer keeps its binding.
+import * as THREE from 'three/webgpu';
+import { texture, uv } from 'three/tsl';
+import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+import { loadModel, loadTexture, resolveModelUrl } from '../core/assets.js';
+import { flattenToGeometry } from './scatter.js';
+import { lampLight } from './lampField.js';
+
+// ── the registries ────────────────────────────────────────────────────────────────────
+export const colliders = []; // fence capsules + tree circles (everything else is in the BVH)
+// Every building mesh, baked into the collision BVH (world.build) and raycast by weather.
+export const buildingObjects = [];
+// Working doors: one record per DOORWAY (not per building). The game wires an
+// E-interactable to each; updateDoors() eases the swing.
+export const doors = [];
+// CLIMBABLE LADDERS: one record per continuous ladder, in world space, for the Climbing
+// controller. { base:Vector3, quat:Quaternion, height:number }.
+export const ladders = [];
+// The slab that shuts an opening. Its own array, NOT `colliders`: there are 130-odd of
+// them, they never move, and collide() walks `colliders` linearly 200-400 times a frame.
+// Bucketed instead (indexDoors/doorsAt), so a door costs a Map lookup, not a scan.
+export const doorColliders = [];
+// { key, geometry, mat, part } — filled by the stamper's makeDoors, drained by buildDoorBatches
+export const leafQueue = [];
+
+// ── door swing tunables ───────────────────────────────────────────────────────────────
+const BAT_OPEN = 1.7;             // ~97 deg — a batwing thrown wide; it has no frame to hit
+const DOOR_OPEN = 1.5;            // ~86 deg — a door in a jamb buries itself in its own wall past 90
+const DOOR_SECS = 0.6;            // the whole swing, at a constant rate (the coach's idiom)
+
+// ── geometry helpers ──────────────────────────────────────────────────────────────────
+export const det3 = (m) => m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9])
+  + m[8] * (m[1] * m[6] - m[2] * m[5]);
+
+export function flipWinding(g) {
+  for (const attr of Object.values(g.attributes)) {
+    const a = attr.array, s = attr.itemSize;
+    for (let i = 0; i < attr.count; i += 3) {
+      for (let c = 0; c < s; c++) {
+        const i1 = (i + 1) * s + c, i2 = (i + 2) * s + c;
+        const t = a[i1]; a[i1] = a[i2]; a[i2] = t;
+      }
+    }
+    attr.needsUpdate = true;
+  }
+  return g;
+}
+
+// geometry with `m` baked in, ready to merge into a positive-determinant parent
+export function bake(base, m) {
+  const g = base.clone().applyMatrix4(m);
+  const flat = g.index ? g.toNonIndexed() : g;
+  return det3(m.elements) < 0 ? flipWinding(flat) : flat;
+}
+
+// ── ladders ───────────────────────────────────────────────────────────────────────────
+// Resolve gathered ladder prop matrices → world climb records, MERGING collinear stacked
+// segments (same x,z, stepped y) into one tall ladder. Measures each unique GLB's
+// Y-extent once for the per-segment height (× the instance's Y-scale).
+export async function buildLadders(insts) {
+  if (!insts.length) return [];
+  const localH = {};
+  for (const li of insts) {
+    const key = `${li.dir}/${li.file}`;
+    if (localH[key] != null) continue;
+    try { const flat = flattenToGeometry(await loadModel(`${key}.fbx`)); flat.geometry.computeBoundingBox(); const bb = flat.geometry.boundingBox; localH[key] = bb.max.y - bb.min.y; }
+    catch { localH[key] = 3.0; }
+  }
+  const _p = new THREE.Vector3(), _q = new THREE.Quaternion(), _s = new THREE.Vector3();
+  const recs = insts.map((li) => {
+    li.m.decompose(_p, _q, _s);
+    return { base: _p.clone(), quat: _q.clone(), height: (localH[`${li.dir}/${li.file}`] ?? 3.0) * Math.abs(_s.y) };
+  });
+  const out = [], used = new Array(recs.length).fill(false);
+  for (let i = 0; i < recs.length; i++) {
+    if (used[i]) continue;
+    const group = [recs[i]]; used[i] = true;
+    for (let j = i + 1; j < recs.length; j++) {
+      if (!used[j] && Math.hypot(recs[j].base.x - recs[i].base.x, recs[j].base.z - recs[i].base.z) < 0.6) { group.push(recs[j]); used[j] = true; }
+    }
+    group.sort((a, b) => a.base.y - b.base.y);
+    const bot = group[0], top = group[group.length - 1];
+    out.push({ base: bot.base, quat: bot.quat, height: (top.base.y + top.height) - bot.base.y });
+  }
+  return out;
+}
+
+// ── door batches ──────────────────────────────────────────────────────────────────────
+export function buildDoorBatches(scene) {
+  const byMat = new Map();
+  for (const l of leafQueue) {
+    if (!byMat.has(l.mat)) byMat.set(l.mat, []);
+    byMat.get(l.mat).push(l);
+  }
+  let batches = 0, leaves = 0;
+  for (const [mat, list] of byMat) {
+    const geos = new Map();
+    for (const l of list) if (!geos.has(l.key)) geos.set(l.key, l.geometry);
+    let verts = 0;
+    for (const g of geos.values()) verts += g.attributes.position.count;
+    try {
+      const bm = new THREE.BatchedMesh(list.length, verts, 0, mat);   // 0 indices: bake() hands us non-indexed
+      const ids = new Map();
+      for (const [k, g] of geos) ids.set(k, bm.addGeometry(g));
+      for (const l of list) {
+        const iid = bm.addInstance(ids.get(l.key));
+        bm.setMatrixAt(iid, l.part.rest);
+        l.part.batch = bm; l.part.iid = iid;
+      }
+      bm.castShadow = true; bm.receiveShadow = true;
+      bm.name = `doors:${batches}`;
+      bm.userData.noBVH = true;      // they MOVE — collision must never freeze them into the BVH
+      scene.add(bm);
+    } catch (e) {
+      // A doorless county is a worse bug than a slow one: fall back to a Mesh per leaf.
+      console.warn('[doors] batching failed — falling back to one mesh per leaf', e);
+      for (const l of list) {
+        const mesh = new THREE.Mesh(l.geometry, mat);
+        mesh.castShadow = true; mesh.receiveShadow = true;
+        mesh.name = `door:${l.key}`;
+        mesh.userData.noBVH = true;
+        mesh.matrixAutoUpdate = false;
+        mesh.matrix.copy(l.part.rest);
+        mesh.updateMatrixWorld(true);
+        scene.add(mesh);
+        l.part.mesh = mesh;
+      }
+    }
+    leaves += list.length;
+    batches++;
+  }
+  leafQueue.length = 0;
+  return { batches, leaves };
+}
+
+// ── the shut-door slabs, bucketed into an 8 m grid (one Map lookup inside collide()) ──
+const DOOR_CELL = 8;
+const _doorGrid = new Map();
+const _noDoors = [];
+const cellOf = (x, z) => (Math.floor(x / DOOR_CELL) + 2048) * 4096 + (Math.floor(z / DOOR_CELL) + 2048);
+export function indexDoors() {
+  _doorGrid.clear();
+  for (const c of doorColliders) {
+    const r = Math.hypot(c.hx, c.hz) + 1.2;                // slab half-diagonal + the fattest body radius
+    for (let gx = Math.floor((c.x - r) / DOOR_CELL); gx <= Math.floor((c.x + r) / DOOR_CELL); gx++) {
+      for (let gz = Math.floor((c.z - r) / DOOR_CELL); gz <= Math.floor((c.z + r) / DOOR_CELL); gz++) {
+        const k = (gx + 2048) * 4096 + (gz + 2048);
+        let a = _doorGrid.get(k);
+        if (!a) _doorGrid.set(k, a = []);
+        a.push(c);
+      }
+    }
+  }
+  return doorColliders.length;
+}
+export const doorsAt = (x, z) => _doorGrid.get(cellOf(x, z)) ?? _noDoors;
+
+// ── the swing ─────────────────────────────────────────────────────────────────────────
+const _m4 = new THREE.Matrix4();
+const _ry4 = new THREE.Matrix4();
+export function updateDoors(dt) {
+  for (const d of doors) {
+    const want = d.open ? 1 : 0;
+    if (d.t === want) continue;                            // at rest: 130 float compares, and nothing else
+    d.t = Math.max(0, Math.min(1, d.t + Math.sign(want - d.t) * (dt / DOOR_SECS)));
+    const e = d.t * d.t * (3 - 2 * d.t);
+    // `sign` is which side the opener stood on; a door swings AWAY from that side. The
+    // saloon batwings are double-acting (no jamb) so they go the same way, thrown wider.
+    const a = -(d.bat ? BAT_OPEN : DOOR_OPEN) * d.sign * e;
+    for (const p of d.parts) {
+      _m4.copy(p.rest).multiply(_ry4.makeRotationY(p.dir * a));
+      if (p.batch) p.batch.setMatrixAt(p.iid, _m4);
+      else if (p.mesh) { p.mesh.matrix.copy(_m4); p.mesh.matrixWorldNeedsUpdate = true; }
+    }
+  }
+}
+
+// Toggle a door. Wired to the game's E-interactable; safe for anything else to call.
+export function toggleDoor(d, fromX, fromZ) {
+  d.open = !d.open;
+  if (d.open) {
+    // which side of the opening the opener is standing on (recomputed per toggle)
+    d.sign = Math.sign((fromX - d.x) * d.nx + (fromZ - d.z) * d.nz) || 1;
+    d.col.hx = 0;            // hx<=0 IS the "off" switch in collide — the opening is a hole
+  } else {
+    d.col.hx = d.colHx;      // shut: the slab is solid again
+  }
+  return d.open;
+}
+
+
+// ═══ THE KIT CONTRACT (world splits 5b) — the game-content knobs the stamper machinery
+// reads: naming regexes for the publisher's kit, the hinge-hardware table, asset dirs and
+// atlases. A game registers once (setKitContent in its town module); the machinery below
+// never hardcodes a file name.
+let KC = {
+  doorRe: /Door/i,                 // leaves pulled OUT of the weld onto hinges
+  shellRe: null,                   // …except these: shells that don't render from inside stay welded
+  paneRe: /_Window(?=_\d+$)|_Glass$/i,   // glass welded back ONTO its leaf
+  batRe: /Swinging/i,              // double-acting pairs (no jamb, thrown wide)
+  hingeHw: {},                     // file-local hinge direction per leaf name, measured off the meshes
+  shellBody: null,                 // kit pieces that enclose a ROOM (get an interior box)
+  fencePanel: null,                // props that lay a low jumpable capsule along their +X span
+  dirs: {}, defaultDir: null,      // asset dirs by layout keyword
+  atlases: {},                     // atlas per dir keyword
+  texOverrides: [],                // [{ re, tex }] file-name texture overrides (signboards)
+  materialParams: { roughness: 0.9, metalness: 0 },
+  // ── 5c: the area stamper's knobs ──
+  heightAt: () => 0,               // the game's terrain — every seat/snap/drop test reads it
+  groundOff: 0.45,                 // the pack's floor plane above the demo's dirt (see buildingLift)
+  snap: 0.30,                      // landing within this of the dirt IS a ground prop
+  bed: 0.22,                       // how deep a skirt/foundation beds below the dirt
+  noCollide: /$^/,                 // scatter named Deco — excluded from the collision BVH
+  propDelete: new Set(),           // per-position ledger: demo junk flagged for the bin
+  propGround: new Set(),           // per-position ledger: explicit flat-on-the-dirt
+  airborneOk: /$^/,                // authored height is deliberate (hangs, leans, is held)
+  areaGroundOnly: /$^/,            // wheels ride the dirt (floor-datum areas only)
+  pathRe: /$^/,                    // raised path pieces culled when no landform bears them
+  // ── 5d: the town stamper's content (one authored settlement the game calls home) ──
+  roadDistance: () => Infinity,    // the game's road field — building nudge guard-rail
+  town: null,                      // { layout, pieces, dressing, fenceRuns, extras, map, mapAnchor,
+                                   //   buildingTex(b, pieces)?, softShell?, airborneOk, groundOnly, outdoorOnly }
+};
+export function setKitContent(c = {}) { Object.assign(KC, c); }
+export const kitContent = () => KC;
+
+const doorSplit = (name) => KC.doorRe.test(name) && !(KC.shellRe && KC.shellRe.test(name));
+export const resolveDir = (e) => KC.dirs[e.dir] ?? KC.dirs[KC.defaultDir];
+export const resolveTex = (e) => e.tex ?? (KC.texOverrides.find((o) => o.re.test(e.f ?? ''))?.tex ?? KC.atlases[e.dir] ?? KC.atlases[KC.defaultDir]);
+
+// A fence panel placed as a prop still has to push back: name-excluded from the BVH, it
+// gets one low jumpable capsule along the panel's local +X span instead.
+export function addFenceCapsule(f, mat, r) {
+  if (!KC.fencePanel || !KC.fencePanel.test(f)) return;
+  const e = mat.elements, ax = e[0], az = e[2], al = Math.hypot(ax, az) || 1;
+  const half = Math.max(1.2, r ?? 1.6), cx = e[12], cz = e[14];
+  colliders.push({ x1: cx - (ax / al) * half, z1: cz - (az / al) * half, x2: cx + (ax / al) * half, z2: cz + (az / al) * half, r: 0.3, low: true });
+}
+
+// WHICH STILE HANGS: the registered hardware table first; otherwise the stile FARTHEST
+// from the kit piece's own origin (the outer one — mirrored fronts open away from each other).
+function hingeHint(name, geo) {
+  const hw = KC.hingeHw[name];
+  if (hw) return hw;
+  geo.computeBoundingBox();
+  const b = geo.boundingBox;
+  const wide = (b.max.x - b.min.x) >= (b.max.z - b.min.z);
+  const lo = wide ? b.min.x : b.min.z, hi = wide ? b.max.x : b.max.z;
+  const s = Math.abs(lo) > Math.abs(hi) ? -1 : 1;                 // which end is farther out
+  return wide ? [s, 0] : [0, s];
+}
+
+// ── geometry: one merged geometry per DISTINCT building, shared by its tiled copies ──
+const _geoCache = new Map();
+const _mat = new Map();
+
+// Merge a whole building's kit pieces into ONE geometry in building-local space. Door
+// leaves are pulled OUT of the weld (doorSplit) onto hinge pivots; panes weld back onto
+// their leaf; mirrored (negative-determinant) pieces get their winding fixed by bake();
+// shellBody pieces record their interior box so props can be claimed by the right room.
+export async function buildingGeometry(id, pieces) {
+  const key = pieces.map((p) => `${p.dir}/${p.f}:${p.m.join(',')}`).join('|');
+  let entry = _geoCache.get(key);
+  if (entry !== undefined) return entry;
+  const m = new THREE.Matrix4();
+  const parts = [];
+  const interiors = []; // building-local XZ boxes of the SHELL pieces — the rooms, wall to wall
+  const leaves = [];   // { name, geometry, hint } in BUILDING-LOCAL space
+  for (const p of pieces) {
+    try {
+      const master = await loadModel(`${resolveDir(p)}/${p.f}.fbx`, { texture: resolveTex(p) });
+      const flat = flattenToGeometry(master, { split: doorSplit });
+      if (!flat) continue;
+      const pm = m.fromArray(p.m);
+      const mine = [], panes = [];
+      for (const d of flat.parts ?? []) {
+        const pane = KC.paneRe.test(d.name);
+        const hint = pane ? null : hingeHint(d.name, d.geometry);   // read the hardware FILE-local
+        const g = bake(d.geometry, pm);
+        if (g.attributes.color) g.deleteAttribute('color');
+        if (pane) panes.push({ owner: d.name.replace(KC.paneRe, ''), geometry: g });
+        else mine.push({ name: d.name, geometry: g, hint: new THREE.Vector3(hint[0], 0, hint[1]).transformDirection(pm) });
+      }
+      for (const pane of panes) {
+        const leaf = mine.find((l) => l.name === pane.owner);
+        if (leaf) leaf.glass = pane.geometry;
+        else parts.push(pane.geometry);                            // a pane with no leaf: weld it back
+      }
+      for (const l of mine) {
+        if (l.glass) l.geometry = BufferGeometryUtils.mergeGeometries([l.geometry, l.glass], false);
+        leaves.push(l);
+      }
+      const g = bake(flat.geometry, pm);
+      // cross-file merge: attribute sets and index state must match, so normalise both
+      if (g.attributes.color) g.deleteAttribute('color');
+      if (KC.shellBody && KC.shellBody.test(p.f)) {
+        g.computeBoundingBox();
+        const b = g.boundingBox;
+        interiors.push({ x0: b.min.x, z0: b.min.z, x1: b.max.x, z1: b.max.z });
+      }
+      parts.push(g);
+    } catch (e) { console.warn(`[town] piece ${id}/${p.f} failed`, e); }
+  }
+  const geo = parts.length ? BufferGeometryUtils.mergeGeometries(parts, false) : null;
+  if (geo) geo.computeBoundingSphere();
+  entry = { geo, key, doorways: clusterDoorways(leaves), interiors };
+  _geoCache.set(key, entry);
+  return entry;
+}
+
+// ONE DOORWAY PER GROUP OF LEAVES: two leaves share a doorway when they stand side by
+// side (centres closer than their half widths + 0.35 m of jamb) AND their heights overlap.
+function clusterDoorways(leaves) {
+  if (!leaves.length) return [];
+  const info = leaves.map((l) => {
+    const box = new THREE.Box3().setFromBufferAttribute(l.geometry.attributes.position);
+    // hypot of the horizontal extents, not the wider one: chamfered-corner doors hang at 45°
+    return { l, box, c: box.getCenter(new THREE.Vector3()), w: Math.hypot(box.max.x - box.min.x, box.max.z - box.min.z) };
+  });
+  const up = info.map((_, i) => i);
+  const find = (i) => (up[i] === i ? i : (up[i] = find(up[i])));
+  for (let i = 0; i < info.length; i++) {
+    for (let j = i + 1; j < info.length; j++) {
+      const a = info[i], b = info[j];
+      if (a.box.min.y > b.box.max.y - 0.1 || b.box.min.y > a.box.max.y - 0.1) continue;
+      if (Math.hypot(a.c.x - b.c.x, a.c.z - b.c.z) > (a.w + b.w) / 2 + 0.35) continue;
+      up[find(i)] = find(j);
+    }
+  }
+  const groups = new Map();
+  info.forEach((v, i) => {
+    const r = find(i);
+    if (!groups.has(r)) groups.set(r, []);
+    groups.get(r).push(v);
+  });
+  return [...groups.values()].map(doorway);
+}
+
+// One doorway, in BUILDING-LOCAL space. Cached with the merged geometry, so every tiled
+// copy of a plot shares these leaf geometries — which lets them share one batch.
+function doorway(g) {
+  const single = g.length === 1;
+  const mid = new THREE.Vector3();
+  for (const i of g) mid.add(i.c);
+  mid.divideScalar(g.length);
+  // The SPAN is the line the leaves hang along — not axis-aligned in general.
+  let sx, sz;
+  if (single) { sx = g[0].l.hint.x; sz = g[0].l.hint.z; }
+  else { sx = g[g.length - 1].c.x - g[0].c.x; sz = g[g.length - 1].c.z - g[0].c.z; }
+  const sl = Math.hypot(sx, sz) || 1;
+  sx /= sl; sz /= sl;
+  const leaves = [];
+  let halfSpan = 0, y0 = Infinity, y1 = -Infinity;
+  for (const i of g) {
+    const b = i.box;
+    y0 = Math.min(y0, b.min.y); y1 = Math.max(y1, b.max.y);
+    // A PAIR hinges on its OUTER stiles; a SINGLE on the end its hardware points at.
+    let bestS = -Infinity, bestAbs = -1;
+    for (const cx of [b.min.x, b.max.x]) {
+      for (const cz of [b.min.z, b.max.z]) {
+        const s = (cx - mid.x) * sx + (cz - mid.z) * sz;
+        if (single ? s > bestS : Math.abs(s) > bestAbs) { bestS = s; bestAbs = Math.abs(s); }
+      }
+    }
+    // keep the hinge ON the span line through the leaf's centre
+    const perp = (i.c.x - mid.x) * -sz + (i.c.z - mid.z) * sx;
+    const hx = mid.x + sx * bestS + -sz * perp;
+    const hz = mid.z + sz * bestS + sx * perp;
+    halfSpan = Math.max(halfSpan, Math.abs(bestS));
+    leaves.push({
+      name: i.l.name,
+      geometry: i.l.geometry.clone().translate(-hx, 0, -hz),   // hinge-local: the frame the batch instances
+      hx, hz,
+      dir: Math.sign(bestS) || 1,                              // which side of the opening it hangs on
+    });
+  }
+  return { leaves, mid, sx, sz, halfSpan, y0, y1, bat: g.some((i) => KC.batRe.test(i.l.name)) };
+}
+
+// Stand this building's doorways up in the world: leaves become instances in a shared
+// batch, each carrying its own REST matrix; the doorway gets its switchable slab collider.
+export function makeDoors(bldMesh, doorways, floorY, mat, key) {
+  bldMesh.updateWorldMatrix(true, false);
+  const ry = bldMesh.rotation.y;
+  const cr = Math.cos(ry), sr = Math.sin(ry);
+  const out = [];
+  for (let k = 0; k < doorways.length; k++) {
+    const d = doorways[k];
+    const world = bldMesh.localToWorld(new THREE.Vector3(d.mid.x, 0, d.mid.z));
+    const wsx = d.sx * cr + d.sz * sr;                      // span, rotated into world
+    const wsz = -d.sx * sr + d.sz * cr;
+    const col = {
+      x: world.x, z: world.z,
+      cs: wsx, sn: -wsz,                                    // collide's box: +x axis is (cs, -sn)
+      hx: Math.max(d.halfSpan, 0.6), hz: 0.18,              // a thin slab across the opening
+      y0: floorY + d.y0, y1: floorY + d.y1,                 // THE LEAF'S OWN BAND (upstairs doors)
+    };
+    doorColliders.push(col);
+    const parts = [];
+    for (let i = 0; i < d.leaves.length; i++) {
+      const l = d.leaves[i];
+      const h = bldMesh.localToWorld(new THREE.Vector3(l.hx, 0, l.hz));
+      const rest = new THREE.Matrix4().makeRotationY(ry).setPosition(h.x, h.y, h.z);
+      const part = { rest, dir: l.dir, batch: null, iid: -1, mesh: null };
+      parts.push(part);
+      // key by the GEOMETRY CACHE entry, so all copies of a plot share one leaf geometry
+      leafQueue.push({ key: `${key}#${k}.${i}`, geometry: l.geometry, mat, part });
+    }
+    out.push({
+      x: world.x, z: world.z, y: floorY + d.y0, y0: floorY + d.y0, y1: floorY + d.y1,
+      nx: -wsz, nz: wsx,                                    // doorway normal = perpendicular to the span
+      bat: d.bat,
+      parts, col, colHx: col.hx, open: false, t: 0, sign: 1,
+    });
+  }
+  return out;
+}
+
+// ONE material per (atlas, uv-flip) for the whole town — a new material is a new WebGPU
+// pipeline. The flip must match the RESOLVED master format (GLB twins: flipY false).
+export async function townMaterial(texUrl, url) {
+  const isGLB = /\.glb$/i.test(await resolveModelUrl(url, { texture: texUrl }));
+  const key = `${texUrl}|${isGLB}`;
+  if (!_mat.has(key)) {
+    const tex = await loadTexture(texUrl, isGLB ? { flipY: false } : {});
+    const tm = new THREE.MeshStandardNodeMaterial({ map: tex, ...KC.materialParams });
+    tm.emissiveNode = lampLight(texture(tex, uv()).rgb);   // real lamp light on the shell + its props
+    _mat.set(key, tm);
+  }
+  return _mat.get(key);
+}
+
+// One integer-metre key per prop position — the ledgers (KC.propDelete / KC.propGround)
+// are keyed on it.
+export const propKey = (x, z) => `${Math.round(x)},${Math.round(z)}`;
+
+// ── THE GROUND DATUM ─────────────────────────────────────────────────────────────────────────
+// A kit is authored with the building FLOOR at local y = 0 and the GROUND below it (Synty:
+// ≈ 0.45 m — foundation skirts to −0.667, porch posts to −0.567, deck steps placed at −0.447
+// so the dirt meets the bottom step). Seating local 0 on the terrain buries the whole town.
+// So: LIFT each building onto its ground plane. KC.groundOff is that datum, and each building
+// derives its own lift from its REAL merged geometry (a well/outhouse/water tower has no
+// skirt: min.y ≈ 0, so it must NOT rise, or it floats).
+export const buildingLift = (geo) => {
+  geo.computeBoundingBox();
+  const lo = geo.boundingBox?.min.y ?? 0;                     // lowest point in building-local space
+  // Seat the geometry bottom KC.bed metres into the dirt, but never raise the floor more than
+  // KC.groundOff (deep foundation skirts would otherwise lift the boardwalk out of reach of its
+  // steps). CAN go negative: a building authored floating above its plot origin must be PULLED
+  // DOWN onto the ground — a `max(0, …)` here left one hanging in the air.
+  return Math.min(KC.groundOff, -lo - KC.bed);
+};
+
+// THE AREA STAMPER (world splits 5c) — stamps one authored AREA (pieces/buildings/props/fences,
+// matrices in metres, area-local) into the world at `at` {x, z, ry, skip?}. The same pipeline
+// the town uses: merged building geometry via buildingGeometry, doors on hinges, instanced
+// prop batches, fence capsules, ladders. Returns { lampPositions } for the game's lamp field.
+export async function buildArea(scene, area, at) {
+  const cos = Math.cos(at.ry ?? 0), sin = Math.sin(at.ry ?? 0);
+  const toWorld = (lx, lz) => [at.x + lx * cos + lz * sin, at.z - lx * sin + lz * cos];
+  const R = new THREE.Matrix4().makeRotationY(at.ry ?? 0);
+  const lampPositions = [];
+  const floors = [];
+  let built = 0;
+
+  for (const b of area.buildings ?? []) {
+    const pieces = area.pieces?.[b.id] ?? [];
+    if (!pieces.length) { console.warn(`[outpost] no pieces for ${area.id}/${b.id}`); continue; }
+    const { geo, key, doorways } = await buildingGeometry(`${area.id}:${b.id}`, pieces);
+    if (!geo) continue;
+    const [bx, bz] = toWorld(b.x, b.z);
+    let y = KC.heightAt(bx, bz);
+    const r = (b.collider ?? 6) * 0.7;
+    for (const [dx, dz] of [[r, 0], [-r, 0], [0, r], [0, -r]]) y = Math.min(y, KC.heightAt(bx + dx, bz + dz));
+    y = Math.max(y, KC.heightAt(bx, bz) - 0.8);
+
+    const mat = await townMaterial(resolveTex(pieces[0]), `${resolveDir(pieces[0])}/${pieces[0].f}.fbx`);
+    const mesh = new THREE.Mesh(geo, mat);
+    const floorY = y + buildingLift(geo);
+    mesh.position.set(bx, floorY, bz);
+    mesh.rotation.y = (b.ry ?? 0) + (at.ry ?? 0);
+    mesh.castShadow = true; mesh.receiveShadow = true;
+    mesh.name = `bld:${area.id}_${b.id}`;
+    scene.add(mesh);
+    buildingObjects.push(mesh);
+    geo.computeBoundingBox();                       // the REAL box, not a circle — see the town builder
+    const bb = geo.boundingBox;
+    floors.push({
+      x: bx, z: bz, y: floorY, ry: (b.ry ?? 0) + (at.ry ?? 0),
+      hx: Math.max(bb.max.x, -bb.min.x) + 0.4,
+      hz: Math.max(bb.max.z, -bb.min.z) + 0.4,
+    });
+    for (const d of makeDoors(mesh, doorways, floorY, mat, key)) {
+      d.name = b.name ?? area.name;
+      doors.push(d);
+    }
+    built++;
+  }
+
+  for (const f of area.fences ?? []) {
+    const [x1, z1] = toWorld(f.x1, f.z1);
+    const [x2, z2] = toWorld(f.x2, f.z2);
+    colliders.push({ x1, z1, x2, z2, r: 0.35, low: true });
+  }
+
+  const S = new THREE.Matrix4().makeScale(-1, 1, 1);
+  const byFile = new Map();
+  const floorUnder = (x, z) => {     // world → building-local is the INVERSE rotation — see the town builder
+    for (const f of floors) {
+      const dx = x - f.x, dz = z - f.z;
+      const c = Math.cos(f.ry), sn = Math.sin(f.ry);
+      const lx = c * dx - sn * dz, lz = sn * dx + c * dz;
+      if (Math.abs(lx) < f.hx && Math.abs(lz) < f.hz) return f.y;
+    }
+    return null;
+  };
+  // A HAND TOOL'S ORIGIN IS ITS GRIP, NOT ITS FOOT — the class of prop KC.airborneOk names.
+  // (Measured off Synty farm GLBs: a rake spans y −1.365…+0.029 — authored to be HELD, so the
+  // whole tool hangs below its origin. Planted as a ground prop it is buried to the last
+  // centimetre of its handle; lifted to seat its head on the dirt it asks for dy ≈ 1.3, which
+  // the drop rule slams straight back down. KC.airborneOk is exactly the declaration this
+  // needs: the authored height is deliberate.)
+
+  // ── WHOSE ZERO IS IT? THE LAYOUT DECLARES ITS DATUM ────────────────────────────────────────
+  // default        → m[13] is height above the pack's floor plane, which sits KC.groundOff
+  //                  above the dirt. Lift it, snap it, seat it. Hand-authored areas are written
+  //                  to this contract.
+  //   datum 'ground' → m[13] IS the height above the dirt. No lift, and no floor conversion
+  //                  either: a pot on a windowsill is already authored at windowsill height.
+  //                  (A parser that re-datums every matrix onto the area's own ground authors a
+  //                  chair in the dirt at m[13] ≈ 0; add the lift and it stands KC.groundOff up —
+  //                  too far to snap, not far enough to be dropped. It lands DEAD IN THE BAND
+  //                  and floats. Measured: 130 props off the ground across four areas, one dead-
+  //                  uniform constant added where it didn't belong.)
+  const groundDatum = area.datum === 'ground';
+  const LIFT = groundDatum ? 0 : KC.groundOff;
+
+  // ── THE DROP RULE IS FOR DRESSING, NOT FOR LANDFORM ────────────────────────────────────────
+  // A prop authored 2 m up with nothing under it is a mistake — in the source demo it stood on
+  // scenery we do not ship — so we drop it on the dirt. A PIT WALL authored 8 m up is not a
+  // mistake: it is the pit. Running the drop rule over a self-supporting 3D set piece makes A
+  // PANCAKE (measured: 218 of 293 pieces slammed flat, the worst falling 13.89 m — a quarry
+  // with no hole in it).
+  //
+  // WHICH PIECES ARE THE GROUND IS THE LAYOUT'S BUSINESS, NOT A REGEX'S. The layout marks them
+  // (`land: 1`): the pack's own rock and pit geometry. Two consequences, and they are the whole fix:
+  //   * landform KEEPS ITS AUTHORED HEIGHT — never snapped, never dropped, never seated on a floor.
+  //     It is the ground; there is nothing to seat it on.
+  //   * landform BEARS WEIGHT — it is what `overLandform` looks for, so a barrel on a bench or a
+  //     rail on a trestle is SUPPORTED and keeps its height too, instead of raining onto the pad.
+  // Everything else — tunnels, tramway, works, planks, dressing — stands on it and is judged by
+  // that support test, which is why none of them needs a flag of its own.
+  const land = (area.props ?? []).filter((q) => q.land);
+  // Each landform piece covers a disc of radius `r` (its real footprint, from the extractor —
+  // not a guess) and holds up anything within 6 m above it.
+  const overLandform = (p) => land.some((q) => {
+    const dx = p.m[12] - q.m[12], dz = p.m[14] - q.m[14];
+    return dx * dx + dz * dz < Math.pow((q.r ?? 2) + 1.5, 2) && q.m[13] + 0.5 >= p.m[13] - 6;
+  });
+  let cut = 0;
+  const ladderInst = [];   // /Ladder/i props in this area → climbable records after the loop (appended to the town's set)
+  for (const p of area.props ?? []) {
+    if (at.skip?.(p)) continue;                                    // pieces that needed the demo's own scenery
+    // A PATH WITH NOTHING UNDER IT IS NOT A PATH. Where the landform ends, the demo's ground
+    // carried on and ours does not — a raised path piece (KC.pathRe) survives only if landform
+    // actually sits beneath it. The ones that survive stay UP ON IT, which is what a tramway is.
+    // A cart on the ground beats a cart hanging over a deleted trestle.
+    if (KC.pathRe.test(p.f) && p.m[13] > 1.0 && !overLandform(p)) { cut++; continue; }
+    const m = new THREE.Matrix4().fromArray(p.m).premultiply(R);   // area-local → world heading
+    const [px, pz] = toWorld(p.m[12], p.m[14]);
+    if (KC.propDelete.has(propKey(px, pz))) continue;
+    m.elements[12] = px; m.elements[14] = pz;
+    const g = KC.heightAt(px, pz);
+    if (p.land) {
+      m.elements[13] = g + p.m[13];      // THE GROUND ITSELF: exactly as authored, and that is all
+    } else {
+      let dy = p.m[13] + LIFT;
+      // "WHEELS RIDE THE DIRT" IS A FLOOR-DATUM RULE. It exists because a building's floor box
+      // reaches out past its walls, and a coach drawn up against a wall got lifted onto the
+      // floorboards. Under a ground datum nothing is ever lifted onto a floor, so the rule has
+      // no work to do — and it did harm: ore carts authored ON THE TRESTLE got dragged off it
+      // into the dirt. (Every other wheeled prop measured sat within 7 cm of the ground, so
+      // they snap to it anyway.)
+      const ground = Math.abs(dy) < KC.snap || (!groundDatum && KC.areaGroundOnly.test(p.f));
+      if (ground) dy = 0;
+      // Same rule as the town: only low porch dressing rides a floor; a prop authored high sat
+      // on scenery we don't ship and drops to the dirt.
+      // ...UNLESS THE AREA SAYS ITS FLOORS ARE TALL. A station platform's deck is 0.878 above
+      // the building origin, and every bench/barrel/lamp on it is authored at that height
+      // EXPECTING the floor conversion — a 0.5 cutoff sends the whole platform's dressing to
+      // the dirt underneath (an empty deck over a furnished crawlspace). `floorSeat` is the
+      // area's own declared ceiling for floor-seated dressing; areas that don't declare one
+      // keep the old rule.
+      const floor = (ground || p.m[13] > (area.floorSeat ?? 0.5)) ? null : floorUnder(px, pz);
+      // Is there ANYTHING under this — a building, or the landform it was set down on?
+      const supported = floor !== null || overLandform(p);
+      // On a ground-datum layout the floor test no longer CONVERTS anything (dy is already the
+      // true height above the dirt) — it survives as a VETO on the drop rule: there IS something
+      // under this, so leave it where the artist put it.
+      if (floor !== null && !groundDatum) m.elements[13] = floor + p.m[13];
+      else m.elements[13] = (dy > 0.5 && !supported && !KC.airborneOk.test(p.f)) ? g : dy + g;   // nothing under it → the dirt
+    }
+    if (KC.propGround.has(propKey(px, pz))) m.elements[13] = g;   // explicit: flat on the dirt
+    if (/Ladder/i.test(p.f)) ladderInst.push({ m: m.clone(), file: p.f, dir: resolveDir(p) });   // climbable — gathered BEFORE the mirror-flip below (a flipped basis would corrupt the climb quat)
+    const url = `${resolveDir(p)}/${p.f}`;
+    const mirrored = det3(m.elements) < 0;
+    if (mirrored) m.multiply(S);
+    const key = `${url}|${mirrored}`;
+    if (!byFile.has(key)) byFile.set(key, { url, tex: resolveTex(p), mirrored, mats: [] });
+    byFile.get(key).mats.push(m);
+    addFenceCapsule(p.f, m, p.r);
+    if (/Lantern|Campfire|Torch/i.test(p.f)) lampPositions.push({ x: px, y: m.elements[13] + 1.1, z: pz, ground: KC.heightAt(px, pz) });
+  }
+
+  for (const { url, tex, mirrored, mats } of byFile.values()) {
+    try {
+      const master = await loadModel(`${url}.fbx`, { texture: tex });
+      const flat = flattenToGeometry(master);
+      if (!flat) continue;
+      const geo = mirrored ? bake(flat.geometry, S) : flat.geometry;
+      const mesh = new THREE.InstancedMesh(geo, await townMaterial(tex, `${url}.fbx`), mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = mats.length < 4;
+      mesh.receiveShadow = true;
+      const file = url.split('/').pop();
+      mesh.name = `${KC.noCollide.test(file) ? 'scatterDeco' : 'scatter'}:${file}.fbx`;
+      mesh.matrixAutoUpdate = false; mesh.updateMatrix();
+      scene.add(mesh);
+    } catch (e) { console.warn(`[outpost] prop batch ${url} failed`, e); }
+  }
+  ladders.push(...await buildLadders(ladderInst));   // APPEND (the town builder already reset + filled the town's; areas add to them)
+  console.log(`[outpost] ${area.name}: ${built} buildings, ${(area.props ?? []).length} props, ${ladderInst.length} ladder(s) at (${at.x}, ${at.z})`);
+  return { lampPositions };
+}
+
+// THE TOWN STAMPER (world splits 5d) — stamps the game's authored settlement (KC.town):
+// merged buildings on the road-clearance guard-rail, fence capsule runs, the full prop
+// seating law (interior floors → snap band → floor claim → drop rule), the EXTRAS hand
+// list, and the editable town-centre map. Returns { lampPositions, doors, ladders }.
+export async function buildTown(scene) {
+  const T = KC.town;
+  if (!T) { console.warn('[town] no KC.town registered — nothing to stamp'); return { lampPositions: [], doors, ladders }; }
+  const lampPositions = [];
+  // Every building's FLOOR PLANE, for grounding its dressing (see the props loop): a building
+  // is seated ONCE at its centre's terrain height, but each prop used to be seated on the
+  // terrain under ITSELF — so on any slope the furniture drifted off the floor it stands on
+  // (the saloon's till floated 0.27m over the bar). Interior props ride the building instead.
+  const floors = [];   // { x, z, r2, y }
+
+  // ---- buildings ---------------------------------------------------------------
+  for (const b of T.layout) {
+    const pieces = T.pieces[b.id] ?? [];
+    if (!pieces.length) { console.warn(`[town] no pieces for ${b.id}`); continue; }
+    const { geo, key, doorways, interiors } = await buildingGeometry(b.id, pieces);
+    if (!geo) continue;
+
+    // Shove any building whose footprint straddles a road off the carriageway, along the
+    // road-distance gradient. A generator that guarantees every building clears
+    // KC.roadDistance by collider+2.5m never fires this — it stays as the guard-rail for
+    // hand edits.
+    let bx = b.x, bz = b.z;
+    const clearance = (b.collider ?? 7) + 2.5;
+    for (let i = 0; i < 6 && KC.roadDistance(bx, bz) < clearance; i++) {
+      const d = KC.roadDistance(bx, bz);
+      let gx = KC.roadDistance(bx + 0.5, bz) - KC.roadDistance(bx - 0.5, bz);
+      let gz = KC.roadDistance(bx, bz + 0.5) - KC.roadDistance(bx, bz - 0.5);
+      let gl = Math.hypot(gx, gz);
+      if (gl < 0.05) { gx = bx || 1; gz = bz || 1; gl = Math.hypot(gx, gz) || 1; } // dead on centreline → push radially out
+      const step = Math.max(1, clearance - d);
+      bx += (gx / gl) * step; bz += (gz / gl) * step;
+      if (i === 0) console.warn(`[town] nudging ${b.name} off the road (${d.toFixed(1)}m < ${clearance.toFixed(1)}m)`);
+    }
+    // seat on the LOWEST ground point under the footprint, never floating — but never
+    // more than 0.8m below the centre either (a sample in a hollow would bury
+    // the whole building; the "black slabs")
+    let y = KC.heightAt(bx, bz);
+    const r = (b.collider ?? 6) * 0.7;
+    for (const [dx, dz] of [[r, 0], [-r, 0], [0, r], [0, -r], [r * 0.7, r * 0.7], [-r * 0.7, -r * 0.7]]) {
+      y = Math.min(y, KC.heightAt(bx + dx, bz + dz));
+    }
+    y = Math.max(y, KC.heightAt(bx, bz) - 0.8);
+
+    // each plot draws its own paint (recolour atlases etc.) through the game's hook
+    const tex = T.buildingTex ? T.buildingTex(b, pieces) : resolveTex(pieces[0]);
+    const mat = await townMaterial(tex, `${resolveDir(pieces[0])}/${pieces[0].f}.fbx`);
+    const mesh = new THREE.Mesh(geo, mat);
+    // sit the building on its own ground plane (see KC.groundOff): the floor/boardwalk rides
+    // proud of the street, its skirt beds into the dirt, and the deck steps land on the street
+    const floorY = y + buildingLift(geo);
+    mesh.position.set(bx, floorY, bz);
+    mesh.rotation.y = b.ry;
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    mesh.name = `bld:${b.id}`;
+    scene.add(mesh);
+    // A TENT DOES NOT STOP A MAN, AND ITS PEG CERTAINLY DOESN'T. A soft shell's guy-ropes and
+    // pegs are part of the one welded mesh, so putting it in the collision BVH snags the player
+    // at ankle height — you walk into a tent and get stuck on the rope on the way out. It is
+    // soft canvas: walk through it. (KC.town.softShell names them; a teepee's hide is stiffer
+    // and its poles are a real obstacle, so those keep their collision.)
+    const noCollide = T.softShell && pieces.some((pc) => T.softShell.test(pc.f));
+    if (!noCollide) buildingObjects.push(mesh); // collision is the capsule-vs-BVH sweep, not a 2D shape
+    // building-local y=0 IS the floor plane — that is the datum its dressing must stand on.
+    // FOOTPRINT = THE BUILDING'S REAL BOX, not a circle round its centre. `collider` is a
+    // road-clearance radius, and it is far smaller than the building: a circle that size
+    // leaves every CORNER of every interior outside it, so the furniture standing there got
+    // seated on the terrain instead of on the floorboards — and floated (or sank) by the
+    // ground's slope. Take the box from the merged geometry, which is the actual thing we
+    // just built.
+    geo.computeBoundingBox();
+    const bb = geo.boundingBox;
+    floors.push({
+      x: bx, z: bz, y: floorY, ry: b.ry ?? 0,
+      hx: Math.max(bb.max.x, -bb.min.x) + 0.4,     // half-extents in BUILDING-LOCAL space
+      hz: Math.max(bb.max.z, -bb.min.z) + 0.4,
+      interiors,                                   // the SHELL pieces' own boxes — the rooms
+    });
+    for (const d of makeDoors(mesh, doorways, floorY, mat, key)) {
+      d.name = b.name;
+      doors.push(d);
+    }
+  }
+
+  // ---- fences: capsules, because the BVH won't take them -------------------------
+  // world.build EXCLUDEs /fence/ meshes from the mesh BVH (they must stay jumpable), so
+  // fence panels get one low capsule each — endpoints derived from each panel's real box.
+  for (const r of T.fenceRuns ?? []) colliders.push({ ...r, r: 0.35, low: true });
+
+  // ---- props: ONE InstancedMesh per file, full per-instance matrices --------------
+  // The layout's matrices carry rotation AND scale AND tilt (a leaning barrel, a tipped
+  // cart), which an x/y/z/ry-only scatter path cannot express — so props are stamped
+  // as instanced batches. Stored m[13] is height ABOVE GROUND; heightAt adds the terrain.
+  // A MIRRORED instance can't share a batch: winding is per draw call, not per instance. So a
+  // file with mirrored placements gets a SECOND batch built from a pre-mirrored geometry
+  // (X negated, winding flipped) with the mirror factored out of each instance matrix:
+  //   M = M' · S, S = diag(-1,1,1)  ⇒  M'·(S·v) = M·v exactly, and det(M') > 0.
+  const S = new THREE.Matrix4().makeScale(-1, 1, 1);
+  const byFile = new Map(); // `${dir}/${f}|mirror` -> { url, tex, mirrored, mats[] }
+  const add = (p, mat) => {
+    const url = `${resolveDir(p)}/${p.f}`;
+    const mirrored = det3(mat.elements) < 0;
+    if (mirrored) mat.multiply(S);   // M' = M · S (positive determinant)
+    const key = `${url}|${mirrored}`;
+    if (!byFile.has(key)) byFile.set(key, { url, tex: resolveTex(p), mirrored, mats: [] });
+    byFile.get(key).mats.push(mat);
+  };
+  // Stored m[13] is the prop's height in the SOURCE's frame — same datum as the buildings, so
+  // it gets the same KC.groundOff lift (an interior chair at 0 lands on the floor, a porch
+  // barrel on the boardwalk). KC.snap: source ground dressing scatters in a band below zero;
+  // anything that lands within snap of our dirt IS a ground prop and is planted exactly on it
+  // — no floating troughs, no half-sunk fences.
+  // A prop that did NOT snap to the dirt is standing on something the BUILDING owns — its
+  // floor, its bar top, its upstairs. Those must be seated on the building's floor plane, not
+  // on the terrain under the prop: the two differ by the ground's slope across the footprint,
+  // and that difference is exactly the gap the till hovered over the bar (measured: 0.27m).
+  // ...tested in the BUILDING'S OWN FRAME: rotate the prop into it and check the box.
+  // WORLD → LOCAL IS THE INVERSE ROTATION, and the inverse of makeRotationY(ry) — which maps
+  // local (x,z) to world (cos·x + sin·z, −sin·x + cos·z) — is that same matrix TRANSPOSED:
+  //   lx = cos(ry)·dx − sin(ry)·dz,   lz = sin(ry)·dx + cos(ry)·dz
+  // Negating the angle as well applies the FORWARD rotation instead, i.e. it tests the prop
+  // against the box's mirror image. It cancels out at ry = 0 and ±π/2 (a symmetric box cannot
+  // tell a point from its negation) — and it is wrong at every other angle.
+  const floorUnder = (x, z) => {
+    for (const f of floors) {
+      const dx = x - f.x, dz = z - f.z;
+      const c = Math.cos(f.ry), s = Math.sin(f.ry);
+      const lx = c * dx - s * dz, lz = s * dx + c * dz;
+      if (Math.abs(lx) < f.hx && Math.abs(lz) < f.hz) return f.y;
+    }
+    return null;
+  };
+  // ...but WITHIN THE WALLS the floor is not up for debate. A parser that anchors each plot at
+  // the source's y=0 keeps the source's own bedding — whole plots sunk into sculpted sand — so
+  // a plot's INTERIOR dressing can be stored slightly NEGATIVE. The snap test reads that band
+  // as "ground dressing" — a datum the bedded plots never shared — and plants the props on the
+  // dirt, below the floorboards they stand dead-centre on: a barrel stack waist-deep in the
+  // floor. So a prop inside a SHELL piece's own box (the room, not the eaves-padded plot box
+  // floorUnder checks) belongs to that building's floor plane before the snap test, before
+  // groundOnly, before everything: stored y above local 0 is kept (the upstairs stays
+  // upstairs), stored y below it is the plot's bedding and is clamped to the boards. Outside
+  // the walls nothing here fires and the rules below hold unchanged.
+  const interiorUnder = (x, z) => {
+    for (const f of floors) {
+      const dx = x - f.x, dz = z - f.z;
+      const c = Math.cos(f.ry), s = Math.sin(f.ry);
+      const lx = c * dx - s * dz, lz = s * dx + c * dz;
+      if (Math.abs(lx) >= f.hx || Math.abs(lz) >= f.hz) continue;   // cheap reject: outside the plot box
+      for (const b of f.interiors) {
+        if (lx > b.x0 && lx < b.x1 && lz > b.z0 && lz < b.z1) return f.y;
+      }
+    }
+    return null;
+  };
+  // Props that HANG or MOUNT are allowed to sit in mid-air with nothing under them — that is
+  // what a sign on a post, a lantern on a bracket or a curtain on its rail IS. Everything else
+  // is furniture, and furniture needs a floor. (T.airborneOk)
+  // ...and things with WHEELS belong on the dirt, whatever the footprint test says. A building's
+  // floor datum is claimed by its whole BOX, which reaches out past the walls under the eaves —
+  // so a stagecoach drawn up against the wall got lifted onto the floorboards and stood there
+  // hovering. Wheels stay on the ground. (T.groundOnly)
+  // T.outdoorOnly = groundOnly minus the decorative wheel: OUTDOOR furniture that must NEVER
+  // be lifted onto a building's floor, even when the interior box over-reaches to the wall's
+  // edge and claims it. A `Wheel` is exempt: a cartwheel leaning on an inside wall genuinely
+  // stands on the boards.
+  const AIRBORNE_OK = T.airborneOk ?? /$^/;
+  const GROUND_ONLY = T.groundOnly ?? /$^/;
+  const OUTDOOR_ONLY = T.outdoorOnly ?? /$^/;
+  const ladderInst = [];              // /Ladder/i props gathered here; resolved to world climb records after the meshes load
+  ladders.length = 0;
+  for (const p of T.dressing) {
+    if (KC.propDelete.has(propKey(p.m[12], p.m[14]))) continue;   // source junk flagged for the bin
+    const m = new THREE.Matrix4().fromArray(p.m);
+    const inside = OUTDOOR_ONLY.test(p.f) ? null : interiorUnder(p.m[12], p.m[14]);   // outdoor furniture never rides a floor
+    if (inside !== null) {
+      // Inside a shell: on that building's floor plane, bedding clamped (see interiorUnder).
+      // Even a wheel — a cartwheel leaning on the inside wall stands on the boards;
+      // groundOnly exists for the overreaching plot box, and the walls don't overreach.
+      m.elements[13] = inside + Math.max(p.m[13], 0);
+    } else {
+      let dy = p.m[13] + KC.groundOff;
+      const onWheels = GROUND_ONLY.test(p.f);
+      const ground = Math.abs(dy) < KC.snap || onWheels;
+      if (ground) dy = 0;
+      // A building's floor only claims REAL porch dressing — a prop authored near y=0 that stands
+      // on the boardwalk. A prop the source authored HIGH (p.m[13] > 0.5) sat on furniture or
+      // scenery we don't ship; it is not floor dressing, so it drops to the dirt like any
+      // unsupported prop. This is the whole street of floating crates, beds, sacks, coffins
+      // and desks at once.
+      const floor = (ground || p.m[13] > 0.5) ? null : floorUnder(p.m[12], p.m[14]);
+      if (floor !== null) {
+        m.elements[13] = floor + p.m[13];
+      } else {
+        const g = KC.heightAt(p.m[12], p.m[14]);
+        m.elements[13] = (dy > 0.5 && !AIRBORNE_OK.test(p.f)) ? g : dy + g;
+      }
+    }
+    if (KC.propGround.has(propKey(p.m[12], p.m[14]))) m.elements[13] = KC.heightAt(p.m[12], p.m[14]);   // explicit: flat on the dirt
+    add(p, m);
+    if (/Ladder/i.test(p.f)) ladderInst.push({ m: m.clone(), file: p.f, dir: resolveDir(p) });   // climbable — resolved after the meshes load
+    addFenceCapsule(p.f, m, p.r);
+    if (/Lantern/i.test(p.f)) lampPositions.push({ x: p.m[12], y: m.elements[13] + 1.1, z: p.m[14], ground: KC.heightAt(p.m[12], p.m[14]) });
+  }
+  for (const p of T.extras ?? []) {
+    const y = KC.heightAt(p.x, p.z);
+    add(p, new THREE.Matrix4().compose(
+      new THREE.Vector3(p.x, y + (p.y ?? 0), p.z),                          // `y`: sit it ON something (a lamp on its post)
+      new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), p.ry),
+      new THREE.Vector3(1, p.sy ?? 1, 1),                                   // `sy`: stretch a fence post into a lamp post
+    ));
+    // the glow belongs at the FLAME, which is now up on the post — not down in the dirt
+    if (p.lamp) lampPositions.push({ x: p.x, y: y + (p.y ?? 0) + 0.15, z: p.z, ground: y });
+  }
+
+  for (const { url, tex, mirrored, mats } of byFile.values()) {
+    try {
+      const master = await loadModel(`${url}.fbx`, { texture: tex });
+      const flat = flattenToGeometry(master);
+      if (!flat) continue;
+      const geo = mirrored ? bake(flat.geometry, S) : flat.geometry;
+      const mesh = new THREE.InstancedMesh(geo, await townMaterial(tex, `${url}.fbx`), mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = mats.length < 4;
+      mesh.receiveShadow = true;
+      // `scatter:` → world.build bakes it into the collision BVH (its own EXCLUDE regex also
+      // drops fence/grass/ground names — which is exactly why fenceRuns exists above).
+      // `scatterDeco:` → visual only.
+      const file = url.split('/').pop();
+      mesh.name = `${KC.noCollide.test(file) ? 'scatterDeco' : 'scatter'}:${file}.fbx`;
+      mesh.matrixAutoUpdate = false; mesh.updateMatrix();
+      scene.add(mesh);
+    } catch (e) { console.warn(`[town] prop batch ${url} failed`, e); }
+  }
+
+  ladders.push(...await buildLadders(ladderInst));
+  await dressTownCenter(scene);
+  console.log(`[town] ${doors.length} working door(s) · ${ladders.length} climbable ladder(s)`);
+  return { lampPositions, doors, ladders };
+}
+
+// Town-centre: render the editable town-map objects (KC.town.map, authored in the game's
+// map editor). One instanced mesh per (file, collider) group. Stored Y is relative to the
+// flat town pad; we add the pad height (sampled at KC.town.mapAnchor) here. Objects flagged
+// as colliders are named `scatterCol:` so world.build bakes them into the collision BVH;
+// the rest (`scatterDeco:`) are visual. The path stays live for the map editor even when
+// the map ships empty.
+async function dressTownCenter(scene) {
+  const T = KC.town;
+  if (!T?.map?.length) return;
+  const a = T.mapAnchor ?? { x: 0, z: 0 };
+  const baseY = KC.heightAt(a.x, a.z);
+  const groups = new Map(); // `${file}|${collide}` -> { file, collide, mats[] }
+  for (const o of T.map) {
+    const key = `${o.f}|${o.c}`;
+    if (!groups.has(key)) groups.set(key, { file: o.f, collide: o.c, mats: [] });
+    const m = new THREE.Matrix4().fromArray(o.m);
+    m.elements[13] += baseY; // stored Y is relative to the pad
+    groups.get(key).mats.push(m);
+  }
+
+  for (const { file, collide, mats } of groups.values()) {
+    try {
+      const url = `${KC.dirs[KC.defaultDir]}/${file}.fbx`;
+      const master = await loadModel(url, { texture: KC.atlases[KC.defaultDir] });
+      const flat = flattenToGeometry(master);
+      if (!flat) continue;
+      const mesh = new THREE.InstancedMesh(flat.geometry, await townMaterial(KC.atlases[KC.defaultDir], url), mats.length);
+      mats.forEach((m, i) => mesh.setMatrixAt(i, m));
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.castShadow = !!collide;
+      mesh.receiveShadow = true;
+      mesh.frustumCulled = false;
+      mesh.name = `${collide ? 'scatterCol' : 'scatterDeco'}:${file}.fbx`;
+      scene.add(mesh);
+    } catch (e) { console.warn(`map ${file} failed`, e); }
+  }
+}