sindicate 0.1.0 → 0.4.0

package/src/world/sky.js

@@ -0,0 +1,363 @@
+// Dynamic sky: gradient dome, sun/moon orbit, stars, fog and light color
+// driven by a 24h clock. Also tints toward dread inside Gravemoor.
+import * as THREE from 'three/webgpu';
+import { clamp, lerp, smoothstep } from '../core/utils.js';
+import { getQuality } from '../core/quality.js';
+import { uDayness, uSkyCol, uHorizonCol, uSunDir, uCloudiness, uWindDir, uWindStr } from './weatherUniforms.js';
+import { buildCloudMaterial } from './clouds.js';
+
+const DAY = {
+  sky: new THREE.Color(0x7fb2e5), horizon: new THREE.Color(0xdfe9d8),
+  fog: new THREE.Color(0xc3d4dd), sun: new THREE.Color(0xfff1d6), sunI: 2.6, ambI: 0.85,
+};
+const DUSK = {
+  sky: new THREE.Color(0x4a4a7a), horizon: new THREE.Color(0xf2a05a),
+  fog: new THREE.Color(0xb38a6a), sun: new THREE.Color(0xffb070), sunI: 1.5, ambI: 0.5,
+};
+const NIGHT = {
+  // fog/horizon must stay DARKER than moonlit ground or distance glows brighter than
+  // the foreground (fog is applied post-lighting, so it wins at range)
+  sky: new THREE.Color(0x0b1026), horizon: new THREE.Color(0x121828),
+  fog: new THREE.Color(0x0b101e), sun: new THREE.Color(0x9fb4e0), sunI: 2.6, ambI: 0.8,
+};
+const MOOR_TINT = new THREE.Color(0x5a6358);
+// reused every frame in update() to avoid per-frame GC churn
+const WHITE = new THREE.Color(0xffffff);
+const STORM_CLOUD = new THREE.Color(0x49505b);   // heavy slate deck at full weather
+const _grey = new THREE.Color();   // scratch for the overcast desaturation
+const _cloudM = new THREE.Matrix4(), _cloudQ = new THREE.Quaternion(), _cloudQ2 = new THREE.Quaternion(), _cloudV = new THREE.Vector3(), _cloudS = new THREE.Vector3();
+const _cloudDir = new THREE.Vector3(), _cloudZ = new THREE.Vector3(0, 0, 1);
+const _cloudUp = new THREE.Vector3(0, 1, 0), _cloudRight = new THREE.Vector3(), _cloudUp2 = new THREE.Vector3(), _cloudB = new THREE.Matrix4();
+const CLOUD_MAXR = 5.5;   // the cloud field's horizontal half-extent in sky units (h≈1); past it a cloud re-enters upwind
+const _sunDir = new THREE.Vector3();
+const _moonDir = new THREE.Vector3();
+
+function blendPhase(hour, a, b, out, t) {
+  out.sky.copy(a.sky).lerp(b.sky, t);
+  out.horizon.copy(a.horizon).lerp(b.horizon, t);
+  out.fog.copy(a.fog).lerp(b.fog, t);
+  out.sun.copy(a.sun).lerp(b.sun, t);
+  out.sunI = lerp(a.sunI, b.sunI, t);
+  out.ambI = lerp(a.ambI, b.ambI, t);
+}
+
+export class Sky {
+  constructor(scene) {
+    this.scene = scene;
+    this.hour = 10;             // start mid-morning
+    this.speed = 24 / 900;      // game-hours per real second (15-minute full day)
+
+    // THE SKY MUST FIT INSIDE THE CAMERA FAR PLANE. The dome/discs/stars were authored at
+    // 320-340m — beyond LOW's cameraFar (200m) the whole celestial rig was frustum-clipped,
+    // leaving flat fog only ("sky is just misty… no sun or moon anymore"). Scale everything
+    // to the active preset's far plane instead.
+    const q = getQuality();
+    this.skyR = Math.min(330, (q.cameraFar ?? 800) * 0.85);
+
+    // gradient dome via vertex colors on an inverted sphere
+    const geo = new THREE.SphereGeometry(340, 32, 16);
+    const colors = new Float32Array(geo.attributes.position.count * 3);
+    geo.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+    this.domeGeo = geo;
+    this.dome = new THREE.Mesh(geo, new THREE.MeshBasicMaterial({
+      vertexColors: true, side: THREE.BackSide, fog: false, depthWrite: false,
+    }));
+    this.dome.scale.setScalar(this.skyR / 340);
+    this.dome.renderOrder = -10;
+    this.dome.frustumCulled = false;
+    scene.add(this.dome);
+
+    // Clear colour behind everything. The dome only spans 340m around the player,
+    // but the terrain reaches 360m — past that edge there's no dome, so without this
+    // the bare clear colour (white/black) shows as "the end of the world". Tracking
+    // the fog colour each frame makes that gap read as more sky/haze instead.
+    scene.background = new THREE.Color(0xc3d4dd);
+
+    // stars
+    const starGeo = new THREE.BufferGeometry();
+    const n = 700, sp = new Float32Array(n * 3);
+    for (let i = 0; i < n; i++) {
+      const v = new THREE.Vector3().randomDirection();
+      v.y = Math.abs(v.y) * 0.9 + 0.1;
+      v.multiplyScalar(330);
+      sp.set([v.x, v.y, v.z], i * 3);
+    }
+    starGeo.setAttribute('position', new THREE.BufferAttribute(sp, 3));
+    this.stars = new THREE.Points(starGeo, new THREE.PointsMaterial({
+      color: 0xcfd8ff, size: 1.1, sizeAttenuation: false, transparent: true, opacity: 0, fog: false,
+    }));
+    this.stars.scale.setScalar(this.skyR / 340);   // stars fit inside the far plane too
+    this.stars.frustumCulled = false;
+    scene.add(this.stars);
+
+    // lights — shadow settings fixed at construction (see quality.js note)
+    this.sun = new THREE.DirectionalLight(0xfff1d6, 2.6);
+    this.sun.castShadow = q.shadows;
+    this.sun.shadow.mapSize.set(q.shadowSize, q.shadowSize);
+    // 55m half-extent: the 2048 map covers a quarter of the old 90m area — the
+    // shadow pass encodes ~1/4 the casters per frame (measured ~2k casters at 90)
+    // and near shadows get 2.6x the texel density. Distant tree shadows fade out
+    // past ~55m, where they were soft mush anyway.
+    const s = 55;
+    // far was 400 — casters up to 400m along the sun ray were encoded into a 110m shadow patch, i.e.
+    // a lot of geometry too far to cast a visible shadow. 170 covers the on-screen near field.
+    Object.assign(this.sun.shadow.camera, { left: -s, right: s, top: s, bottom: -s, near: 1, far: 170 });
+    this.sun.shadow.bias = -0.0004;
+    scene.add(this.sun, this.sun.target);
+
+    this.hemi = new THREE.HemisphereLight(0xbdd3e8, 0xc9b18a, 0.85); // ground bounce = desert sand, not Albion grass
+    scene.add(this.hemi);
+
+    // sun/moon discs — the sun gets a warm gold core (0xfff4cc read as pure white through the
+    // ACES tonemapper: "i see sun but its white?") + a soft halo sprite behind it
+    // depthWrite:false + renderOrder -9 (right after the dome): the discs are physically NEARER
+    // than the horizon terrain (they must fit inside the far plane), so honest depth put the
+    // setting sun IN FRONT of the hills ("sinks into the earth"). Drawn early writing no depth,
+    // the terrain paints over them — the sun now sets behind the landscape like the dome does.
+    this.sunDisc = new THREE.Mesh(
+      new THREE.SphereGeometry(7, 12, 12),
+      new THREE.MeshBasicMaterial({ color: 0xffc84f, fog: false, depthWrite: false })
+    );
+    this.sunDisc.renderOrder = -9;
+    {
+      const hv = document.createElement('canvas'); hv.width = hv.height = 128;
+      const hx = hv.getContext('2d');
+      const hg = hx.createRadialGradient(64, 64, 4, 64, 64, 63);
+      hg.addColorStop(0, 'rgba(255,196,90,0.85)');
+      hg.addColorStop(0.35, 'rgba(255,180,70,0.32)');
+      hg.addColorStop(1, 'rgba(255,170,60,0)');
+      hx.fillStyle = hg; hx.fillRect(0, 0, 128, 128);
+      this.sunHalo = new THREE.Sprite(new THREE.SpriteMaterial({
+        map: new THREE.CanvasTexture(hv), transparent: true, depthWrite: false, fog: false,
+      }));
+      this.sunHalo.scale.setScalar(46);
+      scene.add(this.sunHalo);
+    }
+    this.moonColor = new THREE.Color(0xe8edff); // story hook: set toward 0xff4038 for a demon-moon period
+    this.moonDisc = new THREE.Mesh(
+      new THREE.SphereGeometry(8, 12, 12),
+      new THREE.MeshBasicMaterial({ color: 0xe8edff, fog: false, depthWrite: false })
+    );
+    this.moonDisc.renderOrder = -9;
+    scene.add(this.sunDisc, this.moonDisc);
+
+    scene.fog = new THREE.Fog(0xc3d4dd, 60, 300);
+    this._phase = { sky: new THREE.Color(), horizon: new THREE.Color(), fog: new THREE.Color(), sun: new THREE.Color(), sunI: 1, ambI: 1 };
+
+    // ---- clouds: PROCEDURAL FBM-noise puffs on dome-anchored quads (world/clouds.js) ----
+    // Each quad is one soft cumulus built from noise — no two alike, soft evolving edges, streamed
+    // downwind on the global wind — instead of the old single radial-blob sprite (52 identical flat discs).
+    // DOME-ANCHORED (a fixed radius/bearing that follows the player, like the dome/sun): the layer fills
+    // the WHOLE sky — horizon to zenith — and can never be far-plane-clipped. Tint + opacity are driven
+    // per phase/weather below (uCloudiness leads the rain: the deck thickens BEFORE precipitation).
+    {
+      const cloud = buildCloudMaterial();
+      this.cloudMat = cloud.material; this._cloudTint = cloud.tint; this._cloudOpacity = cloud.opacity;
+      const N = 40;
+      this.clouds = new THREE.InstancedMesh(new THREE.PlaneGeometry(1, 1), this.cloudMat, N);
+      this.clouds.frustumCulled = false;
+      this.clouds.renderOrder = -5;                      // over the dome, under everything else
+      this._aSun = new THREE.InstancedBufferAttribute(new Float32Array(N), 1);   // per-cloud sun-side, for the directional shading
+      this.clouds.geometry.setAttribute('aSun', this._aSun);
+      // POSITIONS: a horizontal cloud FIELD overhead — each cloud has an (x,z) position in sky units at
+      // altitude h, and its view direction (where it sits on the dome) falls out of that, so clouds bunch
+      // toward the horizon and DRIFT WITH THE WIND (see _updateClouds). Clumped into clusters with clear
+      // sky between, a few solo strays — a real sky is patchy. Size/shape vary per cloud (+ noise freq in clouds.js).
+      this._cloud = [];
+      const CLUSTERS = 7, centers = [];
+      const scatter = (spread) => { const a = Math.random() * Math.PI * 2, rr = Math.pow(Math.random(), 1.1) * spread; return { x: Math.cos(a) * rr, z: Math.sin(a) * rr }; };
+      for (let k = 0; k < CLUSTERS; k++) centers.push(scatter(CLOUD_MAXR * 0.85));
+      for (let i = 0; i < N; i++) {
+        const solo = Math.random() < 0.26;
+        const base = solo ? scatter(CLOUD_MAXR) : centers[(Math.random() * CLUSTERS) | 0];
+        this._cloud.push({
+          x: base.x + (solo ? 0 : (Math.random() - 0.5) * 1.7),   // horizontal position (sky units) — clump jitter
+          z: base.z + (solo ? 0 : (Math.random() - 0.5) * 1.7),
+          h: 0.9 + Math.random() * 0.5,                           // altitude → higher sits higher + smaller (depth)
+          spd: 0.75 + Math.random() * 0.5,                        // per-cloud drift speed (parallax: some sail faster)
+          s: 0.15 + Math.pow(Math.random(), 1.3) * 0.5,           // angular size — bigger floor + less small-bias (Nick: too many tiny clouds)
+          wx: 0.85 + Math.random() * 0.55,                        // width — rounder
+          asp: 0.5 + Math.random() * 0.35,                        // flatness — body
+          roll: (Math.random() - 0.5) * 0.5,                      // small tilt only
+        });
+      }
+      scene.add(this.clouds);
+    }
+  }
+
+  // drift the dome-anchored clouds; tint by the current phase + WEATHER (uCloudiness leads the
+  // rain/snow: the deck swells + darkens BEFORE precipitation starts and thins after it stops)
+  _updateClouds(dt, center, p, dayness) {
+    const R = this.skyR * 0.88, m = _cloudM, q = _cloudQ, v = _cloudV;
+    const w = uCloudiness.value;
+    // DRIFT WITH THE GLOBAL WIND (wind.js writes uWindDir/uWindStr): translate the whole field along the
+    // current bearing so every cloud sails the SAME way the tumbleweeds/grass/rain lean — gusts push harder.
+    const wx = uWindDir.value.x, wz = uWindDir.value.y;
+    const drift = (0.008 + uWindStr.value * 0.014) * Math.min(dt, 0.1);   // gentle — a light breeze crosses the sky in ~10+ min, not a hurricane
+    let shx = uSunDir.value.x, shz = uSunDir.value.z; const shl = Math.hypot(shx, shz) || 1; shx /= shl; shz /= shl;   // horizontal sun bearing → which side of each cloud is lit
+    const sun = this._aSun.array;
+    for (let i = 0; i < this._cloud.length; i++) {
+      const c = this._cloud[i];
+      c.x += wx * drift * c.spd; c.z += wz * drift * c.spd;
+      if (c.x * c.x + c.z * c.z > CLOUD_MAXR * CLOUD_MAXR) {            // sailed off the leeward edge → re-enter on the WINDWARD side
+        // Respawn across the WINDWARD half of the field (outer band = mostly low on the horizon), ALWAYS
+        // inside the radius. The old math put a wide perpendicular spread OUTSIDE the field, so those
+        // clouds re-triggered the recycle every frame and only the windward strip stayed fed — which
+        // left half the sky bare (Nick). Folding a disk sample onto the windward half keeps density even.
+        const a = Math.random() * 6.2832;
+        const rr = (0.45 + 0.55 * Math.random()) * CLOUD_MAXR * 0.95;
+        let nx = Math.cos(a) * rr, nz = Math.sin(a) * rr;
+        if (nx * wx + nz * wz > 0) { nx = -nx; nz = -nz; }             // fold onto the windward half so it drifts back across the sky
+        c.x = nx; c.z = nz;
+      }
+      _cloudDir.set(c.x, c.h, c.z);
+      const L = _cloudDir.length() || 1;
+      _cloudDir.multiplyScalar(1 / L);
+      const sizeFac = Math.max(0.6, c.h / L);           // perspective: far/low clouds shrink a bit (floor 0.6 so they don't go tiny)
+      // Billboard on the sphere, but keep the quad's UP aligned to WORLD UP so wide/flat clouds stay
+      // HORIZONTAL — like real cloud banks. (setFromUnitVectors left the up arbitrary, which tilted every
+      // wide cloud to a random angle: Nick's "slash-shaped clouds at weird angles".) Basis = (right, up,
+      // faceDir); a small per-cloud roll is the only tilt.
+      _cloudRight.crossVectors(_cloudUp, _cloudDir);
+      if (_cloudRight.lengthSq() < 1e-6) _cloudRight.set(1, 0, 0);       // straight overhead: world-up ∥ view dir
+      _cloudRight.normalize();
+      sun[i] = shx * _cloudRight.x + shz * _cloudRight.z;                 // −1 sun to the cloud's left … +1 to its right
+      _cloudUp2.crossVectors(_cloudDir, _cloudRight).normalize();
+      _cloudB.makeBasis(_cloudRight, _cloudUp2, _cloudDir);
+      q.setFromRotationMatrix(_cloudB);
+      q.multiply(_cloudQ2.setFromAxisAngle(_cloudZ, c.roll));            // small tilt for variety only
+      const s = c.s * R * (1 + w * 0.7) * sizeFac;       // storm deck swells clouds; sizeFac shrinks the far/low ones for depth
+      m.compose(v.copy(center).addScaledVector(_cloudDir, R), q, _cloudS.set(s * c.wx, s * c.asp, 1));
+      this.clouds.setMatrixAt(i, m);
+    }
+    this.clouds.instanceMatrix.needsUpdate = true;
+    this._aSun.needsUpdate = true;
+    // day: white puffs; dusk: catch the phase colour; night: dim moonlit grey; storm: slate-dark
+    this._cloudTint.value.copy(WHITE).lerp(p.sky, 0.25).lerp(STORM_CLOUD, w * 0.85).multiplyScalar(lerp(0.32, 1, dayness));
+    this._cloudOpacity.value = lerp(lerp(0.5, 0.72, dayness), 0.96, w);
+  }
+
+  get isNight() { return this.hour < 4.8 || this.hour > 21.4; }
+
+  update(dt, center, moorAmount = 0) {
+    this.hour = (this.hour + dt * this.speed) % 24;
+    const h = this.hour;
+    const p = this._phase;
+
+    // phase blending: night -> dawn -> day -> dusk -> night
+    if (h < 4) blendPhase(h, NIGHT, NIGHT, p, 0);
+    else if (h < 5.5) blendPhase(h, NIGHT, DUSK, p, smoothstep(4, 5.5, h));
+    else if (h < 7.5) blendPhase(h, DUSK, DAY, p, smoothstep(5.5, 7.5, h));
+    else if (h < 19) blendPhase(h, DAY, DAY, p, 0);
+    else if (h < 20.8) blendPhase(h, DAY, DUSK, p, smoothstep(19, 20.8, h));   // golden hour while the sun drops
+    else if (h < 22.2) blendPhase(h, DUSK, NIGHT, p, smoothstep(20.8, 22.2, h)); // sun gone ~21:15 → dark by ~22
+    else blendPhase(h, NIGHT, NIGHT, p, 0);
+
+    // Gravemoor dread tint
+    if (moorAmount > 0) {
+      p.fog.lerp(MOOR_TINT, moorAmount * 0.7);
+      p.sky.lerp(MOOR_TINT, moorAmount * 0.45);
+      p.horizon.lerp(MOOR_TINT, moorAmount * 0.55);
+      p.sunI *= 1 - moorAmount * 0.35;
+    }
+
+    // OVERCAST: rain/storm greys the SKY, not just the clouds. Desaturate + darken the phase colours
+    // toward a flat slate and pull the sky down toward the horizon (an overcast sky has little top-to-
+    // bottom gradient). Weather-driven off uCloudiness (which LEADS the rain), and day/night-aware because
+    // it works from each colour's OWN luminance — a stormy night stays dark, not grey-bright. (Nick: the
+    // sky stayed light blue while it rained.)
+    const wsky = uCloudiness.value;
+    if (wsky > 0.01) {
+      const k = 0.9 * wsky;   // blend strength toward the storm slate
+      for (const col of [p.sky, p.horizon, p.fog]) {
+        const l = col.r * 0.3 + col.g * 0.59 + col.b * 0.11;   // this colour's OWN luminance (keeps it day/night-aware)
+        const t = l * 0.27 + 0.035;                            // a DARK neutral target ~0.27× the luminance
+        col.lerp(_grey.setRGB(t, t, t), k);
+        // then KILL the residual blue — the day sky's blue channel is so high a plain lerp leaves it tinted,
+        // and a storm sky is a neutral GREY, not blue. Pull each channel toward the colour's mean.
+        const m = (col.r + col.g + col.b) / 3;
+        col.r += (m - col.r) * 0.6 * wsky; col.g += (m - col.g) * 0.6 * wsky; col.b += (m - col.b) * 0.6 * wsky;
+      }
+      p.sky.lerp(p.horizon, 0.4 * wsky);   // flatten the dome gradient
+    }
+
+    // dome colors — recompute only when light meaningfully changes (~every
+    // few game-minutes), not per frame: this loop touches ~560 vertices.
+    const domeKey = `${h.toFixed(1)}:${moorAmount.toFixed(1)}:${(uCloudiness.value * 20) | 0}`;
+    if (domeKey !== this._domeKey) {
+      this._domeKey = domeKey;
+      const pos = this.domeGeo.attributes.position;
+      const col = this.domeGeo.attributes.color;
+      const c = new THREE.Color();
+      for (let i = 0; i < pos.count; i++) {
+        const t = clamp(pos.getY(i) / 340, -0.1, 1);
+        c.copy(p.horizon).lerp(p.sky, smoothstep(0, 0.55, t));
+        col.setXYZ(i, c.r, c.g, c.b);
+      }
+      col.needsUpdate = true;
+    }
+
+    // sun orbit: a SOUTHERN arc (alt-Britain sits at UK latitude — the sun never reaches the
+    // zenith; it crosses the southern sky at ~55° max). The old orbit put noon straight overhead,
+    // where no camera ever looks ("I see clouds but no sun") and the cloud deck sat in front of it.
+    // asymmetric day: above the horizon 05:00-21:00 (British summer), below overnight — Nick's
+    // spec: the sun shouldn't touch the horizon until ~20:30 and should be fully gone by ~21:30.
+    const SUNRISE = 5, SUNSET = 21, dayLen = SUNSET - SUNRISE;
+    const ang = (h >= SUNRISE && h < SUNSET)
+      ? ((h - SUNRISE) / dayLen) * Math.PI
+      : Math.PI + (((h - SUNSET + 24) % 24) / (24 - dayLen)) * Math.PI;
+    const sunDir = _sunDir.set(Math.cos(ang) * 0.55, Math.sin(ang) * 0.8, Math.cos(ang) * 0.3 + 0.5).normalize();
+    const dayness = smoothstep(-0.12, 0.12, sunDir.y);
+    this.dayness = dayness; // 0 = night, 1 = day — read by the renderer for night exposure dimming
+    uDayness.value = dayness; // shared TSL uniform — unlit impostor materials dim toward moonlit blue at night
+    uSkyCol.value.copy(p.sky); uHorizonCol.value.copy(p.horizon); // water fresnel reflections track the sky phases
+
+    // after sundown the directional light swings to the MOON's direction (opposite orbit,
+    // above the horizon) — following the sun below ground lit surfaces from underneath,
+    // i.e. moonless pitch-black nights
+    // The moon runs its own LOW arc (~31° elevation) instead of mirroring the sun through
+    // the zenith — near midnight the mirrored direction is straight up, where no camera
+    // ever looks ("there is literally no moon in the sky"). Azimuth mirrors the sun's
+    // horizontal bearing, blending to a fixed SSE anchor when that bearing vanishes.
+    let mx = -sunDir.x, mz = -sunDir.z;
+    const ml = Math.hypot(mx, mz), mk = Math.min(1, ml / 0.3);
+    mx = (ml > 1e-4 ? mx / ml : 0) * mk + 0.35 * (1 - mk);
+    mz = (ml > 1e-4 ? mz / ml : 0) * mk + 0.85 * (1 - mk);
+    const mxz = Math.hypot(mx, mz) || 1;
+    const MOON_EL = 0.55; // radians above the horizon
+    const moonDir = _moonDir.set((mx / mxz) * Math.cos(MOON_EL), Math.sin(MOON_EL), (mz / mxz) * Math.cos(MOON_EL));
+    const lightDir = sunDir.y >= -0.05 ? sunDir : moonDir;
+    uSunDir.value.copy(lightDir); // shared TSL uniform — grass backlight follows the key light
+    this.sun.position.copy(center).addScaledVector(lightDir, 140);
+    this.sun.target.position.copy(center);
+    this.sun.color.copy(NIGHT.sun).lerp(p.sun, dayness);   // EASE the key-light colour across the horizon crossing — the old hard `dayness>0.5` switch snapped the ground colour in one frame at ~sunset (Nick: "at 9:15 the ground colour changed in a blink")
+    this.sun.intensity = lerp(NIGHT.sunI, p.sunI, dayness);
+
+    this.hemi.intensity = p.ambI * 1.5; // desert lift: dark western wood crushed to black at Albion ambient levels
+    this.hemi.color.copy(p.sky).lerp(WHITE, 0.4);
+
+    const discR = this.skyR * 0.94;   // inside the dome AND the far plane (LOW clips past 200m)
+    this.sunDisc.position.copy(center).addScaledVector(sunDir, discR);
+    this.sunDisc.visible = sunDir.y > -0.05;
+    this.sunHalo.position.copy(center).addScaledVector(sunDir, discR * 0.99);
+    this.sunHalo.visible = this.sunDisc.visible;
+    this.sunHalo.material.opacity = lerp(0.25, 0.85, dayness);
+    this.moonDisc.position.copy(center).addScaledVector(moonDir, discR);
+    this.moonDisc.visible = sunDir.y < 0.1;
+    this.moonDisc.material.color.copy(this.moonColor);
+
+    this.stars.material.opacity = 1 - dayness;
+
+    this.scene.fog.color.copy(p.fog);
+    if (this.scene.background?.copy) this.scene.background.copy(p.fog); // void past the world edge = sky/haze, not white
+    const fogScale = this.fogScale ?? 1;
+    this.scene.fog.near = lerp(26, 70, 1 - moorAmount * 0.7) * fogScale;
+    this.scene.fog.far = lerp(120, 320, (1 - moorAmount * 0.55) * lerp(0.6, 1, dayness)) * fogScale;   // storm fog is pulled in by weather.js (uCloudiness) after this — no rain factor needed here
+
+    // keep dome/stars centred on the player
+    this.dome.position.copy(center);
+    this.stars.position.copy(center);
+
+    this._updateClouds(dt, center, p, dayness);
+  }
+}

