sindicate 0.13.0 → 0.16.0

package/src/world/waterMeshes.js

@@ -0,0 +1,168 @@
+// THE WATER MESHES (world splits, step 6) — river ribbons, lake sheets and the sea plane,
+// moved verbatim from western's zones.js. All geometry + per-vertex hydraulic bakes; the
+// MATERIALS stay the game's choice (one shared waterMaterial across lakes, one shared
+// riverMaterial across courses — each distinct refracting material pays its own viewport
+// copy per frame, so sharing collapses the copies however many bodies the county gains).
+import * as THREE from 'three/webgpu';
+
+// A river ribbon: walk the path in ~2m steps, emit left/right cross-section verts at ±w,
+// bake the still-water depth (level − bed) + downstream UVs per vertex, strip the quads.
+// Emitted as ~200 m CHUNKS (each its own geometry + bounding sphere) rather than one
+// course-long mesh: a 3.6 km course has a county-sized bounding sphere, so frustumCulled
+// never actually culled, and refraction pays a viewport copy per DRAW. Boundary
+// cross-section rows are duplicated into both neighbouring chunks — identical baked values
+// from identical inputs, so the strip has no seam.
+export function buildRiverMesh(scene, R, mat, { heightAt }) {
+  const L = THREE.MathUtils.lerp, pts = [];
+  // Reference half-width for the flow bake: the course's own source→mouth hydraulic ramp,
+  // PER STATION — not one course-wide constant. The solved widths are that ramp ±25 %
+  // pool/riffle modulation, and it is the MODULATION continuity should answer to: against a
+  // constant reference, a narrow upstream pool computes faster than a wide downstream riffle
+  // (measured: pools averaged 0.50 m/s to the riffles' 0.44), which is backwards. Against
+  // the local ramp, wide-for-here runs slow and narrow-for-here runs quick, the whole course over.
+  const wEnd = R.pts.length - 1 || 1;
+  const wrefAt = (f) => L(R.wsrc ?? R.w, R.w, f);
+  for (let i = 0; i < R.pts.length - 1; i++) {
+    const a = R.pts[i], b = R.pts[i + 1], steps = Math.max(1, Math.round(Math.hypot(b.x - a.x, b.z - a.z) / 2));
+    for (let s = 0; s < steps; s++) { const t = s / steps; pts.push({ x: L(a.x, b.x, t), z: L(a.z, b.z, t), wy: L(R.wy[i], R.wy[i + 1], t), ww: L(R.ww[i], R.ww[i + 1], t), wr: wrefAt((i + t) / wEnd) }); }
+  }
+  const e = R.pts.length - 1; pts.push({ x: R.pts[e].x, z: R.pts[e].z, wy: R.wy[e], ww: R.ww[e], wr: wrefAt(1) });
+
+  // cross-section resolution scales with the river's width — ~2.4m across (odd → centreline)
+  const K = Math.max(9, Math.min(41, 2 * Math.round(Math.max(...R.ww) / 2.4) + 1));
+  const CHUNK_LEN = 200;   // m of course per geometry
+  const meshes = [];
+  const newChunk = () => ({ verts: [], depths: [], uvs: [], flows: [], drops: [], bWy: [], bX: [], bZ: [], rows: 0 });
+  const pushRow = (c, row) => {
+    for (const [dst, src] of [[c.verts, row.verts], [c.depths, row.depths], [c.uvs, row.uvs],
+      [c.flows, row.flows], [c.drops, row.drops], [c.bWy, row.bWy], [c.bX, row.bX], [c.bZ, row.bZ]]) dst.push(...src);
+    c.rows++;
+  };
+  const flush = (c) => {
+    const idx = [];
+    for (let i = 0; i < c.rows - 1; i++) for (let k = 0; k < K - 1; k++) {
+      const a = i * K + k, b = a + 1, q = (i + 1) * K + k, d = q + 1;
+      idx.push(a, q, b, b, q, d);
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.Float32BufferAttribute(c.verts, 3));
+    geo.setAttribute('aDepth', new THREE.Float32BufferAttribute(c.depths, 1));
+    geo.setAttribute('uv', new THREE.Float32BufferAttribute(c.uvs, 2));
+    geo.setAttribute('aFlow', new THREE.Float32BufferAttribute(c.flows, 2));
+    geo.setAttribute('aDrop', new THREE.Float32BufferAttribute(c.drops, 1));
+    geo.setIndex(idx);
+    const mesh = new THREE.Mesh(geo, mat);
+    // per-chunk bake data — refreshRiverDepths already iterates N meshes, so each chunk
+    // re-derives its own aDepth after the terrain pads mutate heightAt
+    mesh.userData.riverVerts = { wy: Float32Array.from(c.bWy), x: Float32Array.from(c.bX), z: Float32Array.from(c.bZ) };
+    geo.computeBoundingSphere();
+    mesh.frustumCulled = true; // refraction pays a viewport copy per DRAW — never draw off-screen chunks
+    scene.add(mesh);
+    meshes.push(mesh);
+  };
+  let cur = newChunk(), chunkStart = 0, along = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i], pa = pts[Math.max(0, i - 1)], pb = pts[Math.min(pts.length - 1, i + 1)];
+    let tx = pb.x - pa.x, tz = pb.z - pa.z; const tl = Math.hypot(tx, tz) || 1; tx /= tl; tz /= tl;
+    const nx = -tz, nz = tx;                                    // perpendicular in the XZ plane
+    if (i > 0) along += Math.hypot(p.x - pts[i - 1].x, p.z - pts[i - 1].z);
+    // rapids strength: how fast the water level DROPS just downstream of here (per metre)
+    const pd = pts[Math.min(pts.length - 1, i + 3)];
+    const dDist = Math.hypot(pd.x - p.x, pd.z - p.z) || 1;
+    const drop = Math.max(0, (p.wy - pd.wy) / dDist);
+    const row = newChunk();                                     // one cross-section, built once…
+    for (let k = 0; k < K; k++) {
+      const side = (k / (K - 1)) * 2 - 1;                       // -1 (left bank) … 0 (centre) … 1 (right bank)
+      const vx = p.x + nx * p.ww * side, vz = p.z + nz * p.ww * side;
+      const g = heightAt(vx, vz);
+      // wet verts sit at water level; DRY verts dive a fixed metre BELOW the surface, so the
+      // sheet submerges and the waterline is the smooth surface/terrain intersection
+      row.verts.push(vx, g < p.wy ? p.wy : p.wy - 1.0, vz);
+      row.depths.push(p.wy - g);                                // ≤0 on dry verts → transparent + bank foam at the line
+      row.bWy.push(p.wy); row.bX.push(vx); row.bZ.push(vz);
+      row.uvs.push((side + 1) * 0.5, along * 0.1);              // V runs down the WHOLE course — seamless across chunks
+      // downstream velocity (m/s), BAKED FROM THE HYDRAULICS instead of a universal
+      // constant (every reach of every course at the same speed — a pool as fast as a
+      // rapid). Slope sets the pace (drop is already per-metre, from the reach-baked wy
+      // three nodes downstream), width modulates it by continuity against the local ramp
+      // (wr above): the solved courses run ±25 % pool/riffle width, so a narrow riffle
+      // visibly quickens and a wide pool slows to a crawl.
+      const v = THREE.MathUtils.clamp(0.4 + 10 * drop, 0.3, 2.4) * (p.wr / p.ww);
+      row.flows.push(tx * v, tz * v);
+      row.drops.push(drop);
+    }
+    pushRow(cur, row);
+    if (along - chunkStart >= CHUNK_LEN && i < pts.length - 1) {
+      flush(cur);
+      cur = newChunk(); chunkStart = along;
+      pushRow(cur, row);                                        // …and shared by both sides of the cut
+    }
+  }
+  flush(cur);
+  return meshes;
+}
+
+// A lake sheet: one plane per body at the survey level − drop, per-vertex aDepth bake, dry
+// verts dived below the surface, per-vertex aRClip so ONE shared material keeps per-lake
+// sprawl clip. The shared material is the game's (waterMaterial({ rClip: 'attribute' })).
+export function buildLake(scene, Lk, mat, { heightAt, drop = 0.8 }) {
+  const rClip = Lk.rClip ?? Lk.r * 0.85;
+  const wr = rClip + 4;
+  const wseg = THREE.MathUtils.clamp(Math.round((wr * 2) / 1.8), 16, 64);    // ~1.8m facets
+  const wgeo = new THREE.PlaneGeometry(wr * 2, wr * 2, wseg, wseg);
+  const waterY = Lk.level - drop;
+  const dp = wgeo.attributes.position, aDepth = new Float32Array(dp.count);
+  const aRClip = new Float32Array(dp.count).fill(rClip);     // per-vertex so the shared shader keeps per-lake sprawl clip
+  for (let i = 0; i < dp.count; i++) {
+    const g = heightAt(Lk.x + dp.getX(i), Lk.z - dp.getY(i));
+    aDepth[i] = waterY - g;
+    if (g >= waterY) dp.setZ(i, -drop); // dry verts dive below the surface (plane local +z is world up)
+  }
+  wgeo.setAttribute('aDepth', new THREE.BufferAttribute(aDepth, 1));
+  wgeo.setAttribute('aRClip', new THREE.BufferAttribute(aRClip, 1));
+  const lake = new THREE.Mesh(wgeo, mat);
+  lake.rotation.x = -Math.PI / 2;
+  lake.position.set(Lk.x, waterY, Lk.z);
+  scene.add(lake);
+  return lake;
+}
+
+// The sea: a flat ocean plane at seaLevel, shown only where land dips below it past coastZ.
+export function buildSea(scene, mat, { worldSize, seaLevel, coastZ, heightAt }) {
+  const SEG = 256;
+  const geo = new THREE.PlaneGeometry(worldSize, worldSize, SEG, SEG);
+  const pos = geo.attributes.position, aDepth = new Float32Array(pos.count);
+  for (let i = 0; i < pos.count; i++) {
+    const X = pos.getX(i), Z = -pos.getY(i);
+    aDepth[i] = Z > coastZ ? Math.max(0, seaLevel - heightAt(X, Z)) : 0;
+  }
+  geo.setAttribute('aDepth', new THREE.BufferAttribute(aDepth, 1));
+  const mesh = new THREE.Mesh(geo, mat);
+  mesh.rotation.x = -Math.PI / 2;
+  mesh.position.y = seaLevel;
+  mesh.frustumCulled = false;
+  scene.add(mesh);
+  return mesh;
+}
+
+// Rivers v2: re-derive every river vert's depth from the CURRENT terrain — pads that
+// register during world.build mutate heightAt AFTER the ribbons bake, leaving stale aDepth.
+// Called at the END of world.build; re-runnable whenever terrain changes.
+export function refreshRiverDepths(waters, { heightAt }) {
+  let fixed = 0;
+  for (const m of waters ?? []) {
+    const rb = m.userData?.riverVerts;
+    if (!rb) continue;
+    const pos = m.geometry.attributes.position, aD = m.geometry.attributes.aDepth;
+    for (let i = 0; i < aD.count; i++) {
+      const g = heightAt(rb.x[i], rb.z[i]);
+      const d = rb.wy[i] - g;
+      if (Math.abs(d - aD.getX(i)) > 0.02) fixed++;
+      aD.setX(i, d);
+      pos.setY(i, g < rb.wy[i] ? rb.wy[i] : rb.wy[i] - 1.0);
+    }
+    aD.needsUpdate = true; pos.needsUpdate = true;
+    m.geometry.computeBoundingSphere();
+  }
+  if (fixed) console.log(`[rivers] depth refresh: ${fixed} verts re-derived after terrain pads`);
+}

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; });
+  }
+}