sindicate 0.1.0 → 0.4.0

package/src/systems/riding.js

@@ -0,0 +1,580 @@
+// Riding: the player's mount/ride/dismount controller. Owns the rider-side rig work
+// proven out in src/tools/horsetest.js — a baked seated pose (world-space retarget
+// of the Malbers rider idle onto our Synty rig), 2-bone rein IK, the climb clips,
+// and the mount state machine + camera. The Horse entity provides the saddle + rein
+// bones; this drives the horse's movement while mounted.
+import * as THREE from 'three/webgpu';
+import { FBXLoader } from '../vendor/FBXLoader.js';
+import { clone as skeletonClone } from 'three/addons/utils/SkeletonUtils.js';
+import { loadModel, loadClips } from '../core/assets.js';
+import { clamp, angleLerp } from '../core/utils.js';
+
+const HA = '/assets/horse/anims';
+const RIDER_CLIPS = {
+  rideIdle: `${HA}/Rider_Idle_01.fbx`,
+  mountL: `${HA}/Rider_Mount_Dismount_Left.fbx`,
+  mountR: `${HA}/Rider_Mount_Dismount_Right.fbx`,
+};
+// Rider Biped → player-rig bone map, from Unity's Humanoid avatar (R_CG is the Hips). The
+// player is the Modular Fantasy Hero rig (Hips/Shoulder/Elbow/UpperLeg naming), NOT the old
+// peasant (Pelvis/UpperArm/Thigh). Foot→Ball, Toe→Toes (modular has no separate ankle bone).
+export const BIPED_TO_SYNTY = {
+  R_CG: 'Hips', R_Spine: 'Spine_01', R_Spine1: 'Spine_02', R_Spine2: 'Spine_03', R_Neck: 'Neck', R_Head: 'Head',
+  R_L_Clavicle: 'Clavicle_L', R_L_UpperArm: 'Shoulder_L', R_L_Forearm: 'Elbow_L', R_L_Hand: 'Hand_L',
+  R_R_Clavicle: 'Clavicle_R', R_R_UpperArm: 'Shoulder_R', R_R_Forearm: 'Elbow_R', R_R_Hand: 'Hand_R',
+  R_L_Thigh: 'UpperLeg_L', R_L_Calf: 'LowerLeg_L', R_L_Foot: 'Ball_L', R_L_Toe0: 'Toes_L',
+  R_R_Thigh: 'UpperLeg_R', R_R_Calf: 'LowerLeg_R', R_R_Foot: 'Ball_R', R_R_Toe0: 'Toes_R',
+};
+// Rider_Mount_Dismount is one 3.4s clip: climb-on (0–1.1s) · seated hold · climb-off (2.5–3.4s).
+const MOUNT_RANGE = [0, 1.1], DISMOUNT_RANGE = [2.5, 3.4];
+// Rider-root offset from the horse's back bone. Exported because a road traveller sits on the SAME
+// horse in the SAME rig, and two copies of this number is one copy too many (mountedTraveller.js).
+export const SADDLE = new THREE.Vector3(0, -0.48, 0.12);
+const REIN_OFF = new THREE.Vector3(0, 0, 0);
+const REIN_CLEAR = 0.35;    // metres the hands are held above the neck bone so they never punch into it
+// Mounted aim camera: slide over the shoulder so the rider isn't dead-centre (you must see past him
+// down the sights), and pull in for ADS. Idle keeps a small offset so the chase cam isn't bolt-behind.
+const MOUNTED_SHOULDER = 0.85;      // sideways framing offset while aiming (m)
+const MOUNTED_SHOULDER_IDLE = 0.2;  // small offset when not aiming
+const MOUNTED_ADS_DIST = 2.6;       // camera pulled in this close while aiming
+const AIM_YAW_ARC = 1.4;            // rad — while aiming the CAMERA itself can't twist past ±80° of forward
+const AIM_PITCH_ARC = 0.5;          // rad — and up/down is symmetric ±~28° (matches player.js aimDir cone)
+const YAW_SIGN = -2;        // body-turn correction during the climb
+const UP = new THREE.Vector3(0, 1, 0);
+
+function captureBind(root, only = null) {
+  root.updateMatrixWorld(true);
+  const m = new Map();
+  root.traverse((o) => { if (o.isBone && (!only || only.has(o))) { const q = new THREE.Quaternion(); o.getWorldQuaternion(q); m.set(o.name, q); } });
+  return m;
+}
+
+// First occurrence per bone name = exactly the bones THREE's AnimationMixer binds to (and the
+// visible meshes follow). The modular FBX repeats every bone across ~70 part skeletons, many at
+// a degenerate identity bind; capturing a later dupe collapses the retarget to identity (T-pose).
+export function realBonesOf(root) {
+  const byName = new Map();
+  root.traverse((o) => { if (o.isBone && !byName.has(o.name)) byName.set(o.name, o); });
+  return new Set(byName.values());
+}
+
+// Rider Biped → old PEASANT rig bone map (SK_Chr_* NPCs — Pelvis/UpperArm_L/Thigh_L/calf_l
+// naming, distinct from the modular hero above). Lets mounted road-traveller NPCs reuse the
+// same seated-pose retarget. See makeSeatedPose / mountedTraveller.js.
+export const BIPED_TO_PEASANT = {
+  R_CG: 'Pelvis', R_Spine: 'spine_01', R_Spine1: 'spine_02', R_Spine2: 'spine_03', R_Neck: 'neck_01', R_Head: 'head',
+  R_L_Clavicle: 'clavicle_l', R_L_UpperArm: 'UpperArm_L', R_L_Forearm: 'lowerarm_l', R_L_Hand: 'Hand_L',
+  R_R_Clavicle: 'clavicle_r', R_R_UpperArm: 'UpperArm_R', R_R_Forearm: 'lowerarm_r', R_R_Hand: 'Hand_R',
+  R_L_Thigh: 'Thigh_L', R_L_Calf: 'calf_l', R_L_Foot: 'Foot_L', R_L_Toe0: 'toes_l',
+  R_R_Thigh: 'Thigh_R', R_R_Calf: 'calf_r', R_R_Foot: 'Foot_R', R_R_Toe0: 'toes_r',
+};
+
+// World-space pose retarget of a single clip frame → { syntyBone: localQuaternion }.
+// boneMap picks the target rig (modular hero for the player, peasant for NPC riders).
+export function computeSeatedPose(riderRig, clip, peasantRoot, boneMap = BIPED_TO_SYNTY) {
+  const srcBind = captureBind(riderRig);
+  const savePos = peasantRoot.position.clone(), saveRot = peasantRoot.rotation.clone();
+  peasantRoot.position.set(0, 0, 0); peasantRoot.rotation.set(0, 0, 0); peasantRoot.updateMatrixWorld(true);
+  const real = realBonesOf(peasantRoot);
+  const tgtBind = captureBind(peasantRoot, real);
+  const mx = new THREE.AnimationMixer(riderRig);
+  mx.clipAction(clip).play(); mx.update(0); riderRig.updateMatrixWorld(true);
+  const srcPosed = new Map();
+  riderRig.traverse((o) => { if (o.isBone) { const q = new THREE.Quaternion(); o.getWorldQuaternion(q); srcPosed.set(o.name, q); } });
+  const tgtToSrc = {}; for (const s in boneMap) tgtToSrc[boneMap[s]] = s;
+  const pose = {};
+  const pw = new THREE.Quaternion(), want = new THREE.Quaternion(), loc = new THREE.Quaternion();
+  peasantRoot.traverse((o) => {
+    if (!o.isBone || !real.has(o)) return;
+    const sName = tgtToSrc[o.name];
+    if (!sName || !srcPosed.has(sName) || !srcBind.has(sName) || !tgtBind.has(o.name)) return;
+    const delta = srcBind.get(sName).clone().invert().multiply(tgtBind.get(o.name));
+    want.copy(srcPosed.get(sName)).multiply(delta);
+    o.parent.getWorldQuaternion(pw);
+    loc.copy(pw.invert()).multiply(want);
+    o.quaternion.copy(loc); o.updateWorldMatrix(false, false);
+    pose[o.name] = loc.clone();
+  });
+  peasantRoot.position.copy(savePos); peasantRoot.rotation.copy(saveRot); peasantRoot.updateMatrixWorld(true);
+  return pose;
+}
+
+// Reusable seated pose for a loaded character rig (NPC riders). Loads the Biped rider rig +
+// idle clip once, then bakes the seated pose against `targetRoot` using `boneMap`. Returns
+// { pose:{bone:localQuat}, pbone:{name:bone} } — apply pose to pbone every frame while seated.
+let _riderRigPromise = null;
+const _poseCache = new Map();   // clip url -> the loaded clip (the rig master is shared)
+
+// `clipUrl` picks WHICH sit. Rider_Idle_01 is a man ON A HORSE — legs astride, which is right
+// for the saddle and wrong for a bench. The Malbers set also ships a real chair sit (Actions/Sit,
+// which comes with a Chair.fbx beside it): knees forward, feet down. Both are authored on the
+// same Malbers biped, so the same retarget carries either one onto a Synty body.
+export async function makeSeatedPose(targetRoot, boneMap = BIPED_TO_PEASANT, clipUrl = null) {
+  // FRESH FBX load (not the shared loadModel master — the player's Riding setup poses that and
+  // never restores it, so captureBind on it would read a posed rig, not bind).
+  if (!_riderRigPromise) _riderRigPromise = Promise.all([new FBXLoader().loadAsync('/assets/horse/Rider.fbx'), loadClips({ rideIdle: RIDER_CLIPS.rideIdle })]);
+  const [riderMaster, rClips] = await _riderRigPromise;
+  // Pick the clip into a LOCAL — never write it back into rClips. That shared object is the
+  // cache: overwriting rideIdle with the chair sit meant the very next call that asked for the
+  // riding pose silently got the sit instead, so the coachman's "rein arms" were the sit's arms
+  // and the numbers moved around like a rumour.
+  let clip = rClips.rideIdle;
+  if (clipUrl) {
+    if (!_poseCache.has(clipUrl)) _poseCache.set(clipUrl, (await loadClips({ pose: clipUrl })).pose);
+    clip = _poseCache.get(clipUrl) ?? clip;
+  }
+  // clone a FRESH bind rig each call — computeSeatedPose poses the rig it's given and never
+  // restores it, so reusing one master would corrupt every call after the first (T-poses).
+  const riderRig = skeletonClone(riderMaster);
+  const pbone = {};
+  for (const b of realBonesOf(targetRoot)) pbone[b.name] = b;
+  const pose = computeSeatedPose(riderRig, clip, targetRoot, boneMap);
+  return { pose, pbone };
+}
+
+// THE COACHMAN: a man driving a box, which is two poses at once.
+// His LEGS want the chair sit (knees forward, feet on the footboard) and his ARMS want the
+// RIDING pose — because a driver holds the reins exactly the way a rider does: hands together,
+// forward, at his lap. Neither clip is right on its own: the chair sit leaves his arms hanging
+// like a man on a park bench, and the horse sit puts his legs astride a horse that isn't there.
+// So take the lower body from one and the arms from the other. They are both authored on the
+// same Malbers biped, so they compose without a fight.
+// A NOTE ON THE COACHMAN'S ARMS (unfinished, deliberately not bodged).
+// The driver currently wears the RIDER seated pose, which is right about his hands — together,
+// out in front, exactly where a driver holds the reins — and a little too high, because a
+// rider's hands are at SADDLE height.
+// Two things were tried and BOTH ARE WRONG, so don't repeat them:
+//   * The Malbers chair sit (Common/Human Anims/Actions/Sit) through computeSeatedPose comes out
+//     FOLDED — measured on the bench, the head ends up 0.06m BELOW the hips. That machinery was
+//     built for one specific clip on one specific rig; it does not generalise as-is.
+//   * Rotating Shoulder_L/R to drop the arms spins the whole body instead of the arm, so the
+//     bone the name resolves to is not the one that idea assumes.
+// The honest fix is a real driving pose (or a proper look at why computeSeatedPose folds a
+// second clip) — not another rotation stacked on top of a pose we already know is wrong.
+
+// Per-frame world-space retarget of a whole rider clip → { clip, rootYaw, fps }.
+function retargetClipWorldSpace(clip, riderRig, peasantRoot, fps = 30) {
+  const srcBind = captureBind(riderRig);
+  const savePos = peasantRoot.position.clone(), saveRot = peasantRoot.rotation.clone();
+  peasantRoot.position.set(0, 0, 0); peasantRoot.rotation.set(0, 0, 0); peasantRoot.updateMatrixWorld(true);
+  const real = realBonesOf(peasantRoot);
+  const tgtBind = captureBind(peasantRoot, real);
+  const riderBones = {}; riderRig.traverse((o) => { if (o.isBone) riderBones[o.name] = o; });
+  const tgtToSrc = {}; for (const s in BIPED_TO_SYNTY) tgtToSrc[BIPED_TO_SYNTY[s]] = s;
+  const targets = [];
+  peasantRoot.traverse((o) => { if (o.isBone && real.has(o) && tgtToSrc[o.name] && srcBind.has(tgtToSrc[o.name]) && tgtBind.has(o.name) && riderBones[tgtToSrc[o.name]]) targets.push(o); });
+  const delta = new Map();
+  for (const o of targets) delta.set(o, srcBind.get(tgtToSrc[o.name]).clone().invert().multiply(tgtBind.get(o.name)));
+  const mx = new THREE.AnimationMixer(riderRig); mx.clipAction(clip).play();
+  const dur = clip.duration, n = Math.max(2, Math.ceil(dur * fps) + 1);
+  const times = new Array(n), vals = {}; for (const o of targets) vals[o.name] = new Array(n * 4);
+  const rootBone = riderBones.R_CG || riderBones.R_Pelvis, rootYaw = new Array(n).fill(0);
+  const pw = new THREE.Quaternion(), want = new THREE.Quaternion(), loc = new THREE.Quaternion(), q = new THREE.Quaternion(), re = new THREE.Euler();
+  for (let i = 0; i < n; i++) {
+    const t = (i / (n - 1)) * dur; times[i] = t;
+    mx.setTime(t); riderRig.updateMatrixWorld(true);
+    if (rootBone) { rootBone.getWorldQuaternion(q); re.setFromQuaternion(q, 'YXZ'); rootYaw[i] = re.y; }
+    for (const o of targets) {
+      riderBones[tgtToSrc[o.name]].getWorldQuaternion(q);
+      want.copy(q).multiply(delta.get(o));
+      o.parent.getWorldQuaternion(pw);
+      loc.copy(pw.invert()).multiply(want);
+      o.quaternion.copy(loc); o.updateWorldMatrix(false, false);
+      loc.toArray(vals[o.name], i * 4);
+    }
+  }
+  peasantRoot.position.copy(savePos); peasantRoot.rotation.copy(saveRot); peasantRoot.updateMatrixWorld(true);
+  const tracks = targets.map((o) => new THREE.QuaternionKeyframeTrack(`${o.name}.quaternion`, times, vals[o.name]));
+  return { clip: new THREE.AnimationClip(clip.name + '_synty', dur, tracks), rootYaw, fps: (n - 1) / dur };
+}
+
+// --- analytic 2-bone IK so the hands reach the rein bones (IKReins.cs) ---
+const _a = new THREE.Vector3(), _b = new THREE.Vector3(), _c = new THREE.Vector3(), _t = new THREE.Vector3();
+const _dBA = new THREE.Vector3(), _dBC = new THREE.Vector3(), _axis = new THREE.Vector3();
+const _qd = new THREE.Quaternion(), _qp = new THREE.Quaternion(), _qpi = new THREE.Quaternion();
+const _qBone = new THREE.Quaternion(), _qBone2 = new THREE.Quaternion(), _qBase = new THREE.Quaternion(), _qSeatEul = new THREE.Euler();
+const SEAT_TILT = 0.25; // 0 = bolt upright, 1 = rigidly glued to the saddle bone (≈35° swing — too much)
+const C = (x) => Math.max(-1, Math.min(1, x));
+function rotateBoneWorld(bone, worldAxis, angle) {
+  if (!(Math.abs(angle) > 1e-5)) return;
+  _qd.setFromAxisAngle(worldAxis, angle);
+  bone.parent.getWorldQuaternion(_qp); _qpi.copy(_qp).invert();
+  bone.quaternion.premultiply(_qp).premultiply(_qd).premultiply(_qpi);
+  bone.updateWorldMatrix(false, true);
+}
+export function twoBoneIK(upper, lower, end, target) {
+  if (!upper || !lower || !end) return;
+  _t.copy(target);
+  upper.getWorldPosition(_a); lower.getWorldPosition(_b); end.getWorldPosition(_c);
+  const lab = _a.distanceTo(_b), lcb = _b.distanceTo(_c);
+  const lat = Math.max(1e-3, Math.min(_a.distanceTo(_t), lab + lcb - 1e-3));
+  _dBA.copy(_a).sub(_b).normalize(); _dBC.copy(_c).sub(_b).normalize();
+  const cur = Math.acos(C(_dBA.dot(_dBC)));
+  const des = Math.acos(C((lab * lab + lcb * lcb - lat * lat) / (2 * lab * lcb)));
+  _axis.copy(_dBC).cross(_dBA);
+  if (_axis.lengthSq() > 1e-8) { _axis.normalize(); rotateBoneWorld(lower, _axis, des - cur); }
+  end.getWorldPosition(_c);
+  _dBA.copy(_c).sub(_a).normalize(); _dBC.copy(_t).sub(_a).normalize();
+  _axis.copy(_dBA).cross(_dBC);
+  if (_axis.lengthSq() > 1e-8) { _axis.normalize(); rotateBoneWorld(upper, _axis, Math.acos(C(_dBA.dot(_dBC)))); }
+}
+
+const _sp = new THREE.Vector3(), _beside = new THREE.Vector3(), _tl = new THREE.Vector3(), _tr = new THREE.Vector3();
+const _head = new THREE.Vector3(), _camTarget = new THREE.Vector3(), _neck = new THREE.Vector3();
+
+export class Riding {
+  constructor(player) {
+    this.game = player.game;
+    this.player = player;
+    this.mode = 'foot';        // foot | mounting | mounted | dismounting
+    this.horse = null;
+    this.mountT = 0; this.speed = 0; this.jumpSpeed = 0; this.mountSide = -1;
+    this.pbone = {};
+    this.seatedPose = {};
+    this.mountActionL = null; this.mountActionR = null; this.mountAction = null;
+    this.mountYawL = null; this.mountYawR = null; this.mountYaw = null; this.mountFps = 30;
+    this._lookHold = 0; // grace period after free-look before the camera re-centers
+    this.ready = false;
+    this._stepT = 0; this._idleT = 3; this._sfxLoaded = false; // horse SFX cadence timers
+    this._reinLoc = null; // rein hand rest positions, captured in the horse's frame (static hands)
+  }
+
+  // Curated real recordings (Malbers Horse AnimSet Pro) — hoofsteps synced to gait,
+  // breathing/whinny at rest. Loaded once, lazily, on the first mount.
+  _loadSfx() {
+    if (this._sfxLoaded) return;
+    this._sfxLoaded = true;
+    const H = '/assets/audio/horse';
+    this.game.audio?.loadSamples({
+      step1: `${H}/step1.m4a`, step2: `${H}/step2.m4a`, step3: `${H}/step3.m4a`, step4: `${H}/step4.m4a`, step5: `${H}/step5.m4a`,
+      whinny1: `${H}/whinny1.m4a`, whinny2: `${H}/whinny2.m4a`, whinny3: `${H}/whinny3.m4a`,
+      neigh: `${H}/neigh.m4a`, neigh2: `${H}/neigh2.m4a`, neigh3: `${H}/neigh3.m4a`,
+      breath1: `${H}/breath1.m4a`, breath2: `${H}/breath2.m4a`, snort: `${H}/snort.m4a`, headshake: `${H}/headshake.m4a`,
+      whistle: `${H}/whistle.m4a`, whistleStop: `${H}/whistle_stop.m4a`,
+    });
+  }
+
+  // Per-frame horse audio while mounted. Hoofsteps fire on a speed-derived cadence
+  // (faster + louder at gallop); at rest, occasional breathing / snort / whinny.
+  _audio(dt, grounded) {
+    const a = this.game.audio; if (!a) return;
+    const spd = Math.abs(this.speed);
+    if (spd > 0.6 && grounded) {
+      this._idleT = 3 + Math.random() * 4;
+      this._stepT -= dt;
+      if (this._stepT <= 0) {
+        this._stepT = clamp(2.6 / Math.max(spd, 1.5), 0.2, 0.55) * (0.9 + Math.random() * 0.2);
+        a.sample('step' + (1 + Math.floor(Math.random() * 5)), { gain: clamp(0.22 + spd * 0.03, 0.25, 0.6), rate: 0.92 + Math.random() * 0.16 });
+      }
+    } else {
+      this._stepT = 0;
+      this._idleT -= dt;
+      if (this._idleT <= 0) {
+        this._idleT = 5 + Math.random() * 7;
+        // weighted idle vocalisations — mostly soft breathing, rarer whinny/neigh calls
+        const pick = (arr) => arr[Math.floor(Math.random() * arr.length)];
+        const r = Math.random();
+        if (r < 0.4) a.sample(pick(['breath1', 'breath2']), { gain: 0.5 });
+        else if (r < 0.6) a.sample('snort', { gain: 0.5 });
+        else if (r < 0.75) a.sample('headshake', { gain: 0.5 });
+        else if (r < 0.92) a.sample(pick(['whinny1', 'whinny2', 'whinny3']), { gain: 0.45 });
+        else a.sample(pick(['neigh', 'neigh2', 'neigh3']), { gain: 0.4 });
+      }
+    }
+  }
+
+  // One-time: load the Biped rider rig + clips, bake the seated pose + climb clips
+  // onto the player's rig and mixer. Call after the player model is loaded.
+  async setup() {
+    const player = this.player.model;
+    const [riderRig, rClips] = await Promise.all([
+      loadModel('/assets/horse/Rider.fbx'),
+      loadClips(RIDER_CLIPS),
+    ]);
+    for (const b of realBonesOf(player)) this.pbone[b.name] = b; // first-occurrence bones (modular dupes)
+    this.seatedPose = computeSeatedPose(riderRig, rClips.rideIdle, this.player.root);
+    const mixer = this.player.animator.mixer;
+    for (const [side, clip] of [['L', rClips.mountL], ['R', rClips.mountR]]) {
+      const r = retargetClipWorldSpace(clip, riderRig, this.player.root);
+      const a = mixer.clipAction(r.clip);
+      a.setLoop(THREE.LoopOnce, 1); a.clampWhenFinished = true;
+      this.mountFps = r.fps;
+      if (side === 'L') { this.mountActionL = a; this.mountYawL = r.rootYaw; }
+      else { this.mountActionR = a; this.mountYawR = r.rootYaw; }
+    }
+    this.ready = true;
+  }
+
+  get mounted() { return this.mode !== 'foot'; }
+
+  // +1 = horse's right, -1 = left, from where the player stands relative to the horse.
+  climbSide() {
+    const h = this.horse;
+    return ((this.player.position.x - h.position.x) * Math.cos(h.heading) - (this.player.position.z - h.position.z) * Math.sin(h.heading)) >= 0 ? 1 : -1;
+  }
+
+  besidePos(out) {
+    const h = this.horse;
+    out.set(h.position.x + this.mountSide * Math.cos(h.heading) * 1.4, 0, h.position.z - this.mountSide * Math.sin(h.heading) * 1.4);
+    // walkSurfaceAt, not groundAt: dismounting ON a deck (the station platform) must land on the
+    // PLANKS, not the dirt 0.9 m under them (Nick stepped off at Dustwater Station and stood under
+    // the platform). A one-shot placement — exactly the seating class that oracle exists for; the
+    // per-frame capsule takes over the moment he is on his feet.
+    out.y = this.game.world.walkSurfaceAt(out.x, out.z);
+  }
+
+  startClimb(side) {
+    this.mountSide = side;
+    this.mountAction = side > 0 ? this.mountActionR : this.mountActionL;
+    this.mountYaw = side > 0 ? this.mountYawR : this.mountYawL;
+    this.player.animator.stopAll();
+    this.player.busy = false;   // stopAll orphans a pending once-clip onDone — don't strand busy
+    this.mountAction.reset().play(); this.mountAction.paused = true;
+  }
+
+  yawAt(t) {
+    if (!this.mountYaw) return 0;
+    const i = clamp(Math.round(t * this.mountFps), 0, this.mountYaw.length - 1);
+    return this.mountYaw[i];
+  }
+
+  climbYaw(up) {
+    const ref = this.yawAt(up ? MOUNT_RANGE[1] : DISMOUNT_RANGE[0]);
+    return this.horse.heading + YAW_SIGN * (this.yawAt(this.mountAction.time) - ref);
+  }
+
+  applySeatedPose() {
+    for (const name in this.seatedPose) { const b = this.pbone[name]; if (b) b.quaternion.copy(this.seatedPose[name]); }
+    this.ikHandsToReins();
+  }
+
+  ikHandsToReins() {
+    const h = this.horse; if (!h.reinL || !h.reinR) return;
+    this.player.root.updateMatrixWorld(true);
+    // The hands DON'T MOVE (Nick). The rein bones bob with the head, so IK-ing to them every frame
+    // made the hands bounce into the neck. Capture the rein positions ONCE in the horse's own frame
+    // (position + heading, not the bobbing bones), lifted clear of the neck, then hold the hands
+    // exactly there every frame. They follow the horse's body/turning but never bob with the head.
+    if (!this._reinLoc) {
+      h.reinL.getWorldPosition(_tl).add(REIN_OFF);
+      h.reinR.getWorldPosition(_tr).add(REIN_OFF);
+      if (h.neckBone) {
+        const floorY = h.neckBone.getWorldPosition(_neck).y + REIN_CLEAR;
+        if (_tl.y < floorY) _tl.y = floorY;
+        if (_tr.y < floorY) _tr.y = floorY;
+      }
+      this._reinLoc = { L: this._toHorseLocal(_tl), R: this._toHorseLocal(_tr) };
+    }
+    this._fromHorseLocal(this._reinLoc.L, _tl);
+    this._fromHorseLocal(this._reinLoc.R, _tr);
+    twoBoneIK(this.pbone.Shoulder_L, this.pbone.Elbow_L, this.pbone.Hand_L, _tl); // modular arm chain
+    twoBoneIK(this.pbone.Shoulder_R, this.pbone.Elbow_R, this.pbone.Hand_R, _tr);
+  }
+
+  // Horse-frame (position + heading only, NOT the bobbing bones) ↔ world, for holding the hands
+  // steady relative to the horse's body.
+  _toHorseLocal(w) {
+    const h = this.horse, ch = Math.cos(h.heading), sh = Math.sin(h.heading);
+    const rx = w.x - h.position.x, rz = w.z - h.position.z;
+    return { r: rx * ch - rz * sh, f: rx * sh + rz * ch, y: w.y - h.position.y };
+  }
+
+  _fromHorseLocal(loc, out) {
+    const h = this.horse, ch = Math.cos(h.heading), sh = Math.sin(h.heading);
+    return out.set(h.position.x + loc.r * ch + loc.f * sh, h.position.y + loc.y, h.position.z - loc.r * sh + loc.f * ch);
+  }
+
+  saddlePos(out) { return this.horse.saddlePos(out, SADDLE); }
+
+  // Player must be near a mountable (riderless) horse.
+  mount(horse) {
+    if (!this.ready || this.mounted || horse.rider) return false;
+    this.horse = horse; horse.rider = this.player;
+    // the last horse he throws a leg over is HIS: it trails him afoot and rides the map/compass/minimap.
+    // The one he left behind goes feral again (back to grazing with the herd).
+    if (this.game.ownHorse && this.game.ownHorse !== horse) this.game.ownHorse.owner = null;
+    this.game.ownHorse = horse; horse.owner = this.player;
+    this.mode = 'mounting'; this.mountT = 0; this.speed = 0;
+    this._loadSfx(); this.game.audio?.sample('snort', { gain: 0.5 }); // silent the very first mount (samples still decoding)
+    this.startClimb(this.climbSide());
+    this.besidePos(this.player.position);
+    this.player.root.rotation.y = horse.heading;
+    return true;
+  }
+
+  dismount() {
+    if (this.mode !== 'mounted') return;
+    this.mode = 'dismounting'; this.mountT = 0; this.speed = 0;
+    this.horse.vy = 0;
+    this.startClimb(this.mountSide);
+  }
+
+  // Instantly drop to foot WITHOUT the climb-off animation and WITHOUT moving the player
+  // (used on Load Game — the loaded position must stick, not be overwritten by the saddle).
+  hardReset() {
+    const horse = this.horse;
+    if (horse) { horse.rider = null; horse.speed = 0; }
+    this.mountAction?.stop?.();   // a Load mid-climb left the clamped mount clip blended in (audit m1)
+    this._seatQuat = null; this._reinLoc = null;
+    this.horse = null; this.mode = 'foot';
+    this.player.vy = 0; this.player._capGrounded = false;
+    this.player.animator?.play('idle', { fade: 0.1 });
+  }
+
+  // Called from player.update each frame while mounted/transitioning. Drives the
+  // horse + seated pose + camera; the player's mixer was already advanced upstream.
+  update(dt, input, camera) {
+    const player = this.player, horse = this.horse;
+    if (!horse) { this.mode = 'foot'; return; } // horse gone (unlinked/removed) — drop to foot, never crash
+    const inMenu = this.game.ui?.menuOpen || this.game.ui?.dialogueOpen || this.game.ui?.worldMap?.visible || this.game.ui?.cinematic;
+
+    if (this.mode === 'mounting' || this.mode === 'dismounting') {
+      const up = this.mode === 'mounting';
+      const [t0, t1] = up ? MOUNT_RANGE : DISMOUNT_RANGE;
+      this.mountT += dt;
+      const e = Math.min(1, this.mountT / (t1 - t0));
+      this.mountAction.time = t0 + e * (t1 - t0); this.mountAction.paused = true;
+      this.saddlePos(_sp); this.besidePos(_beside);
+      player.root.position.lerpVectors(_beside, _sp, up ? e : 1 - e);
+      player.root.rotation.set(0, this.climbYaw(up), 0); // full reset — clears any saddle tilt from mounted mode
+      this.ikHandsToReins();
+      if (e >= 1) {
+        this.mountAction.stop();
+        if (up) this.mode = 'mounted';
+        else this._endDismount();
+      }
+    } else { // mounted
+      let fwd = 0, turn = 0, sprint = false, jump = false;
+      if (!inMenu) {
+        const st = input.moveStick;
+        if (st && (st.x || st.y)) {
+          // ANALOG REIN. Left/right is the turn, and it curves like the aim stick: a squared
+          // response, so a gentle push is a gentle lean and only the far edge is a hard turn
+          // (Nick: "wider the stick the heavier the turn", and it was snapping to a full turn on
+          // any nudge). Forward from −y.
+          fwd = -st.y;
+          turn = -st.x * Math.abs(st.x);      // sign(x)·x² — gentle near centre, heavy at the edge
+        } else {
+          if (input.down('KeyW')) fwd += 1;
+          if (input.down('KeyS')) fwd -= 1;
+          if (input.down('KeyA')) turn += 1;
+          if (input.down('KeyD')) turn -= 1;
+        }
+        sprint = input.down('ShiftLeft');
+        jump = input.hit('Space');
+      }
+      const grounded = !horse.airborne;
+      // A real leap, not a hop: ~2 m of height (impulse 9 vs gravity 20) and forward drive so it
+      // carries over ground, not straight up (Nick: "it's not like a leaping jump"). From a canter
+      // the leap keeps the canter's speed; from a standstill it still springs forward at 5 m/s.
+      if (jump && grounded) { horse.jump(9); this.jumpSpeed = Math.max(Math.abs(this.speed), 5); }
+      if (horse.airborne) {
+        this.speed = this.jumpSpeed; // leap carries momentum
+      } else {
+        // Reverse needs a near-FULL pull-back (fwd < −0.5), not a nudge — a slight back on the
+        // stick just stops (Nick: "slightly back and it reverses; should need full on backwards").
+        // THE STICK'S THROW IS THE GAIT (Nick: "the less we move it the slower — slower = walk not
+        // jog"): a gentle push walks, half throw trots, the far edge canters, sprint gallops. BANDS,
+        // not a linear scale — a man holds a steady trot with a steady thumb, and each band's speed
+        // sits mid-clip so the legs match the ground. Keyboard W is a full push and rides as before.
+        const mag = Math.min(1, Math.abs(fwd));
+        const cruise = mag < 0.35 ? 1.8 : mag < 0.75 ? 3.4 : 9;   // walk · trot · canter (must beat on-foot sprint 8.06)
+        const target = fwd > 0.05 ? (sprint ? 13 : cruise) : fwd < -0.5 ? -1.6 : 0;
+        const decel = Math.abs(target) < Math.abs(this.speed);
+        this.speed += (target - this.speed) * Math.min(1, dt * (decel ? 10 : 3));
+        if (target === 0 && Math.abs(this.speed) < 0.4) this.speed = 0;
+      }
+      horse.driveMove(this.speed, turn * 1.4, dt);   // was 1.8 — a horse leans into a turn, it doesn't spin
+      // Advance the horse's gait NOW so the seat reads the CURRENT skeleton pose, not
+      // last frame's — otherwise the saddle bone's fore/aft surge + tilt reach the rider
+      // a frame late and read as "the saddle moves but we don't". horse.update skips its
+      // own tick this frame (see _mixerTicked there).
+      horse.mixer.update(dt); horse._mixerTicked = true;
+      this._audio(dt, grounded);
+      this.saddlePos(player.root.position);
+      // Glue the rider to the saddle bone's FULL orientation (pitch/roll + heading yaw),
+      // so we tilt and surge with the saddle instead of sitting bolt upright. The fixed
+      // local seat offset is captured once on the first mounted frame.
+      const bone = horse.saddleBone;
+      if (bone) {
+        bone.getWorldQuaternion(_qBone);
+        if (!this._seatQuat) {
+          this._seatQuat = new THREE.Quaternion();
+          _qBone2.setFromEuler(_qSeatEul.set(0, horse.heading, 0));
+          this._seatQuat.copy(_qBone).invert().multiply(_qBone2);
+        }
+        _qBone2.copy(_qBone).multiply(this._seatQuat);               // full saddle-bone orientation
+        _qBase.setFromEuler(_qSeatEul.set(0, horse.heading, 0));     // upright, facing heading
+        player.root.quaternion.copy(_qBase).slerp(_qBone2, SEAT_TILT); // follow a FRACTION → subtle lean, not thrashing
+      } else {
+        player.root.rotation.y = horse.heading;
+      }
+      player.heading = horse.heading; // track the mount's facing so the minimap arrow + compass rotate while riding
+      this.applySeatedPose();
+    }
+
+    if (this.horse) this._mountCamera(dt, input, camera, inMenu); // _endDismount() above can null the horse this frame
+  }
+
+  _endDismount() {
+    const horse = this.horse;
+    this.besidePos(this.player.root.position);
+    this.player.heading = horse.heading; this.player.root.rotation.set(0, horse.heading, 0); // clear saddle tilt
+    this._seatQuat = null; this._reinLoc = null; // recapture seat + rein hands on the next mount
+    this.game.audio?.sample('snort', { gain: 0.45 });
+    horse.rider = null; horse.speed = 0;
+    this.horse = null; this.mode = 'foot';
+    this.player.vy = 0; this.player._capGrounded = false;
+    this.player.animator.play('idle', { fade: 0.1 });
+  }
+
+  // RDR2-style chase cam: trails behind the horse's heading and auto-recenters when
+  // you're not free-looking; free-look (mouse/stick) overrides and holds briefly
+  // before easing back. Pulls back a touch at speed. Reuses the player's
+  // camYaw/Pitch/Dist so the on-foot↔mounted transition is seamless.
+  _mountCamera(dt, input, camera, inMenu) {
+    const p = this.player, horse = this.horse;
+    const aiming = p.aiming || p._gunRecoilT > 0;
+    let looking = false;
+    if (!inMenu) {
+      const sens = p.camSensitivity, inv = p.invertY ? -1 : 1;
+      p.camYaw -= input.mouse.dx * 0.0028 * sens + input.stickLook.x * p.padCamSpeed * sens * dt;
+      // Pitch: normally mostly-down (chase cam); while aiming it's the symmetric aim cone so you can
+      // aim UP as well as down (Nick: "aims down but not up").
+      const pMin = aiming ? -AIM_PITCH_ARC : -0.2, pMax = aiming ? AIM_PITCH_ARC : 1.1;
+      p.camPitch = clamp(p.camPitch + input.mouse.dy * 0.0022 * sens * inv + input.stickLook.y * p.padCamSpeed * sens * inv * dt, pMin, pMax);
+      // While aiming the CAMERA itself is held inside the ±40° arc — you can't twist further than the
+      // gun can point (Nick: "lets us twist the aiming camera more than 40° from front").
+      if (aiming) {
+        const fwd = horse.heading + Math.PI;
+        p.camYaw = fwd + clamp(Math.atan2(Math.sin(p.camYaw - fwd), Math.cos(p.camYaw - fwd)), -AIM_YAW_ARC, AIM_YAW_ARC);
+      }
+      // no wheel zoom — camDist stays at the fixed on-foot follow distance (Nick: "get rid of all these zooms")
+      looking = Math.abs(input.mouse.dx) > 0.01 || Math.abs(input.mouse.dy) > 0.01 || Math.abs(input.stickLook.x) > 0.05 || Math.abs(input.stickLook.y) > 0.05;
+    }
+    // auto-follow: ease the camera behind the horse's heading once free-look settles — but NOT while
+    // aiming, when the camera is the aim and must stay where you point it.
+    if (looking || aiming) this._lookHold = 1.1;
+    else if (this._lookHold > 0) this._lookHold -= dt;
+    if (this._lookHold <= 0) p.camYaw = angleLerp(p.camYaw, horse.heading + Math.PI, Math.min(1, dt * 3));
+
+    // Over-the-shoulder: slide the framing to the side so the rider isn't dead-centre (you have to see
+    // past him down the sights), harder when aiming; and pull the camera in for ADS. Both eased.
+    const shTarget = aiming ? MOUNTED_SHOULDER : MOUNTED_SHOULDER_IDLE;
+    this._shNow = this._shNow == null ? shTarget : this._shNow + (shTarget - this._shNow) * Math.min(1, dt * 8);
+    const wide = p.camDist + Math.min(Math.abs(horse.speed) * 0.12, 1.6); // widen at gallop
+    const distTarget = aiming ? MOUNTED_ADS_DIST : wide;
+    this._camDistNow = this._camDistNow == null ? distTarget : this._camDistNow + (distTarget - this._camDistNow) * Math.min(1, dt * 6);
+    const dist = this._camDistNow;
+    this.saddlePos(_head); _head.y += 1.1; // rider torso/head height above the saddle
+    _head.x += Math.cos(p.camYaw) * this._shNow;   // shoulder offset — to the right of the view line
+    _head.z -= Math.sin(p.camYaw) * this._shNow;
+    const cx = _head.x + Math.sin(p.camYaw) * Math.cos(p.camPitch) * dist;
+    const cz = _head.z + Math.cos(p.camYaw) * Math.cos(p.camPitch) * dist;
+    let cy = _head.y + Math.sin(p.camPitch) * dist;
+    const groundCam = this.game.world.groundAt(cx, cz) + 0.4;
+    if (cy < groundCam) cy = groundCam;
+    camera.position.lerp(_camTarget.set(cx, cy, cz), Math.min(1, dt * 10));
+    camera.lookAt(_head);
+  }
+}