package/src/world/tileManager.js

@@ -0,0 +1,197 @@
+// Phase-2 static-env tile streaming: RESIDENT scatter meshes. Every spec owns ONE resident
+// InstancedMesh set for the life of the app (built empty on the loading screen, capacity = the
+// max any 5×5 tile window can hold); tiles stream by WRITING slices of the instance buffers +
+// counts — no meshes are ever created, destroyed or re-parented at tile boundaries. That churn
+// was the proven 150-500ms travel hitch: r184 WebGPU pays ~3 pipeline-cache entries per new
+// InstancedMesh OBJECT even with fully shared geometry/material/texture. Terrain stays one
+// analytic plane (heightAt, untouched). NEVER touches skinned meshes (player/NPCs/horses are
+// resident-for-life too). Fed deterministic {pl, ensure, write, free} specs from the zones
+// manifest, so a tile rebuilds identically whenever it's revisited.
+import { buildBVH, buildBVHAsync } from './collision.js';
+
+const TILE = 180;     // metres; must match the manifest bucketing in zones.js
+const RADIUS = 2;     // 5×5 active set → nearest unloaded tile edge = 2*TILE = 360m > 320m max fog
+const keyOf = (tx, tz) => tx * 100003 + tz;
+// same exclusions as the monolithic world BVH (world.js): fences/flowers/paving/grass don't collide.
+const COLLIDE_EXCLUDE = /fence|flower|path|brick|ground|floor|grass/i;
+
+export class TileField {
+  constructor(scene, specs, { colliders = [] } = {}) {
+    this._colliders = colliders;   // the game's live collider array — spliced on tile free
+    this.scene = scene;
+    this.specs = specs;
+    // bucket every spec's placements by tile → tileKey: [{ spec, sub:[placements in this tile] }]
+    this.buckets = new Map();
+    for (const spec of specs) {
+      const byTile = new Map();
+      for (const p of spec.pl) {
+        const k = keyOf(Math.floor(p.x / TILE), Math.floor(p.z / TILE));
+        let arr = byTile.get(k); if (!arr) byTile.set(k, (arr = []));
+        arr.push(p);
+      }
+      for (const [k, sub] of byTile) {
+        let arr = this.buckets.get(k); if (!arr) this.buckets.set(k, (arr = []));
+        arr.push({ spec, sub });
+      }
+    }
+    this.loaded = new Map();   // tileKey → { disposed, bvh, bvhBuilding, tileCols, specs, lodCol }
+    this.queue = [];           // tileKeys awaiting build, nearest-first
+    this.bvhQueue = [];        // built tiles awaiting their (heavy) collision BVH — one per frame
+    this._cur = null;          // last player tile, for crossing detection
+  }
+
+  // Build every spec's RESIDENT mesh set (empty) on the loading screen. Capacity per spec = the
+  // max instances any 5×5 window of ITS tiles can hold (windows centred outside a spec's tile
+  // bbox are dominated by the per-axis-clamped centre, so scanning the bbox is exact). This is
+  // also the boot-time prefetch of every far-biome FBX/LOD-glb/impostor-JSON/texture — the role
+  // the old warmAllTypes played — and it instantiates every cached tier material, so the boot
+  // warm render (main.js warmRenderHidden) compiles every scatter pipeline before play.
+  // MUST run BEFORE buildInitial, and AFTER the world-BVH bake (getLODColliderGroups reads
+  // lodGroups entry counts — resident entries register empty, so the bake stays clean either way).
+  async buildResidents() {
+    const t0 = performance.now();
+    let totalCap = 0, built = 0;
+    await Promise.all(this.specs.map(async (spec) => {
+      const byTile = new Map();
+      let minx = Infinity, maxx = -Infinity, minz = Infinity, maxz = -Infinity;
+      for (const p of spec.pl) {
+        const tx = Math.floor(p.x / TILE), tz = Math.floor(p.z / TILE);
+        const k = tx + ',' + tz;
+        byTile.set(k, (byTile.get(k) ?? 0) + 1);
+        if (tx < minx) minx = tx; if (tx > maxx) maxx = tx;
+        if (tz < minz) minz = tz; if (tz > maxz) maxz = tz;
+      }
+      let cap = 0;
+      for (let cx = minx; cx <= maxx; cx++) for (let cz = minz; cz <= maxz; cz++) {
+        let s = 0;
+        for (let i = -RADIUS; i <= RADIUS; i++) for (let j = -RADIUS; j <= RADIUS; j++) s += byTile.get((cx + i) + ',' + (cz + j)) ?? 0;
+        if (s > cap) cap = s;
+      }
+      const h = await spec.ensure(cap);
+      if (h?.group) { this.scene.add(h.group); built++; totalCap += cap; }
+    }));
+    console.log(`[resident] ${built}/${this.specs.length} scatter specs resident in ${Math.round(performance.now() - t0)}ms · Σ window capacity ${totalCap} instances`);
+  }
+
+  update(px, pz) {
+    const tx = Math.floor(px / TILE), tz = Math.floor(pz / TILE);
+    if (!this._cur || this._cur.tx !== tx || this._cur.tz !== tz) {
+      this._cur = { tx, tz };
+      const desired = new Set();
+      for (let i = -RADIUS; i <= RADIUS; i++) for (let j = -RADIUS; j <= RADIUS; j++) desired.add(keyOf(tx + i, tz + j));
+      // dispose tiles that left the active set FIRST — frees their slices, so the incoming
+      // ring can never overflow the window-sized resident buffers
+      for (const k of [...this.loaded.keys()]) if (!desired.has(k)) this._dispose(k);
+      // (re)build the build queue, nearest ring first, only tiles that have content + aren't live
+      this.queue = [];
+      for (let r = 0; r <= RADIUS; r++) for (let i = -r; i <= r; i++) for (let j = -r; j <= r; j++) {
+        if (Math.max(Math.abs(i), Math.abs(j)) !== r) continue; // only the cells on ring r
+        const k = keyOf(tx + i, tz + j);
+        if (this.buckets.has(k) && !this.loaded.has(k)) this.queue.push(k);
+      }
+    }
+    if (this.queue.length) this._build(this.queue.shift()); // one tile per update — frame-spread
+    // deferred collision: dispatch finished tiles' BVH builds to the WORKER (off-thread). The build
+    // itself (~30-80ms, the old town streaming hitch) no longer runs on the main thread — all we do
+    // here is gather matrices + post. Throttle to a couple of dispatches/frame to keep that gather cheap.
+    let dispatched = 0;
+    while (this.bvhQueue.length && dispatched < 2) {
+      const live = this.bvhQueue.shift();
+      if (live.disposed || live.bvh || live.bvhBuilding) continue;
+      live.bvhBuilding = true;
+      this._buildCollidersAsync(live);
+      dispatched++;
+    }
+  }
+
+  // Build the spawn neighbourhood up front (awaited), during the loading screen, so the player never
+  // drops into an empty world. Same 5×5 set as update() but built all at once, not frame-spread.
+  // Disposes any tiles outside the target window first, so a teleport/save-load re-seat can call it
+  // without overflowing the resident slice tables.
+  async buildInitial(px, pz) {
+    const tx = Math.floor(px / TILE), tz = Math.floor(pz / TILE);
+    this._cur = { tx, tz };
+    const desired = new Set();
+    for (let i = -RADIUS; i <= RADIUS; i++) for (let j = -RADIUS; j <= RADIUS; j++) desired.add(keyOf(tx + i, tz + j));
+    for (const k of [...this.loaded.keys()]) if (!desired.has(k)) this._dispose(k);
+    const builds = [];
+    for (const k of desired) {
+      if (this.buckets.has(k) && !this.loaded.has(k)) builds.push(this._build(k));
+    }
+    await Promise.all(builds);
+    // build the spawn ring's colliders up front (we're on the loading screen — no frame budget needed)
+    for (const live of this.bvhQueue) if (!live.disposed) this._buildColliders(live);
+    this.bvhQueue.length = 0;
+  }
+
+  // Stream a tile IN: write each spec's placement slice into its resident buffers. Pure typed-array
+  // writes — no meshes, no scene-graph changes, no frame yields needed (a whole tile is well under
+  // a millisecond once residents exist; the awaits only suspend during boot's asset loads).
+  async _build(k) {
+    if (this.loaded.has(k) || !this.buckets.has(k)) return;
+    const live = { disposed: false, bvh: null, bvhBuilding: false, tileCols: [], specs: [], lodCol: [] };
+    this.loaded.set(k, live);            // claim immediately so a re-enqueue can't double-build
+    for (const { spec, sub } of this.buckets.get(k)) {
+      let bvhMats = null;
+      try { bvhMats = await spec.write(k, sub, (c) => live.tileCols.push(c)); } catch (e) { bvhMats = null; console.warn(`[tiles] spec '${spec.name ?? '?'}' write failed for tile ${k} — props + collision missing there`, e?.message ?? e); }
+      if (live.disposed) { spec.free(k); continue; } // tile left mid-build (boot-time await) → back out
+      live.specs.push(spec);
+      const h = spec.handle?.();
+      if (bvhMats && h?.colliderGeometry && !COLLIDE_EXCLUDE.test(h.colliderName || '')) {
+        // LOD chains + plain scatter collide via LOD0 geometry × the FULL tile instance set
+        // (never the live LOD-bucketed count); the per-tile matrix copy survives slice compaction.
+        live.lodCol.push({ name: h.colliderName, geometry: h.colliderGeometry, matrices: bvhMats, count: sub.length });
+      }
+    }
+    if (!live.disposed) this.bvhQueue.push(live); // defer BVH → update() dispatches to the worker
+  }
+
+  // Stream a tile OUT: free each spec's slice (compaction inside the resident entry). No scene
+  // or mesh changes — the render list is untouched by boundary crossings.
+  _dispose(k) {
+    const live = this.loaded.get(k);
+    if (!live) return;
+    this.loaded.delete(k);
+    live.disposed = true;                // any in-flight build for this tile will bail + back out
+    for (const spec of live.specs) { try { spec.free(k); } catch { /* spec never resolved */ } }
+    live.specs.length = 0;
+    live.lodCol.length = 0;
+    live.bvh?.geometry?.dispose?.(); live.bvh = null; // three-mesh-bvh doesn't auto-dispose its geometry
+    if (live.tileCols?.length) {   // drop this tile's 2D trunk circles from the global list (else re-entry duplicates them forever)
+      const rm = new Set(live.tileCols);
+      const cs = this._colliders;
+      for (let i = cs.length - 1; i >= 0; i--) if (rm.has(cs[i])) cs.splice(i, 1);
+      live.tileCols.length = 0;
+    }
+  }
+
+  // Synchronous BVH — only for the spawn ring at boot (loading screen, no frame budget to protect).
+  _buildColliders(live) {
+    if (live.lodCol.length) { try { live.bvh = buildBVH([], live.lodCol); } catch { live.bvh = null; } }
+  }
+
+  // Off-main-thread BVH (bvhWorker.js) — for runtime streamed tiles, so the build never blocks a frame.
+  // The tile collides as soon as the worker returns (a frame or two later); until then forEachBVHNear
+  // simply skips it (bvh null), which is imperceptible.
+  _buildCollidersAsync(live) {
+    if (!live.lodCol.length) { live.bvhBuilding = false; return; }
+    buildBVHAsync([], live.lodCol).then((bvh) => {
+      live.bvhBuilding = false;
+      if (live.disposed) { bvh?.geometry?.dispose?.(); return; } // tile left while building → toss it
+      if (bvh) live.bvh = bvh;
+    }).catch(() => { live.bvhBuilding = false; });
+  }
+
+  // Run cb(bvh) for every loaded tile near (x,z) — the tile containing it + its 8 neighbours, so a
+  // capsule straddling a boundary still sees both sides' colliders. world._capsuleStep uses this.
+  forEachBVHNear(x, z, cb) {
+    const tx = Math.floor(x / TILE), tz = Math.floor(z / TILE);
+    for (let i = -1; i <= 1; i++) for (let j = -1; j <= 1; j++) {
+      const live = this.loaded.get(keyOf(tx + i, tz + j));
+      if (live?.bvh) cb(live.bvh);
+    }
+  }
+
+  // diagnostics
+  info() { return { loaded: this.loaded.size, tiles: this.buckets.size, queued: this.queue.length, specs: this.specs.length }; }
+}

