sindicate 0.2.0 → 0.4.0

package/src/systems/climbing.js

@@ -0,0 +1,136 @@
+// Climbing: the player's ladder controller — ported from fable/src/game/climbing.js and adapted to
+// western. The climb clips (climbMount/Up/Down/Top/Idle) are already retargeted onto the player rig
+// through the normal clip pipeline (clips.js → the default Synty rig), so this just snaps the player to
+// a registered ladder and runs mount → up/down loop (code-driven vertical) → climb-off.
+//
+// Ladders come from world.ladders (town.js buildLadders): [{ base:Vector3(world), quat:Quaternion(world),
+// height }]. main.js's E-contest resolves the nearest one and calls mount(l). Mirrors Riding's
+// "takes over the player's update + camera" shape; player.update early-returns while active.
+import * as THREE from 'three/webgpu';
+
+const CLIMB_SPEED = 1.7;   // m/s along the rungs (match the up/down loop cadence)
+const ANIM_SPEED = 2;      // clip playback ×; the mocap loops are slow, so 2× keeps the hands with the movement
+const BODY_OFF = 0.30;     // player root sits this far back from the ladder line (gripping side)
+const FACE_SIGN = 1;       // +1 for western's ladder props (fable used −1); flips which side the climber grips + faces
+const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+const _axis = new THREE.Vector3(), _face = new THREE.Vector3();
+
+export class Climbing {
+  constructor(player) {
+    this.player = player;
+    this.game = player.game;
+    this.mode = 'off';      // off | mounting | climbing | dismounting
+    this.ladder = null; this.h = 0; this.faceYaw = 0; this.height = 0;
+  }
+
+  get active() { return this.mode !== 'off'; }   // getter — never assign it; forceOff() resets the raw fields
+
+  // up-the-rungs axis (from the prop quat) + the horizontal yaw to face INTO the ladder
+  _solve(l) {
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();      // climb direction
+    _face.set(_axis.x, 0, _axis.z);                              // a leaning ladder tilts away from the wall
+    if (_face.lengthSq() < 1e-3) _face.set(0, 0, 1).applyQuaternion(l.quat).setY(0);   // vertical ladder → prop +Z
+    _face.normalize();
+    this.faceYaw = Math.atan2(FACE_SIGN * _face.x, FACE_SIGN * _face.z);
+  }
+
+  // Cap the climb at the SURFACE you step onto. The ladder MESH runs from its base to its own top, which
+  // sits above the roofline (a real ladder pokes past the eaves). Raycast down over the ladder top, nudged
+  // toward the building, for the highest roof/floor at/below the mesh top, and top the climb out there so
+  // you don't climb off into thin air. Falls back to the mesh height if no surface is found.
+  _resolveHeight(l) {
+    const W = this.game.world;
+    const bvhs = [W.buildingBVH, ...(W.sideBVHs || [])].filter((b) => b && b.raycast);
+    if (!bvhs.length || !W._snapRay) return l.height;
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    const sx = l.base.x + _axis.x * l.height + Math.sin(this.faceYaw) * 0.7;   // over the top, onto the roof
+    const sz = l.base.z + _axis.z * l.height + Math.cos(this.faceYaw) * 0.7;
+    const ray = W._snapRay; ray.origin.set(sx, l.base.y + l.height + 4, sz); ray.direction.set(0, -1, 0);
+    let roof = -Infinity;
+    for (const b of bvhs) {
+      const hs = b.raycast(ray, 2) || [];
+      for (const h of hs) {
+        const n = h.face?.normal;
+        if (n && Math.abs(n.y) > 0.4 && h.point.y > roof && h.point.y <= l.base.y + l.height + 0.3) roof = h.point.y;
+      }
+    }
+    return roof > l.base.y + 1 ? Math.min(l.height, roof - l.base.y + 0.15) : l.height;
+  }
+
+  // ENTRY — main.js's E-contest resolves the nearest ladder and calls this. Enters at the bottom, or the
+  // top if you walked onto it from the roof platform.
+  mount(l) {
+    if (this.active || !l) return;
+    this._solve(l);
+    this.height = this._resolveHeight(l);   // cap the climb at the surface you step ONTO (the mesh pokes above)
+    // Enter at YOUR height on the rungs — project (you − base) onto the climb axis — so grabbing from the
+    // street enters at the bottom, from the roof at the top, and RE-GRABBING MID-AIR (after a hop-off)
+    // continues from where you are instead of snapping to an end.
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    const p = this.player.position;
+    const hAlong = (p.x - l.base.x) * _axis.x + (p.y - l.base.y) * _axis.y + (p.z - l.base.z) * _axis.z;
+    this.ladder = l; this.mode = 'mounting'; this.h = clamp(hAlong, 0, this.height);
+    this._place(); this.player.busy = true;
+    this.player.animator.play('climbMount', { once: true, fade: 0.12, timeScale: ANIM_SPEED, onDone: () => { if (this.mode === 'mounting') this.mode = 'climbing'; } });
+  }
+
+  // place the player at height h along the rungs, set back from the ladder by BODY_OFF, facing it
+  _place() {
+    const l = this.ladder, p = this.player;
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    p.position.x = l.base.x + _axis.x * this.h - Math.sin(this.faceYaw) * BODY_OFF;
+    p.position.z = l.base.z + _axis.z * this.h - Math.cos(this.faceYaw) * BODY_OFF;
+    p.position.y = l.base.y + _axis.y * this.h;
+    p._visualY = p.position.y;                  // keep the model lift glued to the climb height
+    p.heading = this.faceYaw; p.root.rotation.y = this.faceYaw;
+  }
+
+  update(dt, input, camera) {
+    const p = this.player, l = this.ladder;
+    const ui = this.game.ui;
+    const inMenu = ui?.anyPanelOpen || ui?.dialogueOpen || ui?.cinematic;
+    if (this.mode === 'climbing') {
+      let v = 0;
+      if (!inMenu) { if (input.down('KeyW')) v += 1; if (input.down('KeyS')) v -= 1; }   // held W/S
+      p.animator.play(v > 0 ? 'climbUp' : v < 0 ? 'climbDown' : 'climbIdle', { fade: 0.12, timeScale: ANIM_SPEED });
+      this.h = clamp(this.h + v * CLIMB_SPEED * dt, 0, this.height);
+      this._place();
+      if (this.h >= this.height && v > 0) {                    // reached the top → climb off
+        this.mode = 'dismounting';
+        p.animator.play('climbTop', { once: true, fade: 0.12, timeScale: ANIM_SPEED, onDone: () => this._dismount(true) });
+      } else if (this.h <= 0 && v < 0) this._dismount(false);  // stepped off the bottom
+      else if (!inMenu && input.hit('Space')) this._dismount(false); // hop off anywhere
+    } else {
+      this._place();                                            // mounting | dismounting — hold while the clip plays
+    }
+    // Reuse the player's OWN look + follow camera (not a bespoke one) so the on-foot ↔ climb transition is
+    // seamless — _camera reads position + _visualY, which _place() keeps synced to the climb height.
+    if (!inMenu) p._look?.(input, this.game.rawDt ?? dt);
+    p._camera(dt, input, camera);
+  }
+
+  _dismount(top) {
+    const l = this.ladder, p = this.player;
+    if (top) {                                                 // step forward off the top onto the surface
+      _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+      p.position.x = l.base.x + _axis.x * this.height + Math.sin(this.faceYaw) * 0.7;
+      p.position.z = l.base.z + _axis.z * this.height + Math.cos(this.faceYaw) * 0.7;
+      p.position.y = l.base.y + _axis.y * this.height + 0.1;
+    }
+    this.mode = 'off'; this.ladder = null;
+    // PIN _visualY to the current feet height, NOT undefined: this same frame the climb update still calls
+    // p._camera(), which reads `_visualY + 1.55` — undefined there = NaN = a grey (void) screen. position.y
+    // is valid, and the on-foot smoother continues cleanly from it next frame.
+    p.busy = false; p.vy = 0; p.airborne = false; p._visualY = p.position.y;
+    p.animator.play('idle', { fade: 0.15 });
+  }
+
+  // Hard exit for death / fast-travel / load — a LIVE controller re-glues the player to the ladder every
+  // frame via _place(), silently undoing any teleport. Reset the raw fields (never assign .active).
+  forceOff() {
+    if (!this.active) return;
+    const p = this.player;
+    this.mode = 'off'; this.ladder = null;
+    p.busy = false; p.vy = 0; p.airborne = false; p._visualY = p.position.y;
+  }
+}

