sindicate 0.13.0 → 0.15.0

package/src/world/worldBase.js

@@ -0,0 +1,493 @@
+// THE WORLD FACADE's ENGINE HALF (world splits, step 7) — the capsule character
+// controller, the 2D collider walk, the BVH oracles (floors, sight, shots), the dev
+// probes and the region streamer, moved verbatim from western's world.js (whose body was
+// duplicated near line-for-line in fable). A game subclasses this with its build()
+// recipe, its update() loop, its zoneName() and its overrides of the HOOKS below:
+//
+//   groundAt(x, z)            terrain + any analytic lifts (western adds walk-humps,
+//                             fable branches into its dungeon)
+//   _colliderList(x, z)       the 2D collider array collide() walks (fable swaps to its
+//                             dungeon set inside the barrow); default: the kit registry
+//   _sweepBVHs(x, z, sweep)   every BVH the capsule depenetrates against
+//   _moveBVHs(pos)            the BVHs the ground snap + floor oracles raycast
+//   _shotBVHs()               every BVH that stops sight/shots (movement's set + pieces)
+//   _losBVHs(from)            per-query override of the shot set (fable's dungeon)
+//   _terrainCatchable(x, z)   veto the heightfield ground catch (fable's Ironkeep mask
+//                             hides the snow skin inside the halls — fall to the MESH)
+//   _vlogExtra(pos)           extra columns for the __vdebug flight recorder
+import * as THREE from 'three/webgpu';
+import { colliders, doorsAt, buildingObjects } from './kit.js';
+import { buildBVHAsync, colliderWireframe } from './collision.js';
+import { getLODColliderGroups } from './scatter.js';
+import { dist2D } from '../core/utils.js';
+
+export class WorldBase {
+  constructor(scene, { heightAt = () => 0, waterSurfaceAt = null } = {}) {
+    this.scene = scene;
+    this._heightAt = heightAt;
+    this._waterSurfaceAt = waterSurfaceAt;
+    this.sky = null;
+    this.weather = null;
+    this.lamps = [];
+    this.water = null;
+    this.grass = null;
+    this.footprints = null;
+    this.tiles = null;
+    this.bridges = [];
+    this.time = 0;
+    this.buildingBVH = null;
+    this.sideBVHs = [];
+    this.deferredRegions = [];
+    this._capSeg = new THREE.Line3();
+    this._capBox = new THREE.Box3();
+    this._triPt = new THREE.Vector3();
+    this._capPt = new THREE.Vector3();
+    this._pushDir = new THREE.Vector3();
+    this._snapRay = new THREE.Ray();
+    this._losRay = new THREE.Ray();
+    this._losDir = new THREE.Vector3();
+    this._bodySeg = new THREE.Line3();
+    this._bodyBox = new THREE.Box3();
+    this._bodyTri = new THREE.Vector3();
+    this._bodyPt = new THREE.Vector3();
+    this._bodyDir = new THREE.Vector3();
+  }
+
+  // ── the hooks (see the header) ──
+  groundAt(x, z) { return this._heightAt(x, z); }
+  _colliderList(x, z) { return colliders; }
+  _sweepBVHs(x, z, sweep) {
+    sweep(this.buildingBVH);
+    for (const b of this.sideBVHs ?? []) sweep(b);
+    this.tiles?.forEachBVHNear(x, z, sweep);
+  }
+  _moveBVHs(pos) { return [this.buildingBVH, ...(this.sideBVHs ?? [])]; }
+  _shotBVHs() { return [this.buildingBVH, ...(this.sideBVHs ?? [])]; }
+  _losBVHs(from) { return this._shotBVHs(); }
+  _terrainCatchable(x, z) { return true; }
+  _vlogExtra(pos) { return []; }
+  _regionObjects() { return buildingObjects; }   // the array deferred-region builds push into
+
+  // The rendered water surface Y at (x,z), or null on dry land. Single source of truth
+  // shared with the water meshes — so depth/wade and the visible surface can never
+  // disagree (the recurring bug).
+  waterSurfaceAt(x, z) {
+    return this._waterSurfaceAt ? this._waterSurfaceAt(x, z) : null;
+  }
+
+  // How deep standing water is at (x,z): 0 on dry land, else surface − ground. Derived
+  // from the ONE surface fn, so its footprint == the rendered water footprint (no
+  // phantom wading / walk-underwater).
+  waterDepthAt(x, z) {
+    const s = this.waterSurfaceAt(x, z);
+    return s === null ? 0 : Math.max(0, s - this._heightAt(x, z));
+  }
+
+  // THE SURFACE AN NPC STANDS ON at (x,z): the terrain (groundAt), raised to a building floor or a
+  // boardwalk deck when one is REALLY over this exact column. It is a straight-down BVH ray — the same
+  // real plank/plinth geometry the player's capsule reads — with NO capsule radius, so a plinth LIP
+  // beside the feet can never catch and lift him (that was the hovering-people bug). Off the deck the
+  // ray finds nothing and he sits on the dirt; a pace onto it, he stands on the boards.
+  //
+  // A footprint BOX cannot do this job: a building's box is the whole rectangle (walls, roof-eaves,
+  // an unmodelled interior), so it claims "floor" over open ground a man is only standing BESIDE —
+  // hovering him — and, inset to stop that, buries the man standing in the inset ring on a deck that
+  // really is under him. The geometry itself is the only honest oracle, so we ask it.
+  //
+  // STRICTLY NPC SEATING (post/spawn/settle, traveller & encounter seating) — all at boot /
+  // spawn, never per frame. The PLAYER must not read this: he already rides real plinths through the
+  // per-frame capsule sweep, and groundAt and every player-capsule path are left exactly as they were.
+  // Cast starts a storey above the ground and ignores anything higher (a roof) or wall-steep (a wall).
+  walkSurfaceAt(x, z) {
+    const g = this.groundAt(x, z);
+    const CEIL = 1.4;                                   // a floor a man could step onto; above it is roof
+    let best = g;
+    const ray = this._snapRay;
+    ray.origin.set(x, g + CEIL, z);
+    ray.direction.set(0, -1, 0);
+    for (const bvh of this._moveBVHs({ x, z })) {
+      if (!bvh) continue;
+      const hits = bvh.raycast ? bvh.raycast(ray, THREE.DoubleSide)
+        : (() => { const h = bvh.raycastFirst?.(ray, THREE.DoubleSide); return h ? [h] : []; })();
+      for (const h of hits) {
+        const y = h.point.y;
+        if (y < g - 0.05 || y > g + CEIL + 1e-3 || y <= best) continue;
+        const n = h.face?.normal;
+        if (n && Math.abs(n.y) < 0.5) continue;         // a wall, not a floor
+        best = y;
+      }
+    }
+    return best;
+  }
+
+  // Like walkSurfaceAt but returns the LOWEST floor above the ground — the surface you actually WALK on —
+  // rather than the highest. NAV bake uses this: walkSurfaceAt returns a TABLETOP (the highest horizontal
+  // surface over a floor), which made the bake think a walker stands ON the tables (tables read walkable,
+  // and the floor↔tabletop jump at every table edge speckled the whole interior). Sampling the FLOOR
+  // instead means the bake's furniture ray (which starts a body-height ABOVE the sample) catches the
+  // tabletops/counters sitting on that floor and blocks their cells — clean open lanes between solid tables.
+  navFloorAt(x, z) {
+    const g = this.groundAt(x, z);
+    const CEIL = 1.4;
+    let best = null;
+    const ray = this._snapRay;
+    ray.origin.set(x, g + CEIL, z);
+    ray.direction.set(0, -1, 0);
+    for (const bvh of this._moveBVHs({ x, z })) {
+      if (!bvh) continue;
+      const hits = bvh.raycast ? bvh.raycast(ray, THREE.DoubleSide)
+        : (() => { const h = bvh.raycastFirst?.(ray, THREE.DoubleSide); return h ? [h] : []; })();
+      for (const h of hits) {
+        const y = h.point.y;
+        if (y < g - 0.05 || y > g + CEIL + 1e-3) continue;
+        const n = h.face?.normal;
+        if (n && Math.abs(n.y) < 0.5) continue;         // a wall, not a floor
+        if (best === null || y < best) best = y;        // LOWEST floor above the ground (a real floor, not a tabletop above it)
+      }
+    }
+    return best === null ? g : best;
+  }
+
+  // true if a wall is between `from` and `to` (tested at chest height) — blocks melee/shots through walls
+  losBlocked(from, to) {
+    return this._rayBlocked(this._losBVHs(from), from.x, from.y + 1.0, from.z, to.x, to.y + 1.0, to.z, -0.4);
+  }
+  _rayBlocked(bvhs, fx, fy, fz, tx, ty, tz, slack) {
+    this._losDir.set(tx - fx, ty - fy, tz - fz);
+    const dist = this._losDir.length();
+    if (dist < 0.01) return false;
+    this._losDir.divideScalar(dist);
+    for (const bvh of bvhs) {
+      if (!bvh?.raycastFirst) continue;
+      this._losRay.origin.set(fx, fy, fz);
+      this._losRay.direction.copy(this._losDir);
+      const hit = bvh.raycastFirst(this._losRay, THREE.DoubleSide);
+      if (hit && hit.distance <= dist + slack) return true;
+    }
+    return false;
+  }
+
+  // true if world geometry (building/rock/scatter BVH) crosses the RAW segment from→to.
+  // Projectiles: test each frame's movement step so fast shots can't tunnel through a
+  // thin wall between frames. Real 3D — arcing over a roof correctly misses.
+  segmentBlocked(from, to) {
+    return this._rayBlocked(this._losBVHs(from), from.x, from.y, from.z, to.x, to.y, to.z, 0);
+  }
+
+  // Push a point out of the static colliders the BVH does NOT own: fence
+  // capsules (jumpable) and trees (circles). Buildings, rocks and props are
+  // handled by the capsule-vs-BVH sweep in moveCapsule.
+  // Shapes: oriented box ({hx,hz,cs,sn}), capsule along a segment (x1..z2/r), circle ({x,z,r}).
+  // `skip` is the collider list of a vehicle the entity is RIDING: a man on a
+  // coach roof must not be pushed about by the coach's own box. Short array, or null.
+  collide(x, z, radius = 0.45, airClear = 0, y, skip = null) {
+    for (const c of this._colliderList(x, z)) {
+      if (skip && skip.includes(c)) continue;
+      if (c.low && airClear > 0.6) continue; // fences: cleared by a jump
+      // height-banded colliders (multi-storey: an upstairs balcony must not block the
+      // street below it). No band = always solid.
+      if (c.y0 !== undefined && y !== undefined && (y > c.y1 || y + 1.8 < c.y0)) continue;
+      if (c.hx !== undefined) {
+        if (c.hx <= 0) continue;   // opened doorway: hx=0 must mean OFF — the +radius inflation
+                                   // otherwise leaves an invisible radius-wide pillar at the
+                                   // centre of EVERY open door (the mid-doorway blockade)
+        // oriented box: resolve in the box's local frame, push out the nearest face
+        const dx = x - c.x, dz = z - c.z;
+        let lx = c.cs * dx - c.sn * dz;
+        let lz = c.sn * dx + c.cs * dz;
+        const ex = c.hx + radius, ez = c.hz + radius;
+        if (Math.abs(lx) < ex && Math.abs(lz) < ez) {
+          if (ex - Math.abs(lx) < ez - Math.abs(lz)) lx = lx < 0 ? -ex : ex;
+          else lz = lz < 0 ? -ez : ez;
+          x = c.x + c.cs * lx + c.sn * lz;
+          z = c.z - c.sn * lx + c.cs * lz;
+        }
+      } else if (c.x1 !== undefined) {
+        // capsule: closest point on the segment, then push out radially
+        const vx = c.x2 - c.x1, vz = c.z2 - c.z1;
+        const len2 = vx * vx + vz * vz || 1;
+        let t = ((x - c.x1) * vx + (z - c.z1) * vz) / len2;
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+        const px = c.x1 + vx * t, pz = c.z1 + vz * t;
+        const d = dist2D(x, z, px, pz);
+        const min = c.r + radius;
+        if (d < min && d > 0.0001) {
+          const push = (min - d) / d;
+          x += (x - px) * push;
+          z += (z - pz) * push;
+        }
+      } else {
+        const d = dist2D(x, z, c.x, c.z);
+        const min = c.r + radius;
+        if (d < min && d > 0.0001) {
+          const push = (min - d) / d;
+          x += (x - c.x) * push;
+          z += (z - c.z) * push;
+        }
+      }
+    }
+    // THE DOORS. A shut one is a thin oriented slab across its opening; an open one is a hole
+    // (toggleDoor sets hx = 0). They are NOT in `colliders`: there are 130-odd, they never move, and
+    // this function is called 200-400 times a frame — so they are bucketed into an 8 m grid (kit.js)
+    // and only the one or two under your feet are ever tested.
+    const near = doorsAt(x, z);
+    for (let i = 0; i < near.length; i++) {
+      const c = near[i];
+      if (c.hx <= 0) continue;                             // opened doorway: no invisible pillar in it
+      if (y !== undefined && (y > c.y1 || y + 1.8 < c.y0)) continue;   // the leaf's own band: upstairs doors
+      const dx = x - c.x, dz = z - c.z;
+      let lx = c.cs * dx - c.sn * dz;
+      let lz = c.sn * dx + c.cs * dz;
+      const ex = c.hx + radius, ez = c.hz + radius;
+      if (Math.abs(lx) < ex && Math.abs(lz) < ez) {
+        if (ex - Math.abs(lx) < ez - Math.abs(lz)) lx = lx < 0 ? -ex : ex;
+        else lz = lz < 0 ? -ez : ez;
+        x = c.x + c.cs * lx + c.sn * lz;
+        z = c.z - c.sn * lx + c.cs * lz;
+      }
+    }
+    return { x, z };
+  }
+
+  // HOW FAR A BODY HAS TO MOVE TO BE OUT OF THE SOLID WORLD, horizontally, at (x,z), standing on
+  // ground y. The player's controller already does this and then walks on (moveCapsule); a VEHICLE
+  // wants the vector back, because four tons that has hit a wall must lose its speed as well as its
+  // ground, and only the caller knows which way it was going.
+  //
+  // Both halves of the world, because the player is stopped by both and a coach that consulted only
+  // one would drive through the other: the props/fences/trees/vehicles LIST (collide, above) and the
+  // BUILDINGS, which live in the BVH and in nothing else — which is exactly why a driven coach used
+  // to park in the middle of the station.
+  //
+  // Only WALLS. A contact whose normal points mostly up is a floor, a porch deck or a boardwalk, and
+  // a vehicle does not climb: she is on the dirt, her height comes from the heightfield, and a push
+  // out of a floor she is standing near would only shove her sideways for no reason.
+  solidPush(x, y, z, r, out, skip = null) {
+    const c = this.collide(x, z, r, 0, y, skip);
+    const seg = this._bodySeg, box = this._bodyBox;
+    // her body, as a vertical stick: clear of the dirt (so the ground itself is never a contact) up
+    // to the top of her box — the same band her own collider carries.
+    seg.start.set(c.x, y + 0.35, c.z);
+    seg.end.set(c.x, y + 1.70, c.z);
+    const sweep = (bvh) => {
+      if (!bvh) return;
+      box.makeEmpty();
+      box.expandByPoint(seg.start);
+      box.expandByPoint(seg.end);
+      box.min.addScalar(-r);
+      box.max.addScalar(r);
+      bvh.shapecast({
+        intersectsBounds: (b) => b.intersectsBox(box),
+        intersectsTriangle: (tri) => {
+          const d = tri.closestPointToSegment(seg, this._bodyTri, this._bodyPt);
+          if (d >= r) return;
+          this._bodyDir.copy(this._bodyPt).sub(this._bodyTri);
+          const len = this._bodyDir.length();
+          if (len < 1e-6) return;
+          this._bodyDir.multiplyScalar(1 / len);
+          if (Math.abs(this._bodyDir.y) > 0.6) return;   // a floor or a roof, not a wall
+          const depth = r - d;
+          const px = this._bodyDir.x * depth, pz = this._bodyDir.z * depth;
+          seg.start.x += px; seg.start.z += pz;
+          seg.end.x += px; seg.end.z += pz;
+        },
+      });
+    };
+    this._sweepBVHs(seg.start.x, seg.start.z, sweep);
+    return out.set(seg.start.x - x, 0, seg.start.z - z);
+  }
+
+  // Capsule character controller (bvh mode). Substeps the move to avoid
+  // tunneling through stairs, depenetrating a vertical capsule against the
+  // building BVH each substep, with the terrain heightfield as the ground floor
+  // and the legacy 2D pass still handling props/fences/trees (buildings skipped).
+  // Mutates entity.position / entity.vy / entity.airborne. Returns grounded.
+  moveCapsule(entity, hx, hz, dt) {
+    const steps = entity.capsuleSteps ?? 5;
+    let grounded = false;
+    for (let s = 0; s < steps; s++) {
+      if (this._capsuleStep(entity, hx / steps, hz / steps, dt / steps)) grounded = true;
+    }
+    const pos = entity.position;
+    const radius = entity.capsuleR ?? entity.radius ?? 0.4;
+
+    // snap-to-ground: if we were grounded and aren't moving up, stay glued to a
+    // surface within one step below — stops falling through open stair treads or
+    // off the nose of a downslope. Jumps (vy>0) and real ledge drops (>snap) skip it.
+    if (!grounded && entity._capGrounded && entity.vy <= 0) {
+      const snap = 0.55;
+      const terrainY = this.groundAt(pos.x, pos.z);
+      let target = (pos.y - terrainY >= 0 && pos.y - terrainY < snap) ? terrainY : -Infinity;
+      for (const bvh of this._moveBVHs(pos)) {
+        if (!bvh) continue;
+        this._snapRay.origin.set(pos.x, pos.y + 0.1, pos.z);
+        this._snapRay.direction.set(0, -1, 0);
+        const hit = bvh.raycastFirst(this._snapRay, THREE.DoubleSide);
+        if (hit && hit.point.y <= pos.y + 0.1 && pos.y - hit.point.y < snap && hit.point.y > target) target = hit.point.y;   // glue to porch floors/stairs, not just terrain
+      }
+      if (target > -Infinity) { pos.y = target; grounded = true; entity.vy = 0; }
+    }
+
+    // props / fences / trees on the legacy 2D pass, once per frame
+    // (buildings are owned by the BVH so they're skipped here)
+    const c = this.collide(pos.x, pos.z, radius, pos.y - this.groundAt(pos.x, pos.z), pos.y, entity._skipCols);
+    pos.x = c.x; pos.z = c.z;
+
+    entity._capGrounded = grounded;
+    entity.airborne = !grounded;
+    if (typeof window !== 'undefined' && window.__vdebug && entity.game && entity.game.player === entity) {
+      (window.__vlog ??= []).push([+pos.y.toFixed(3), grounded ? 1 : 0, +this.groundAt(pos.x, pos.z).toFixed(3), +(entity.vy ?? 0).toFixed(2), ...this._vlogExtra(pos)]);
+      if (window.__vlog.length > 600) window.__vlog.shift();
+    }
+    return grounded;
+  }
+
+  _capsuleStep(entity, hx, hz, dt) {
+    const pos = entity.position;
+    const radius = entity.capsuleR ?? entity.radius ?? 0.4;
+    const height = entity.capsuleH ?? 1.7;
+    entity.vy = (entity.vy ?? 0) - 20 * dt;
+    let nx = pos.x + hx, nz = pos.z + hz, ny = pos.y + entity.vy * dt;
+    let grounded = false;
+
+    const seg = this._capSeg, box = this._capBox;
+    seg.start.set(nx, ny + radius, nz);
+    seg.end.set(nx, ny + height - radius, nz);
+    const y0 = seg.start.y;
+    // Sweep the capsule against ONE bvh, accumulating depenetration into `seg`. The bounds box is
+    // recomputed each call since seg moves between casts. We sweep the boot BVH (buildings + non-tiled
+    // scatter) PLUS every loaded TileField BVH near the capsule, so streamed colliders block too.
+    const sweep = (bvh) => {
+      if (!bvh) return;
+      box.makeEmpty();
+      box.expandByPoint(seg.start);
+      box.expandByPoint(seg.end);
+      box.min.addScalar(-radius);
+      box.max.addScalar(radius);
+      bvh.shapecast({
+        intersectsBounds: (b) => b.intersectsBox(box),
+        intersectsTriangle: (tri) => {
+          const d = tri.closestPointToSegment(seg, this._triPt, this._capPt);
+          if (d < radius) {
+            const depth = radius - d;
+            this._pushDir.copy(this._capPt).sub(this._triPt);
+            const len = this._pushDir.length();
+            if (len > 1e-6) {
+              this._pushDir.multiplyScalar(1 / len);
+              if (this._pushDir.y > 0.6) {
+                // Walkable ground/slope (contact normal mostly up): resolve the
+                // penetration straight UP, not along the tilted normal. On bumpy
+                // stone the normal tilts, so a full-normal push has a horizontal
+                // component that drifts the capsule every frame — the character
+                // slides while standing still. Pushing up by depth/normal.y
+                // clears the overlap with zero horizontal motion (and still
+                // counts as grounded below). Walls (near-horizontal normal) fall
+                // through to the full push, so they block and you slide along.
+                const dy = depth / this._pushDir.y;
+                seg.start.y += dy;
+                seg.end.y += dy;
+              } else {
+                seg.start.addScaledVector(this._pushDir, depth);
+                seg.end.addScaledVector(this._pushDir, depth);
+              }
+            }
+          }
+        },
+      });
+    };
+    this._sweepBVHs(nx, nz, sweep);
+    nx = seg.start.x;
+    nz = seg.start.z;
+    ny = seg.start.y - radius;
+    // a net upward push means we're standing on something (floor/stair/balcony)
+    if (seg.start.y - y0 > 1e-3 && entity.vy <= 0) { grounded = true; entity.vy = 0; }
+
+    // The terrain heightfield is the ground floor — BUT the capsule sweep above is
+    // authoritative: if it already grounded us on a MESH (building floor, stair),
+    // the heightfield must NOT yank us off it. Only catch us with the terrain when
+    // nothing solid is underfoot (and the game hasn't vetoed the catch — a hidden
+    // terrain skin inside a mesh-floored hall must not catch anyone).
+    const terrainY = this.groundAt(nx, nz);
+    if (ny <= terrainY && !grounded && this._terrainCatchable(nx, nz)) { ny = terrainY; if (entity.vy < 0) entity.vy = 0; grounded = true; }
+
+    pos.set(nx, ny, nz);
+    return grounded;
+  }
+
+  // Dev probe: drop a capsule at (x,z) from `fromY`, settle a few frames, and
+  // report where it rests. Lets collision be checked numerically (game.__probe).
+  probe(x, z, fromY = 50) {
+    const dummy = { position: new THREE.Vector3(x, fromY, z), vy: 0, airborne: true, radius: 0.4 };
+    const tr = [];
+    for (let i = 0; i < 60; i++) { this.moveCapsule(dummy, 0, 0, 1 / 60); tr.push(+dummy.position.y.toFixed(3)); }
+    const last = tr.slice(-15);
+    return { x: dummy.position.x, y: +dummy.position.y.toFixed(3), z: dummy.position.z, grounded: !dummy.airborne, settle: +(Math.max(...last) - Math.min(...last)).toFixed(3), tail: tr.slice(-6) };
+  }
+
+  // Dev: what actually got baked into the collision BVH.
+  colliderInfo() {
+    const EXCLUDE = /tree|bush|fence|flower|path|brick|ground|floor|grass/i;
+    const inc = [], exc = [];
+    for (const g of getLODColliderGroups()) (EXCLUDE.test(g.name) ? exc : inc).push(`${g.name} x${g.count}`);
+    const scatterMeshes = [];
+    this.scene.traverse((o) => {
+      if (o.isInstancedMesh && /^scatter:/.test(o.name || '') && !EXCLUDE.test(o.name)) {
+        scatterMeshes.push(`${o.name} (live x${o.count})`);
+      }
+    });
+    return {
+      tris: this.buildingBVH ? Math.round(this.buildingBVH.geometry.attributes.position.count / 3) : 0,
+      lodBaked: inc,        // distance-LOD groups in the collider (rocks)
+      lodSkipped: exc,      // excluded (trees / roads / bushes)
+      plainScatter: scatterMeshes,
+    };
+  }
+
+  showCollider(on = true) {
+    if (on && !this._colliderViz && this.buildingBVH) {
+      this._colliderViz = colliderWireframe(this.buildingBVH);
+      if (this._colliderViz) this.scene.add(this._colliderViz);
+    } else if (!on && this._colliderViz) {
+      this.scene.remove(this._colliderViz);
+      this._colliderViz = null;
+    }
+  }
+
+  // REGION STREAMER (GTA loading): builds the regions the boot bubble skipped, in play.
+  // One region at a time, nearest-first. Two triggers: APPROACH (inside TRIGGER_R — the
+  // player is heading there, build now) and IDLE TRICKLE (one region every few seconds
+  // regardless, so the whole map quietly finishes in the first minutes). Builders await
+  // per-asset loads, so the work naturally yields; deferred buildings land AFTER the boot
+  // BVH bake, so their buildingObjects pushes are spliced into a worker-built side-BVH
+  // (swept by shots/snap/capsule via this.sideBVHs). Lamp positions join the lamp pool
+  // (append is safe — the pool re-sorts nightly; light COUNT never changes).
+  _updateRegionStreamer(playerPos) {
+    if (!this.deferredRegions?.length || this._regionBuilding) return;
+    // grace: let the opening seconds present smoothly before any background building
+    if (!this._streamT0) this._streamT0 = performance.now();
+    if (performance.now() - this._streamT0 < 8000) return;
+    const TRIGGER_R = 600, IDLE_MS = 5000;
+    let best = null, bestD = Infinity;
+    for (const r of this.deferredRegions) {
+      const d = Math.hypot(playerPos.x - r.x, playerPos.z - r.z);
+      if (d < bestD) { bestD = d; best = r; }
+    }
+    const idleDue = performance.now() > (this._lastRegionBuild ?? 0) + IDLE_MS;
+    if (!best || (bestD > TRIGGER_R && !idleDue)) return;
+    this._regionBuilding = true;
+    this._lastRegionBuild = performance.now();
+    this.deferredRegions.splice(this.deferredRegions.indexOf(best), 1);
+    const regionObjs = this._regionObjects();
+    const before = regionObjs.length;
+    best.build().then(async (res) => {
+      const newObjs = regionObjs.splice(before);   // one build at a time — no interleaved pushes
+      if (res?.lampPositions?.length) this.lampPositions.push(...res.lampPositions.map((lp) => ({ x: lp.x, y: lp.y, z: lp.z })));
+      if (newObjs.length) {
+        try { const bvh = await buildBVHAsync(newObjs, []); if (bvh) this.sideBVHs.push(bvh); }
+        catch (e) { console.warn(`[region] ${best.name} side-BVH failed`, e); }
+      }
+      console.log(`[region] ${best.name} built in play (${newObjs.length} building colliders, ${Math.round(bestD)}m away, ${this.deferredRegions.length} to go)`);
+    }).catch((e) => console.warn(`[region] ${best.name} build failed`, e))
+      .finally(() => { this._regionBuilding = false; });
+  }
+}