package/src/world/walkHumps.js

@@ -0,0 +1,74 @@
+// ── WALK-OVER GROUND DRESSING — the analytic lift under every dust pile ─────────────────────────
+//
+// The dust piles (SM_Env_DustPile_*) are resFlat ground dressing: their colliders are named
+// `scatterGround:` and the tile BVH bake drops them by NAME (tileManager COLLIDE_EXCLUDE), which
+// is RIGHT — a BVH full of pebbles stops horses — but it left every walker clipping THROUGH the
+// one piece of dressing tall enough to read as ground. Nick, verbatim: "yeah they need to walk
+// over them too".
+//
+// So the piles are terrain now, analytically: world.groundAt returns heightAt + humpLift, and
+// humpLift is a rotated elliptical dome per pile, derived from the SAME placement rows the
+// renderer draws (zones.js registers them at boot, identically on the cooked and computed paths —
+// no cook data moves). ONE seam lifts everything that walks: the player capsule's terrain floor,
+// the NPCs and children, the ambient horses, the travellers and the herds all read world.groundAt.
+// And a lift can never BLOCK movement — it is a floor, not a wall.
+//
+// The coach and the train read ground too, but the placement law keeps piles ≥6 m (town) / ≥8 m
+// (desert) off every road centreline and their lanes run at ±1.15 / ±3.6 m — no pile can reach a
+// wheel-line. No special case needed.
+//
+// PERF LAW: fixed 16 m grid over the placements, numeric cell keys, flat number rows — ZERO
+// allocation per query, and the common case (no pile within reach) exits on an empty cell.
+
+// Footprint half-extents (x, z) and bbox apex, measured off the GLBs (probe: gltf-transform bbox).
+// The apex rides above the −0.08 m seat placementField sinks every pile by.
+const DIMS = {
+  SM_Env_DustPile_Large_01: [5.66, 5.66, 0.82],
+  SM_Env_DustPile_Small_02: [1.35, 1.41, 0.82],
+  SM_Env_DustPile_Small_01: [1.29, 1.42, 0.54],
+  SM_Env_DustPile_Small_04: [0.37, 0.45, 0.22],
+  SM_Env_DustPile_Long_02: [2.98, 1.0, 0.62],
+};
+const SEAT = 0.08;          // placementField seats piles at heightAt − 0.08
+const CELL = 16, HALF = 512;
+const key = (cx, cz) => (cx + HALF) * 4096 + (cz + HALF);
+const _grid = new Map();    // int key → flat rows [x, z, cos, sin, 1/rx, 1/rz, apex] × n
+
+export function registerHumps(file, placements) {
+  const dims = DIMS[file];
+  if (!dims) throw new Error(`[walkHumps] no dome dims for ${file} — measure the GLB and add it to DIMS`);
+  for (const p of placements) {
+    const rx = dims[0] * p.s, rz = dims[1] * p.s, h = dims[2] * p.s - SEAT;
+    if (h <= 0.05) continue;                     // a 5 cm mound is texture, not terrain
+    const c = Math.cos(p.ry), s = Math.sin(p.ry);
+    const r = Math.max(rx, rz);
+    for (let cx = Math.floor((p.x - r) / CELL); cx <= Math.floor((p.x + r) / CELL); cx++)
+      for (let cz = Math.floor((p.z - r) / CELL); cz <= Math.floor((p.z + r) / CELL); cz++) {
+        const k = key(cx, cz);
+        let cell = _grid.get(k);
+        if (!cell) _grid.set(k, cell = []);
+        cell.push(p.x, p.z, c, s, 1 / rx, 1 / rz, h);
+      }
+  }
+}
+
+// The dome: apex·(1−d²)^1.5 in the pile's rotated elliptical frame — a fair read of the Synty
+// mound's profile — and the MAX over overlapping piles, never the sum (two piles half-merged are
+// one lump of dirt, not a tower).
+export function humpLift(x, z) {
+  const cell = _grid.get(key(Math.floor(x / CELL), Math.floor(z / CELL)));
+  if (!cell) return 0;
+  let lift = 0;
+  for (let i = 0; i < cell.length; i += 7) {
+    const dx = x - cell[i], dz = z - cell[i + 1];
+    const c = cell[i + 2], s = cell[i + 3];
+    const u = (dx * c - dz * s) * cell[i + 4];   // world → pile frame (undo rotation.y = ry)
+    const v = (dx * s + dz * c) * cell[i + 5];
+    const d2 = u * u + v * v;
+    if (d2 >= 1) continue;
+    const k = 1 - d2;
+    const l = cell[i + 6] * k * Math.sqrt(k);
+    if (l > lift) lift = l;
+  }
+  return lift;
+}