package/src/systems/deadeye.js

@@ -0,0 +1,332 @@
+// DEAD EYE — the RDR2 signature, on CTRL.
+//
+// THE CONTRACT (why this file exists at all): AIMING must not change the screen or the clock.
+// RMB is a lean, nothing more. THIS is the thing that slows time, drains the world of colour
+// and lets you paint shots onto a man before you take them.
+//
+// FLOW
+//   Ctrl (gun drawn, meter has charge) → ACTIVE
+//     · the WORLD runs at ~0.3× (main.js multiplies its world-dt chain by this.scale) while
+//       the camera and the aim IK keep running on wall-clock dt — you aim at full speed
+//       inside a slow world, which is the whole trick. (player.js reads game.rawDt.)
+//     · the screen desaturates to sepia + a red vignette closes in + grain (ONE uniform:
+//       renderer.js's deadEyeGrade, driven from this.amount).
+//     · the audio goes underwater (audio.setDeadEye — lowpass + slowed sample pitch).
+//     · CLICKING a man marks a shot at the exact body point under the reticle. One click, one bullet.
+//   Ctrl again / LMB / an empty meter → RELEASE: the tags fire in sequence, ~0.12s apart,
+//     each one down the SAME combat.fireBullet path as a normal shot (identical damage,
+//     blood, impacts, ammo, recoil), and time ramps back to normal as the queue empties.
+//
+// TIME DISCIPLINE: every timer in this file runs on RAW (wall-clock) dt. A Dead Eye that
+// metered itself in slow-mo time would drain 3× slower the moment it started slowing the
+// world — the feature would fight its own clock. main.js calls update(rawDt) BEFORE it
+// applies the dt multiplier chain, so the scale returned here lands on the SAME frame.
+import * as THREE from 'three/webgpu';
+import { clamp, lerp } from '../core/utils.js';
+
+// ---- TUNABLES (all of them, in one place) -------------------------------------------
+export const DEAD_EYE = {
+  meterMax: 1,          // the meter is normalised 0..1 (player.deadEye — the HUD contract)
+  drainRate: 0.15,      // meter/sec while ACTIVE  → ~6.7s of slow-mo from full. It was 0.30 and three
+                        // seconds is not long enough to read a street, pick your men and paint them —
+                        // you spent the whole meter deciding. Twice the time, same meter.
+  refillRate: 0.022,    // meter/sec passive       → ~45s from empty doing nothing
+  refillPerDamage: 0.004, // meter per point of damage dealt (a 16-dmg revolver hit ≈ 0.064)
+  refillOnKill: 0.20,   // meter per kill — the loop that keeps a gunfight in Dead Eye
+  timeScale: 0.3,       // the WORLD's dt multiplier at full amount (camera/aim stay 1×)
+  maxTags: 6,           // hard cap (also capped by ammo in the chamber and meter left)
+  tagRadius: 1.0,       // metres — how close the aim ray must pass to a body to paint it
+  tagCost: 0.09,        // meter spent per tag — this is what "cap tags by meter" means
+  tagCooldown: 0.16,    // seconds between tags, so one hover doesn't dump the whole cylinder
+  tagInterval: 0.12,    // seconds between the queued shots on release
+  rampIn: 9,            // amount lerp rate into Dead Eye (fast — the snap is the drama)
+  rampOut: 5,           // and out of it
+  minCharge: 0.12,      // meter needed to activate at all (a sliver can't buy a shot)
+  range: 60,            // metres — how far a tag can be painted
+};
+
+const _o = new THREE.Vector3();   // ray origin (camera)
+const _d = new THREE.Vector3();   // ray direction (the aim ray)
+const _a = new THREE.Vector3();   // body segment foot
+const _b = new THREE.Vector3();   // body segment head
+const _p = new THREE.Vector3();   // closest point on the body
+const _hit = new THREE.Vector3();
+const _pt = new THREE.Vector3();
+
+export class DeadEye {
+  constructor(game) {
+    this.game = game;
+    this.active = false;       // Ctrl-slow-mo running, painting tags
+    this.firing = false;       // the volley is going out
+    this.amount = 0;           // 0..1 — the ONE blend: grade uniform, audio, time scale
+    this.scale = 1;            // world-dt multiplier main.js reads (1 → DEAD_EYE.timeScale)
+    this.tags = [];            // [{ enemy, off: Vector3, point: Vector3 }] — painted shots
+    this.queue = [];           // tags being fired out, in paint order
+    this._queueN = 0;          // queue length at release (drives the ramp back to full speed)
+    this._tagT = 0;            // tag cooldown
+    this._fireT = 0;           // next-shot timer during the volley
+    this._hpSum = null;        // enemy-health census, for the hit/kill refill (no combat hook)
+    this._aliveN = null;
+    this._lastAmt = -1;        // change-gates for the uniform + audio writes
+    this._lastAudio = -1;
+  }
+
+  // ---- state ------------------------------------------------------------------------
+
+  // Everything that must be true to hold Dead Eye open. Mirrors player.js's own "stolen"
+  // guards (menu / dialogue / cinematic / mounted / dead) plus: you need a GUN IN HAND.
+  _canUse() {
+    const p = this.game.player, ui = this.game.ui;
+    if (!p || !p.alive) return false;
+    if (p.riding?.mounted) return false;
+    if (ui?.menuOpen || ui?.dialogueOpen || ui?.cinematic) return false;
+    if (!p.drawn || p.weapon === 'fists' || !(p.ammoMax > 0)) return false;
+    return true;
+  }
+
+  activate() {
+    if (this.active || this.firing) return false;
+    const p = this.game.player;
+    // A MAN WHO CALLS FOR DEAD EYE WANTS HIS GUN IN HIS HAND. Ctrl used to be refused outright with
+    // the revolver still in leather (_canUse rejects !p.drawn), so it took two keys to express one
+    // intention: draw, then Ctrl. Now Ctrl IS the draw — it clears leather and comes up aiming, which
+    // is the whole beat. (player.js reads deadEyeActive as an aim hold, so the stance follows.)
+    if (p?.alive && !p.riding?.mounted) {
+      if (p.weapon === 'fists' && p.ammoMax !== 0) p.weapon = 'revolver';
+      if (!p.drawn && p._drawT <= 0) p._startDraw();
+    }
+    if (!this._canUse()) return false;
+    if ((p.deadEye ?? 0) < DEAD_EYE.minCharge) { this.game.audio?.play('dryfire'); return false; }
+    this.active = true;
+    this._tagT = 0;
+    this.tags.length = 0;
+    p.deadEyeActive = true;
+    this.game.hint?.('deadeye', 'DEAD EYE — CLICK each man to mark him. Let go (or Ctrl) and they all go.');
+    return true;
+  }
+
+  // Let the painted shots fly. Empty queue = just drop out of slow-mo.
+  release() {
+    if (!this.active) return;
+    this.active = false;
+    this.game.player.deadEyeActive = false;
+    this.queue = this.tags.slice();
+    this.tags = [];
+    this._queueN = this.queue.length;
+    if (!this._queueN) { this.firing = false; return; }
+    this.firing = true;
+    this._fireT = 0;   // the first shot leaves immediately
+  }
+
+  // Hard stop, no shots fired — death, mount, menu, holster.
+  cancel() {
+    if (!this.active && !this.firing) return;
+    this.active = false;
+    this.firing = false;
+    this.tags.length = 0;
+    this.queue.length = 0;
+    this._queueN = 0;
+    if (this.game.player) this.game.player.deadEyeActive = false;
+  }
+
+  // ---- frame --------------------------------------------------------------------------
+  // rawDt is WALL-CLOCK seconds (see the header). Called from main.js before the dt chain.
+  update(rawDt) {
+    const p = this.game.player;
+    if (!p) return;
+    const input = this.game.input;
+    const dt = Math.min(rawDt, 0.1);
+
+    // an interruption (death / mount / menu / the gun going back to leather) kills it dead
+    if ((this.active || this.firing) && !this._canUse()) this.cancel();
+
+    // ---- input. Ctrl TOGGLES. The MIDDLE MOUSE BUTTON HOLDS: press it and she is up, let go and the
+    // volley leaves — the gesture your hand already knows, and one that cannot strand you in slow-mo
+    // because you forgot you were in it. LMB also looses the volley (and is CONSUMED so player.js's
+    // gun state machine never sees it — otherwise the same click would fire a hip shot as well).
+    if (input && !this.game.ui?.menuOpen) {
+      if (input.hit('ControlLeft') || input.hit('ControlRight')) {
+        if (this.active) this.release();
+        else if (!this.firing) this.activate();
+      }
+      const mmb = input.held(1) && input.acting;
+      if (mmb && !this._mmb && !this.active && !this.firing) this.activate();   // pressed: she comes up
+      else if (!mmb && this._mmb && this.active) this.release();                // let go: they go
+      this._mmb = mmb;
+
+      // LEFT CLICK MARKS A MAN. It used to LOOSE the volley, and the marks painted themselves off
+      // whatever the reticle happened to sweep across — so the shots were chosen by where you waved
+      // the mouse, not by you, and a man you merely glanced past took a bullet. Now it is deliberate:
+      // hold Dead Eye, click each man you want, let go and they all go. Consumed, so player.js's gun
+      // state machine never sees the click and does not also fire a hip shot down the same barrel.
+      if (this.active && input.mouseHit(0) && input.acting) {
+        input.consumeMouse?.(0);
+        this._mark();
+      }
+    }
+
+    // ---- meter. Drains ONLY while active; refills on time, and on damage/kills (polled
+    // from the enemy roster, so combat.js needs no hook).
+    this._refill(dt);
+    if (this.active) {
+      p.deadEye = clamp((p.deadEye ?? 0) - DEAD_EYE.drainRate * dt, 0, DEAD_EYE.meterMax);
+      if (p.deadEye <= 0) this.release();          // ran dry → the shots go anyway
+    }
+
+    // ---- painting. NOT automatic any more: a mark is a click (see _mark, called from the input
+    // block above). The cooldown still ticks, so a held mouse button cannot empty the cylinder.
+    if (this.active) this._tagT = Math.max(0, this._tagT - dt);
+
+    // ---- the volley
+    if (this.firing) this._volley(dt);
+
+    // ---- ONE blend drives everything. While the volley empties, the target falls with the
+    // queue — so time is already most of the way back to normal by the last shot.
+    const target = this.active ? 1
+      : (this.firing && this._queueN) ? clamp(this.queue.length / this._queueN, 0, 1)
+        : 0;
+    const rate = target > this.amount ? DEAD_EYE.rampIn : DEAD_EYE.rampOut;
+    this.amount = lerp(this.amount, target, Math.min(1, dt * rate));
+    if (this.amount < 0.002 && target === 0) this.amount = 0;   // settle exactly to zero
+    this.scale = 1 + (DEAD_EYE.timeScale - 1) * this.amount;
+
+    // screen grade: ONE uniform (renderer.js). Written only when it actually moves.
+    const amt = this.amount;
+    if (Math.abs(amt - this._lastAmt) > 0.002) {
+      this._lastAmt = amt;
+      const u = this.game.postProcessing?.gradeAmount;
+      if (u) u.value = amt;
+    }
+    // audio: lowpass + slowed sample pitch. setTargetAtTime ramps, so a coarse gate is fine.
+    if (Math.abs(amt - this._lastAudio) > 0.02 || (amt === 0 && this._lastAudio !== 0)) {
+      this._lastAudio = amt;
+      this.game.audio?.setDeadEye?.(amt);
+    }
+
+    // markers (screen-space DOM Xs, drawn by ui.js)
+    this.game.ui?.deadEyeTags?.(this.active || this.firing ? this._live() : null);
+  }
+
+  // Refill: passive trickle + the damage/kill census. No combat.js hook — we just watch the
+  // enemy roster's total health and headcount. A drop in health can only have come from the
+  // player (nothing else hurts them), and a drop in the alive count is a kill. Respawns
+  // raise both, and a rise clamps to zero credit.
+  _refill(dt) {
+    const p = this.game.player;
+    const es = this.game.combat?.enemies;
+    let credit = 0;
+    if (es) {
+      let sum = 0, n = 0;
+      for (const e of es) { if (e.alive) { n++; sum += Math.max(0, e.health); } }
+      if (this._hpSum !== null) {
+        credit += Math.max(0, this._hpSum - sum) * DEAD_EYE.refillPerDamage;
+        credit += Math.max(0, this._aliveN - n) * DEAD_EYE.refillOnKill;
+      }
+      this._hpSum = sum;
+      this._aliveN = n;
+    }
+    if (this.active) return;                      // drains only while active — no fighting it
+    credit += DEAD_EYE.refillRate * dt;
+    if (credit > 0) p.deadEye = clamp((p.deadEye ?? 0) + credit, 0, DEAD_EYE.meterMax);
+  }
+
+  // ---- marking ------------------------------------------------------------------------
+  // ONE CLICK, ONE MARK. The aim ray is the CAMERA ray (player.aimDir — the same vector _fire()
+  // shoots down), so the man under the reticle when you click is the man who gets the bullet, and
+  // nobody else does. A dry click (no man under the reticle, no chambers left, no meter) says so and
+  // paints nothing.
+  _mark() {
+    const p = this.game.player;
+    const cap = Math.min(DEAD_EYE.maxTags, p.ammo ?? 0);
+    // A refused mark must SAY it was refused — a click that silently does nothing reads as a broken
+    // button, and you will keep clicking it. Out of chambers and out of meter are the two caps.
+    if (this.tags.length >= cap) { this.game.audio?.play('dryfire'); return; }
+    if ((p.deadEye ?? 0) < DEAD_EYE.tagCost) { this.game.audio?.play('dryfire'); return; }
+    if (this._tagT > 0) return;                      // ...but a double-click inside 0.16s is just a hand
+
+    _o.copy(this.game.camera.position);
+    p.aimDir(_d).normalize();
+
+    let best = null, bestT = Infinity;
+    for (const e of this.game.combat?.enemies ?? []) {
+      // noTarget (npc.js) — belt and braces. A child is never an Enemy, so this list cannot hold
+      // one today; the guard is here so that the guarantee survives someone making one tomorrow.
+      if (!e.alive || e.faction === 'ally' || e.noTarget) continue;
+      if (e.position.distanceTo(p.position) > DEAD_EYE.range) continue;
+      // body = a vertical segment from shin to head — a tag lands where the ray crossed it
+      _a.set(e.position.x, e.position.y + 0.35, e.position.z);
+      _b.set(e.position.x, e.position.y + 1.75, e.position.z);
+      const t = this._raySeg(_o, _d, _a, _b, _p);
+      if (t < 0 || t > bestT) continue;
+      if (_p.distanceTo(_hit.copy(_o).addScaledVector(_d, t)) > DEAD_EYE.tagRadius) continue;
+      if (this.game.world?.losBlocked?.(p.position, e.position)) continue;  // no marking through walls
+      best = { e, t, point: _p.clone() };
+      bestT = t;
+    }
+    if (!best) return;
+
+    // store the point as an offset from the enemy's origin, so the marker (and the bullet)
+    // track him as he keeps walking in slow motion
+    this.tags.push({
+      enemy: best.e,
+      off: best.point.clone().sub(best.e.position),
+      point: best.point.clone(),
+    });
+    p.deadEye = clamp(p.deadEye - DEAD_EYE.tagCost, 0, DEAD_EYE.meterMax);
+    this._tagT = DEAD_EYE.tagCooldown;
+    this.game.audio?.play('ui');
+  }
+
+  // Closest approach of ray (o,dir — dir normalized) to segment [a,b]. Returns the ray
+  // parameter t of the closest point (>= 0), or -1 if the closest approach is behind the
+  // lens; writes the closest point ON THE SEGMENT into `out`. (Ericson, clamped.)
+  _raySeg(o, dir, a, b, out) {
+    const vx = b.x - a.x, vy = b.y - a.y, vz = b.z - a.z;
+    const wx = o.x - a.x, wy = o.y - a.y, wz = o.z - a.z;
+    const bb = dir.x * vx + dir.y * vy + dir.z * vz;      // u·v
+    const cc = vx * vx + vy * vy + vz * vz;               // v·v
+    const dd = dir.x * wx + dir.y * wy + dir.z * wz;      // u·w
+    const ee = vx * wx + vy * wy + vz * wz;               // v·w
+    const den = cc - bb * bb;                             // (u·u = 1)
+    // segment param = (a·e − b·d)/D with a = u·u = 1. The sign matters: flipped, every hit
+    // clamps to the man's SHINS and lands >1m off the ray, so nothing ever tags.
+    let s = den > 1e-9 ? (ee - bb * dd) / den : 0;
+    s = clamp(s, 0, 1);
+    const t = bb * s - dd;                                // ray param at that s
+    out.set(a.x + vx * s, a.y + vy * s, a.z + vz * s);
+    return t < 0 ? -1 : t;
+  }
+
+  // Live world points of the current tags (they follow their man). Reused array — this runs
+  // every frame while Dead Eye is up.
+  _live() {
+    const list = this._liveArr ??= [];
+    list.length = 0;
+    const src = this.active ? this.tags : this.queue;
+    for (const t of src) {
+      if (t.enemy?.alive) t.point.copy(t.enemy.position).add(t.off);   // track the moving man
+      list.push(t.point);
+    }
+    return list;
+  }
+
+  // ---- the volley ---------------------------------------------------------------------
+  // One shot every tagInterval, in paint order, each down player.deadEyeShot → the same
+  // combat.fireBullet path as LMB (same damage, blood, impacts, ammo, muzzle-flip, kick).
+  _volley(dt) {
+    const p = this.game.player;
+    this._fireT -= dt;
+    while (this._fireT <= 0 && this.queue.length) {
+      const tag = this.queue.shift();
+      if (tag.enemy?.alive) tag.point.copy(tag.enemy.position).add(tag.off);
+      _pt.copy(tag.point);
+      if (!p.deadEyeShot(_pt)) { this.queue.length = 0; break; }   // dry — drop the rest
+      this._fireT += DEAD_EYE.tagInterval;
+    }
+    // the last shot still gets its beat before time snaps back
+    if (!this.queue.length && this._fireT <= 0) {
+      this.firing = false;
+      this._queueN = 0;
+    }
+  }
+}

