sindicate 0.4.0 → 0.6.0

package/src/systems/player.js

@@ -0,0 +1,1619 @@
+// The Gunslinger: third-person controller, camera, locomotion FSM, and the
+// revolver/rifle gun state machine.
+//
+// CONTROLS — the RDR2 model. There is no "bullet mode" to enter:
+//   LMB   fire ONE shot. Holstered? the click draws first and is BUFFERED across the
+//         draw gate, so the shot lands the instant the leather clears. Never dropped.
+//   RMB   OPTIONAL ADS (hold): tighter over-shoulder cam, tighter spread, reticle.
+//         You never have to hold it to shoot — hip-fire just scatters more.
+//   R     reload · Q  weapon cycle · Alt  dodge · E  mount.
+//   Ctrl is NOT bound here — it belongs to Dead Eye.
+//
+// WHERE THE GUN POINTS is a procedural IK (applyAimIK), not heading math. The pack's aim
+// clips are BLADED (the body is angled off the aim line), so no amount of rotating the root
+// can make the muzzle track the reticle — the old code tried (heading = camYaw + PI plus an
+// _aimTwist spine twist) and that is exactly what made the player "face slightly right" and
+// the torso "spin around" on a wrap. Now the root just faces the camera on the shortest arc
+// and the right-arm chain is rotated in world space onto the camera ray.
+import * as THREE from 'three/webgpu';
+import { aimPoint, nearestBody, rayCapsule, shotDir } from './aim.js';
+import { Character } from './entity.js';
+
+import { instantiate, resolveModelUrl } from '../core/assets.js';
+import { clamp, lerp, angleLerp, tmpV1 } from '../core/utils.js';
+
+
+// Player content is GAME data — register at boot, before the Player is constructed:
+//   setPlayerContent({ model, playerClips, clipSubset, weapons, weaponMesh, weaponTex,
+//                      attachments, clipTiming, worldSize })
+// WEAPONS is a registered live export: satchel/shop/benches read it as they always did.
+export const WEAPONS = {};
+let PC = {
+  clipSubset: (c) => c, playerClips: [], weaponMesh: {}, weaponTex: null,
+  model: { model: null, keep: null, texture: null, texFlipY: true, playerLook: false, outfit: null,
+           speed: 5.2, health: 100, faction: 'player', name: 'Player' },
+  attachments: {}, clipTiming: {}, worldSize: 4320,
+};
+export function setPlayerContent(c = {}) {
+  if (c.weapons) Object.assign(WEAPONS, c.weapons);
+  PC = { ...PC, ...c };
+}
+import { Riding } from './riding.js';
+import { Climbing } from './climbing.js';
+import { Footsteps } from './footsteps.js';
+import { collectFistJoints, applyFist } from './fistCurl.js';
+
+const _camTarget = new THREE.Vector3(); // reused each frame for the camera lerp
+const _camDir = new THREE.Vector3(), _camRay = new THREE.Ray(); // camera-wall raycast scratch
+const _rbQ1 = new THREE.Quaternion(), _rbQ2 = new THREE.Quaternion(); // torso re-blade scratch
+// aim-IK scratch (no per-frame allocation — this runs inside the render loop)
+const _ikA = new THREE.Vector3(), _ikB = new THREE.Vector3(), _ikDir = new THREE.Vector3();
+const _ikQ1 = new THREE.Quaternion(), _ikQ2 = new THREE.Quaternion(), _ikQ3 = new THREE.Quaternion();
+
+
+// WeaponData (contract): rate = seconds between shots, recoil scales the camera
+// kick, range caps the bullet flight. Reserve ammo is infinite in v1.
+// A BULLET DOES NOT STOP BECAUSE IT IS TIRED.
+// `range` is only the distance at which the round is finally swept up (combat.js: ttl = range /
+// speed) — it exists so a stray shot into the sky doesn't live forever, NOT to define how far you
+// can kill a man. It used to be 60m on the revolver and 120m on the rifle, which meant a round
+// aimed at somebody further away simply evaporated in mid-air: the reticle was on him, the gun went
+// off, and nothing happened, with no impact and no miss to explain it. Real guns carry to the
+// horizon and so do these. What punishes a long shot is the SPREAD (and your hand), which is where
+// the difficulty belongs — the world is ~2km across, so these numbers are "as far as there is".
+
+// recoil kick: peak camPitch deflection = RECOIL_KICK × weapon.recoil (rad), snapped
+// up in ~60ms then eased back over the rest of RECOIL_TIME — code, not clip.
+const RECOIL_KICK = 0.055;
+const BASE_FADE = 0.18;   // Animator.play's default fade — overlay fade-outs MUST match it
+const RECOIL_TIME = 0.3;
+const FIRE_BUF = 0.35;    // LMB buffer (same idea as _atkBuf) — FROZEN while a draw is in flight
+const DRAW_GATE = 0.5;    // seconds of gunDraw before the gun can fire (leather-to-level)
+const _aimFrom = new THREE.Vector3(), _aimDir = new THREE.Vector3(), _aimTo = new THREE.Vector3();
+const _aimFrom2 = new THREE.Vector3();
+const MENACE_R = 25;   // a child this close sees the gun you are pointing at him. Beyond it he doesn't.
+const _fireFrom = new THREE.Vector3(), _fireAim = new THREE.Vector3(), _fireDir = new THREE.Vector3();
+const _fireRight = new THREE.Vector3(), _fireUp = new THREE.Vector3();
+// The body, as the AIM sees it — the same capsule the bullets use (combat.js BODY_LO/HI/R), a hair
+// wider so the crosshair is forgiving where the round is not. If these two ever disagree, the
+// reticle lights green on a shot that misses, which is worse than no reticle at all.
+const AIM_LO = 0.25, AIM_HI = 1.80, AIM_R = 0.50;
+const AUTO_RELOAD_WAIT = 0.35;   // the beat between the empty click and his hand going to his belt
+const HOLSTER_IDLE = 6;   // unaimed/unfired seconds before the gun goes back to leather
+const ADS_CAM_DIST = 1.2; // aim (RMB / L1) pulls the camera in from camDist (4.0) — a tight over-the-shoulder for a lined-up shot (Nick: zoom closer)
+// FALL DAMAGE (GTA V / RDR2 model): measured on NET DESCENT from the ground you took off from — a flat
+// jump nets ~0 and never hurts; only a real drop off a ledge/ladder past FALL_SAFE_M does, scaled linearly.
+const FALL_SAFE_M = 2;        // a drop up to 2 m is free
+const FALL_DMG_PER_M = 12;    // HP per metre past the safe drop → a ~10 m fall is about lethal (100 HP)
+// Over-the-shoulder framing. SHOULDER_IDLE is how much of it you get just WALKING AROUND (this
+// is an over-the-shoulder game, not a centred one that lurches sideways whenever you shoot);
+// aiming takes it to the full SHOULDER_OFF. The gap between them is deliberately small.
+const SHOULDER_OFF = 0.58;   // metres to the camera's right, at full ADS
+const SHOULDER_IDLE = 0.8;   // fraction of it you ride with by default (≈0.46m)
+// SPREAD — radians, half-angle. It is ZERO, and that is a decision, not an oversight.
+//
+// It used to be 0.045 at the hip, doubled again on the move: 5.7 degrees, which is plus or minus
+// two and a half METRES at 25m. You put the sights on a man, pulled the trigger, and the round went
+// somewhere else — and because a miss looks exactly like a bug, every miss felt like one. The gun
+// was not inaccurate, it was random, and random is not difficulty: it is the game overruling you
+// after you have already done the hard part.
+//
+// Verified on /shoottest.html with the dice removed: crosshair on the head → 100% hits and 100%
+// HEADSHOTS at every range from 10m to 500m, standing or walking. So the round now goes exactly
+// where you point it, and the difficulty lives where it belongs — in whether YOU can put the
+// crosshair on a moving man while he shoots back at you.
+const SPREAD = { ads: 0, hip: 0, moveMul: 1 };
+// Aim IK. AIM_IK_SPINE = the share of the correction Spine_02 takes (the rest goes to the
+// shoulder) — a lean, so the arm isn't dislocated from the torso.
+// AIM_IK_MAX caps ONE frame's correction so a wild transient can't wrench the arm. It is
+// MEASURED, not guessed: the aim clip's shoulder→hand line sits 69°–94° off the camera ray
+// (that IS the "points slightly to the right / at the floor" bug), so a cap below ~1.65 rad
+// SATURATES and leaves a permanent residual — 1.2 rad left 7–9° of error at negative pitch.
+// 1.9 rad clears the real ask with margin and still refuses to swing the arm halfway round
+// the body in a single frame.
+const AIM_IK_SPINE = 0;   // spine share = 0: rotating the SPINE toward the aim bent the player forward. The arm alone reaches the ray.
+const AIM_IK_MAX = 1.9;
+const MOUNTED_ARC = 1.4;    // rad — aim zone is ±80° off the horse's facing (Nick). Can't twist further in the saddle.
+const MOUNTED_PITCH = 0.5;  // rad — and ±~28° up/down: the aim is a cone off forward, not a free look.
+const MOUNTED_HOLSTER = 0.4; // s after the aim is released before the gun goes back and the hand returns to the rein
+
+// FIST CURL lives in fistCurl.js (shared with the brawler enemies) — the tuned numbers, the joint
+// collector, and applyFist(). player.js only adds the weapon-mode gating around it (applyFistCurl below).
+
+export class Player extends Character {
+  constructor(game, clips) {
+    super(game, {
+      ...PC.model,   // the game's registered player body/dress/stats (see setPlayerContent)
+      clips: PC.clipSubset(clips, PC.playerClips),
+    });
+    this.stamina = 100;
+    // CHARACTER LEVEL — a stub, pinned at 1, until the XP/level system is built. It exists now so
+    // that anything which should GROW with the character (the satchel's carry cap today; health,
+    // Dead Eye, aim tomorrow) reads one field and follows it the day levelling lands, instead of
+    // being wired to a constant that then has to be hunted down. Raise this and the bag gets bigger.
+    this.level = 1;
+    this.capsuleSteps = 5;     // smoother capsule stepping for the player (stairs)
+
+    // ---- gun state (HUD contract: weapon/aiming/ammo/ammoMax/reloading/deadEye/drawn)
+    this.weapon = 'revolver';  // 'revolver' | 'rifle' | 'fists'
+    this.aiming = false;       // RMB held — ADS. NOT required to fire.
+    this.drawn = false;        // gun in hand vs in leather (HUD contract)
+    this.reloading = false;
+    this.deadEye = 1;          // 0..1 meter — OWNED by game/deadeye.js (Ctrl). HUD contract.
+    this.deadEyeActive = false; // slow-mo + tagging running — set by deadeye.js. HUD contract.
+    this._mags = { revolver: WEAPONS.revolver.mag, rifle: WEAPONS.rifle.mag }; // per-weapon mag persists across Q cycling
+    this.ammo = this._mags.revolver;
+    this.ammoMax = WEAPONS.revolver.mag;
+    this._drawT = 0;           // gunDraw one-shot input gate
+    this._holsterT = 0;        // unaimed seconds until the gun goes back to leather
+    this._holstering = false;  // holster clip in flight — the gun is still in hand
+    this._gunFireT = 0;        // per-weapon rate limit
+    this._gunRecoilT = 0;      // brief post-shot window that keeps the aim pose + shoulder cam up
+    this._muzzleFlip = 0;      // procedural barrel rise on the shot (radians), eased out
+    this._recoilT = 0; this._recoilAmp = 0; this._recoilOff = 0; // camera kick envelope
+    this._fireBuf = 0;         // buffered LMB — survives the draw so one click is always one shot
+    this._ikW = 0;             // aim-IK blend weight (0 holstered · 0.6 gun in hand · 1 ADS)
+
+    // melee (fists) — combat.playerMelee drives these
+    this.lockTarget = null;
+    this.comboStep = 0;
+    this.comboWindow = 0;
+    this.attackCooldown = 0;
+    this.dodgeT = 0;
+    this.aboard = null;          // the coach he is riding, if any (coach.js board/alight)
+    this.airborne = false;
+    this.vy = 0;
+
+    // ON TOP OF SOMETHING THAT MOVES — the coach roof (game/platform.js). Not the same thing as
+    // `aboard`: aboard is a seat and it takes his legs away, this is a man STANDING on a moving
+    // floor, with his capsule, his locomotion, his gun and his jump all still his own. Only the
+    // player is rideable; nobody else queries the registry, so the NPCs and the horses pay nothing.
+    this.rideable = true;
+    this.platform = null;        // the Ride record while he is up there
+    this._airVX = 0;             // inherited horizontal momentum: the ONLY persistent one he has.
+    this._airVZ = 0;             // hx/hz are recomputed from the keys every frame, so without it a
+                                 // man who jumps off a galloping coach stops dead in mid-air.
+    this._mantleT = 0;           // ledge-catch lock-out
+    this._skipCols = null;       // his platform's own collider entries, ignored while he rides it
+    this._skipT = 0;
+
+    // camera rig — start looking north up the main street (player spawns south of centre)
+    this.camYaw = 0;
+    this.camPitch = 0.35;
+    this.camDist = 3.0;   // fixed close-follow (Nick's call)
+    this.heading = Math.PI; // back to the camera
+
+    // camera tuning (persisted) + gamepad look rate
+    this.camSensitivity = clamp(parseFloat(localStorage.getItem('av_camSens')) || 1, 0.25, 3);
+    this.invertY = localStorage.getItem('av_invertY') === '1';
+    this.padCamSpeed = 2.6; // right-stick turn rate (rad/s) at full deflection
+
+    // input buffers (seconds) so presses a few frames early still land
+    this._atkBuf = 0;
+    this._heavyBuf = 0;
+    this._jumpBuf = 0;
+    this._combatT = 0;
+
+    this.riding = new Riding(this); // mount/ride/dismount (set up after load)
+    this.climbing = new Climbing(this); // ladder climb controller (game/climbing.js)
+    this.footsteps = new Footsteps(this.game); // surface-aware foot SFX
+  }
+
+  async load() {
+    await super.load();
+    // body-split clips: leg clips drive only the lower body while the gun pose rides the
+    // torso/arms as a masked overlay — strafe-aiming. Hips goes with the LEGS so the whole
+    // lower body is one consistent walk (pelvis faces travel); the aim clips pose the spine
+    // for THEIR bladed pelvis, so applyUpperReblade() re-aims the torso on top.
+    const LOWER = /^(Hips|UpperLeg|LowerLeg|Thigh|calf|shin|Foot|Ball|Toes|Pelvis|ik_foot)/i;
+    this.animator.registerMasked('walkLower', 'walk', (b) => LOWER.test(b));
+    this.animator.registerMasked('idleLower', 'idle', (b) => LOWER.test(b));
+    // directional strafe/backpedal LEGS for aim-locked movement: while aiming the travel
+    // direction is body-relative, so play the clip that matches (back/left/right).
+    this.animator.registerMasked('walkBackLower', 'walkBack', (b) => LOWER.test(b));
+    this.animator.registerMasked('strafeLLower', 'strafeL', (b) => LOWER.test(b));
+    this.animator.registerMasked('strafeRLower', 'strafeR', (b) => LOWER.test(b));
+    // upper-body gun poses (masked complements of the leg splits):
+    //   gunAimUpper/rifleAimUpper — ADS hold, pinned at the clip's aim frame each frame
+    //   gunFireUpper             — the shot one-shot (a single fan-beat of gunFire)
+    //   gunDrawUpper/gunReloadUpper — draw/reload one-shots over walking legs
+    this.animator.registerMasked('gunAimUpper', 'gunAim', (b) => !LOWER.test(b));
+    this.animator.registerMasked('gunFireUpper', 'gunFire', (b) => !LOWER.test(b));
+    this.animator.registerMasked('rifleAimUpper', 'rifleAim', (b) => !LOWER.test(b));
+    this.animator.registerMasked('gunDrawUpper', 'gunDraw', (b) => !LOWER.test(b));
+    this.animator.registerMasked('gunReloadUpper', 'gunReload', (b) => !LOWER.test(b));
+    this.animator.registerMasked('gunHolsterUpper', 'gunHolster', (b) => !LOWER.test(b));
+    // reference pelvis pose of the aim clip (frame 0), for applyUpperReblade(): its spine
+    // tracks are authored against THIS pelvis, not the walk pelvis.
+    const hipsRef = (name) => {
+      const t = this.animator.actions[name]?.getClip().tracks.find((tr) => tr.name === 'Hips.quaternion');
+      return t ? new THREE.Quaternion().fromArray(t.values, 0) : null;
+    };
+    this._gunHipsRef = hipsRef('gunAim');
+    this._rifleHipsRef = hipsRef('rifleAim');   // rifle spine tracks are authored against ITS pelvis
+    this._rebladeW = 0;
+    // find attachment bones. Holster contract: revolver on Hips (right hip), rifle on Spine_03.
+    this.handBone = null;
+    this.handBoneL = null;
+    this.spineBone = null;
+    this.hipsBone = null;
+    this.model.traverse((o) => {
+      if (!o.isBone) return;
+      if (o.name === 'Hand_R') this.handBone = o;
+      if (o.name === 'Hand_L') this.handBoneL = o;
+      if (/^spine_03$/i.test(o.name)) this.spineBone = o;
+      if (/^hips$/i.test(o.name)) this.hipsBone = o;
+    });
+    // FIST joints for the bare-knuckle curl (applyFistCurl), captured HERE at the imported rest pose —
+    // before the mixer ever poses the fingers, so the curl is ADDED to an open hand as tuned in the bench.
+    this._fistBones = collectFistJoints(this.model);
+    await this.equipWeaponModel();
+    return this;
+  }
+
+  async equipWeaponModel() {
+    if (!this.handBone) return;
+    // Coalesce concurrent calls (same guard as the old sword path): only one build runs;
+    // a call arriving mid-build re-runs once after.
+    if (this._equipWeaponBusy) { this._equipWeaponQueued = true; return; }
+    this._equipWeaponBusy = true;
+    try {
+      for (const w of ['revolver']) {   // rifle parked for now
+        const key = `${w}Obj`;
+        if (this[key]) continue;
+        const url = PC.weaponMesh[w];
+        this[key] = await instantiate(url, { texture: PC.weaponTex });
+        // hand bones live in the FBX's centimetre space: a raw cm FBX sits right at scale 1,
+        // but a GLB twin is METRES → ×100 back to cm or the gun renders 1cm long
+        this[key].scale.setScalar(/\.glb$/i.test(await resolveModelUrl(url, { texture: PC.weaponTex })) ? 100 : 1);
+      }
+      this.placeWeapons();
+    } catch (e) { console.warn('weapon model failed', e); }
+    this._equipWeaponBusy = false;
+    if (this._equipWeaponQueued) { this._equipWeaponQueued = false; return this.equipWeaponModel(); }
+  }
+
+  // Drawn gun → hand; everything else → holsters (revolver right hip, rifle across the back).
+  placeWeapons() {
+    const put = (obj, bone, slot) => {
+      if (!obj || !bone) return;
+      this.gripNodeFor(bone).add(obj); // grip node normalises bone world-scale for cm props
+      const a = PC.attachments[slot]; if (!a) return;
+      obj.position.set(a.pos[0], a.pos[1], a.pos[2]);
+      obj.rotation.set(a.rot[0], a.rot[1], a.rot[2]);
+    };
+    const hip = this.hipsBone ?? this.spineBone ?? this.handBone;
+    const back = this.spineBone ?? this.handBone;
+    const held = this.drawn ? this.weapon : null;
+    put(this.revolverObj, held === 'revolver' ? this.handBone : hip, held === 'revolver' ? 'revolver' : 'revolverHip');
+    put(this.rifleObj, held === 'rifle' ? this.handBone : back, held === 'rifle' ? 'rifle' : 'rifleBack');
+    this.weaponObj = held === 'revolver' ? this.revolverObj : held === 'rifle' ? this.rifleObj : null;
+  }
+
+  // Kept for the fists flow + combat compat: "in combat" for a few seconds after a swing/hit.
+  enterCombatStance() { this._combatT = 4; }
+
+  // GREET (G) — the hat-tip. If a townsperson is close enough to see it, it counts: five distinct
+  // courtesies earn a point of the town's regard (missions stat 'reputation' — the same scale the
+  // shop counters and THE STANDING read). Each soul counts once; the town remembers who's civil,
+  // not who's repetitive.
+  greet() {
+    if (!this.alive || this.busy || this.riding?.mounted) return;
+    this.busy = true;
+    this.animator.play('hatTip', { once: true, fade: 0.12, onDone: () => { this.busy = false; } });
+    const n = this.game._talkCand, m = this.game.missions;
+    if (!n || n._greeted || Math.hypot(n.position.x - this.position.x, n.position.z - this.position.z) > 5) return;
+    n._greeted = true;
+    m?.addStat?.('greets', 1);
+    const g = m?.stat?.('greets') ?? 0;
+    if (g % 5 === 0) {
+      m?.addStat?.('reputation', 1);
+      this.game.ui?.toast?.(`Word gets around that the deputy has manners. The town's regard rises.`, 5000);
+    } else {
+      this.game.ui?.toast?.(`${n.name} returns the nod.`, 2600);
+    }
+  }
+
+  // WHISTLE for the horse (H). No two-finger-whistle clip ships, so this is the "over here" wave
+  // (idleWave, one-shot — you pause a beat to call) plus the whistle recording. The companion horse
+  // reads ownHorse._summoned and breaks into a gallop to reach you (horse.js _followOwner).
+  whistle() {
+    if (!this.alive || this.busy || this.riding?.mounted) return;
+    this.busy = true;
+    this.animator.play('idleWave', { once: true, fade: 0.12, onDone: () => { this.busy = false; } });
+    this.riding?._loadSfx?.();                                     // whistle sample loads lazily on first mount — pull it in
+    this.game.audio?.sample?.('whistle', { gain: 0.6 });
+    const h = this.game.ownHorse;
+    if (h && !h.rider && h.alive !== false) {
+      h._summoned = 3;                                             // seconds of urgent gallop toward you
+      // LEAN-TO STABLE (upg_stable): the whistle reaches county-wide — a horse too far to hear you
+      // is brought around to the edge of earshot (Jesse's whole job) and gallops the rest itself.
+      const d = Math.hypot(h.position.x - this.position.x, h.position.z - this.position.z);
+      if (d > 150 && this.game.missions?.flag?.('upg_stable')) {
+        const a = Math.atan2(h.position.x - this.position.x, h.position.z - this.position.z);
+        const nx = this.position.x + Math.sin(a) * 80, nz = this.position.z + Math.cos(a) * 80;
+        h.root.position.set(nx, this.game.world.groundAt(nx, nz), nz);
+        this.game.ui?.toast?.(`Jesse had him saddled before the whistle died.`, 4000);
+      }
+    }
+  }
+
+  // Live grip tuning for the held gun — find the look in-game, then bake the
+  // numbers into data/attachments.js.
+  setGunRot(x, y, z) { this.weaponObj?.rotation.set(x, y, z); console.log('[gun] rot', x, y, z); }
+  setGunPos(x, y, z) { this.weaponObj?.position.set(x, y, z); console.log('[gun] pos', x, y, z); }
+
+  // Torso re-blade for strafe-aim. Hips lives in the LOWER mask, so while moving the
+  // pelvis faces travel — but the aim upper-body clip poses the spine for ITS (bladed)
+  // pelvis. Post-mixer, premultiply Spine_01 by (liveHips⁻¹ · clipHips): the torso lands
+  // where the full-body clip would put it. Planted the delta collapses to identity, so
+  // moving↔planted fades stay smooth. Runs after super.update (mixer).
+  applyUpperReblade(dt) {
+    // resolve the MIXER-BOUND Hips/Spine_01 lazily — only nodes in the mixer's property
+    // bindings actually animate (harmless with one skeleton, vital with duplicates)
+    if (!this._rebladeBones) {
+      let hips = null, spine = null;
+      for (const pm of this.animator.mixer._bindings ?? []) {
+        const n = pm.binding?.node;
+        if (!n) continue;
+        if (!hips && n.name === 'Hips') hips = n;
+        if (!spine && n.name === 'Spine_01') spine = n;
+        if (hips && spine) break;
+      }
+      if (!hips || !spine) return; // bindings appear once actions have played
+      this._rebladeBones = { hips, spine };
+    }
+    const { hips, spine } = this._rebladeBones;
+    // the aim CLIP is on the upper body whenever ADS is held OR the post-shot hold is up
+    const onAimClip = this.aiming || this._gunRecoilT > 0;
+    const ref = onAimClip ? (this.weapon === 'rifle' ? (this._rifleHipsRef ?? this._gunHipsRef) : this._gunHipsRef) : null;
+    if (ref) this._rebladeRef = ref; // remembered so the fade-out has a pose to ease from
+    this._rebladeW = lerp(this._rebladeW, ref ? 1 : 0, Math.min(1, dt * 10));
+    if (this._rebladeW < 0.001 || !this._rebladeRef) return;
+    _rbQ1.copy(hips.quaternion).invert().multiply(this._rebladeRef);
+    _rbQ2.identity().slerp(_rbQ1, this._rebladeW);
+    spine.quaternion.premultiply(_rbQ2);
+    // NOTE: the old _aimTwist term lived here — a world-yaw twist injected into the spine to
+    // drag the torso onto the aim line. It is GONE. Its wrap is what "spun the top half of the
+    // player around", and it could never point the muzzle anywhere precise anyway. applyAimIK
+    // now owns the aim direction; this function is back to its one honest job (re-seating the
+    // aim clip's spine on top of the walk pelvis).
+  }
+
+  // The CAMERA RAY, i.e. forward away from the lens. VERIFIED against the camera placement
+  // at the bottom of update(): the camera sits at head + (sinY·cosP, sinP, cosY·cosP)·dist and
+  // looks AT head, so forward = −(sinY·cosP, sinP, cosY·cosP). Positive camPitch = camera above
+  // = looking DOWN, hence the −sin(pitch) on Y. _fire() shoots along this same vector.
+  aimDir(out = _ikDir) {
+    let yaw = this.camYaw, pitch = this.camPitch;
+    // Mounted: the aim is a CONE off the horse's facing — ±40° across and ±~28° up/down (Nick). You
+    // can't twist round in the saddle, so the gun (and the shot, which reads this same vector) stops
+    // at the edge of the cone instead of pointing back through the rider or straight up/down.
+    if (this.riding.mounted && this.riding.horse) {
+      const fwd = this.riding.horse.heading + Math.PI;        // camYaw that points along the horse
+      const d = Math.atan2(Math.sin(yaw - fwd), Math.cos(yaw - fwd));
+      yaw = fwd + clamp(d, -MOUNTED_ARC, MOUNTED_ARC);
+      pitch = clamp(pitch, -MOUNTED_PITCH, MOUNTED_PITCH);
+    }
+    const cp = Math.cos(pitch);
+    return out.set(-Math.sin(yaw) * cp, -Math.sin(pitch), -Math.cos(yaw) * cp);
+  }
+
+  // ---- PROCEDURAL AIM IK ------------------------------------------------------------------
+  // Rotate the right-arm chain so the SHOULDER→HAND line (and with it the gun, which is
+  // gripped on Hand_R) lands on the camera ray — yaw AND pitch. This is the fix for both
+  // "points slightly to the right" (the clip's bladed stance) and "aims at the floor"
+  // (the clip has no pitch at all). Runs AFTER the mixer and AFTER applyUpperReblade, and
+  // is overwritten by the mixer next frame — so it never accumulates.
+  //
+  // Every correction is applied the same way as the reblade: a WORLD-space corrective C is
+  // conjugated into the bone's parent space (parentWorld⁻¹ · C · parentWorld) and premultiplied
+  // onto the local quaternion, which rotates the bone's world orientation about its own origin.
+  // The hand therefore swings around the shoulder and the arm line rotates by exactly C.
+  applyAimIK(dt) {
+    // bones MUST come from the mixer's driven bindings — this model has duplicate bone names
+    // across skeletons and a scene traverse grabs an undriven orphan (see footsteps.js)
+    if (!this._ikBones) {
+      let sh = null, sp = null, hd = null;
+      for (const pm of this.animator.mixer._bindings ?? []) {
+        const n = pm.binding?.node;
+        if (!n) continue;
+        if (!sh && n.name === 'Shoulder_R') sh = n;
+        if (!sp && n.name === 'Spine_02') sp = n;
+        if (!hd && n.name === 'Hand_R') hd = n;
+        if (sh && sp && hd) break;
+      }
+      if (!sh || !hd) return;   // bindings only appear once actions have played
+      this._ikBones = { sh, sp, hd };
+    }
+    const { sh, sp, hd } = this._ikBones;
+    // weight: ADS = 1 (the muzzle IS the reticle), gun merely in hand = 0.6 (hip-fire still
+    // tracks, just loosely), holstered/reloading/holstering/stunned/mounted = 0. Never snapped.
+    // DEAD EYE also pins it to 1: you're painting shots down the reticle, so the muzzle had
+    // better BE the reticle — and `dt` here is wall-clock (see update), so the arm keeps
+    // tracking at full speed while the world crawls.
+    // ONLY while genuinely aiming (ADS or Dead Eye). At hip-ready the gun-carry clips hang the
+    // arm at the side BY DESIGN — that is the pose. Running the IK there dragged the hand up to
+    // the camera ray and pushed a share of that correction into the spine, folding the player
+    // in half. The bench never showed it because the bench plays the clips raw, with no IK.
+    const want = (!WEAPONS[this.weapon] || !this.drawn || !this.alive || this.busy
+      || this.reloading || this._holstering || this.riding.mounted) ? 0
+      : (this.aiming || this.deadEyeActive) ? 1 : 0;
+    this._ikW = lerp(this._ikW, want, Math.min(1, dt * 10));
+    if (this._ikW < 0.001) return;
+
+    this.model.updateWorldMatrix(true, true); // bones moved this frame (mixer + reblade)
+    const dir = this.aimDir(_ikDir);
+    // pass 1: a little of the correction at the spine, for a lean instead of a dislocated arm
+    if (sp && this._solveArm(sh, hd, dir, AIM_IK_SPINE * this._ikW, sp)) {
+      sp.updateWorldMatrix(true, true); // refresh the arm's world transforms under the new spine
+    }
+    // pass 2: the shoulder takes the REMAINING error exactly — re-solved, so the two passes
+    // compose to land on the ray rather than over/under-shooting it
+    this._solveArm(sh, hd, dir, this._ikW, sh);
+  }
+
+  // One IK pass: measure the shoulder→hand line, build the world corrective that takes it to
+  // `dir`, clamp it, and apply `frac` of it at `bone`.
+  _solveArm(sh, hd, dir, frac, bone) {
+    if (frac < 0.001) return false;
+    sh.getWorldPosition(_ikA);
+    hd.getWorldPosition(_ikB);
+    _ikB.sub(_ikA);
+    const len = _ikB.length();
+    if (len < 1e-5) return false;          // degenerate (bind pose not built yet)
+    _ikB.divideScalar(len);
+    // ANTI-PARALLEL GUARD: at dot ≈ −1 setFromUnitVectors has no defined axis — it picks an
+    // arbitrary perpendicular and swings 180°, which flips the arm inside out. Sit this frame
+    // out instead; the body heading is already easing round, so it resolves in a few frames.
+    if (_ikB.dot(dir) < -0.999) return false;
+    _ikQ1.setFromUnitVectors(_ikB, dir);   // world-space corrective: arm line → camera ray
+    // CLAMP one frame's correction (see AIM_IK_MAX — the cap is above the real ask, so the
+    // steady-state solve lands exactly on the ray instead of saturating short of it).
+    const ang = 2 * Math.acos(Math.min(1, Math.abs(_ikQ1.w)));
+    if (ang > AIM_IK_MAX) _ikQ1.slerp(_ikQ2.identity(), 1 - AIM_IK_MAX / ang);
+    _ikQ3.identity().slerp(_ikQ1, Math.min(1, frac));
+    bone.parent.getWorldQuaternion(_ikQ2);
+    // local' = (parentWorld⁻¹ · C · parentWorld) · local  ⇒  world' = C · world
+    _ikQ1.copy(_ikQ2).invert().multiply(_ikQ3).multiply(_ikQ2);
+    bone.quaternion.premultiply(_ikQ1);
+    return true;
+  }
+
+  // ---- FIST CURL --------------------------------------------------------------------------
+  // Close both hands into fists for the bare-knuckle clips. The pose itself (knuckle flex + thumb fold)
+  // and the joint set live in fistCurl.js (applyFist / collectFistJoints, shared with the brawlers).
+  // This method is just the WEAPON-MODE gating around it. Runs AFTER the mixer, so it wins over the clip.
+  //
+  // OWNERSHIP is the subtle part. This doubled-skeleton rig binds each finger clip-track to just ONE
+  // instance per name (~11), but _fistBones spans BOTH hands' joints (22) — so the mixer never re-poses
+  // the extra joints we curl. If we merely stopped curling, they'd stay stuck in a fist. So:
+  //   • fists weapon mode  → WE own the fingers: full fist on a punch* clip, open (bind) on the shared
+  //                          locomotion clips (unarmed run/jump), every frame — nothing drifts.
+  //   • any other mode     → the gun/rifle clips own the fingers (the grip). We keep hands off, but the
+  //                          first frame after leaving fists we reset every joint to bind ONCE, so the
+  //                          residual curl on the un-driven joints is cleared and both hands hand back open.
+  applyFistCurl() {
+    const bones = this._fistBones;
+    if (!bones || !bones.length) return;
+    if (this.weapon !== 'fists') {
+      if (this._fistActive) { applyFist(bones, false); this._fistActive = false; }   // hand the fingers back open, once
+      return;
+    }
+    this._fistActive = true;
+    applyFist(bones, (this.animator?.currentName || '').startsWith('punch'));         // fist on the punch clips, open otherwise
+  }
+
+  // ---- MOUNTED AIM ------------------------------------------------------------------------
+  // On foot the gunAim CLIP puts the hand in a firing grip (gun aligned with the arm) and then
+  // applyAimIK points that arm line at the reticle. Mounted there is no aim clip — the seated pose
+  // leaves the hand on the reins — so pointing the arm line alone rolls the gun up. Fix: copy the
+  // gunAim clip's OWN right-arm pose onto the arm first (so the gun is gripped for firing), THEN
+  // point the shoulder at the reticle. The left hand keeps the reins.
+  _captureGunArmPose() {
+    const clip = this.animator.actions['gunAim']?.getClip();
+    if (!clip) return;
+    const q = (name) => {
+      const t = clip.tracks.find((t) => t.name === name + '.quaternion');
+      if (!t) return null;
+      const o = t.values.length - 4;   // last keyframe = the settled aim-hold pose
+      return new THREE.Quaternion(t.values[o], t.values[o + 1], t.values[o + 2], t.values[o + 3]);
+    };
+    const sh = q('Shoulder_R'), el = q('Elbow_R'), hd = q('Hand_R');
+    if (sh && el && hd) this._gunArmPose = { sh, el, hd };
+  }
+
+  applyMountedAim(dt) {
+    if (!this._gunArmPose) this._captureGunArmPose();
+    const gp = this._gunArmPose, pb = this.riding.pbone;
+    const sh = pb?.Shoulder_R, el = pb?.Elbow_R, hd = pb?.Hand_R;
+    if (!gp || !sh || !el || !hd) return;
+    // firing grip on the right arm, overriding the rein pose the seat just applied
+    sh.quaternion.copy(gp.sh); el.quaternion.copy(gp.el); hd.quaternion.copy(gp.hd);
+    sh.updateWorldMatrix(true, true);
+    // point the shoulder→hand line (and the gun on it) at the clamped aim ray
+    this._solveArm(sh, hd, this.aimDir(_ikDir), 1, sh);
+  }
+
+  // Ease the body heading to `target` along the SHORTEST arc. camYaw is unbounded (it just
+  // accumulates mouse deltas — it reads 16.2 rad after a few spins), so `heading = camYaw + PI`
+  // handed the root an unbounded angle and any lerp against it could take the long way round:
+  // that is the 2π wrap the user saw as the torso "spinning around". angleLerp wraps the DELTA
+  // into [−π, π] first, so no step can ever be a wrap.
+  _faceAngle(target, dt, rate = 9) {
+    this.heading = angleLerp(this.heading, target, Math.min(1, dt * rate));
+    this.root.rotation.y = this.heading;
+  }
+
+  // The held gun's grip follows the CURRENT pose: a per-clip override
+  // (ATTACHMENTS.<weapon>.clips, tuned in /attach.html) when one exists, else the
+  // base grip. Gun poses ride masked overlays, so derive the logical clip name
+  // instead of animator.currentName (which is a leg clip while aiming on the move).
+  updateWeaponPose() {
+    if (!this.weaponObj) return;
+    const slot = PC.attachments[this.weapon];
+    if (!slot) return;
+    const key = this.reloading ? 'gunReload'
+      : (this.aiming || this._gunRecoilT > 0) ? 'gunAim'
+        : this.animator?.currentName;
+    const ov = slot.clips?.[key];
+    const r = ov?.rot ?? slot.rot;
+    const p = ov?.pos ?? slot.pos;
+    this.weaponObj.rotation.set(r[0], r[1], r[2]);
+    this.weaponObj.position.set(p[0], p[1], p[2]);
+  }
+
+  // Live jump tuning: frac (0..1) skips into the clip past the ground wind-up.
+  setJumpStart(frac, scale) { this._jumpStart = frac; if (scale != null) this._jumpScale = scale; console.log('[jump] startFrac', frac, 'timeScale', this._jumpScale ?? 1.4); }
+
+  // Freeze on one clip pose so the gun grip can be tuned against the exact frame
+  // that looks wrong:
+  //   game.player.holdAnim('gunAim', 0.0)  // orbit camera to inspect
+  //   game.player.setGunRot(...) / setGunPos(...)  // dial it in
+  //   game.player.unfreeze()
+  holdAnim(name, t = 0.5) {
+    const a = this.animator.play(name, { once: true, fade: 0 });
+    if (!a) { console.warn('[hold] no clip', name); return; }
+    this.busy = true;
+    a.paused = true;
+    a.time = a.getClip().duration * clamp(t, 0, 1);
+    this.animator.mixer.update(0);
+    this._heldAction = a;
+    console.log(`[hold] ${name} @ ${t} — tune the grip, then game.player.unfreeze()`);
+  }
+  unfreeze() { if (this._heldAction) { this._heldAction.paused = false; this._heldAction = null; } this.busy = false; }
+
+  get moveSpeed() { return this.speed; }
+  // bare-knuckle damage (fists mode + combat.playerMelee compat)
+  get fistDamage() { return 12; }
+  get meleeDamage() { return this.fistDamage; }
+
+  update(dt, input, camera) {
+    // A MODAL PANEL (pause menu, world map, satchel, shop) freezes the player SOLID — no mixer, no
+    // gravity, no movement — so he doesn't fall through his spawn or run in place while a screen is
+    // up. main.js already freezes the WORLD when a panel is open; the player was the one thing that
+    // kept ticking (mixer at super.update + gravity in moveCapsule below), which read as "still
+    // moving on pause". Dialogue is excluded — its two-shot needs him breathing and turning to the
+    // lens, and main.js ticks that path by hand.
+    const _ui = this.game.ui;
+    if (_ui && (_ui.menuOpen || _ui.mapOpen || _ui.satchelOpen || _ui.shopOpen || _ui.deathOpen)) return;
+    super.update(dt); // advances the mixer (mount climb clip, or nothing while seated)
+    if (!this.alive) return;
+    // DEAD EYE TIME SPLIT. `dt` is WORLD time — main.js has already multiplied it by the
+    // Dead Eye / hit-stop chain, so the mixer, the movement and the physics above and below
+    // all crawl in slow motion, which is the point. `rdt` is WALL-CLOCK time, and the two
+    // things that must NOT crawl read it instead: the camera (look + follow) and the aim IK.
+    // Aiming stays crisp inside a slow world — that IS Dead Eye. (Mouse look is already
+    // dt-free: it integrates per-event pixel deltas.)
+    const rdt = this.game.rawDt ?? dt;
+    // timers — up here (not the on-foot block) so they also tick while riding
+    this._combatT = Math.max(0, this._combatT - dt);
+    this._stamPause = Math.max(0, (this._stamPause ?? 0) - dt);
+    this._gunFireT = Math.max(0, this._gunFireT - dt);
+    this._drawT = Math.max(0, this._drawT - dt);
+    this._gunRecoilT = Math.max(0, this._gunRecoilT - dt);
+    this._mantleT = Math.max(0, this._mantleT - dt);
+    // the collider-skip grace outlives the platform by a few frames: he is still at roof height on
+    // the way off it, and a train car's box is banded all the way to its own roof
+    if (this._skipT > 0 && !this.platform) {
+      this._skipT -= dt;
+      if (this._skipT <= 0) this._skipCols = null;
+    }
+    if (this._stamPause <= 0) this.stamina = Math.min(100, this.stamina + dt * 22);
+    // slow out-of-combat mend
+    if (this._combatT <= 0 && this.health < this.maxHealth) this.health = Math.min(this.maxHealth, this.health + dt * 1.5);
+    // no outfit → no known feetDrop: ground the feet once the idle pose has settled
+    // (the model origin sits at the hips; measuring at load catches a half-faded pose)
+    if (!this._grounded && this.model) {
+      this._groundT = (this._groundT ?? 0) + dt;
+      if (this._groundT > 0.5) { this._grounded = true; this._groundFeet(); }
+    }
+    // a live aim/reload dies the moment anything steals the gun out from under it
+    // (menu/dialogue, mount, death handled in takeDamage) — otherwise the stale state
+    // fires a phantom pose/refill whenever gunInputs next runs
+    if (this.aiming || this.reloading || this._drawT > 0) {
+      const stolen = !WEAPONS[this.weapon] || this.riding.mode === 'mounting' || this.riding.mode === 'dismounting'
+        || this.game.ui?.menuOpen || this.game.ui?.dialogueOpen || this.game.ui?.cinematic;
+      if (stolen) this.cancelGun();
+    }
+    // an interrupt (dodge/hit sets busy, jump sets airborne) cancels the reload cleanly —
+    // the old ammo stands, no refill from the fading one-shot
+    // A RELOAD SURVIVES A HIT. `busy` goes up for the flinch as well as for a dodge, so the old
+    // guard (busy || airborne) threw away your reload the instant anyone clipped you — in the one
+    // situation where an empty gun actually kills you. Now only a DODGE or leaving the ground
+    // interrupts it: a man rolling out of the way is not thumbing rounds into a cylinder, but a
+    // man who just took a graze absolutely is. The flinch plays over the top.
+    if (this.reloading && (this.dodgeT > 0 || this.airborne)) this.cancelReload();
+    // ease the model's ground lift: bone-measured drop on foot, 0 while mounted (hips sit
+    // ON the saddle). Easing kills the pop — and the camera jump — on dismount.
+    const targetBase = this.riding.mounted ? 0 : (this._baseModelY ?? 0);
+    this._baseModelY2 = this._baseModelY2 == null ? targetBase : this._baseModelY2 + (targetBase - this._baseModelY2) * Math.min(1, dt * 6);
+    if (this.riding.mounted) {
+      // A MAN IN THE SADDLE IS NOT AIRBORNE — the horse is. The aboard-the-stage branch below has
+      // exactly this reset and this branch never did, so a jump that ended in a mount left
+      // `airborne` stale-true for the whole ride, and airborne gates BOTH starting a reload and
+      // keeping one alive (Nick: R1 on horseback did nothing).
+      this.airborne = false;
+      this.model.position.y = this._baseModelY2;
+      const inMenu = this.game.ui?.menuOpen || this.game.ui?.dialogueOpen || this.game.ui?.cinematic;
+      // Draw/aim/fire from the saddle (only while fully mounted — not mid climb). The right hand
+      // takes the gun; the left keeps the reins. Reins want the hand back, so holster promptly once
+      // the aim is released rather than after the on-foot 6 s idle (that block never runs mounted).
+      if (this.riding.mode === 'mounted' && WEAPONS[this.weapon] && !inMenu) {
+        this.gunInputs(input, dt);
+        if (this.drawn && !this.aiming && this._drawT <= 0 && this._gunFireT <= 0) {
+          this._mHolsterT = (this._mHolsterT ?? MOUNTED_HOLSTER) - dt;
+          if (this._mHolsterT <= 0) { this.holsterGun(); this._mHolsterT = null; }
+        } else this._mHolsterT = MOUNTED_HOLSTER;
+      } else if (this.drawn) {
+        this.holsterGun();
+      }
+      this.riding.update(dt, input, camera);                 // seated pose + rein IK (both hands)
+      if (this.drawn && this.riding.mode === 'mounted') {     // override the right arm onto the gun
+        this.applyMountedAim(dt);
+        this.updateWeaponPose();
+      }
+      return;
+    }
+
+    // ABOARD THE STAGE. He is not walking, he is being CARRIED — so his position is written from
+    // the seat rather than integrated from his own legs. It is still written, every frame, and not
+    // faked by reparenting him onto the coach: collision, the camera, the aim and the law's line of
+    // sight all read player.position, and a player hidden inside a moving group is a player none of
+    // them can find. (The coach drives itself off this same tick — W/S/A/D go to it, not to him.)
+    if (this.aboard) {
+      const c = this.aboard;
+      c.seatWorld(this.position, c.rider?.kind ?? 'inside');
+      // A QUARTER TURN CLOCKWISE on the box. He faces across the coach otherwise; this is the turn
+      // that puts him along it, looking down the road with the reins in front of him.
+      this.heading = c.root.rotation.y - Math.PI / 2;
+      this.root.rotation.y = this.heading;
+      this.vy = 0;
+      this.airborne = false;
+      this.busy = false;                       // he can still be shot at, and still draw
+      // THE VISUAL-HEIGHT SMOOTHER DOES NOT RUN ON THIS PATH, so its state must not be left to rot.
+      // It carries `_visualY` — a lagged copy of your feet height — and the model is drawn at
+      // (_visualY - position.y) above the root to ease out micro-bumps. Skip the update while your
+      // position is being teleported onto a coach seat and that difference is no longer a bump, it
+      // is a stale number: measured at 24 METRES, which fired the player straight up into the sky
+      // and left an empty box seat rolling down the street. Keep it pinned.
+      this._visualY = this.position.y;
+      this.model.position.y = this._baseModelY2 ?? 0;
+      // SIT HIM DOWN. The animator is not ticked on this path, so nothing fights the pose: we
+      // re-seat it and solve his limbs onto the reins every frame, exactly as the coach does for
+      // its own driver (seatedRider.js). Costs four two-bone solves — no clip, no mixer.
+      this.game.coaches?.playerRider?.solve();
+      // A HOST MAY OWN THE LENS OUTRIGHT — the train does (game/trainCamera.js), and when it does, NONE
+      // of the block below runs: no look, no follow camera, and the mouse is dead, because a passenger
+      // on a train is watching a film and not steering a turret. It is filmed at the END of the tick
+      // instead, from aboardPost() — main.js moves the player at :664 and the TRAINS at :683, so every
+      // car transform read on this line is one frame old, and at 16 m/s against a frame time that
+      // jitters that is a camera bolted to a carriage that shivers. (Measured, riding at line speed, in
+      // the carriage's own frame: he sits still to within 0.5 mm a frame while the lens slid 234 mm.)
+      //
+      // A STAGECOACH OWNS NO CAMERA and answers none of this, so it keeps its look, its recentre and
+      // its follow camera, here, on this frame, exactly as it always has.
+      if (!c.camera) {
+        // LOOK AROUND — you are on a coach, not in a cutscene.
+        const rdt2 = this.game.rawDt ?? dt;
+        const moved = this.game.ui?.menuOpen ? false : this._look(input, rdt2);
+        if (moved) this._lookHoldT = 1.4;                     // your hand is on the mouse: leave him alone
+        else this._lookHoldT = Math.max(0, (this._lookHoldT ?? 0) - dt);
+        // ...and when you take your hand off, the camera drifts back behind her, as it does in every
+        // driving game there has ever been. Only while DRIVING: a passenger looks where he likes.
+        if (c.driven && this._lookHoldT <= 0) {
+          const want = c.root.rotation.y + Math.PI;
+          let d = want - this.camYaw;
+          while (d > Math.PI) d -= Math.PI * 2;
+          while (d < -Math.PI) d += Math.PI * 2;
+          this.camYaw += d * Math.min(1, dt * 1.6);
+        }
+        this._camera(dt, input, camera);
+      }
+      return;
+    }
+
+    // ON A LADDER. Like the mounted/aboard paths, the controller owns position + camera; the on-foot
+    // locomotion/gravity/capsule/combat below is fully suppressed. super.update(dt) above already ticked
+    // the mixer so the climb clips animate. The model rests at its base offset (the visual-Y line below
+    // is skipped). .active is a getter — forceOff() resets it on death/fast-travel/load (main.js).
+    if (this.climbing?.active) {
+      this.model.position.y = this._baseModelY2 ?? 0;
+      this.climbing.update(dt, input, camera);
+      return;
+    }
+
+    const ui = this.game.ui;
+    const inMenu = ui?.menuOpen || ui?.dialogueOpen || ui?.cinematic;
+
+    this.attackCooldown = Math.max(0, this.attackCooldown - dt);
+    if (this.comboWindow > 0) {
+      this.comboWindow -= dt;
+      if (this.comboWindow <= 0) this.comboStep = 0;
+    }
+    if (this.dodgeT > 0) this.dodgeT -= dt;
+    if (this._hitGraceT > 0) this._hitGraceT -= dt;
+    // dodge burst (see dodge()) — inMenu freezes it with the rest of the world
+    if (this._dodgeBurst && !inMenu) {
+      const b = this._dodgeBurst;
+      const step = Math.min(dt, b.left);
+      // ...on a coach roof it is a displacement across the DECK. Character.move() goes through
+      // moveCapsule, which knows nothing about decks and would drop him onto the road.
+      if (this.platform) this.game.platforms.step(this, b.dx * this.moveSpeed * 1.6 * step, b.dz * this.moveSpeed * 1.6 * step);
+      else this.move(tmpV1.set(b.dx, 0, b.dz), this.moveSpeed * 1.6, step);
+      b.left -= step;
+      if (b.left <= 0) this._dodgeBurst = null;
+    }
+    // never record a respawn point on a moving roof
+    if (!this.airborne && !this.platform) { const sp = this._lastSafePos ??= {}; sp.x = this.position.x; sp.y = this.position.y; sp.z = this.position.z; }
+    // TAKEOFF HEIGHT for fall damage: the ground you last stood on. A flat jump lands fast but this stays
+    // level with the landing (net 0), so only a real DROP past it hurts — a walk/hop off a ledge or ladder.
+    if (!this.airborne && !this.platform) this._airStartY = this.position.y;
+    this._sinceGrounded = this.airborne ? (this._sinceGrounded ?? 0) + dt : 0; // for coyote-time jumps
+
+    // ---- camera orbit
+    if (!inMenu) this._look(input, rdt);
+
+    // ---- recoil kick + settle (code, not clip): an attack/decay envelope feeds camPitch
+    // by DELTA so player look input composes. Negative pitch = muzzle climb (aim rises).
+    if (this._recoilT > 0 || this._recoilOff !== 0) {
+      this._recoilT = Math.max(0, this._recoilT - dt);
+      const t = this._recoilT / RECOIL_TIME;                 // 1 → 0 over the envelope
+      const env = t > 0.8 ? (1 - t) * 5 : t / 0.8;           // ~60ms snap up, eased settle
+      const off = this._recoilAmp * env;
+      this.camPitch = clamp(this.camPitch - (off - this._recoilOff), -0.6, 1.1);
+      this._recoilOff = off;
+    }
+
+    // ---- movement intent (camera relative)
+    let mx = 0, mz = 0, moveMag = 0;
+    if (!inMenu) {
+      const st = input.moveStick;
+      if (st && (st.x || st.y)) {
+        // analog left stick: direction AND magnitude (a light push walks, a full push runs).
+        // stick +y is toward the player (down), so forward is −y.
+        mx = st.x; mz = -st.y; moveMag = Math.min(1, Math.hypot(mx, mz));
+      } else {
+        if (input.down('KeyW')) mz += 1;
+        if (input.down('KeyS')) mz -= 1;
+        if (input.down('KeyA')) mx -= 1;
+        if (input.down('KeyD')) mx += 1;
+        moveMag = (mx || mz) ? 1 : 0;   // keyboard is always full throw
+      }
+    }
+    const moving = moveMag > 0.02 && !this.busy;
+    const sprinting = moving && input.down('ShiftLeft') && !this.aiming && this.stamina > 1;
+    if (sprinting) { this.stamina = Math.max(0, this.stamina - dt * 8); this._stamPause = Math.max(this._stamPause ?? 0, 0.6); }
+    let hx = 0, hz = 0; // horizontal delta for the capsule controller
+
+    if (moving) {
+      const len = Math.hypot(mx, mz);
+      mx /= len; mz /= len;
+      // camera sits at +(sin,cos)·camYaw from the player, so camera-forward
+      // (away from the lens) is -(sin,cos); camera-right is (cos,-sin).
+      const sin = Math.sin(this.camYaw), cos = Math.cos(this.camYaw);
+      const dir = tmpV1.set(mx * cos - mz * sin, 0, -mx * sin - mz * cos);
+      // wading: the creek drags you down at chest depth — only when actually IN the water
+      const surfW = this.game.world.waterSurfaceAt?.(this.position.x, this.position.z);
+      const immersed = surfW != null ? surfW - this.position.y : 0;
+      const wade = Math.max(0, Math.min(immersed, this.game.world.waterDepthAt?.(this.position.x, this.position.z) ?? 0));
+      const wadeK = wade > 0.15 ? Math.max(0.45, 1 - wade * 0.45) : 1;
+      const aimSlow = (this.aiming || this.reloading) ? 0.45 : 1;
+      // analog: a half-pushed stick walks, a full push runs. Keyboard holds moveMag at 1,
+      // so it is unaffected; sprint (Shift/L1) still overrides to the flat-out rate.
+      const speed = this.moveSpeed * (sprinting ? 1.55 : moveMag) * aimSlow * wadeK;
+      hx = dir.x * speed * dt; hz = dir.z * speed * dt;
+      this._hspeed = speed;    // what he is ACTUALLY doing — the running jump reads this, not the keys
+      // face travel direction (or target when locked) — UNLESS aiming, which owns the heading
+      if (this.aiming) { /* handled below */ }
+      else if (this.lockTarget?.alive) {
+        this.faceToward(this.lockTarget.position.x, this.lockTarget.position.z, dt);
+      } else {
+        this._faceAngle(Math.atan2(dir.x, dir.z), dt, 10);
+      }
+    } else if (this.lockTarget?.alive && !this.busy && !this.aiming) {
+      this.faceToward(this.lockTarget.position.x, this.lockTarget.position.z, dt);
+    }
+    // ---- ADS body heading: EASE onto the camera direction (shortest arc, moving or planted).
+    // The body faces the shot, the legs strafe under it, and the arm IK does the precision —
+    // no snap, no wrap. (The old code hard-assigned heading = camYaw + PI when planted and
+    // twisted the spine when moving; both are gone.)
+    // Gun out = the body squares to the camera (faster while ADS). The character must face where
+    // you are LOOKING, or the shot — and the whole stance — reads sideways. Shortest arc, no wrap.
+    if (this.drawn && !this.busy && !moving) this._faceAngle(this.camYaw + Math.PI, dt, this.aiming ? 9 : 5);
+    else if (this.aiming && !this.busy) this._faceAngle(this.camYaw + Math.PI, dt, 9);
+
+    // ---- INHERITED MOMENTUM. Jump off a coach doing 10.5 m/s and you go with her: this is the
+    // speed she gave you, added ON TOP of your own air control (it never replaces it — hold W and
+    // you go further, let go and you still fly). It is OUTSIDE the moving block above on purpose:
+    // hx/hz are only ever assigned in there, and "let go of the keys in mid-air and stop dead" is
+    // precisely the bug this exists to kill. No drag while airborne — a jump is ballistics, which
+    // is what lets you hop straight up on a galloping coach and land back on her roof. On the
+    // ground it bleeds off in a quarter of a second: a stumble, not a skate.
+    if (this._airVX || this._airVZ) {
+      hx += this._airVX * dt; hz += this._airVZ * dt;
+      if (!this.airborne) {
+        const k = Math.exp(-dt / 0.25);
+        this._airVX *= k; this._airVZ *= k;
+        if (Math.hypot(this._airVX, this._airVZ) < 0.2) { this._airVX = 0; this._airVZ = 0; }
+      }
+    }
+
+    // ---- don't walk through people (the coach's crew are in none of its lists, so a roof rider
+    // has nobody to be separated from — and being shoved in WORLD x/z would fight the carry)
+    if (!this.platform) this.separateFromPeople();
+
+    // ---- vertical resolution: the capsule controller owns gravity, ground/stairs/slopes — unless
+    // he is standing on a moving floor, where the deck IS the floor (game/platform.js)
+    const wasAir = this.airborne;
+    const fallSpeed = -this.vy; // capture BEFORE the capsule zeroes it on touchdown
+    const prevFeetY = this.position.y; // for the swept landing test — his height at the top of the frame
+    const plat = this.game.platforms;
+    if (this.platform) {
+      plat.deckMove(this, hx, hz, dt);
+    } else {
+      this.game.world.moveCapsule(this, hx, hz, dt);
+      // STANDING-STILL Y LATCH. Measured on the store roof (Nick's vibrating screen): two
+      // overlapping roof surfaces 19 cm apart under one capsule made the resolver alternate
+      // between them — the player physically bounced at breathing rate while standing dead still,
+      // and every smoother downstream just softened it into a shimmer. A man with NO input does
+      // not need his feet re-negotiated every frame: latch the height he stood down at, and hold
+      // it while the capsule still calls him grounded and his height stays within a step of the
+      // latch. Any real movement — input, a shove off the edge (grounded drops), a dodge, a jump —
+      // releases it.
+      const still = Math.abs(hx) < 1e-4 && Math.abs(hz) < 1e-4 && !this.airborne && this.vy <= 0 && this.dodgeT <= 0;
+      if (still && this._standLatch != null && Math.abs(this.position.y - this._standLatch) < 0.3) {
+        this.position.y = this._standLatch;
+        this.vy = 0;
+      } else {
+        this._standLatch = still ? this.position.y : null;
+      }
+      plat?.tryLand(this, prevFeetY, wasAir);   // ...did he just come down on a coach roof?
+      if (!this.platform) plat?.hullPush(this); // ...and if he missed it, he hit the side of her
+    }
+    // keep the player ~20m inside the world edge (a clamp on a roof would desync his deck coords —
+    // and no coach route goes within a kilometre of the edge)
+    if (!this.platform) {
+      const EDGE = PC.worldSize / 2 - 20;
+      this.position.x = clamp(this.position.x, -EDGE, EDGE);
+      this.position.z = clamp(this.position.z, -EDGE, EDGE);
+    }
+    if (wasAir && !this.airborne) {
+      const fell = (this._airStartY ?? this.position.y) - this.position.y;   // NET descent from takeoff
+      if (fell > FALL_SAFE_M && this.alive && !this._resting) {
+        // FALL DAMAGE — a drop past the safe height hurts, scaled by how far past; a big fall is lethal.
+        // takeDamage plays the hit reel + damage flash + shake and handles death (fromPos null = no reel dir).
+        this.takeDamage(Math.round((fell - FALL_SAFE_M) * FALL_DMG_PER_M), null);
+      } else if (!moving && fallSpeed > 8.5) {
+        // land-lock on a hard-but-safe touchdown (> a normal jump's ~7.2 m/s) — the soft land clip, no damage
+        this.busy = true;
+        this.animator.play('land', { once: true, fade: 0.08, onDone: () => { this.busy = false; } });
+      }
+    }
+
+    // ---- locomotion animation
+    // NO MASKS, NO OVERLAYS. The gunslinger pack is a COMPLETE locomotion set (Idle_w_Revolver,
+    // Walk_wRevolver, Walk_wRevolverAimed, Run_w_Gun, Fulldraw_Idle, Idle_Reload...), so every
+    // gun state has a real FULL-BODY clip. The old code grafted a gun TORSO (masked overlay)
+    // onto SYNTY LEGS (masked base) — but the gun clips are authored against their own BLADED
+    // pelvis, so bolting that torso onto the Synty idle's hips rotated it ~90deg off the legs:
+    // the body-split after every shot. Masking also created the whole T-pose class (any weight
+    // gap fills from the bind pose). Full-body clips remove both. The gun is pointed by the
+    // arm-only aim IK, which is now the only thing that touches a bone after the mixer.
+    const gunW = WEAPONS[this.weapon];
+    // "the gun is in use": aiming, reloading, mid-draw, or still settling from a shot. The
+    // auto-holster below counts idle seconds against it. (This local survived the move to
+    // full-body clips — the holster timer still reads it, so it must still exist.)
+    const gunPose = !!gunW && (this.aiming || this.reloading || this._drawT > 0 || this._gunRecoilT > 0);
+    if (!this.busy && !this.airborne) {
+      if (this.animator._overlay) this.animator.setOverlay(null, { fade: BASE_FADE });
+      if (this.drawn && gunW) {
+        if (this.reloading) this.animator.play(moving ? 'gunReloadWalk' : 'gunReload');
+        else if (this._holstering) this.animator.play(moving ? 'gunWalkHolster' : 'gunHolster');
+        else if (this.aiming) this.animator.play(moving ? 'gunWalkAimed' : 'gunAim');
+        else if (moving && sprinting) this.animator.play('gunRun');
+        else if (moving) this.animator.play('gunWalk');
+        else this.animator.play('gunIdle');
+      } else if (moving && sprinting) this.animator.play('sprint');
+      else if (moving) this.animator.play('run');
+      else if (this.weapon === 'fists') this.animator.play('punchIdle');
+      else this.animator.play('idle');
+    }
+
+    // ---- footsteps: surface-aware step SFX on a distance-stride timer (on foot only)
+    this.footsteps.update(dt, moving, sprinting);
+
+    // ---- combat inputs (buffers cleared while a menu/dialogue is open so a press
+    // made just before it opened can't fire a phantom shot/jump on close)
+    if (!inMenu && this.alive) this.combatInputs(input, dt);
+    else { this._atkBuf = 0; this._heavyBuf = 0; this._jumpBuf = 0; }
+
+    // ---- auto-holster: ~6s without aiming/firing/reloading sends the gun back to leather
+    if (this.drawn && !gunPose) {
+      this._holsterT -= dt;
+      if (this._holsterT <= 0) this.holsterGun();
+    }
+
+    // ---- POST-MIXER pose fixes, in order: re-seat the aim clip's spine on the walk pelvis
+    // (reblade), THEN swing the arm onto the camera ray (IK), THEN the grip — the grip reads
+    // bone poses, so the arm has to be final before it runs.
+    // REBLADE DISABLED. It was built for the bow: it premultiplies Spine_01 by
+    // (liveHips⁻¹ · clipHipsRef) to re-aim a torso whose clip was authored against a different
+    // pelvis. With the gunslinger clips that difference is large, so it LEANED THE PLAYER OVER.
+    // The bench plays the clips raw — no reblade — and looks correct; the game did not. The aim
+    // IK (arm only) is what points the gun now, so the reblade has no job left.
+    // this.applyUpperReblade(dt);
+    // AIM IK: arm only (AIM_IK_SPINE = 0), and only while genuinely aiming. It is what puts the
+    // muzzle ON the reticle — without it the gun points wherever the clip happens to point, so
+    // you aim down the street and he fires sideways. It does NOT touch the posture: the pose is
+    // measurably identical to /guntest.html (tilt 8.2 deg, lean 0.099m) with it off or on.
+    this.applyAimIK(rdt);
+    this.applyFistCurl();   // bare-knuckle: curl the fingers into fists on the punch clips (post-mixer)
+    this.updateWeaponPose();
+    // muzzle flip: the gun rises on the shot and settles. Runs AFTER updateWeaponPose, which
+    // rewrites rotation from the grip every frame — so this is an OFFSET on a fresh value, not
+    // an accumulating rotate (rotateX() on an unreset transform spins the gun like a propeller).
+    if (this._muzzleFlip > 0.0001 && this.weaponObj) {
+      this.weaponObj.rotateX(-this._muzzleFlip);      // safe: rotation was just reset above
+      this._muzzleFlip = Math.max(0, this._muzzleFlip - dt * 4.5);
+    }
+
+    // ---- smooth the VISUAL height on the way DOWN over micro-bumps so descents
+    // aren't choppy. Physics stay exact; ascents/jumps track 1:1.
+    // ON A MOVING FLOOR neither this nor the camera below may run here: his position is still the
+    // one the coach had LAST frame (she moves after him — main.js), so both would be a frame stale.
+    // platform.js's postUpdate does the same two jobs at the end of the tick, once she has moved.
+    if (!this.platform) {
+      const py = this.position.y;
+      if (this.airborne || this._visualY === undefined || Math.abs(py - this._visualY) > 1.5) {
+        this._visualY = py;
+      } else if (py < this._visualY) {
+        this._visualY += (py - this._visualY) * Math.min(1, dt * 12); // ease down
+      } else {
+        this._visualY = py;
+      }
+      this.model.position.y = this._baseModelY2 + (this._visualY - py);
+
+      this._camera(dt, input, camera);
+    }
+  }
+
+  // THE LOOK, on its own — for the same reason the camera is: a man who has climbed onto a coach has
+  // not gone blind. It was buried in the middle of update(), below the early-out for riding, so the
+  // moment you took the reins your mouse stopped turning your head.
+  // Returns true if the player actually MOVED the look this frame, which is what tells a vehicle
+  // camera to stop recentring and leave him alone (RDR2/GTA: look freely, and it drifts back behind
+  // the vehicle only once you take your hand off).
+  _look(input, rdt) {
+    const sens = this.camSensitivity;
+    const inv = this.invertY ? -1 : 1;
+    const dx = input.mouse.dx, dy = input.mouse.dy;
+    const sx = input.stickLook.x, sy = input.stickLook.y;
+    // mouse: per-event deltas are already framerate-independent
+    this.camYaw -= dx * 0.0028 * sens;
+    this.camPitch = clamp(this.camPitch + dy * 0.0022 * sens * inv, -0.6, 1.1);
+    // gamepad right stick: rate-based so the turn speed doesn't scale with fps — and on
+    // WALL-CLOCK dt, so a pad player's look doesn't slow to a crawl inside Dead Eye
+    this.camYaw -= sx * this.padCamSpeed * sens * rdt;
+    this.camPitch = clamp(this.camPitch + sy * this.padCamSpeed * sens * inv * rdt, -0.6, 1.1);
+    return Math.abs(dx) + Math.abs(dy) + Math.abs(sx) + Math.abs(sy) > 0.001;
+  }
+
+  // THE VEHICLE CAMERA, AFTER THE VEHICLE HAS MOVED. main.js calls this at the end of the tick, beside
+  // platform.js's postUpdate, which exists for exactly this reason — once the coaches and the trains
+  // have run and train.js's host.sync() has put him back on his bench on the car where it NOW is.
+  // Only a host that OWNS its camera comes through here; the stagecoach is filmed in update(), as before.
+  aboardPost(dt, input, camera) {
+    const c = this.aboard;
+    if (!c?.camera) return;
+    // The rig answers false the moment it must not be filming — he aimed, he drew, he took a round, a
+    // fight started, or he pressed V — and then the ordinary follow camera takes the lens straight
+    // back, with the mouse live again.
+    if (c.camera(dt, camera, this, input)) return;
+    const rdt = this.game.rawDt ?? dt;
+    if (!this.game.ui?.menuOpen) this._look(input, rdt);
+    this._camera(dt, input, camera);
+  }
+
+  // THE FOLLOW CAMERA, on its own so anything that takes over the player's legs (a horse, the box
+  // seat of a stagecoach) can still hand him a camera. Riding is not the same as being gone.
+  _camera(dt, input, camera) {
+    const rdt = this.game.rawDt ?? dt;
+    // ---- camera position. RMB (ADS) also pulls the camera IN — eased, so the transition
+    // reads as a lean rather than a cut. Note this.camDist stays the user's follow distance.
+    // (every ease in this block runs on rdt — WALL-CLOCK. On world dt the follow cam would
+    // lag a third of a second behind the mouse inside Dead Eye, which reads as input lag.)
+    const head = tmpV1.set(this.position.x, this._visualY + 1.55, this.position.z);
+    // A COACH IS BIGGER THAN A MAN. The on-foot follow distance puts the lens inside the roof rack.
+    // ...but a vehicle you sit INSIDE is smaller than the follow distance: a railway carriage's saloon
+    // is 2.98 m wide and 9 m of camera lands outside the planking, looking at the outside of it. So a
+    // host may say how far back its lens goes (train.js: makeSeat). A stagecoach says nothing and gets
+    // the 9 m it has always had.
+    const wantDist = this.aboard ? (this.aiming ? (this.aboard.camAdsDist ?? 6.0) : (this.aboard.camDist ?? 9.0)) : (this.aiming ? ADS_CAM_DIST : this.camDist);
+    this._camDistNow = this._camDistNow == null ? this.camDist : lerp(this._camDistNow, wantDist, Math.min(1, rdt * 8));
+    const dist = this._camDistNow;
+    let cx = head.x + Math.sin(this.camYaw) * Math.cos(this.camPitch) * dist;
+    let cz = head.z + Math.cos(this.camYaw) * Math.cos(this.camPitch) * dist;
+    let cy = head.y + Math.sin(this.camPitch) * dist;
+    // OVER THE SHOULDER — BY DEFAULT, NOT ONLY TO SHOOT.
+    // This used to snap sideways the instant you aimed OR fired (the shot's recoil window kept
+    // it there for 0.28s) and snap back after: the camera lurched on every single trigger pull,
+    // which Nick rightly called a sickening sensation. A framing you only adopt to shoot is a
+    // framing that lurches every time you shoot. So the game simply IS an over-the-shoulder
+    // game: the player rides off to the left of frame all the time, the centre of the screen is
+    // always clear of his body, and aiming merely DEEPENS the offset a little. Nothing snaps,
+    // because nothing has to travel.
+    // (Parallel shift: camera AND look-target move together, so the framing pans rather than
+    // orbiting — the aim ray out of the screen centre is unchanged.)
+    const wantShoulder = (this.aiming || this._gunRecoilT > 0) ? 1 : SHOULDER_IDLE;
+    this._shoulderT = lerp(this._shoulderT ?? SHOULDER_IDLE, wantShoulder, Math.min(1, rdt * 8));
+    if (this._shoulderT > 0.001) {
+      const off = SHOULDER_OFF * this._shoulderT;       // metres to the camera's right
+      const rx = Math.cos(this.camYaw) * off, rz = -Math.sin(this.camYaw) * off;
+      head.x += rx; head.z += rz; cx += rx; cz += rz;   // shift target + camera together → player goes left
+    }
+    const groundCam = this.game.world.groundAt(cx, cz) + 0.4;
+    if (cy < groundCam) cy = groundCam;
+    // ...and a vehicle with a ROOF on it keeps the lens indoors. The wall ray below only knows about
+    // buildings — its BVH is baked out of the town at world build, and a moving train is not in it —
+    // so a host that has an inside says where the lens may go, in its own frame (train.js: makeSeat).
+    // Swing the camera round to look out of the left-hand window and it presses against the right-hand
+    // wall instead of standing a metre outside it staring at the planking.
+    if (this.aboard?.camConfine) { const p = this.aboard.camConfine(cx, cy, cz); cx = p.x; cy = p.y; cz = p.z; }
+    // pull the camera in if a wall is between it and the player, so inside rooms you
+    // keep facing the player instead of looking through the wall from outside
+    const W = this.game.world;
+    const camBvhs = [W.buildingBVH];
+    _camDir.set(cx - head.x, cy - head.y, cz - head.z);
+    const want = _camDir.length();
+    let wallClipped = false;
+    if (want > 0.01) {
+      _camDir.divideScalar(want);
+      _camRay.origin.copy(head); _camRay.direction.copy(_camDir);
+      let nearest = want;
+      for (const bvh of camBvhs) {
+        if (!bvh || !bvh.raycastFirst) continue;
+        try { const hit = bvh.raycastFirst(_camRay, THREE.DoubleSide); if (hit && hit.distance < nearest) nearest = hit.distance; }
+        catch (e) { if (!this._wallRayWarned) { console.error('[cam wall ray]', e); this._wallRayWarned = true; } }
+      }
+      // THE CLIP DISTANCE IS HELD, NOT RE-DECIDED EVERY FRAME. Standing on a roof, the ray to the
+      // desired camera spot GRAZES the parapet under your own heels — hit one frame, miss the next —
+      // and the old instant-cut-in / eased-out pair turned that into a standing VIBRATION (Nick).
+      // A hit pulls the held distance in at once; a miss lets it breathe back out slowly. The hard
+      // CUT only fires when a wall bites meaningfully DEEPER than what is already held — walking
+      // into a room still cuts, a grazing flicker no longer does.
+      // GLIDE, NOT POP. Measured on the store roof (player amplitude 0.000, camera 0.53 m): the
+      // wall ray GRAZES the roof edge and the idle head-sway flips it hit/miss forever — any rule
+      // that pops the distance on a state change is a vibration with that as its clock. So: a wall
+      // biting a full METRE inside the camera's current stance cuts instantly (walking into a
+      // room); everything nearer GLIDES in; release starts only after the ray has been clean for
+      // 0.6 s and eases; and a re-bite mid-breathe just glides back down. No edge, no pop.
+      const eff = this._camWallD ?? want;
+      if (nearest < want) {
+        if (nearest < eff - 1.0) wallClipped = true;
+        this._camWallD = wallClipped ? nearest : Math.min(eff, eff + (nearest - eff) * Math.min(1, rdt * 6));
+        this._camWallT = 0;
+      } else if (this._camWallD != null) {
+        // release only after the ray has been clean LONGER than the idle sway that drives the
+        // flicker (~1-2 s breathing period, measured at steep pitch on the store roof — a 0.6 s
+        // window released mid-flicker and the 2 m hit/miss gap pumped the camera every cycle)
+        this._camWallT = (this._camWallT ?? 0) + rdt;
+        if (this._camWallT > 2.0) {
+          this._camWallD += (want - this._camWallD) * Math.min(1, rdt * 2.5);
+          if (this._camWallD > want - 0.02) this._camWallD = null;
+        }
+      }
+      if (this._camWallD != null && this._camWallD < want) {
+        const s = Math.max(0.4, this._camWallD - 0.35);
+        cx = head.x + _camDir.x * s; cy = head.y + _camDir.y * s; cz = head.z + _camDir.z * s;
+      }
+    }
+    // cut in INSTANTLY when a wall newly constrains the camera, ease normally relaxing out.
+    // ...and _camSnap is the same instant, asked for from outside: a cinematic camera handing the lens
+    // back (trainCamera.js) is standing sixty metres away, and easing home from there takes half a
+    // second — half a second of a man with a gun in his hand watching the world swoop past him while
+    // somebody shoots at him. It CUTS. One flag, consumed the frame it is read.
+    const snap = wallClipped || this._camSnap;
+    this._camSnap = false;
+    camera.position.lerp(_camTarget.set(cx, cy, cz), snap ? 1 : Math.min(1, rdt * 10));
+    camera.lookAt(head);
+  }
+
+  combatInputs(input, dt) {
+    const combat = this.game.combat;
+
+    // toggle weapon: revolver → rifle → fists → revolver. Cancels any live aim/reload
+    // (the release guard — old weapon keeps its part-filled mag).
+    if (input.hit('KeyQ') && !this.busy) {
+      this.cancelGun();
+      this.weapon = this.weapon === 'revolver' ? 'fists' : 'revolver';  // rifle parked — untuned sling, sorted later
+      const w = WEAPONS[this.weapon];
+      this.ammoMax = w?.mag ?? 0;
+      this.ammo = w ? this._mags[this.weapon] : 0;
+      this.drawn = false; // fresh weapon starts holstered — first fire/aim plays the draw
+      this._holstering = false;
+      this.placeWeapons();
+      this.game.audio?.play('ui');
+    }
+    // WHISTLE (H) — call the companion horse over. On foot only (this whole block never runs mounted).
+    if (input.hit('KeyH') && !this.busy) this.whistle();
+    // GREET (G) — tip the hat to whoever's near. Manners are cheap and the town keeps books.
+    if (input.hit('KeyG') && !this.busy && !this.drawn) this.greet();
+    // lock-on (fists brawling aid — guns aim with the camera)
+    if (input.hit('Tab')) {
+      this.lockTarget = combat?.nearestEnemy?.(this.position, 18, this.lockTarget) ?? null;
+      if (this.lockTarget) this.enterCombatStance();
+    }
+    if (this.lockTarget && (!this.lockTarget.alive || this.lockTarget.position.distanceTo(this.position) > 25)) {
+      this.lockTarget = null;
+    }
+
+    // ---- input buffers: stamp presses, then decay EVERY frame so a press a few frames
+    // early still lands. update() zeroes them while a menu is open.
+    const canMelee = this.weapon === 'fists';
+    if (canMelee && input.mouseHit(0) && input.acting) this._atkBuf = 0.35;
+    if (canMelee && input.hit('KeyF')) {
+      // finisher first (if combat offers one): a staggered foe in front eats the execute
+      if (!this.busy && combat?.finishTarget && combat.executeFinisher?.()) { this._heavyBuf = 0; this._atkBuf = 0; }
+      else this._heavyBuf = 0.35;
+    }
+    if (input.hit('Space')) this._jumpBuf = 0.12;
+    this._atkBuf = Math.max(0, this._atkBuf - dt);
+    this._heavyBuf = Math.max(0, this._heavyBuf - dt);
+    this._jumpBuf = Math.max(0, this._jumpBuf - dt);
+
+    // Alt = DODGE (the only dodge key). Space jumps in the open and dodges when locked on.
+    // Ctrl is deliberately UNBOUND in this file — it belongs to Dead Eye.
+    if ((input.hit('AltLeft') || input.hit('AltRight')) && !this.busy && this.dodgeT <= 0 && !this.airborne) {
+      this.dodge(input);
+      return;
+    }
+    // coyote time: a jump pressed just after walking off a ledge (<0.12s) is honoured
+    if (this._jumpBuf > 0 && !this.busy && (!this.airborne || (this._sinceGrounded < 0.12 && this.vy <= 0))) {
+      this._jumpBuf = 0;
+      if (this.lockTarget?.alive && this.dodgeT <= 0) this.dodge(input);
+      else this.jump(input);
+      return;
+    }
+
+    if (this.weapon === 'fists') {
+      if (!this.busy && this.attackCooldown <= 0) {
+        if (this._heavyBuf > 0) { this.enterCombatStance(); combat?.playerMelee?.(true, true); this._heavyBuf = 0; this._atkBuf = 0; }
+        else if (this._atkBuf > 0) { this.enterCombatStance(); combat?.playerMelee?.(false, true); this._atkBuf = 0; }
+      }
+    } else {
+      this.gunInputs(input, dt);
+    }
+  }
+
+  // THE GUN STATE MACHINE — RDR2 rules. There is no mode to enter.
+  //   LMB : ONE shot, rate-limited. Holstered? draw, and the click is BUFFERED across the
+  //         draw gate so it fires the moment the gun is level. Empty chamber → dryfire.
+  //   RMB : OPTIONAL ADS while held. Tighter cam, tighter spread, reticle. Also draws.
+  //   R   : reload.  Ctrl : NOT BOUND (Dead Eye owns it).
+  gunInputs(input, dt) {
+    const w = WEAPONS[this.weapon];
+    if (!w) return;
+    const movin = input.down('KeyW') || input.down('KeyA') || input.down('KeyS') || input.down('KeyD');
+
+    // ---- RMB = optional ADS (never required to fire)... and DEAD EYE AIMS TOO. Ctrl puts him in
+    // the same shoulder-aim as RMB, because a man picking his shots is a man looking down the barrel,
+    // not one marking them from the hip. The gun POSE already knew this (the aim overlay reads
+    // `this.aiming || this.deadEyeActive` above) — it was the camera and the reticle that did not, so
+    // Dead Eye looked like a different, sloppier stance than the one it borrows its animation from.
+    const deadEyeAim = this.deadEyeActive && !this.busy && !this.airborne;   // Ctrl aims on its own — no mouse held
+    const adsHeld = (input.held(2) && input.acting && !this.busy && !this.airborne) || deadEyeAim;
+    if (adsHeld && this._holstering) this._abortHolster();       // re-aim aborts the stow
+    if (adsHeld && !this.drawn && this._drawT <= 0) this._startDraw();
+    const wasAiming = this.aiming;
+    this.aiming = adsHeld && this.drawn && this._drawT <= 0 && !this._holstering;
+    // aim released: normally the locomotion block hands the upper body back to a full-body
+    // base in ONE frame (matched fades, sum stays 1). It's skipped while busy/airborne, so
+    // only THEN do we drop the overlay here — otherwise it would strand a masked base.
+    if (wasAiming && !this.aiming && (this.busy || this.airborne)) {
+      this.animator.setOverlay(null, { fade: BASE_FADE });
+    }
+
+    // ---- LMB. THE FIRST CLICK DRAWS. THE SECOND ONE SHOOTS.
+    // A holstered man does not shoot: he draws. The click that clears leather is the click that
+    // puts you IN gunfighting stance — the gun comes up, the reticle appears, you can see what
+    // you would be shooting at — and only the NEXT click sends a round. It used to hold the fire
+    // buffer THROUGH the draw, so a single click on a holstered gun drew and fired in one motion,
+    // at whatever happened to be under a reticle you had not seen yet.
+    // (Once drawn, the buffer behaves as before: click during the rate-limit or a stow and the
+    // shot still lands the instant the gate clears — you never lose an intended shot.)
+    if (input.mouseHit(0) && input.acting) this._fireBuf = FIRE_BUF;
+    if (this._drawT <= 0) this._fireBuf = Math.max(0, this._fireBuf - dt);
+    if (this._fireBuf > 0 && !this.busy && !this.airborne && !this.reloading) {
+      if (this._holstering) this._abortHolster();                // shoot through a stow
+      if (!this.drawn) {
+        if (this._drawT <= 0) { this._startDraw(); this._fireBuf = 0; }   // this click only DRAWS
+      } else if (this._drawT <= 0 && this._gunFireT <= 0) {
+        this._fireBuf = 0;                                       // consumed — one click, one shot
+        this._holsterT = HOLSTER_IDLE;
+        if (this.ammo > 0) this._fire(w, movin);
+        else { this.game.audio?.play('dryfire'); this._gunFireT = 0.25; }
+      }
+    }
+
+    if (this.drawn) this.game.ui?.aimTarget(this._aimingAtBody());
+    if (this.drawn) this._menaceCheck(dt);
+    if (this.aiming || this.reloading || this._drawT > 0) this._holsterT = HOLSTER_IDLE;
+    if (this.drawn) this.game.hint?.('gun', 'Left-click to fire — hold right-click to aim down the sights. R reloads.');
+
+    // R = reload when the mag isn't full
+    if (input.hit('KeyR') && !this.reloading && this._drawT <= 0 && !this.busy && !this.airborne && this.ammo < this.ammoMax) {
+      this._startReload();
+    }
+
+    // AN EMPTY GUN RELOADS ITSELF. Nobody in a gunfight stands there dry-firing at a man because
+    // they forgot a keybind — the character knows his revolver is empty. There is a short beat
+    // first (AUTO_RELOAD_WAIT) so the last shot's recoil reads and the click of an empty chamber
+    // still lands: it goes click, THEN he reloads, which is the sound of running out. Hitting R
+    // early skips the beat, and a fresh trigger-pull does not (a dry gun cannot be hurried).
+    // (mounted too — a rider's revolver knows it is empty the same as a walker's; the reload is
+    // sound + timer in the saddle, the seat pose holds)
+    if (this.drawn && this.ammo <= 0 && !this.reloading && this._drawT <= 0 && !this.airborne
+        && this.ammoMax > 0) {
+      this._autoReloadT = (this._autoReloadT ?? AUTO_RELOAD_WAIT) - dt;
+      if (this._autoReloadT <= 0 && !this.busy) { this._autoReloadT = null; this._startReload(); }
+    } else {
+      this._autoReloadT = null;
+    }
+  }
+
+  _startDraw() {
+    this.drawn = true;
+    this.placeWeapons();       // the gun appears in the hand as the draw plays
+    this._drawT = DRAW_GATE;   // input gate ≈ the draw's leather-to-level beat
+    this._holsterT = HOLSTER_IDLE;
+    this._overlayOnce('gunDrawUpper');
+  }
+
+  // Abort a stow in flight (a fresh aim or a fresh shot beats the holster). Clearing the
+  // flag is the whole abort: the locomotion block stops picking the holster take next
+  // frame, and the pending stow timer checks the flag and stands down.
+  _abortHolster() {
+    this._holstering = false;
+  }
+
+  _startReload() {
+    this.reloading = true;
+    if (!this.drawn) { this.drawn = true; this.placeWeapons(); }
+    if (this._holstering) this._abortHolster();
+    this._holsterT = HOLSTER_IDLE;
+    this.game.audio?.play('reload');
+    const done = () => {
+      if (!this.reloading) return;   // cancelled — the old ammo stands
+      this.reloading = false;
+      this.ammo = this._mags[this.weapon] = this.ammoMax;
+    };
+    // FULL-BODY reload: the locomotion block owns the pose while `reloading` is up (standing
+    // take planted, walking take on the move — both loop). The old gunReloadUpper overlay
+    // could never finish here: the no-masks locomotion block DROPS overlays every frame, so
+    // its onDone never fired and the reload looped forever. Completion is a TIMER cut to the
+    // standing take's length; the clip may be missing in dev, so fall back to a fixed beat.
+    const dur = this.animator.actions.gunReload?.getClip().duration;
+    this.game.after(dur ? dur / (PC.clipTiming.gunReload?.speed ?? 1) : 1.2, done);
+  }
+
+  // Everything a round can hit, as one list. The reticle and the shot BOTH walk it, so the light
+  // that says "this will connect" and the lead that connects can never be looking at different men.
+  // (The children are in game.npcs too, and aim.js's nearestBody drops anything carrying
+  // `noTarget` — so they are in this generator and yet unreachable through it, by construction.)
+  * _targets() {
+    for (const e of this.game.combat?.enemies ?? []) yield e;
+    for (const n of this.game.npcs ?? []) yield n;
+    for (const c of this.game.coaches?.coaches ?? []) for (const r of c.crew ?? []) yield r;
+  }
+
+  _rayBody(origin, dir) {
+    return nearestBody(origin, dir, this._targets(), { skip: this });
+  }
+
+  // The point the crosshair is over — see aim.js for why this is not the same line as the shot.
+  _aimPoint(out) {
+    return aimPoint(out, this.game.camera.position, this.aimDir(_aimDir), this._targets(), { skip: this });
+  }
+
+  // IS THERE A MAN IN THE LINE OF FIRE?
+  // The same camera ray the bullet takes (aimDir), minus the spread — a cone of luck is not
+  // something to promise the player. A body is a capsule about his spine; we take the NEAREST one
+  // the ray crosses, and only if the world isn't in the way (shooting a man through a wall is not
+  // a shot that connects). Cheap: a dot product per candidate, and the LOS check only for the one
+  // that wins, so a crowded street costs a handful of multiplies, not a raycast per townsman.
+  // POINT A GUN AT A CHILD AND HE RUNS — AND THE STREET THINKS THE WORSE OF YOU.
+  // A child is unreachable through _targets() (aim.js drops `noTarget`), so the reticle never
+  // lights on one and the round never converges on one. That is the safety. This is the REACTION,
+  // and it needs its own ray against its own list — game.children, which populateCounty keeps.
+  //
+  // MENACE is a crime like any other, so it goes through crime.report() and is weighted by
+  // witnesses exactly as a murder is: on Perdition's main street at noon with five people watching
+  // it is nine heat and a black look; alone in a barn it is one heat and nobody cares, because
+  // nobody saw. Scanned at 5 Hz (it is a ray against ~21 children county-wide, and a fright is not
+  // a thing that needs 120 Hz), and charged once per aiming episode.
+  _menaceCheck(dt) {
+    const kids = this.game.children;
+    if (!kids?.length) return;
+    this._menaceT = (this._menaceT ?? 0) - dt;
+    this._menaceCool = Math.max(0, (this._menaceCool ?? 0) - dt);
+    if (this._menaceT > 0) return;
+    this._menaceT = 0.2;
+    // aim.js's nearestBody refuses `noTarget` and every child carries it — which is exactly the
+    // guarantee we want everywhere else and useless here. So ask rayCapsule directly: the same
+    // body model, the same camera ray, past the flag.
+    const cam = this.game.camera.position, dir = this.aimDir(_aimDir);
+    let best = null, bestT = Infinity;
+    for (const k of kids) {
+      if (!k.alive || k.position.distanceTo(this.position) > MENACE_R) continue;
+      const r = rayCapsule(cam.x, cam.y, cam.z, dir.x, dir.y, dir.z, k.position, 0.55);
+      if (!r || r.t >= bestT) continue;
+      best = k; bestT = r.t;
+    }
+    if (!best) return;
+    _aimTo.set(best.position.x, best.position.y + 1.0, best.position.z);
+    if (this.game.world.segmentBlocked?.(this._muzzle(_aimFrom2), _aimTo)) return;
+    best.scare(this.position.x, this.position.z, 6, true);   // and he keeps running while you hold it on him
+    // The STREET's reaction is one event per episode, not a five-a-second siren: crime.report()
+    // already empties the street round the spot (14 m, alarmTown, see crime.js), and firing that
+    // at 5 Hz meant walking all 150 souls 750 times a second to re-panic the same dozen men.
+    if (this._menaceCool <= 0) {
+      this._menaceCool = 4;
+      this.game.crime?.report('menace', best.position.clone());
+    }
+  }
+
+  _aimingAtBody() {
+    if (!this.drawn) return false;
+    const hit = this._rayBody(this.game.camera.position, this.aimDir(_aimDir));
+    if (!hit) return false;
+    // ...and the world must not be in the way, checked along the round's ACTUAL path (muzzle →
+    // him), not along the camera's. Shooting a man through a wall is not a shot that connects.
+    const from = this._muzzle(_aimFrom2);
+    _aimTo.set(hit.e.position.x, hit.e.position.y + 1.0, hit.e.position.z);
+    return !this.game.world.segmentBlocked?.(from, _aimTo);
+  }
+
+  _fire(w, moving) {
+    this._gunFireT = w.rate;
+    // FROM the muzzle, AT what the crosshair is over (_aimPoint) — the two are not the same line
+    // and pretending they are is what put every round below where you were aiming.
+    const from = this._muzzle(_fireFrom);
+    const aim = this._aimPoint(_fireAim);
+    const dir = _fireDir;
+    // ADS is TIGHT; hip-fire is not — that is the whole point of RMB being optional. Moving
+    // scatters either further. The jitter goes in the plane ACROSS the shot, so a spread of x
+    // radians means x radians off the line you actually took, whichever way you happen to face.
+    const spread = (this.aiming ? SPREAD.ads : SPREAD.hip) * (moving ? SPREAD.moveMul : 1);
+    shotDir(dir, from, aim, spread);
+    this._shootAlong(w, dir.clone(), from.clone());
+  }
+
+  // Muzzle = the held gun's world position; fallback = chest height, a little down the aim ray.
+  _muzzle(out) {
+    if (this.weaponObj) this.weaponObj.getWorldPosition(out);
+    else out.set(this.position.x, this.position.y + 1.4, this.position.z).addScaledVector(this.aimDir(_ikDir), 0.4);
+    return out;
+  }
+
+  // THE SHOT: one bullet down `dir`, plus everything that sells it. This is the ONLY place a
+  // round is spent — LMB comes through _fire (camera ray + spread) and DEAD EYE comes through
+  // deadEyeShot (straight at a painted body point), so the two land IDENTICAL damage, blood,
+  // impacts, ammo and recoil by construction, not by two copies agreeing with each other.
+  _shootAlong(w, dir, from = this._muzzle(new THREE.Vector3())) {
+    this.ammo = this._mags[this.weapon] = Math.max(0, this.ammo - 1);
+    this.game.combat?.fireBullet?.({ from, dir, damage: w.damage, speed: 90, range: w.range, friendly: true, shooter: this });
+    this.game.vfx?.muzzleFlash?.(from, dir);
+    this.game.audio?.play('gunshot');
+    // camera kick (RECOIL_KICK × recoil, eased settle — see update)
+    this._recoilAmp = RECOIL_KICK * w.recoil;
+    this._recoilT = RECOIL_TIME;
+    // THE SHOT IS PROCEDURAL. The pack ships no plain 'shoot': its firing clip is Fanning —
+    // a HIP-LEVEL hammer-fan that starts from a hip stance, so playing it yanked the gun out
+    // of the aim and fired from the hip. So we never swap the pose: the aim overlay HOLDS and
+    // the shot is sold by a muzzle-flip on the gun + the camera kick (both already procedural,
+    // and they track wherever you're actually aiming, which a canned clip can't).
+    this._gunRecoilT = 0.28;
+    this._muzzleFlip = 0.55 * (w.recoil ?? 1);   // radians of barrel rise, eased out in update()
+    // VISIBLE SHOT. Removing the masked overlays also removed the fire motion — the gun fired
+    // but the man stood stock still, so the click read as "nothing happened". Play the pack's
+    // own fire clip FULL-BODY (never masked: masking a gun torso onto Synty legs is what
+    // twisted him). While ADS the aim holds instead — the canned fan would yank the gun off
+    // the reticle — and the camera kick + muzzle flip sell that shot.
+    // The full-body fire clip is a hip-fan stance — on the horse it wrenches the seated rider off
+    // the saddle to the side (Nick: "on shot it moves the player to the side of the horse"). Mounted,
+    // never play it: the aim pose holds and the muzzle flash sells the shot, same as ADS on foot.
+    if (!this.aiming && !this.riding.mounted) this.animator.play('gunFire', { once: true, fade: 0.05, onDone: () => {} });
+    this._combatT = Math.max(this._combatT, 4);
+  }
+
+  // DEAD EYE (game/deadeye.js) looses one queued tag: fired at the exact body point that was
+  // painted — no spread (you already aimed, in slow motion) and no rate limit (the volley
+  // owns its own ~0.12s cadence). Returns false on an empty chamber, which ends the volley.
+  deadEyeShot(point) {
+    const w = WEAPONS[this.weapon];
+    if (!w || !this.drawn || this.ammo <= 0) return false;
+    const from = this._muzzle(new THREE.Vector3());
+    const dir = new THREE.Vector3().subVectors(point, from);
+    if (dir.lengthSq() < 1e-8) return false;
+    this._shootAlong(w, dir.normalize(), from);
+    return true;
+  }
+
+  // One-shot masked overlay with restart (setOverlay alone won't reset an action that's
+  // already the overlay — repeat fire). Returns the action, or null when the clip is
+  // missing (loadClips tolerates absent gun FBXs).
+  _overlayOnce(name, { startFrac = 0, onDone = null } = {}) {
+    const a = this.animator.actions[name];
+    if (!a) return null;
+    a.timeScale = 1;                    // a previous reversed play must not leak in
+    a.enabled = true;
+    a.setEffectiveWeight(1);            // a finished one-shot's weight decays -> deficit -> T-POSE
+    // setOverlay does reset -> loop -> weight -> play in the right order and crossfades from
+    // the outgoing overlay of the SAME mask (weights sum to 1 — no T-pose fill). Calling
+    // reset() after it, as this used to, destroyed the fade interpolant and hard-snapped.
+    this.animator.setOverlay(name, { once: true, restart: true, fade: 0.08 });
+    a.paused = false;
+    if (startFrac > 0) a.time = a.getClip().duration * startFrac;
+    a._onceDone = onDone;
+    return a;
+  }
+
+  // Cancel any live aim/draw/reload WITHOUT firing — for interruptions (menu, mount,
+  // weapon swap, death). Whatever took over owns the pose; we just clear state.
+  cancelGun() {
+    this.aiming = false;
+    this._drawT = 0;
+    this._fireBuf = 0;          // a buffered click must not survive the interruption
+    this.cancelReload();
+    this.animator.setOverlay(null, { fade: BASE_FADE });   // bare drop = zero upper weight = T-pose
+  }
+
+  // Reload interrupt: old ammo stands. The reload's pending timer callback checks
+  // `this.reloading` before refilling, so clearing the flag is the whole cancel.
+  cancelReload() {
+    if (!this.reloading) return;
+    this.reloading = false;
+    this.animator.setOverlay(null, { fade: BASE_FADE });
+  }
+
+  // Holster with the real motion: the gun stays IN HAND while the clip plays and only drops
+  // to leather on its last frame (stowing it up-front made the holster look like a no-op —
+  // the weapon teleported to the hip and the animation had nothing left to show).
+  holsterGun() {
+    if (!this.drawn || this._holstering) return;
+    this.cancelGun();
+    const stow = () => { if (!this._holstering) return; this._holstering = false; this.drawn = false; this.placeWeapons(); };
+    this._holstering = true;
+    // FULL-BODY holster, same pattern as the reload: the locomotion block plays the take
+    // (standing or walking) while _holstering is up, and the gun drops to leather on a TIMER
+    // cut to the standing take's length. The old gunHolsterUpper overlay was dropped by the
+    // no-masks locomotion block on the very next frame, so its onDone never fired —
+    // _holstering stuck true forever and the gun could never be stowed (measured live).
+    const dur = this.animator.actions.gunHolster?.getClip().duration;
+    if (dur) this.game.after(dur / (PC.clipTiming.gunHolster?.speed ?? 1), stow);
+    else stow();   // no clip in dev → instant
+  }
+
+  jump(input) {
+    this.airborne = true;
+    // A RUNNING JUMP GOES HIGHER. You cannot convert forward speed into height with a standing
+    // take-off, but a man at a dead run can — he plants and drives up, and every platformer since
+    // the beginning has let him. So the take-off scales with how fast you are ACTUALLY travelling
+    // (not with which key is held: a sprint into a wall is not a run-up), from a standing 7.2 up to
+    // a third higher flat out. Height goes as v², so a third more speed is ~78% more air.
+    const moving = input.down('KeyW') || input.down('KeyA') || input.down('KeyS') || input.down('KeyD');
+    const top = (this.speed ?? 5) * 1.55;                       // flat-out sprint
+    const run = moving ? Math.min(1, (this._hspeed ?? 0) / top) : 0;
+    this.vy = 7.2 * (1 + 0.33 * run);
+    this.busy = true; // suppress locomotion overrides; cleared on landing
+    this.game.audio?.play('whoosh');
+    // start/speed/end come from CLIP_TIMING (tuned in /anim.html)
+    this.animator.play(moving ? 'jumpRun' : 'jumpIdle', { once: true, fade: 0.03 });
+    this.busy = false; // allow air control; anim continues as one-shot
+  }
+
+  // Soft-body separation so the gunslinger can't walk through townsfolk or outlaws.
+  separateFromPeople() {
+    let moved = false;
+    const push = (o) => {
+      if (!o || o === this || o.alive === false) return;
+      const dx = this.position.x - o.position.x, dz = this.position.z - o.position.z;
+      const d = Math.hypot(dx, dz);
+      const min = this.radius + (o.radius ?? 0.45);
+      if (d < min && d > 0.0001) {
+        const k = (min - d) / d;
+        this.position.x += dx * k;
+        this.position.z += dz * k;
+        moved = true;
+      }
+    };
+    for (const o of this.game.npcs ?? []) push(o);
+    for (const o of this.game.combat?.enemies ?? []) push(o);
+    for (const o of this.game.horses ?? []) push(o); // solid horse bodies — no walking through them on foot
+    // re-resolve against walls so a shove can't push us into a building
+    if (moved) {
+      const c = this.game.world.collide(this.position.x, this.position.z, this.radius, 0, this.position.y);
+      this.position.x = c.x; this.position.z = c.z;
+    }
+  }
+
+  dodge(input) {
+    if (this.stamina < 20) { this.game.audio?.play('whoosh'); return; } // too winded to roll
+    this.stamina -= 20;
+    this._stamPause = 1;
+    let anim = 'dodgeF';
+    if (input.down('KeyS')) anim = 'dodgeB';
+    else if (input.down('KeyA')) anim = 'dodgeL';
+    else if (input.down('KeyD')) anim = 'dodgeR';
+    this.busy = true;
+    this.dodgeT = 0.7;
+    this.game.audio?.play('whoosh');
+    this.animator.play(anim, { once: true, fade: 0.08, timeScale: 1.25, onDone: () => { this.busy = false; } });
+    // BURST OF MOVEMENT — WHERE YOU ARE RUNNING, not where the lens is pointed.
+    //
+    // This used to roll along `heading`, and heading is NOT your travel direction while the gun is
+    // out: aiming plants it at camYaw + PI so he can strafe with the revolver up (see the aim block
+    // above). So a man sprinting sideways with his gun drawn dived at the camera instead of the way
+    // he was going, which is exactly the moment a dive is supposed to save you.
+    //
+    // Take the direction he is ACTUALLY travelling — the same camera-relative wish vector the
+    // locomotion builds from the keys — and fall back to his facing only when he is standing still,
+    // where "the way he is going" has no meaning and the way he is looking is the honest answer.
+    let mx = (input.down('KeyD') ? 1 : 0) - (input.down('KeyA') ? 1 : 0);
+    let mz = (input.down('KeyS') ? 1 : 0) - (input.down('KeyW') ? 1 : 0);
+    let dx, dz;
+    if (mx || mz) {
+      const l = Math.hypot(mx, mz); mx /= l; mz /= l;
+      const s = Math.sin(this.camYaw), c = Math.cos(this.camYaw);
+      dx = mx * c - mz * s;
+      dz = -mx * s - mz * c;
+    } else {
+      dx = Math.sin(this.heading); dz = Math.cos(this.heading);
+    }
+    // burst over a fixed ~0.23s window, ticked from update() on GAME dt — frozen by pause,
+    // same distance at 60Hz or 144Hz
+    this._dodgeBurst = { dx, dz, left: 14 / 60 };
+  }
+
+  takeDamage(amount, fromPos, opts) {
+    if (!this.alive) return;               // already dead — don't re-fire onPlayerDeath
+    if (this.game.ui?.dialogueOpen) this.game.ui.closeDialogue?.(); // getting shot ends the conversation
+    if (this.dodgeT > 0.25) return;        // i-frames during roll
+    if (this._hitGraceT > 0) return;       // mercy window after a real hit — no chain-stagger lock
+    amount *= this.game.dmgTakenMul ?? 1;  // DIFFICULTY scales the hurt (Greenhorn 0.55× … Dead Man 1.7×)
+    this.game.shake(0.2 + amount * 0.008); // getting hit should be felt, not just seen
+    this._hitGraceT = 0.6;
+    super.takeDamage(amount, fromPos, opts);
+    this._combatT = Math.max(this._combatT, 4); // struck → stay in combat
+    this.game.noteDamageTaken?.();
+    this.game.ui?.flashDamage();
+    if (!this.alive) {
+      // dying mid-aim/mid-reload: cancel the gun so the corpse doesn't fall with the aim
+      // overlay blended over the death clip, and a cancelled reload can't refill on respawn
+      // (update() early-returns while dead, so the central 'stolen' check never runs)
+      this.cancelGun();
+      this.game.onPlayerDeath();
+    }
+  }
+}