package/tools/ExportKiwiRoadMaterials.cs

@@ -0,0 +1,145 @@
+// EXPORT KIWI ROAD MATERIALS — drop this file into Kiwi's Assets/Editor/ folder, let
+// Unity compile, then run  Tools ▸ Sindicate ▸ Export Road Materials.  (~10 seconds.)
+//
+// It does NOT export models (Sindicate already recovered the geometry). It walks every
+// prefab and records each part's UNITY-RESOLVED world transform (the truth — no more
+// hierarchy archaeology) alongside its material stack. It also walks every
+// road prefab (AIGenerateMap/Prefabs/Roads, JunctionPrefabs, RoadPrefabs) and writes ONE
+// truth file mapping every renderer's mesh to its real material stack:
+//   Assets/SindicateExport/road-materials.json
+//     { entries: [{ prefab, object, mesh, meshGuid,
+//                   materials: [{ name, shader, mainTex, color, tiling, offset }] }] }
+// …and copies every referenced texture into Assets/SindicateExport/textures/.
+// Copy the SindicateExport folder to Nick's Sites machine and Sindicate's assembler
+// applies exact materials to the already-recovered assemblies.
+using UnityEngine;
+using UnityEditor;
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+
+public static class ExportKiwiRoadMaterials
+{
+    static readonly string[] ROOTS = {
+        "Assets/AIGenerateMap/Prefabs/Roads",
+        "Assets/AIGenerateMap/JunctionPrefabs",
+        "Assets/AIGenerateMap/RoadPrefabs",
+    };
+
+    [MenuItem("Tools/Sindicate/Export Road Materials")]
+    public static void Export()
+    {
+        var outDir = "Assets/SindicateExport";
+        var texDir = Path.Combine(outDir, "textures");
+        Directory.CreateDirectory(texDir);
+
+        var sb = new StringBuilder();
+        sb.Append("{\"entries\":[");
+        bool first = true;
+        var texturesCopied = new HashSet<string>();
+        int prefabCount = 0;
+
+        foreach (var root in ROOTS)
+        {
+            foreach (var guid in AssetDatabase.FindAssets("t:Prefab", new[] { root }))
+            {
+                var path = AssetDatabase.GUIDToAssetPath(guid);
+                var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
+                if (prefab == null) continue;
+                prefabCount++;
+
+                foreach (var r in prefab.GetComponentsInChildren<MeshRenderer>(true))
+                {
+                    var mf = r.GetComponent<MeshFilter>();
+                    if (mf == null || mf.sharedMesh == null) continue;
+                    var meshPath = AssetDatabase.GetAssetPath(mf.sharedMesh);
+                    var meshGuid = AssetDatabase.AssetPathToGUID(meshPath);
+
+                    if (!first) sb.Append(",");
+                    first = false;
+                    sb.Append("{\"prefab\":").Append(J(Path.GetFileNameWithoutExtension(path)));
+                    sb.Append(",\"object\":").Append(J(r.gameObject.name));
+                    sb.Append(",\"mesh\":").Append(J(Path.GetFileName(meshPath)));
+                    sb.Append(",\"meshGuid\":").Append(J(meshGuid));
+                    sb.Append(",\"meshName\":").Append(J(mf.sharedMesh.name));
+                    sb.Append(",\"active\":").Append(r.gameObject.activeInHierarchy && r.enabled ? "true" : "false");
+                    var t = r.transform;
+                    var wp = t.position; var wq = t.rotation; var ws = t.lossyScale;
+                    sb.Append(",\"pos\":[").Append(wp.x).Append(",").Append(wp.y).Append(",").Append(wp.z).Append("]");
+                    sb.Append(",\"quat\":[").Append(wq.x).Append(",").Append(wq.y).Append(",").Append(wq.z).Append(",").Append(wq.w).Append("]");
+                    sb.Append(",\"scale\":[").Append(ws.x).Append(",").Append(ws.y).Append(",").Append(ws.z).Append("]");
+                    sb.Append(",\"materials\":[");
+                    for (int i = 0; i < r.sharedMaterials.Length; i++)
+                    {
+                        var m = r.sharedMaterials[i];
+                        if (i > 0) sb.Append(",");
+                        if (m == null) { sb.Append("null"); continue; }
+                        var tex = m.HasProperty("_BaseMap") && m.GetTexture("_BaseMap") != null ? m.GetTexture("_BaseMap")
+                                : m.HasProperty("_MainTex") ? m.GetTexture("_MainTex") : null;
+                        string texName = null;
+                        if (tex != null)
+                        {
+                            var tp = AssetDatabase.GetAssetPath(tex);
+                            texName = Path.GetFileName(tp);
+                            if (!string.IsNullOrEmpty(tp) && texturesCopied.Add(texName))
+                                File.Copy(tp, Path.Combine(texDir, texName), true);
+                        }
+                        var col = m.HasProperty("_BaseColor") ? m.GetColor("_BaseColor")
+                                : m.HasProperty("_Color") ? m.GetColor("_Color") : Color.white;
+                        var st = m.HasProperty("_BaseMap") ? m.GetTextureScale("_BaseMap")
+                               : m.HasProperty("_MainTex") ? m.GetTextureScale("_MainTex") : Vector2.one;
+                        var so = m.HasProperty("_BaseMap") ? m.GetTextureOffset("_BaseMap")
+                               : m.HasProperty("_MainTex") ? m.GetTextureOffset("_MainTex") : Vector2.zero;
+                        sb.Append("{\"name\":").Append(J(m.name));
+                        sb.Append(",\"shader\":").Append(J(m.shader != null ? m.shader.name : ""));
+                        sb.Append(",\"mainTex\":").Append(texName == null ? "null" : J(texName));
+                        sb.Append(",\"color\":[").Append(col.r).Append(",").Append(col.g).Append(",").Append(col.b).Append(",").Append(col.a).Append("]");
+                        sb.Append(",\"tiling\":[").Append(st.x).Append(",").Append(st.y).Append("]");
+                        sb.Append(",\"offset\":[").Append(so.x).Append(",").Append(so.y).Append("]}");
+                    }
+                    sb.Append("]}");
+                }
+            }
+        }
+        sb.Append("],\"nodes\":[");
+
+        // MARKERS — every GameObject WITHOUT a MeshRenderer: connectors, sockets, spawn
+        // points, group empties. These are what tells Sindicate where a junction's arms
+        // are and which way they face, so roads can auto-connect junction to junction.
+        // (Renderers are already covered above; this keeps the file small.)
+        bool firstNode = true;
+        foreach (var root in ROOTS)
+        {
+            foreach (var guid in AssetDatabase.FindAssets("t:Prefab", new[] { root }))
+            {
+                var path = AssetDatabase.GUIDToAssetPath(guid);
+                var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
+                if (prefab == null) continue;
+                foreach (var t in prefab.GetComponentsInChildren<Transform>(true))
+                {
+                    if (t.GetComponent<MeshRenderer>() != null) continue;
+                    if (!firstNode) sb.Append(",");
+                    firstNode = false;
+                    // parent path so hierarchy meaning survives (e.g. Sockets/Connector_A)
+                    var chain = t.name;
+                    for (var p = t.parent; p != null && p != prefab.transform; p = p.parent) chain = p.name + "/" + chain;
+                    sb.Append("{\"prefab\":").Append(J(Path.GetFileNameWithoutExtension(path)));
+                    sb.Append(",\"path\":").Append(J(chain));
+                    sb.Append(",\"name\":").Append(J(t.name));
+                    sb.Append(",\"active\":").Append(t.gameObject.activeInHierarchy ? "true" : "false");
+                    var np = t.position; var nq = t.rotation; var ns = t.lossyScale;
+                    sb.Append(",\"pos\":[").Append(np.x).Append(",").Append(np.y).Append(",").Append(np.z).Append("]");
+                    sb.Append(",\"quat\":[").Append(nq.x).Append(",").Append(nq.y).Append(",").Append(nq.z).Append(",").Append(nq.w).Append("]");
+                    sb.Append(",\"scale\":[").Append(ns.x).Append(",").Append(ns.y).Append(",").Append(ns.z).Append("]}");
+                }
+            }
+        }
+        sb.Append("]}");
+        File.WriteAllText(Path.Combine(outDir, "road-materials.json"), sb.ToString());
+        AssetDatabase.Refresh();
+        EditorUtility.DisplayDialog("Sindicate export",
+            $"Done: {prefabCount} prefabs walked, {texturesCopied.Count} textures copied.\n\nCopy Assets/SindicateExport/ to Sites and tell Claude.", "OK");
+    }
+
+    static string J(string s) => "\"" + (s ?? "").Replace("\\", "\\\\").Replace("\"", "\\\"") + "\"";
+}