sindicate 0.2.0 → 0.5.0

package/src/systems/horse.js

@@ -0,0 +1,361 @@
+// Horse: a rideable entity — Synty horse mesh + Malbers in-place gait clips on a
+// RAW mixer (the clips target the quadruped rig directly, so they bypass the
+// Synty→Synty retargeting Animator). Movement is code-driven through the capsule
+// controller (terrain-follow + building collision); the seated rider is handled
+// by the Riding controller, which reads this horse's saddle + rein bones.
+import * as THREE from 'three/webgpu';
+import { instantiate, loadClips, loadTexture, applyAtlas } from '../core/assets.js';
+import { Character } from './entity.js';
+import { angleLerp, clamp } from '../core/utils.js';
+// the ridable world's edge clamp is game data: setHorseWorld({ worldSize })
+let HW = { worldSize: 4320 };
+export function setHorseWorld(w) { HW = { ...HW, ...w }; }
+import { steerCarrot, mountedTurn } from './pathFollow.js';
+
+const _hDir = new THREE.Vector3();   // ambling horses borrow Character.walkDir (whisker steering)
+const _hAim = { x: 0, z: 0 };        // scratch: the carrot point steerCarrot hands the companion horse to steer at
+
+const HA = '/assets/horse/anims';
+const HORSE_CLIPS = {
+  idle: `${HA}/H_Idle_01.fbx`, walk: `${HA}/H_Walk_IP.fbx`, trot: `${HA}/H_Trot_IP.fbx`,
+  canter: `${HA}/H_Canter_IP.fbx`, gallop: `${HA}/H_Gallop_IP.fbx`,
+  jump: `${HA}/H_Jump_Forward.fbx`,
+  eat: `${HA}/H_Eat.fbx`, drink: `${HA}/H_Drink.fbx`,
+  look: `${HA}/H_Idle_03_Look.fbx`, headShake: `${HA}/H_Idle_02_HeadShake.fbx`,
+};
+// Synty PolygonHorse coat variants (one mesh, many textures) — picked per horse.
+// Only 01–06; 07–10 are Indian war-paint horses, not used here.
+const HORSE_COATS = Array.from({ length: 6 }, (_, i) => `/assets/textures/horse_${String(i + 1).padStart(2, '0')}.png`);
+const UP = new THREE.Vector3(0, 1, 0);
+const _off = new THREE.Vector3();
+const _nrm = new THREE.Vector3(), _qYaw = new THREE.Quaternion(), _qTgt = new THREE.Quaternion();
+const _frustum = new THREE.Frustum(), _projScreen = new THREE.Matrix4(), _sphere = new THREE.Sphere();
+
+// load + de-root-motion the horse clips once; every horse shares them (per-mixer actions)
+let _clipCache = null;
+async function horseClips() {
+  if (!_clipCache) {
+    _clipCache = await loadClips(HORSE_CLIPS);
+    for (const c of Object.values(_clipCache)) c.tracks = c.tracks.filter((t) => !t.name.endsWith('.position'));
+  }
+  return _clipCache;
+}
+
+// Warm the FBX + clip caches once at boot so the first lazy build is a ~1ms clone, not
+// a multi-hundred-ms FBX parse on first approach.
+export async function preloadHorse() {
+  await instantiate('/assets/horse/SyntyHorse.fbx', { texture: '/assets/textures/horse_01.png' });
+  await horseClips();
+}
+
+export class Horse {
+  constructor(game, { x = 0, z = 0, heading = 0, anchor = null, roam = 9, tethered = false, saddle = true, coat = null } = {}) {
+    this.game = game;
+    this.root = new THREE.Group();
+    this.root.position.set(x, game.world.groundAt(x, z), z);
+    this.model = null; this.mixer = null; this._building = false; // model built at spawn (resident for life)
+    this.tethered = tethered; // tethered horses never wander (hitched at a post)
+    this.saddle = saddle;      // false = bareback/wild (hide saddle + reins meshes)
+    this.coat = coat || HORSE_COATS[Math.floor(Math.random() * HORSE_COATS.length)]; // random coat unless specified
+    this.heading = heading;
+    this.root.rotation.y = heading;
+    this.vy = 0; this.airborne = false;
+    this.capsuleR = 0.7; this.capsuleH = 1.6; this.capsuleSteps = 3; this.radius = 0.7;
+    this.rider = null;     // mounted rider (null = mountable)
+    this.speed = 0;
+    this.saddleBone = null; this.reinL = null; this.reinR = null; this.neckBone = null;
+    this.cur = null; this.curName = null;
+    // ambient AI (riderless): graze/idle/wander near a group anchor
+    this.anchor = anchor || { x, z };
+    this.roam = roam;
+    this.aiState = 'idle'; this.aiT = 1 + Math.random() * 2; this.target = null;
+    this.owner = null;   // set to the player once he mounts it — then it TRAILS him afoot (updateAI → _followOwner)
+  }
+
+  get position() { return this.root.position; }
+
+  // Build the heavy skinned model (a clone of the cached master) and attach it. Called
+  // lazily by the spawner, throttled to one per frame — a herd coming into range fades
+  // in over a few frames instead of all-at-once (that one-frame burst was the freeze).
+  async _buildModel() {
+    // explicit scale BLOCKS the glb-twin redirect (resolveModelUrl): this rig + all its
+    // seat/rein tuning are cm-FBX; a metre twin baked later must not silently swap in
+    this.model = await instantiate('/assets/horse/SyntyHorse.fbx', { texture: HORSE_COATS[0], scale: 0.01 });
+    this.model.scale.setScalar(0.01);
+    applyAtlas(this.model, await loadTexture(this.coat)); // give this clone its own coat (master material is shared)
+    this.model.traverse((o) => { if (o.isMesh) { o.castShadow = false; o.receiveShadow = true; o.frustumCulled = false; } });
+
+    // raw mixer (no retarget); clips have baked root motion stripped (code-driven move)
+    const clips = await horseClips();
+    this.mixer = new THREE.AnimationMixer(this.model);
+    this.actions = {};
+    for (const [n, clip] of Object.entries(clips)) this.actions[n] = this.mixer.clipAction(clip);
+
+    this.model.traverse((o) => { // mount point + rein IK targets, built into the rig
+      if (o.name === 'Spine1') this.saddleBone = o;        // back bone (Horse_Saddle locator sits at Y0)
+      else if (o.name === 'Reins_Bn_Hand_L') this.reinL = o;
+      else if (o.name === 'Reins_Bn_Hand_R') this.reinR = o;
+      else if (o.name === 'Neck') this.neckBone = o;       // used to keep the rider's hands clear of the neck
+    });
+
+    this.play('idle');
+    this.root.add(this.model);
+  }
+
+  get shown() { return !!(this.model && this.model.parent); }
+
+  // Build (first time) or re-attach the model. The spawner gates how often this runs so
+  // adds never bunch up in a single frame. Cloning is ~1ms, the first render ~8ms.
+  ensureShown() {
+    if (this._building) return;
+    if (this.model) { if (!this.model.parent) this.root.add(this.model); return; }
+    this._building = true;
+    this._buildModel().then(() => { this._building = false; }).catch((e) => { this._building = false; console.warn('horse build failed', e); });
+  }
+
+  // Detach (don't dispose) the model when far — keeps it cached for a cheap re-attach.
+  hide() { if (this.model && this.model.parent) this.root.remove(this.model); }
+
+  get name() { return this.curName; }
+
+  play(name, { once = false, fade = 0.22 } = {}) {
+    const a = this.actions[name];
+    if (!a || (a === this.cur && !once)) return;
+    a.reset(); a.enabled = true; a.setEffectiveTimeScale(1); a.setEffectiveWeight(1);
+    a.loop = once ? THREE.LoopOnce : THREE.LoopRepeat; a.clampWhenFinished = once;
+    a.fadeIn(fade).play();
+    if (this.cur && this.cur !== a) this.cur.fadeOut(fade);
+    this.cur = a; this.curName = name;
+  }
+
+  // walk sits under the trot now — a horse ambling at 1.8 m/s used to TROT on the spot, which is
+  // what made every gentle stick push read as a jog (Nick). The trot/canter/gallop cuts are untouched.
+  gaitFor(sp) { return sp < 0.4 ? 'idle' : sp < 2.4 ? 'walk' : sp < 4 ? 'trot' : sp < 9.5 ? 'canter' : 'gallop'; }
+
+  // Saddle world position = the back bone + a local-frame offset (rotated by heading).
+  saddlePos(out, off) {
+    if (this.saddleBone) this.saddleBone.getWorldPosition(out); else out.copy(this.position);
+    if (off) out.add(_off.copy(off).applyAxisAngle(UP, this.heading));
+    return out;
+  }
+
+  // Driven by the Riding controller each frame while mounted.
+  driveMove(speed, turn, dt) {
+    this.speed = speed;
+    this.heading += turn * dt;
+    this.game.world.moveCapsule(this, Math.sin(this.heading) * speed * dt, Math.cos(this.heading) * speed * dt, dt);
+    const E = HW.worldSize / 2 - 20;                          // ridden path skips player.js clamp — keep 20m inside
+    this.position.x = clamp(this.position.x, -E, E); this.position.z = clamp(this.position.z, -E, E);
+    // SOLID TRAFFIC. A driven horse shoulders through nobody — walkers, other horses, the man on
+    // foot (Nick rode clean through a road walker and an oncoming rider). The same push-apart the
+    // player uses on foot, throttled to ~8Hz per horse, wall-resolved after so a shove can't put
+    // half a ton of animal inside a building.
+    this._trafT = (this._trafT ?? Math.random() * 0.12) - dt;
+    if (this._trafT <= 0) {
+      this._trafT = 0.12;
+      let moved = false;
+      const push = (o, orad = 0.45) => {
+        if (!o || o === this || o.alive === false) return;
+        const op = o.position ?? o.root?.position;
+        if (!op) return;
+        const dx = this.position.x - op.x, dz = this.position.z - op.z;
+        const d = Math.hypot(dx, dz), min = 1.05 + orad;
+        if (d < min && d > 1e-4) { const k = (min - d) / d; this.position.x += dx * k; this.position.z += dz * k; moved = true; }
+      };
+      for (const n of this.game.npcs ?? []) { if (n !== this.rider && !n.seated) push(n); }
+      for (const h of this.game.horses ?? []) push(h, 1.05);
+      const pl = this.game.player;
+      if (pl && this.rider !== pl) push(pl, 0.5);
+      if (moved) {
+        const c = this.game.world.collide(this.position.x, this.position.z, 0.6, 0, this.position.y);
+        if (c) { this.position.x = c.x; this.position.z = c.z; }
+      }
+    }
+    this._applyGroundTilt(dt);                              // pitch/roll to the slope (incl. heading yaw)
+    if (!this.airborne) this.play(this.gaitFor(Math.abs(speed)));
+    this._applyBob(dt);
+  }
+
+  // Gait-synced vertical bob of the whole model. The _IP gait clips have their root
+  // motion (incl. the vertical bob) stripped, so the body glides flat and a mounted
+  // rider feels glued in place. Bobbing the model makes the body, saddle bone, and the
+  // rider seated on it all rise/fall together. Always ≥0 so hooves never sink.
+  _applyBob(dt) {
+    if (!this.model) return;
+    const sp = Math.abs(this.speed);
+    let target = 0;
+    if (!this.airborne && sp > 0.5) {
+      this._bobPhase = (this._bobPhase ?? 0) + dt * (4 + sp * 0.7); // faster stride at higher gaits
+      const amp = Math.min(0.07, 0.012 + sp * 0.004);
+      target = (Math.sin(this._bobPhase) * 0.5 + 0.5) * amp;       // 0..amp
+    }
+    this.model.position.y += (target - this.model.position.y) * Math.min(1, dt * 12); // ease in/out
+  }
+
+  // THE GROUND UNDER A STANDING HORSE — the terrain, unless his current height says he is ON
+  // something (the player rode him onto the station platform and stepped off: the planks are his
+  // floor, not the dirt a metre under them). The BVH ray is only paid in that rare case; a horse
+  // standing on the dirt, which is every horse nearly always, costs exactly what it used to.
+  _settleY() {
+    const w = this.game.world;
+    const ty = w.groundAt(this.position.x, this.position.z);
+    return (this.position.y - ty > 0.25 && w.walkSurfaceAt)
+      ? Math.max(ty, w.walkSurfaceAt(this.position.x, this.position.z)) : ty;
+  }
+
+  // Orient the body to the ground: tilt up→terrain-normal (pitch/roll) + heading yaw, eased so it
+  // doesn't snap. Sampled from groundAt gradients (cheap, analytic — no BVH).
+  _applyGroundTilt(dt) {
+    const x = this.position.x, z = this.position.z, e = 1.4, w = this.game.world;
+    // slope gradient, split into the body frame: full fore-aft PITCH (climbing reads right)
+    // but lateral ROLL damped to 25% — legs compensate side-slopes, a real horse (and its
+    // rider) stays near-upright crossing a hillside instead of leaning with the ground
+    const gx = (w.groundAt(x + e, z) - w.groundAt(x - e, z)) / (2 * e);
+    const gz = (w.groundAt(x, z + e) - w.groundAt(x, z - e)) / (2 * e);
+    const fx = Math.sin(this.heading), fz = Math.cos(this.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();
+    _qYaw.setFromAxisAngle(UP, this.heading);
+    _qTgt.setFromUnitVectors(UP, _nrm).multiply(_qYaw);     // yaw first, then tilt onto the slope
+    this.root.quaternion.slerp(_qTgt, Math.min(1, dt * 8));
+  }
+
+  jump(impulse = 6) {
+    if (this.airborne) return;
+    this.vy = impulse;
+    this.play('jump', { once: true, fade: 0.1 });
+    // Fit the WHOLE leap (rear → back-legs push-off → tuck → land) into the actual airborne time so
+    // the clip isn't cut after only the front-leg rear when the gait resumes on landing (Nick: "front
+    // legs go up, back doesn't"). Airborne = rise+fall time under gravity (20 m/s²); speed the clip to it.
+    const a = this.actions.jump, air = 2 * impulse / 20;
+    if (a) a.setEffectiveTimeScale(clamp(a.getClip().duration / air, 1, 3.5));
+  }
+
+  update(dt) {
+    if (!this.shown) return;                                  // not built yet, or hidden (far) — nothing to do
+    if (this.rider) { if (!this._mixerTicked) this.mixer.update(dt); this._mixerTicked = false; return; } // ridden: Riding ticks the mixer first (see riding.update) so the seat reads the current pose
+    this._idleVoice(dt);                                      // a hitched horse is not a silent horse
+    this.updateAI(dt);                                        // riderless: graze / idle / look / wander
+    if (this.model && !this.model.visible) return;            // off-screen (main safety-net hid it): AI keeps moving, skip mixer+tilt
+    this.mixer.update(dt);
+    this._applyGroundTilt(dt);                                // riderless: tilt to the slope too
+  }
+
+  // A HITCHED HORSE IS NOT A SILENT HORSE. The Malbers recordings (breathing, snorts,
+  // head-shakes, whinnies, the odd neigh) were only ever played from the saddle — so the three
+  // tied at the rail stood there mute, which is the loudest thing about them. They speak now,
+  // but only when someone is close enough to hear (and rarely enough not to nag).
+  _idleVoice(dt) {
+    const a = this.game.audio, p = this.game.player;
+    if (!a?.sample || !p) return;
+    const d = Math.hypot(this.position.x - p.position.x, this.position.z - p.position.z);
+    if (d > 22) { this._voiceT = 4 + Math.random() * 6; return; }   // out of earshot: don't even count down
+    this.game.player?.riding?._loadSfx?.();                          // samples load lazily on first mount — pull them in
+    this._voiceT = (this._voiceT ?? 4 + Math.random() * 6) - dt;
+    if (this._voiceT > 0) return;
+    this._voiceT = 7 + Math.random() * 11;
+    const gain = (1 - d / 22) * 0.5;                                 // quieter the further off you are
+    const pick = (arr) => arr[Math.floor(Math.random() * arr.length)];
+    const r = Math.random();
+    if (r < 0.45) a.sample(pick(['breath1', 'breath2']), { gain });
+    else if (r < 0.65) a.sample('snort', { gain });
+    else if (r < 0.8) a.sample('headshake', { gain });
+    else if (r < 0.94) a.sample(pick(['whinny1', 'whinny2', 'whinny3']), { gain: gain * 0.9 });
+    else a.sample(pick(['neigh', 'neigh2', 'neigh3']), { gain: gain * 0.85 });
+  }
+
+  // Ambient herd/town behavior: graze, idle, look about, and occasionally amble to a
+  // new spot near the anchor. Standing horses settle to terrain with a cheap
+  // heightfield lookup — only a WANDERING horse runs the BVH capsule controller.
+  updateAI(dt) {
+    this.speed = 0;
+    if (this.owner) return this._followOwner(dt);   // the player's own horse trails him, it doesn't graze with the herd
+    this.aiT -= dt;
+    if (this.aiState === 'wander' && this.target && this.aiT > 0) {
+      const dx = this.target.x - this.position.x, dz = this.target.z - this.position.z;
+      const dd = Math.hypot(dx, dz);
+      if (dd > 0.6) {
+        // whisker steering borrowed from Character (walkDir works on anything with game/position/root)
+        // — ambling horses stop nosing into fences/wells/people; probes are throttled + 45m-gated
+        const sd = Character.prototype.walkDir.call(this, _hDir.set(dx / dd, 0, dz / dd), dt);
+        this.heading = angleLerp(this.heading, Math.atan2(sd.x, sd.z), Math.min(1, dt * 2.5));
+        const mx = Math.sin(this.heading) * 1.7 * dt, mz = Math.cos(this.heading) * 1.7 * dt;
+        // terrain-follow only — NO BVH. Ambient grazers don't need building collision,
+        // and the per-frame BVH sweep was a needless cost.
+        const nx = this.position.x + mx, nz = this.position.z + mz;
+        this.root.position.set(nx, this.game.world.groundAt(nx, nz), nz);
+        this.play('walk');
+        return;
+      }
+      this.aiT = 0; // arrived
+    }
+    this.root.position.y = this._settleY(); // cheap settle — BVH only if he's visibly on a deck
+    if (this.aiT <= 0) this._pickBehavior();
+    if (this.aiState !== 'wander') this.play({ graze: 'eat', drink: 'drink', look: 'look', headShake: 'headShake' }[this.aiState] || 'idle');
+  }
+
+  // THE PLAYER'S HORSE. Once he mounts it, it is his — and a good horse doesn't drift off to graze with
+  // the herd. It trails him at a distance while he's afoot, closing a big gap at a trot or canter and
+  // ambling in when near, settling when he stops. Steers around fences/people with the same whiskers the
+  // ambient amble uses. (RDR2's ever-present companion; a whistle to summon it from further off comes next.)
+  _followOwner(dt) {
+    const p = this.game.player;
+    if (!p) return;
+    const dx = p.position.x - this.position.x, dz = p.position.z - this.position.z;
+    const dd = Math.hypot(dx, dz);
+    // WHISTLED (player.whistle sets _summoned): gallop right up to him, close enough to mount, and stop
+    // trailing at arm's length instead of the lazy 4.5 m follow gap.
+    const summoned = (this._summoned ?? 0) > 0;
+    if (summoned) this._summoned -= dt;
+    // BOND (missions horse_bond, fed through the horse-kit items): a known horse heels closer and
+    // answers the whistle harder. bond_mid at 4, bond_high at 8.
+    const bondHigh = this.game.missions?.flag?.('bond_high'), bondMid = bondHigh || this.game.missions?.flag?.('bond_mid');
+    const KEEP = summoned ? 2.2 : bondHigh ? 3.0 : bondMid ? 3.6 : 4.5;
+    if (dd <= KEEP) {
+      this.root.position.y = this._settleY(); this.speed = 0;
+      if ((this._eatT ?? 0) > 0) { this._eatT -= dt; this.play('eat'); }   // fed from the satchel — the eat clip
+      else this.play('idle');
+      if (dd <= 2.6) this._summoned = 0;
+      return;
+    }
+    const spd = summoned ? (bondHigh ? 11 : 10) : (dd > 16 ? 7 : dd > 6 ? 3.5 : 1.8);   // summoned: gallop · else canter to close · trot · amble in
+    // AIM: A* round buildings when a static blocks the straight line to him — steerCarrot (the same the
+    // mounted riders use) holds a path on the settlement's baked grid and hands back a look-ahead carrot;
+    // a clear line just aims straight. Then whiskers bend it for people/fences, probed from the ground.
+    let aimX = p.position.x, aimZ = p.position.z;
+    if (steerCarrot(this, this.game, p.position, this.position.x, this.position.z, p.position.x, p.position.z, _hAim,
+      { dt, arrive: 1.5, lookahead: clamp(spd * 0.5, 2.5, 4.5), wide: true })) { aimX = _hAim.x; aimZ = _hAim.z; }
+    const adx = aimX - this.position.x, adz = aimZ - this.position.z, L = Math.hypot(adx, adz) || 1;
+    const sd = Character.prototype.walkDir.call(this, _hDir.set(adx / L, 0, adz / L), dt);
+    // pure-pursuit turn with a real minimum radius, then the BVH capsule move so it rounds walls instead
+    // of clipping through them. moveCapsule (not driveMove) because horse.update() applies the ground tilt
+    // once AFTER updateAI, exactly as the ambient amble relies on — driveMove would tilt a second time.
+    const m = mountedTurn(this.heading, this.position.x, this.position.z, this.position.x + sd.x, this.position.z + sd.z, Math.max(0.6, spd), 3.5, 2.4);
+    this.heading += m.turn * dt;
+    const s = spd * m.speedMul;
+    this.game.world.moveCapsule(this, Math.sin(this.heading) * s * dt, Math.cos(this.heading) * s * dt, dt);
+    this.speed = s;
+    this.play(this.gaitFor(s));
+  }
+
+  _pickBehavior() {
+    const r = Math.random();
+    if (r < 0.40) { this.aiState = 'graze'; this.aiT = 4 + Math.random() * 6; }
+    else if (r < 0.58) { this.aiState = 'idle'; this.aiT = 2 + Math.random() * 3; }
+    else if (r < 0.70) { this.aiState = 'drink'; this.aiT = 3 + Math.random() * 3; }
+    else if (r < 0.80) { this.aiState = 'look'; this.aiT = 3 + Math.random() * 2; }
+    else if (r < 0.88 || this.tethered) { this.aiState = 'headShake'; this.aiT = 2.5; } // tethered: calm, never wander
+    else { // amble to a new spot near the anchor
+      this.aiState = 'wander'; this.aiT = 6 + Math.random() * 5;
+      const a = Math.random() * Math.PI * 2, dd = 2 + Math.random() * this.roam;
+      this.target = { x: this.anchor.x + Math.cos(a) * dd, z: this.anchor.z + Math.sin(a) * dd };
+    }
+  }
+}
+
+// walkDir is BORROWED from Character (line ~201) — since the whisker-steering change, walkDir
+// internally calls this._probeSteer(), so the borrower needs that method too. Without it, any
+// horse AMBLING WITHIN 45m OF THE PLAYER threw mid-animation-loop and KILLED the render loop:
+// the intermittent "black screen of death" (HUD alive, viewport dead at whatever frame it hit).
+Horse.prototype._probeSteer = Character.prototype._probeSteer;

package/src/systems/loot.js

@@ -0,0 +1,303 @@
+// MONEY + LOOT. A man who falls spills his purse where he fell; the player walks over it and
+// it's his. That's the whole loop — no inventory screen, no loot table UI, no "press E to open".
+//
+// Three decisions worth writing down:
+//
+//  1. WALK-OVER, NOT PROMPT. E is already contested (mount / dismount / doors / the finisher
+//     outranks all of them — main.js:642-669), and a purse you have to stop and interact with
+//     turns a gunfight into paperwork. Walk within 1.2m and it's yours, with a short magnet
+//     so you never have to hunt for the exact pixel.
+//
+//  2. THE PURSES ARE POOLED. PERF LAW is about SKINNED meshes — a sack is a static prop and
+//     shatter.js adds and removes those freely — but a drop happens at the worst possible
+//     moment (mid-firefight, four men down at once), and instantiate() on the hot path is an
+//     await plus a clone plus a first-sight pipeline/texture upload. So the whole pool is
+//     built ON THE LOADING SCREEN, added to the scene once, and "dropping" is making a
+//     resident sack visible — the same trick the coach uses for its fares.
+//
+//  3. THE HUD LIVES HERE. ui.js owns the hearts, the clock and the ammo pips; the money
+//     counter is one <div> that only this file ever writes, so it ships with the system it
+//     belongs to instead of adding a limb to UI. It is styled off the clock's hex plate so it
+//     reads as part of the same HUD, it is parented to #hud (so it hides when the HUD hides),
+//     and — house law — every DOM write is behind a change check.
+import * as THREE from 'three/webgpu';
+import { instantiate } from '../core/assets.js';
+// purse bands, drop tables and the goods catalogue are GAME data:
+//   setLootContent({ purseFor, purseKind, dropItemsFor, items })
+let LC = { purseFor: () => 0, purseKind: () => 'default', dropItemsFor: () => null, items: {} };
+export function setLootContent(c) { LC = { ...LC, ...c }; }
+
+const ATLAS = '/assets/textures/atlas_western.png';
+// Four sack shapes so a wiped stagecoach doesn't leave four identical props in the dust.
+const SACKS = ['SM_Prop_Sack_01', 'SM_Prop_Sack_02', 'SM_Prop_Sack_03', 'SM_Prop_Sack_04'];
+
+const START_MONEY = 5;   // the player rides in with a few dollars — enough to feel like money exists
+const POOL = 16;         // 16 purses on the ground at once; a full coach (6) plus a street brawl
+const PURSE_H = 0.30;    // metres tall. The pack's sacks are grain-sized; a purse is a hand's-worth,
+                         // and normalising by measured bbox means the FBX/GLB-twin scale can't bite us.
+const PICKUP_R = 1.2;    // walk-over radius (2D — you can grab a purse from the boardwalk above it)
+const MAGNET_R = 2.6;    // beyond pickup, the purse slides to you. Hunting for the exact pixel is not fun.
+const MAGNET_V = 3.4;    // m/s it slides
+const LIFE = 120;        // seconds before it's gone. Otherwise the desert silts up with sacks.
+const FADE = 3;          // last seconds shrink away, so the vanish doesn't look like a bug
+const MERGE_R = 0.7;     // a second body falling on the same spot tops up the purse already there,
+                         // instead of burning a pool slot and stacking two sacks in each other
+const BOB_H = 0.06;
+const SPIN = 1.1;        // rad/s — slow enough to read as loot, not as a pickup from another genre
+
+export class Loot {
+  constructor(game) {
+    this.game = game;
+    this.money = START_MONEY;
+    this.purses = [];        // the pool — every entry resident and scene-attached for life
+    this._live = 0;          // how many are out (cheap early-out in update)
+    this._t = 0;
+    this._bump = false;      // set on a gain, consumed by the HUD next frame
+    this._shown = -1;        // last value written to the DOM (change-gate)
+    this._buildHUD();
+    // Kicked off in the constructor, awaited by boot: `await this.loot.ready`. A drop before
+    // the sacks exist is survivable (the money is simply awarded on the spot) but it should
+    // never happen — the pool is up before the loading screen comes down.
+    this.ready = this._buildPool().catch((e) => { console.warn('[loot] purse pool failed to build', e); });
+  }
+
+  // ── MONEY ────────────────────────────────────────────────────────────────────────────────
+
+  add(n) {
+    n = Math.round(n);
+    if (!n) return this.money;
+    this.money = Math.max(0, this.money + n);
+    if (n > 0) { this._bump = true; this.game.audio?.play('coin'); }   // synth.js has a 'coin' case
+    return this.money;
+  }
+
+  // For the shops/bribes that don't exist yet. Returns false and takes nothing if he's short.
+  spend(n) {
+    n = Math.round(n);
+    if (n > this.money) return false;
+    this.money -= n;
+    this._shown = -1;   // a spend must repaint even though _bump stays false
+    return true;
+  }
+
+  // What a given man is carrying — see data/purse.js. `id` is an npc def id, an ENEMY_TYPES
+  // key, or a coach seat role ('driver' / 'mate' / 'fare'); unknown ids get the default band.
+  amountFor(id, mult = 1) { return LC.purseFor(id, mult); }
+
+  // The convenience the other systems actually want: "this one just died, spill him".
+  // dropFor('driver', rider.position) — one call, no purse arithmetic at the call site.
+  // ...and now his THINGS as well as his cash: dropItemsFor rolls data/drops.js by the same id, so
+  // every caller that already spilled a purse (combat.js, npc.js) starts dropping items for free.
+  dropFor(id, position, mult = 1) { return this.drop(position, LC.purseFor(id, mult), LC.dropItemsFor(id)); }
+
+  // ── THE PURSE ON THE GROUND ──────────────────────────────────────────────────────────────
+
+  // `position` is at the FEET (the codebase's entity convention) — the corpse's own y, NOT
+  // groundAt(), because a man shot on the saloon boardwalk must not drop his purse through
+  // the deck and into the dirt below it.
+  drop(position, amount = LC.purseFor('default'), items = null) {
+    amount = Math.max(1, Math.round(amount));
+    // top up a purse already lying here rather than stacking sacks (a coach crew dies in a heap)
+    for (const p of this.purses) {
+      if (p.t < 0) continue;
+      const dx = p.root.position.x - position.x, dz = p.root.position.z - position.z;
+      if (dx * dx + dz * dz < MERGE_R * MERGE_R && Math.abs(p.baseY - position.y) < 1.2) {
+        p.amount += amount;
+        p.items = mergeItems(p.items, items);   // ...and its THINGS too, or a top-up silently loses them
+        p.t = 0;                     // and its clock restarts — the pile is fresh again
+        return p;
+      }
+    }
+    const p = this._take();
+    if (!p) { this.add(amount); this._giveItems(items); return null; }   // pool not built yet: pay him rather than lose it
+    p.amount = amount;
+    p.items = items;
+    p.t = 0;
+    p.phase = Math.random() * 6.28;
+    p.baseY = position.y + 0.02;
+    // scatter a little so two drops a metre apart still read as two purses
+    p.root.position.set(position.x + (Math.random() - 0.5) * 0.3, p.baseY, position.z + (Math.random() - 0.5) * 0.3);
+    p.root.rotation.y = Math.random() * 6.28;
+    p.root.scale.setScalar(1);
+    p.root.visible = true;
+    this._live++;
+    return p;
+  }
+
+  update(dt) {
+    if (!this._live) { this._syncHUD(); return; }
+    dt = Math.min(dt, 0.05);
+    this._t += dt;
+    const player = this.game.player;
+    const alive = player?.alive !== false;
+    for (const p of this.purses) {
+      if (p.t < 0) continue;
+      p.t += dt;
+      // expire — shrink out over the last few seconds so it doesn't just blink off
+      if (p.t > LIFE) { this._park(p); continue; }
+      const left = LIFE - p.t;
+      if (left < FADE) p.root.scale.setScalar(left / FADE);
+      p.root.rotation.y += SPIN * dt;
+      p.root.position.y = p.baseY + 0.14 + Math.sin(this._t * 2.4 + p.phase) * BOB_H;
+      if (!alive) continue;
+      const px = player.position.x, pz = player.position.z;
+      const dx = px - p.root.position.x, dz = pz - p.root.position.z;
+      const d2 = dx * dx + dz * dz;
+      if (d2 > MAGNET_R * MAGNET_R) continue;
+      if (d2 > PICKUP_R * PICKUP_R) {
+        const d = Math.sqrt(d2) || 1;
+        p.root.position.x += (dx / d) * MAGNET_V * dt;
+        p.root.position.z += (dz / d) * MAGNET_V * dt;
+        continue;
+      }
+      // TAKEN. The float reads like a damage number because that's the beat it lands on —
+      // showDamage() takes any {position} and any string (combat.js passes 'HEADSHOT').
+      this.add(p.amount);
+      this.game.ui?.showDamage({ position: p.root.position }, `$${p.amount}`);
+      this._giveItems(p.items);   // BEFORE _park clears the slot — the money floats, the things get a toast
+      this._park(p);
+    }
+    this._syncHUD();
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────────────────────
+
+  _take() {
+    let oldest = null;
+    for (const p of this.purses) {
+      if (p.t < 0) return p;
+      if (!oldest || p.t > oldest.t) oldest = p;
+    }
+    // Pool exhausted (16 uncollected purses lying about). Recycle the OLDEST — the one he's
+    // had the longest to pick up and didn't. Its cash is forfeit; that's the price of greed.
+    if (oldest) this._live--;
+    return oldest;
+  }
+
+  _park(p) {
+    p.t = -1;
+    p.items = null;                 // a recycled slot must never carry the last body's things
+    p.root.visible = false;
+    this._live = Math.max(0, this._live - 1);
+  }
+
+  // Merge a dropped body's THINGS into the satchel and name them in a toast. Cash floats its own
+  // number (showDamage) the frame it lands; the items get a line so the standout — a watch, a bar —
+  // reads. Guarded on the satchel: a drop before the UI is up simply awards nothing (never in play).
+  _giveItems(items) {
+    if (!items?.length) return;
+    const sat = this.game.ui?.satchel;
+    if (!sat) return;
+    const names = [];
+    for (const it of items) {
+      const got = sat.add(it.id, it.n);
+      if (got > 0) { const nm = LC.items[it.id]?.name ?? it.id; names.push(got > 1 ? `${got}× ${nm}` : nm); }
+    }
+    if (names.length) this.game.ui?.toast?.(`Picked up ${names.join(', ')}`);
+  }
+
+  async _buildPool() {
+    const box = new THREE.Box3();
+    for (let i = 0; i < POOL; i++) {
+      const mesh = await instantiate(`/assets/western/${SACKS[i % SACKS.length]}.fbx`, { texture: ATLAS });
+      // Normalise off the MEASURED height, not a magic scalar: instantiate() hands back a
+      // cm-authored FBX at 0.01 or its metre-scale GLB twin at 1:1 (assets.js decides), and a
+      // hardcoded scale would silently be 100× wrong the day the twin manifest changes.
+      box.setFromObject(mesh);
+      const h = Math.max(1e-3, box.max.y - box.min.y);
+      const s = PURSE_H / h;
+      mesh.scale.multiplyScalar(s);
+      mesh.position.y = -box.min.y * s;   // base sits on the group origin, so bobbing is about the ground
+      const root = new THREE.Group();
+      root.name = 'purse';
+      root.add(mesh);
+      root.visible = false;
+      this.game.scene.add(root);          // added ONCE, here, on the loading screen. Never during play.
+      this.purses.push({ root, amount: 0, t: -1, baseY: 0, phase: 0, items: null });
+    }
+  }
+
+  // ── HUD: "$123", top-right under the clock ───────────────────────────────────────────────
+
+  _buildHUD() {
+    const css = document.createElement('style');
+    // Lifted straight off #clock (ui.js) — same hex plate, same parchment gold, same drop
+    // shadow — so the counter looks like it was always there. Font comes from #hud.
+    css.textContent = `
+      #money { position:absolute; top:74px; right:24px; height:30px; display:flex; align-items:center; justify-content:center; gap:5px; padding:0 20px; filter:drop-shadow(0 2px 4px rgba(0,0,0,0.5)); }
+      #money .mhex { position:absolute; inset:0; z-index:0;
+        background:linear-gradient(180deg,rgba(96,68,34,0.82),rgba(42,28,12,0.86));
+        -webkit-mask:url(/assets/ui/fw/SPR_HUD_FantasyWarrior_Mask_Hexagon_01.png) center/100% 100% no-repeat;
+        mask:url(/assets/ui/fw/SPR_HUD_FantasyWarrior_Mask_Hexagon_01.png) center/100% 100% no-repeat; }
+      #money .mcoin { position:relative; z-index:1; width:15px; height:15px; object-fit:contain; filter:drop-shadow(0 1px 1px rgba(0,0,0,0.6)); }
+      #money .mtxt { position:relative; z-index:1; color:#f0e2c0; font-size:14px; font-weight:600; letter-spacing:1px; text-shadow:0 1px 3px #000; white-space:nowrap; transform-origin:center; }
+      #money .mtxt.bump { animation: moneybump 0.4s ease-out; }
+      @keyframes moneybump { 0% { transform:scale(1.4); color:#fff4c8; } 100% { transform:scale(1); color:#f0e2c0; } }
+    `;
+    document.head.appendChild(css);
+    this._el = null;   // #hud may not exist yet (construction order) — _syncHUD adopts it late
+  }
+
+  _syncHUD() {
+    if (!this._el) {
+      const hud = document.getElementById('hud');
+      if (!hud) return;   // UI not built — try again next frame, cost is one getElementById
+      const div = document.createElement('div');
+      div.id = 'money';
+      div.innerHTML = '<i class="mhex"></i><img class="mcoin" src="/assets/ui/fw/icons/ICON_FantasyWarrior_Inventory_Currency_01_Clean.png" alt=""><span class="mtxt"></span>';
+      hud.appendChild(div);
+      this._el = div.querySelector('.mtxt');
+    }
+    if (this.money === this._shown) return;   // called every frame — only touch the DOM on change
+    const gained = this.money > this._shown && this._bump;
+    this._shown = this.money;
+    this._el.textContent = `$${this.money}`;
+    this._bump = false;
+    if (gained) {
+      // restart the animation: drop the class, force a reflow, put it back
+      this._el.classList.remove('bump');
+      void this._el.offsetWidth;
+      this._el.classList.add('bump');
+    }
+  }
+}
+
+// Fold one drop's item list into another's (a purse top-up on the same spot), summing stacks of the
+// same id. Either side may be null; the result is null only when both are empty.
+function mergeItems(a, b) {
+  if (!a?.length) return b?.length ? b.slice() : null;
+  if (!b?.length) return a.slice();
+  const out = a.map((it) => ({ ...it }));
+  for (const it of b) {
+    const hit = out.find((o) => o.id === it.id);
+    if (hit) hit.n += it.n; else out.push({ ...it });
+  }
+  return out;
+}
+
+// Re-exported so a caller that already has `game.loot` doesn't need a second import to ask
+// "what kind of purse is this man carrying".
+export const purseFor = (...a) => LC.purseFor(...a);
+export const purseKind = (...a) => LC.purseKind(...a);
+
+// ─────────────────────────────────────────────────────────────────────────────────────────
+// WIRING — what main.js must do (this file touches nothing else).
+//
+//  1. import, with the other game systems near the top:
+//         import { Loot } from './game/loot.js';
+//
+//  2. construct in boot(), right after `this.deadEye = new DeadEye(this);` (main.js:209) —
+//     after audio/ui because it drives both — and await the purse pool BEFORE the loading
+//     screen comes down (the sacks are static props, but they are built once, not per drop):
+//         this.loot = new Loot(this);
+//         await this.loot.ready;     // the purse pool: 16 sacks, built on the loading screen
+//
+//  3. tick it inside the `if (!paused)` block, next to vfx/shatter (main.js:617-620), so it
+//     freezes with the pause menu:
+//         this.loot.update(dt);
+//
+//  4. no other hooks. Whoever kills a man calls it:
+//         game.loot.dropFor('driver', rider.position)   // rolls the band from data/purse.js
+//         game.loot.drop(pos, 12)                       // or an explicit sum
+//     and the pickup, the HUD and the coin sound take care of themselves.
+// ─────────────────────────────────────────────────────────────────────────────────────────