package/src/systems/encounters.js

@@ -0,0 +1,123 @@
+// ENCOUNTERS — the bandit camps, the drover outfits and the Red Hawk riding parties that live in
+// the empty country between the towns. Data in data/encounters.js; this file builds it and owns
+// the one rule that isn't already in the game: an outfit that sees you shoot one of its own.
+//
+// PERF LAW, and it is the whole shape of this file: nothing here is ever spawned, despawned or
+// respawned. Every body — 14 bandits, 14 drovers/riders, 6 outfit guns, 2 loners — is constructed
+// behind the loading screen through the machinery that already exists (combat.spawn for the
+// Enemies, new NPC for the civilians) and stands at its anchor for the life of the run. Waking a
+// camp when you ride up to it is not a thing that needs writing: it already happens, because
+// Enemy.update strides its FSM at a quarter rate beyond the entity cull and NPC.update sleeps
+// outright past AI_RANGE, and the moment you cross that line they simply start thinking again.
+//
+// Two consequences, both deliberate:
+//   * `combat.addSpawner` is NOT used. Its respawn tick (combat.js) is the one place in this
+//     codebase that builds a skinned mesh during play. A cleared camp stays cleared — the county
+//     changes because of you, and the perf hazard is deleted rather than managed.
+//   * camp bodies carry `noEvict`, so combat's 6-second corpse eviction never tears their skinned
+//     meshes back out of the scene (r184's dispose handler evicts a removed mesh's pipelines with
+//     it). The dead lie where they fell in the dirt, which is what a western wants anyway.
+import { NPC } from './npc.js';
+// encounter tables are GAME data: setEncounterTables({ camps, outfits, loners })
+let ET = { camps: [], outfits: [], loners: [] };
+export function setEncounterTables(t) { ET = { ...ET, ...t }; }
+
+const T = '/assets/textures';
+const TOWN_TEX = [`${T}/atlas_western.png`, `${T}/atlas_western_b.png`, `${T}/atlas_western_c.png`, `${T}/atlas_western_alt2.png`, `${T}/atlas_western_alt3.png`];
+
+export class Encounters {
+  constructor(game) {
+    this.game = game;
+    this.groups = new Map();   // id → { id, name, kind, x, z, members[], guns[] }
+  }
+
+  async build(clips) {
+    const g = this.game;
+    g.npcs ??= [];
+
+    // ── the gangs. Ordinary hostiles: passive:false, so they aggro when you come inside aggroR.
+    // A short leash (26 m) means a camp holds its ground rather than following you across the
+    // county — enemy.js drops the chase past leashR * 1.6.
+    for (const c of ET.camps) {
+      const grp = { id: c.id, name: c.name, kind: 'camp', x: c.x, z: c.z, members: [], guns: [] };
+      this.groups.set(c.id, grp);
+      await Promise.all(c.men.map(async (type, i) => {
+        const a = (i / c.men.length) * Math.PI * 2;
+        try {
+          const e = await g.combat.spawn(type, c.x + Math.sin(a) * 5.5, c.z + Math.cos(a) * 5.5, { leashR: c.leashR });
+          e.noEvict = true;        // the corpse stays; nothing leaves the scene (see the header)
+          e.group = grp;
+          grp.members.push(e);
+        } catch (err) { console.warn('[encounters] camp body failed', c.id, type, err); }
+      }));
+    }
+
+    // ── the neutral outfits. The men are real NPCs (civilians: shootable, lootable, witnesses);
+    // the one gun in the outfit is a passive Enemy who never starts anything on his own.
+    for (const o of [...OUTFITS]) {
+      const grp = { id: o.id, name: o.name, kind: 'outfit', x: o.x, z: o.z, members: [], guns: [] };
+      this.groups.set(o.id, grp);
+      await Promise.all(o.men.map(async (m, i) => {
+        const def = {
+          id: `${o.id}_${i}`, purse: m.purse, name: m.name, char: m.char,
+          roam: { x: o.x, z: o.z, r: o.r }, idles: m.idles,
+          ...(m.tex != null ? { tex: TOWN_TEX[m.tex % TOWN_TEX.length] } : {}),
+        };
+        try {
+          const npc = new NPC(g, def, clips);
+          await npc.load();
+          npc.settle();
+          g.scene.add(npc.root);
+          g.npcs.push(npc);
+          npc.group = grp;
+          grp.members.push(npc);
+        } catch (err) { console.warn('[encounters] outfit body failed', o.id, m.name, err); }
+      }));
+      if (o.gun) {
+        try {
+          const e = await g.combat.spawn(o.gun, o.x + 3, o.z - 3, { leashR: 22, passive: true });
+          e.noEvict = true;
+          e.group = grp;
+          grp.members.push(e);
+          grp.guns.push(e);
+        } catch (err) { console.warn('[encounters] outfit gun failed', o.id, err); }
+      }
+    }
+
+    // ── the lone ones
+    for (const l of ET.loners) {
+      try {
+        const npc = new NPC(g, { id: l.id, purse: l.purse, name: l.name, char: l.char, roam: { x: l.x, z: l.z, r: l.r }, idles: l.idles }, clips);
+        await npc.load();
+        npc.settle();
+        g.scene.add(npc.root);
+        g.npcs.push(npc);
+      } catch (err) { console.warn('[encounters] loner failed', l.id, err); }
+    }
+
+    const bandits = [...this.groups.values()].filter((x) => x.kind === 'camp').reduce((a, x) => a + x.members.length, 0);
+    const outfit = [...this.groups.values()].filter((x) => x.kind === 'outfit').reduce((a, x) => a + x.members.length, 0);
+    console.log(`[encounters] ${this.groups.size} groups out in the county: ${bandits} bandits (hostile), ${outfit} neutrals, ${ET.loners.length} loners`);
+    return this;
+  }
+
+  // THEY TAKE IT BADLY. You shot one of them; his outfit draws. Called from NPC.takeDamage (a
+  // drover) and Enemy.takeDamage (the outfit's gun) — both only when the PLAYER did it, so an
+  // outlaw's stray round can never start a war with a cattle drive.
+  //
+  // The men of the outfit who aren't the gun are NPCs and have no fight in them: they run, exactly
+  // as a townsman does, and they are the witnesses that make the murder cost you stars. The gun
+  // stops being passive and hunts you. He is the ONLY thing that changes.
+  provokeGroup(who) {
+    const grp = who?.group;
+    if (!grp || grp.kind !== 'outfit' || grp.angry) return;
+    grp.angry = true;
+    for (const gun of grp.guns) {
+      if (!gun.alive || gun === who) continue;
+      gun.provoke();
+      gun.leashR = 40;   // he will follow you a way for this — but not across the county
+    }
+    this.game.ui?.toast?.(`${grp.name} — they saw that.`, 3000);
+    this.game.audio?.play('aggro');
+  }
+}