sindicate 0.1.0 → 0.4.0

package/src/systems/footsteps.js

@@ -0,0 +1,161 @@
+// Player footsteps: surface-aware step sounds fired when a FOOT actually PLANTS — detected from the
+// ankle bone reaching its lowest point in the walk/run cycle. This syncs the SFX to the animation's
+// footfalls and paces the cadence off the clip (not world speed, which was firing them far too fast).
+// Real recordings (cplomedia Footsteps pack) via audio.loadSamples/sample. Six surfaces × six variants.
+import * as THREE from 'three/webgpu';
+// register the road query before surface classification: setFootstepTerrain({ roadDistance })
+let FT = { roadDistance: () => 1e9 };
+export function setFootstepTerrain(t) { FT = { ...FT, ...t }; }
+
+const _fv = new THREE.Vector3();
+
+const SURFACES = ['grass', 'stone', 'earth', 'snow', 'mud', 'water'];
+const VARIANTS = 6;
+
+export class Footsteps {
+  constructor(game) {
+    this.game = game;
+    this._loaded = false;
+    this._lastN = 0;
+    this._feetCache = undefined;   // {L,R} ankle bones once resolved, or null if the rig lacks them
+  }
+
+  // Find the two ankle/foot bones — resolved from the mixer's DRIVEN nodes. The hero model
+  // carries ~117 duplicate outfit-part skeletons; a name traverse lands on an undriven orphan
+  // whose world-Y never cycles with the walk, so plants only fired off terrain-bob noise
+  // (the one-sound-every-5-steps bug). This rig's ankle is Ball_L/R (UpperLeg→LowerLeg→Ball→Toes).
+  _feet() {
+    if (this._feetCache) return this._feetCache;
+    const p = this.game.player;
+    if (!p?.model || !p.animator?.mixer) return null;
+    let L = null, R = null, fL = null, fR = null;
+    for (const pm of p.animator.mixer._bindings ?? []) {
+      const n = pm.binding?.node;
+      if (!n) continue;
+      if (!L && n.name === 'Ball_L') L = n;
+      if (!R && n.name === 'Ball_R') R = n;
+      const low = n.name.toLowerCase();
+      if (/(twist|roll)/.test(low) || !/(ankle|foot)/.test(low)) continue;
+      if (!fL && /(_l\b|left)/.test(low)) fL = n;
+      else if (!fR && /(_r\b|right)/.test(low)) fR = n;
+    }
+    L = L ?? fL; R = R ?? fR;
+    if (!L || !R) return null;   // bindings appear once clips play — retry next frame, never cache failure
+    this._feetCache = { L, R };
+    return this._feetCache;
+  }
+
+  _load() {
+    this._loaded = true;
+    const F = '/assets/audio/footsteps';
+    const map = {};
+    for (const s of SURFACES) for (let i = 1; i <= VARIANTS; i++) map[`${s}${i}`] = `${F}/${s}${i}.wav`;
+    this.game.audio?.loadSamples(map);
+  }
+
+  // What is the hero standing on? A desert plain: wading water (the creek) > packed
+  // main-street dirt (stone set reads hard-packed) > open sand (earth — no sand set ships).
+  surfaceAt(x, z) {
+    // a coach roof is boards, and there is no board set: 'stone' is the hard-packed one (SURFACES)
+    const d = this.game.player?.platform;
+    if (d) return d.deck.surface ?? 'stone';
+    return groundSurface(this.game, x, z);
+  }
+
+  // Called every frame while the hero is on foot. `moving`/`running` come from the locomotion FSM.
+  // Fires a step at each foot-plant (local minimum of that ankle's world Y), so the SFX lands exactly
+  // when the foot meets the ground and the cadence matches the walk/run clip.
+  update(dt, moving, running) {
+    const a = this.game.audio;
+    if (!a || !a.ctx) return;               // audio context not unlocked yet
+    if (!this._loaded) this._load();
+    const p = this.game.player;
+    const feet = this._feet();
+    if (!moving || p.airborne || !feet) {   // reset tracking so re-entry doesn't fire a stale plant
+      this._pyL = this._pyR = undefined; this._pvL = this._pvR = 0;
+      return;
+    }
+    // the floor he is ACTUALLY on — on a coach roof the heightfield is 2.7m of nonsense, and the
+    // rolling floor below only climbs 0.3 m/s, so his steps would go silent for nine seconds
+    const groundY = p.platform ? p.position.y : this.game.world.groundAt(p.position.x, p.position.z);
+    for (const side of ['L', 'R']) {
+      // height RELATIVE to the ground — world-Y minima drift with terrain slope, so on
+      // uphill runs each plant landed "too high" for the rolling floor and got skipped
+      // (the reason snow-country steps still fired sparsely: it's all hills up there)
+      const y = feet[side].getWorldPosition(_fv).y - groundY;
+      const py = this['_py' + side];
+      if (py === undefined) { this['_py' + side] = y; this['_pv' + side] = 0; this['_my' + side] = y; continue; }
+      // velocities in m/s (NOT per-frame deltas — those shrank below the noise floor at
+      // 120Hz and the plant test missed most footfalls)
+      const v = (y - py) / Math.max(dt, 1e-4), pv = this['_pv' + side];
+      this['_py' + side] = y; this['_pv' + side] = v;
+      this['_ct' + side] = Math.max(0, (this['_ct' + side] ?? 0) - dt);
+      // rolling floor: the foot's lowest recent Y, decaying upward so it tracks terrain.
+      // Only a bottom-out NEAR the floor is a plant — the mid-foot Ball bone also dips at
+      // push-off (higher), which double-fired every stride.
+      const my = Math.min((this['_my' + side] ?? y) + 0.3 * dt, y);
+      this['_my' + side] = my;
+      if (pv < -0.15 && v >= -0.03 && y <= my + 0.045 && this['_ct' + side] === 0) {
+        this['_ct' + side] = 0.22;
+        this._step(running);
+      }
+    }
+  }
+
+  _step(running) {
+    const p = this.game.player;
+    const surf = this.surfaceAt(p.position.x, p.position.z);
+    let n = 1 + ((Math.random() * VARIANTS) | 0);
+    if (n === this._lastN) n = (n % VARIANTS) + 1;   // no immediate repeat
+    this._lastN = n;
+    const gain = (running ? 0.5 : 0.34) * (0.85 + Math.random() * 0.3);
+    const rate = 0.94 + Math.random() * 0.12;        // slight pitch jitter per step
+    this.game.audio.sample(`${surf}${n}`, { gain, rate });
+  }
+}
+
+// Ground surface at a point, WITHOUT the player's coach-roof special-case — for NPC/ambient footsteps.
+export function groundSurface(game, x, z) {
+  const w = game.world;
+  if ((w.waterDepthAt?.(x, z) ?? 0) > 0.15) return 'water';
+  if (FT.roadDistance(x, z) < 2.6) return 'stone';   // Dustwater's packed main street
+  return 'earth';                                  // sand/dirt everywhere else
+}
+
+// AMBIENT NPC FOOTSTEPS. The player's plant-accurate bone tracking is far too dear for 132 souls, so this
+// is one cheap central pass a frame: find the WALKING NPCs within earshot, take the nearest few, and step
+// them on a speed-derived cadence, distance-attenuated. Reuses the footstep samples the player already
+// loaded, and the audio's gain hook. "Walking" is read from a POSITION DELTA, not the walk clip — an NPC
+// behind you is frustum-culled (animator skipped, clip stale) but its position still integrates, so you
+// still hear it pass. No stereo pan (the whole SFX bus is mono today), just distance falloff.
+export class NpcFootsteps {
+  constructor(game) { this.game = game; }
+  update(dt) {
+    const a = this.game.audio, p = this.game.player;
+    if (!a?.ctx || !p || dt <= 0) return;
+    const R = 13, MAX = 7, near = [];
+    for (const n of this.game.npcs ?? []) {
+      if (!n.alive) { if (n._fsX !== undefined) n._fsX = undefined; continue; }
+      const d = Math.hypot(n.position.x - p.position.x, n.position.z - p.position.z);
+      if (d > R) { n._fsX = undefined; n._fsT = undefined; continue; }   // out of earshot: forget its stride
+      const lx = n._fsX, lz = n._fsZ; n._fsX = n.position.x; n._fsZ = n.position.z;
+      if (lx === undefined) continue;                                    // first frame in range — no delta yet
+      const spd = Math.hypot(n.position.x - lx, n.position.z - lz) / dt;
+      if (spd < 0.5) { n._fsT = undefined; continue; }                   // standing / idling — no steps
+      near.push({ n, d, spd });
+    }
+    if (!near.length) return;
+    near.sort((u, v) => u.d - v.d);                                      // only the closest few are voiced
+    const lim = Math.min(near.length, MAX);
+    for (let i = 0; i < lim; i++) {
+      const { n, d, spd } = near[i];
+      n._fsT = (n._fsT ?? Math.random() * 0.35) - dt;
+      if (n._fsT > 0) continue;
+      n._fsT = Math.max(0.26, Math.min(0.62, 0.7 / spd)) * (0.88 + Math.random() * 0.24);   // stride from speed
+      const surf = groundSurface(this.game, n.position.x, n.position.z);
+      const gain = (1 - d / R) * (spd > 3 ? 0.3 : 0.2) * (0.85 + Math.random() * 0.3);
+      const k = 1 + ((Math.random() * VARIANTS) | 0);
+      a.sample(`${surf}${k}`, { gain, rate: 0.93 + Math.random() * 0.14 });
+    }
+  }
+}

package/src/systems/glass.js

@@ -0,0 +1,67 @@
+// THE DRINK — a saloon cup (SM_Prop_Cup_01) with a liquid whose level DROPS as it's drunk, ported from
+// the Kiwi bar (Assets/Shaders/BeerGlass.shader + BeerGlassController.cs: fillLevel 0..1, drinkAmount ~0.15,
+// Empty/Fill/TakeDrink). Kiwi coloured a fixed liquid mesh by fragment Y; here we just SCALE a liquid
+// cylinder from its base + ride a foam disc on top — same "content goes down in levels" read, far simpler
+// and rock-solid. The cup is sized at runtime from its own bbox so the liquid always fits inside it.
+import * as THREE from 'three/webgpu';
+import { loadGLB, loadTexture } from '../core/assets.js';
+
+const DRINK_AMOUNT = 0.15;     // fill consumed per swig (Kiwi's default)
+const EMPTY_AT = 0.08;         // below this it reads as empty
+const CHAR_TEX = '/assets/textures/atlas_western.png';
+const LIQUID_COLOR = 0xcaa33e; // amber whiskey/beer
+const FOAM_COLOR = 0xf3e6c4;
+
+let _cupGlb = null, _atlas = null;
+export async function initGlass() {
+  if (_cupGlb) return;
+  [_cupGlb, _atlas] = await Promise.all([
+    loadGLB('/assets/western/SM_Prop_Cup_01.glb'),
+    loadTexture(CHAR_TEX, { flipY: false }),
+  ]);
+}
+
+export class DrinkGlass {
+  constructor() {
+    this.group = new THREE.Group();
+    this._fill = 1;
+    // cup
+    this.cup = _cupGlb.clone();
+    this.cup.traverse((o) => { if (o.isMesh && o.material) { o.material = o.material.clone(); o.material.map = _atlas; o.material.needsUpdate = true; } });
+    this.group.add(this.cup);
+    // measure the cup so the liquid sits INSIDE it (a touch in from the rim, a touch up from the base)
+    const bb = new THREE.Box3().setFromObject(this.cup);
+    const size = bb.getSize(new THREE.Vector3());
+    const r = Math.min(size.x, size.z) * 0.5 * 0.82;      // inner radius
+    this._base = bb.min.y + size.y * 0.06;                 // liquid floor
+    this._colH = size.y * 0.80;                            // full-liquid column height
+    // liquid: a cylinder pinned at its BASE (translate up by 0.5 so scale.y grows from the bottom)
+    const liqGeo = new THREE.CylinderGeometry(r, r * 0.92, 1, 20, 1, true).translate(0, 0.5, 0);
+    this.liquid = new THREE.Mesh(liqGeo, new THREE.MeshStandardNodeMaterial({ color: LIQUID_COLOR, roughness: 0.25, metalness: 0.0 }));
+    this.liquid.position.y = this._base;
+    this.group.add(this.liquid);
+    // foam: a thin disc that rides the liquid surface
+    const foamGeo = new THREE.CylinderGeometry(r * 1.005, r * 1.005, 0.006, 20).translate(0, 0.003, 0);
+    this.foam = new THREE.Mesh(foamGeo, new THREE.MeshStandardNodeMaterial({ color: FOAM_COLOR, roughness: 0.6 }));
+    this.group.add(this.foam);
+    this._apply();
+  }
+
+  get fill() { return this._fill; }
+  set fill(v) { this._fill = THREE.MathUtils.clamp(v, 0, 1); this._apply(); }
+  get isEmpty() { return this._fill <= EMPTY_AT; }
+  get isFull() { return this._fill >= 0.95; }
+
+  _apply() {
+    const h = this._colH * this._fill;
+    this.liquid.scale.y = Math.max(0.0001, h);
+    const top = this._base + h;
+    this.foam.position.y = top;
+    const show = this._fill > 0.001;
+    this.liquid.visible = show; this.foam.visible = show;
+  }
+
+  drink(amount = DRINK_AMOUNT) { this.fill = this._fill - amount; return this.isEmpty; }
+  fillUp() { this.fill = 1; }
+  empty() { this.fill = 0; }
+}

package/src/systems/herd.js

@@ -0,0 +1,277 @@
+// A Herd: every individual of one species rendered as ONE InstancedMesh (VAT-animated — see vat.js)
+// with cheap per-instance AI: idle / graze / wander inside a home radius, and bolt from the player.
+// Terrain-follow only, no BVH. Resident-for-life: built on the loading screen, never added or removed.
+//
+// This is the cheap way to fill a county that just quadrupled in area — one draw call per species and
+// no animator on the CPU at all.
+//
+// PORTED FROM /Users/nick/Sites/fable/src/game/herd.js WITH TWO FIXES, AND THEY ARE NOT OPTIONAL.
+// Fable's version is written for a world where every herd is near the player. Ours are spread over
+// 18.66 km². Shipped as-is, it costs what it should not:
+//
+//   1. IT NEVER FRUSTUM-CULLS. fable sets `mesh.frustumCulled = false`, so all 24 herds are submitted
+//      every frame from anywhere in the county. Fixed by giving each herd a REAL bounding sphere
+//      (anchor, roam + scatter + a margin) and letting three cull it. It never goes stale because the
+//      AI physically cannot leave that sphere: `roam` is the leash.
+//
+//   2. IT SAMPLES THE GROUND FIVE TIMES PER MOVING ANIMAL PER FRAME. _writeMatrix takes one groundAt
+//      for the height and FOUR more for the slope basis, and world.js's groundAt is heightAt (plus
+//      walkHumps' grid-gated dust-pile lift, ~free off the piles) — three
+//      fbm stacks, a roadDistance, the outer relief, the pads loop and the rail box, measured at
+//      626 ns a call. About 40 of ~150 animals are walking at any moment, so that is ~200 heightAt a
+//      frame, 0.13 ms, from herds you cannot see. Fixed with a DISTANCE GATE: past `cullR` the AI loop
+//      does not run at all. Fog ends at 300 m and entityCull is ≤110 m, so at most one or two herds
+//      are ever live, and the cost falls to ~20 calls a frame (0.013 ms).
+//
+// The VAT clock still ticks for a gated-out herd (one float add), so nothing pops when you ride up to
+// it — the animals are simply standing where you left them.
+import * as THREE from 'three/webgpu';
+import { vatMaterial } from './vat.js';
+// Terrain/crop queries are GAME data — register before spawning herds:
+//   setHerdTerrain({ roadDistance, railDistance, waterSurfaceAt, fieldK })
+let HT = { roadDistance: () => 1e9, railDistance: () => 1e9, waterSurfaceAt: () => null, fieldK: () => 0 };
+export function setHerdTerrain(t) { HT = { ...HT, ...t }; }
+
+const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _p = new THREE.Vector3();
+const _gone = new THREE.Vector3(1e-4, 1e-4, 1e-4);   // a skinned carcass's scale: buried and invisible
+const _nrm = new THREE.Vector3(), _fwd = new THREE.Vector3(), _rgt = new THREE.Vector3(), _basis = new THREE.Matrix4();
+
+export class Herd {
+  constructor(game, species, def, count, { anchor = { x: 0, z: 0 }, roam = 16, scatter = 10 } = {}) {
+    this.game = game; this.def = def;
+    this.anchor = anchor;
+    this.roam = roam;
+    this.fleeR = def.fleeR ?? 9;
+    // How far from his anchor an animal may EVER be, fleeing included. The bounding sphere below is
+    // built from this, and three culls the whole herd against that sphere — so this is not a taste
+    // decision, it is the thing that keeps the sphere true. (See the flee branch.)
+    this.leash = Math.max(roam, scatter) + 12;
+    // ground speed from the walk's root motion where the clip has any (legs-move == space-moved);
+    // the PolyPerfect clips are in-place, so this falls back to a hand pace
+    this.speed = species.walkSpeed || ((def.speed ?? 2.2) * 0.5);
+    this.runSpeed = species.runSpeed || def.runSpeed || this.speed * 2.6;
+    this.scale = species.scale;
+    this.ci = species.clipIndex;       // { idle, walk, run, graze?, death?, dead? } → aClip indices
+    this.footY = species.footY;
+    this._scl = new THREE.Vector3(this.scale, this.scale, this.scale);
+    // HUNTABLE bookkeeping (hunting.js). The shader advances a clip at e.z = bakeFps × playRate
+    // frames/sec, so the death take runs table.frames / z seconds before it would WRAP back to the
+    // standing fall-start — kill() times the swap to the frozen `dead` still off this.
+    this.huntable = def.huntable ?? null;
+    const dte = this.ci.death != null ? species.vat.table[this.ci.death] : null;
+    this._deathZ = dte ? dte.fps * ((species.vat.playFps ?? species.vat.fps) / species.vat.fps) : 15;
+    this._deathDur = dte ? dte.frames / this._deathZ : 0;
+    this.hitR = (def.height ?? 1.2) * 0.45;   // bullet test: one sphere about the chest (hunting.js)
+    this.hitY = (def.height ?? 1.2) * 0.55;
+
+    const geo = species.geometry.clone(); // per-herd instanced attrs
+    const aClip = new Float32Array(count), aPhase = new Float32Array(count), aTint = new Float32Array(count * 3);
+    const aClipAttr = new THREE.InstancedBufferAttribute(aClip, 1);
+    aClipAttr.setUsage(THREE.DynamicDrawUsage); // the AI switches clips at runtime; a static buffer never re-uploads in WebGPU
+    geo.setAttribute('aClip', aClipAttr);
+    const aPhaseAttr = new THREE.InstancedBufferAttribute(aPhase, 1);
+    aPhaseAttr.setUsage(THREE.DynamicDrawUsage); // kill() re-phases an instance so its death take starts NOW
+    geo.setAttribute('aPhase', aPhaseAttr);
+    this.aPhase = aPhase;
+    geo.setAttribute('aTint', new THREE.InstancedBufferAttribute(aTint, 3));
+    if (species.layers > 1) { // give each individual a random coat variant from the atlas
+      const aLayer = new Float32Array(count);
+      for (let i = 0; i < count; i++) aLayer[i] = Math.floor(Math.random() * species.layers);
+      geo.setAttribute('aLayer', new THREE.InstancedBufferAttribute(aLayer, 1));
+    }
+    this.aClip = aClip; this.geo = geo;
+    this.mat = vatMaterial(species.vat, species.albedo, species.layers);
+    this.mesh = new THREE.InstancedMesh(geo, this.mat, count);
+    this.mesh.name = `herd:${def.id ?? 'animal'}`;
+
+    const tint = def.tint || [0.9, 0.95, 1.0];
+    this.inst = [];
+    for (let i = 0; i < count; i++) {
+      // THE SPAWN THROW IS CHECKED TOO. The wander targets below re-dart through _clearGround,
+      // but the spawn scatter checked NOTHING — an animal could START the day standing in a
+      // channel (or on the rails) and keep it until his first walk. Same bounded retry as the
+      // wander loop: a few darts, and the last one stands whatever it hit, so a disc that is
+      // somehow all bad ground cannot spin forever.
+      let x = anchor.x, z = anchor.z;
+      for (let tries = 0; tries < 6; tries++) {
+        const a = Math.random() * Math.PI * 2, d = Math.random() * scatter;
+        x = anchor.x + Math.cos(a) * d; z = anchor.z + Math.sin(a) * d;
+        if (this._clearGround(x, z) || tries === 5) break;
+      }
+      this.inst.push({ x, z, y: 0, heading: Math.random() * Math.PI * 2, state: 'idle', t: Math.random() * 3, tx: x, tz: z });
+      aPhase[i] = Math.random() * 6;
+      aClip[i] = this.ci.idle ?? 0;
+      const b = 0.85 + Math.random() * 0.3;
+      aTint[i * 3] = b * tint[0]; aTint[i * 3 + 1] = b * tint[1]; aTint[i * 3 + 2] = b * tint[2];
+      this._writeMatrix(i, this.inst[i]);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+
+    // THE BOUNDING SPHERE, AND WHAT ACTUALLY KEEPS IT HONEST. An InstancedMesh with a null
+    // boundingSphere recomputes it from every instance matrix; set one explicitly and three TRUSTS
+    // it. This comment used to claim the AI could not leave the sphere because "roam is the leash" —
+    // and roam bounds the WALK TARGET, while the flee branch had no bound at all. A deer (runSpeed 7,
+    // fleeR 16) leaves this sphere in ten seconds of being chased, and then the whole herd blinks out
+    // the moment its anchor goes off-screen. The LEASH above is what makes the claim true.
+    // The Y span is generous — these things stand on rolling ground, and a sphere that clips its own
+    // herd off the bottom of the screen is worse than one a few metres too big.
+    const R = Math.max(roam, scatter) + 14;
+    const ay = game.world?.groundAt?.(anchor.x, anchor.z) ?? 0;
+    this.mesh.boundingSphere = new THREE.Sphere(new THREE.Vector3(anchor.x, ay + 2, anchor.z), R + 12);
+    this.mesh.frustumCulled = true;
+    // ...and the AI gate. Past this there is nothing to see: fog closes at 300 m on high (60–300 ×
+    // fogScale) and the camera's far plane is 420 on medium. 260 m + the herd's own extent means an
+    // animal is never frozen while it is on screen.
+    this.cullR = R + 260;
+    this._cull2 = this.cullR * this.cullR;
+  }
+
+  // GROUND AN ANIMAL MAY STAND ON. The same clearances the scatter respects (zones.js: 8 m off a
+  // road, 14 m off the rails) — a cow in the six-foot is a cow the 16 m/s ore train goes through.
+  // NO COWS IN THE CORN. The roads and the rails were already here; the PLOUGHED GROUND is new, and
+  // it is the same kind of rule — a wander target is not a place an animal would actually go.
+  // The farmyard herds sit ~34 m off their pin with 8–12 m of roam, and the fields' near edge is 32 m
+  // out, so their discs genuinely clip the crop: without this, Kessler's goats graze his wheat.
+  // It is the SAME `fieldK` the paint and the scatter read (world/data/biomes.js), so the corn the cow
+  // avoids is exactly the corn you can see — and it costs two compares for any animal that is not
+  // standing next to a farm, because fieldK keeps a bounding box over all twelve fields.
+  // (It does NOT know about the kitchen-garden beds inside a settlement's yard — those are props, not
+  // a mask. Those are kept safe by siting the herds clear of them; see animals.js on Ott's goats.)
+  // AND NO DEER STANDING IN THE RIVER. The water landed in P2 and three herd discs overlap a
+  // channel (measured: deer at (−500,780) and (340,−860)-adjacent country, foxes at (820,−1060) —
+  // up to 4 m INSIDE the wetted line). waterSurfaceAt is null on dry land — and null on the bridge
+  // deck's held plug too, the same P2 law the travellers' verifier reads, so a crossing that is
+  // legal to walk is legal to stand on.
+  _clearGround(x, z) {
+    return HT.roadDistance(x, z) > 8 && HT.railDistance(x, z) > 14 && HT.fieldK(x, z) < 0.25 &&
+      HT.waterSurfaceAt(x, z) == null;
+  }
+
+  _writeMatrix(i, s) {
+    const g = this.game.world, e = 0.6;
+    s.y = g.groundAt(s.x, s.z) - this.footY;
+    // tilt to the slope, but only PITCH fully — lateral roll damped to 25 % so animals stay
+    // near-upright crossing a hillside (the legs compensate; this matches horse.js)
+    const gx = (g.groundAt(s.x + e, s.z) - g.groundAt(s.x - e, s.z)) / (2 * e);
+    const gz = (g.groundAt(s.x, s.z + e) - g.groundAt(s.x, s.z - e)) / (2 * e);
+    const fx = Math.sin(s.heading), fz = Math.cos(s.heading);
+    const rx = fz, rz = -fx;
+    const sF = gx * fx + gz * fz, sR = (gx * rx + gz * rz) * 0.25;
+    _nrm.set(-(fx * sF + rx * sR), 1, -(fz * sF + rz * sR)).normalize();
+    _fwd.set(Math.sin(s.heading), 0, Math.cos(s.heading));
+    _rgt.crossVectors(_nrm, _fwd).normalize();
+    _fwd.crossVectors(_rgt, _nrm).normalize();
+    _q.setFromRotationMatrix(_basis.makeBasis(_rgt, _nrm, _fwd));
+    this.mesh.setMatrixAt(i, _m.compose(_p.set(s.x, s.y, s.z), _q, this._scl));
+  }
+
+  _setClip(i, clip) { if (this.aClip[i] !== clip) { this.aClip[i] = clip; this._clipDirty = true; } }
+
+  // A ROUND TOOK HIM. Play the pack's death take from its FIRST frame — the take starts wherever
+  // (uTime + aPhase) lands, so the phase is rewritten to put frame 0 at NOW — then swap to the
+  // frozen `dead` still a couple of frames before the take would wrap back to standing.
+  kill(i) {
+    const s = this.inst[i];
+    if (!s || s.state === 'dying' || s.state === 'dead' || s.state === 'gone') return false;
+    if (this.ci.death != null && this._deathDur > 0) {
+      const uT = this.mat.userData.uTime.value, period = this._deathDur;
+      this.aPhase[i] = period * Math.ceil(uT / period + 1e-6) - uT;
+      this.geo.getAttribute('aPhase').needsUpdate = true;
+      this._setClip(i, this.ci.death);
+      this.geo.getAttribute('aClip').needsUpdate = true;   // flush NOW — update()'s flush is gated on cullR
+      s.state = 'dying'; s.t = Math.max(0.1, this._deathDur - 2 / this._deathZ);
+    } else {
+      s.state = 'dead';
+      if (this.ci.dead != null) { this._setClip(i, this.ci.dead); this.geo.getAttribute('aClip').needsUpdate = true; }
+    }
+    // the SHOT SPOOKS THE HERD: prey scatters off the kill for a few seconds (update() widens the
+    // flee ring while this runs). Predators (fleeR 0 — the wolf) do not run from a dead packmate.
+    if (this.fleeR > 0) this._spookT = 4;
+    return true;
+  }
+
+  // Skinned: the carcass leaves the world. The instance slot stays (resident-for-life mesh), the
+  // body is buried under the ground at near-zero scale.
+  removeCarcass(i) {
+    const s = this.inst[i]; if (!s) return;
+    s.state = 'gone';
+    this.mesh.setMatrixAt(i, _m.compose(_p.set(s.x, s.y - 6, s.z), _q.identity(), _gone));
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+
+  update(dt, playerPos) {
+    this.mat.userData.uTime.value += dt;   // the VAT clock — cheap, and always: nothing pops on approach
+    // THE GATE. Everything below costs 5 heightAt per MOVING animal; none of it is worth a frame's
+    // work for a herd two kilometres away that is behind fog and outside the far plane anyway.
+    const dx0 = this.anchor.x - playerPos.x, dz0 = this.anchor.z - playerPos.z;
+    if (dx0 * dx0 + dz0 * dz0 > this._cull2) return;
+
+    // a fresh kill widens the flee ring: the whole herd breaks off the shot for a few seconds
+    const fleeR = (this._spookT ?? 0) > 0 ? Math.max(this.fleeR, 30) : this.fleeR;
+    if (this._spookT > 0) this._spookT -= dt;
+
+    let moved = false;
+    for (let i = 0; i < this.inst.length; i++) {
+      const s = this.inst[i];
+      // the dead don't flee. `dying` runs the death take down, then holds the frozen last frame.
+      if (s.state === 'dead' || s.state === 'gone') continue;
+      if (s.state === 'dying') {
+        s.t -= dt;
+        if (s.t <= 0) { s.state = 'dead'; if (this.ci.dead != null) this._setClip(i, this.ci.dead); }
+        continue;
+      }
+      const dpx = s.x - playerPos.x, dpz = s.z - playerPos.z, pd = Math.hypot(dpx, dpz);
+      if (pd < fleeR) { // flee: run directly away from the player
+        s.heading = Math.atan2(dpx, dpz);
+        s.x += Math.sin(s.heading) * this.runSpeed * dt; s.z += Math.cos(s.heading) * this.runSpeed * dt;
+        // ...BUT NOT OUT OF THE COUNTY. The flee had NO leash: it ran directly away for as long as you
+        // stayed inside fleeR, so a deer (runSpeed 7, fleeR 16) leaves its herd's bounding sphere in
+        // TEN SECONDS of being chased — and three culls the whole InstancedMesh against that sphere.
+        // Turn so the anchor is off-screen and the entire herd blinks out while you are looking at it.
+        // The sphere is not the bug; the unbounded run is. Hold him inside the leash and the sphere
+        // stays honest, which is what lets the herd be frustum-culled at all.
+        const lx = s.x - this.anchor.x, lz = s.z - this.anchor.z;
+        const ld = Math.hypot(lx, lz);
+        if (ld > this.leash) { s.x = this.anchor.x + (lx / ld) * this.leash; s.z = this.anchor.z + (lz / ld) * this.leash; }
+        s.state = 'flee'; s.t = 1.5;
+        this._setClip(i, this.ci.run ?? this.ci.walk ?? 0);
+        this._writeMatrix(i, s); moved = true;
+        continue;
+      }
+      s.t -= dt;
+      if (s.state === 'flee') { s.state = 'idle'; s.t = 1 + Math.random() * 2; this._setClip(i, this.ci.idle ?? 0); }
+      else if (s.state === 'walk') {
+        const dx = s.tx - s.x, dz = s.tz - s.z, dd = Math.hypot(dx, dz);
+        if (dd > 0.4 && s.t > 0) {
+          s.heading = Math.atan2(dx, dz);
+          s.x += (dx / dd) * this.speed * dt; s.z += (dz / dd) * this.speed * dt;
+          this._writeMatrix(i, s); moved = true;   // ← the ONLY place the ground is sampled in the steady state
+          continue;
+        }
+        s.state = 'idle'; s.t = 2 + Math.random() * 3; this._setClip(i, this.ci.idle ?? 0);
+      }
+      if (s.t <= 0 && s.state !== 'walk') { // pick a new ambient action
+        const r = Math.random();
+        if (r < 0.45) { s.state = 'idle'; s.t = 2 + Math.random() * 3; this._setClip(i, this.ci.idle ?? 0); }
+        else if (r < 0.72 && this.ci.graze != null) { s.state = 'graze'; s.t = 3 + Math.random() * 4; this._setClip(i, this.ci.graze); }
+        else {
+          s.state = 'walk'; s.t = 4 + Math.random() * 5;
+          // A COW DOES NOT GRAZE ON THE CARRIAGEWAY. The anchor was checked against the roads and the
+          // rails; the ROAM DISC was not — and the animals do not stand on the anchor. Measured: 51 of
+          // the county's 152 head could walk into a road, and sixteen cattle could walk onto the RAILS,
+          // which the coaches and the trains come down. So the target is drawn, and then it has to pass:
+          // a few tries, and if the ground is no good he stays where he is and eats. Cheap, because this
+          // runs once every 4-9 seconds per animal, not per frame.
+          for (let tries = 0; tries < 6; tries++) {
+            const a = Math.random() * Math.PI * 2, d = 2 + Math.random() * this.roam;
+            const tx = this.anchor.x + Math.cos(a) * d, tz = this.anchor.z + Math.sin(a) * d;
+            if (this._clearGround(tx, tz) || tries === 5) { s.tx = tx; s.tz = tz; break; }
+          }
+          this._setClip(i, this.ci.walk ?? 0);
+        }
+      }
+    }
+    if (moved) this.mesh.instanceMatrix.needsUpdate = true;
+    if (this._clipDirty) { this.geo.getAttribute('aClip').needsUpdate = true; this._clipDirty = false; }
+  }
+}