sindicate 0.1.0 → 0.4.0

package/src/systems/mountedTraveller.js

@@ -0,0 +1,518 @@
+// A HORSEMAN COMING THE OTHER WAY ON AN EMPTY ROAD.
+//
+// It is the single most western image there is, and until now this county had four thousand metres of
+// road and not one man on a horse using them. So: a Horse path-following one of terrainData's ROADS,
+// with a man in the saddle — trotting out to the ranch by day, home by dark, and coming past you on
+// the fort road at the exact moment you had decided the desert was empty.
+//
+// ── THE MAN IN THE SADDLE IS AN NPC, AND THAT IS THE WHOLE TRICK ────────────────────────────────
+// He is in game.npcs. So combat.js's bullet loop finds him (shoot him off his horse), crime.js counts
+// him as a witness and calls his killing a MURDER, loot.js drops his purse, alarmTown scatters him,
+// and — this is the one that matters — coach.js's _blocked() look-ahead sees him standing in the road
+// and the stagecoach BRAKES for him, without coach.js knowing that horses exist. Not one of those
+// files needed an edit. fable's version kept its riders in a private list and paid for it in five
+// systems that could not see them.
+//
+// The horse goes in game.horses, which buys the same trick again: the whisker steering already
+// considers horses (entity.js _probeSteer), the player is already pushed out of them
+// (player.separateFromPeople), and they already trample the grass.
+//
+// ── WHAT IS REUSED, VERBATIM ───────────────────────────────────────────────────────────────────
+//   horse.js driveMove     terrain-follow + gait + bob. A traveller's horse moves the way yours does.
+//   riding.js SADDLE       the rider-root offset, dialled in on the player's own mount.
+//   riding.js makeSeatedPose(root, BIPED_TO_SYNTY) + twoBoneIK — the seated pose and the rein IK, the
+//                          same two calls the player's Riding controller makes. Baked at BOOT (a retarget
+//                          mid-gunfight is a stall) and cached per source FBX — see _poses.
+//   traveller.js LANE, DAWN/DUSK, laneTarget, railShut — a horseman keeps to the same side of the same
+//                          road in the same daylight as a man on foot. One definition, two riders.
+//
+// PERF CONTRACT (main.js:118): horse and rider are built ONCE on the loading screen and never leave
+// the scene. Nothing here spawns.
+import * as THREE from 'three/webgpu';
+import { Horse } from './horse.js';
+import { Character } from './entity.js';
+import { NPC } from './npc.js';
+import { makeSeatedPose, twoBoneIK, realBonesOf, BIPED_TO_SYNTY, SADDLE } from './riding.js';
+
+import { LANE, DAWN, DUSK, BVH_R, roadCull, laneTarget, railShut } from './traveller.js';
+import { steerCarrot, mountedTurn, nearestEndpoint } from './pathFollow.js';
+// routes + venue hours are GAME data: setMountedContent({ routes, venueOpen })
+let MC = { routes: [], venueOpen: () => true };
+export function setMountedContent(c) { MC = { ...MC, ...c }; }
+import { dist2D } from '../core/utils.js';
+
+// A WORKING TROT (3.4 m/s). horse.js's gaitFor puts anything from 0.4 to 4 m/s on the trot clip, so
+// this is the gait as well as the speed. It is also the right speed against the traffic: the stage
+// cruises at a canter (6.5, coach.js CRUISE), so she comes up behind a rider at 3.1 m/s and passes
+// him — which is what a stage did, and why the man on the box has a whip.
+const TROT = 3.4;
+const BOLT = 9.0;          // …and what a frightened horse does instead. gaitFor: a canter.
+const BOLT_SECS = 4.5;     // how long it runs before it remembers it has somewhere to be
+const TURN_RATE = 2.4;     // rad/s toward the steered waypoint line — a horse turns, it does not pivot
+const HORSE_RMIN = 3.5;    // minimum turn radius (m): the turn is capped at wmax = speed / Rmin so a
+                           // boxed-in horse curves out and round a fence instead of pivoting into it
+const ARRIVE = 3.2;        // a horse is longer than a man: give the waypoint a wider gate
+const UP = new THREE.Vector3(0, 1, 0);
+const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+const _aim = { x: 0, z: 0 };   // scratch: the point steerCarrot hands back to steer at
+// THE SALOON CALL — where a passing rider ties up for a drink. Two rail spots on the street's east
+// side, clear of the town's three hitched horses (z −16/−4/10); riders alternate between them.
+const SALOON_HITCH = [{ x: 6.5, z: 2 }, { x: 6.5, z: 18 }];
+let _hitchNext = 0;
+
+// THE SEATED POSE IS CACHED PER SOURCE FBX, NOT PER RIDER AND NOT ONCE FOR EVERYONE.
+//
+// A pose is {boneName → localQuaternion}, and it is only transferable between two bodies that share a
+// BIND. The cast comes out of two different packs (data/characters.js: WesternTownChars.fbx and
+// WesternCharacters.fbx), and this game has been bitten before by assuming two Synty rigs agree —
+// see the retarget notes in clips.js and the contorted-NPC trap. A skeleton is a property of the FBX,
+// so that is what the cache is keyed on: two bakes for six riders, both on the loading screen, and a
+// pack that turns out to bind differently sits correctly anyway instead of subtly wrong.
+const _poses = new Map();   // model src → {bone: localQuat}
+const _tl = new THREE.Vector3(), _tr = new THREE.Vector3();
+const _tgt = new THREE.Vector3(), _dir = new THREE.Vector3(), _prevT = new THREE.Vector3();
+
+function angleDelta(a, b) { let d = a - b; while (d > Math.PI) d -= 2 * Math.PI; while (d < -Math.PI) d += 2 * Math.PI; return d; }
+
+// THE MAN. An ordinary NPC in every respect the rest of the game can see — but while he is up there
+// his legs are not his own: the MountedTraveller writes his position and his pose every frame, so
+// every AI branch NPC would otherwise take (wander the street, run away on foot, strike up a chat)
+// has to be switched off, and switched back ON the moment he hits the dirt.
+class Rider extends NPC {
+  get cullDist() { return roadCull(this.game); }
+  get aiRange() { return this.cullDist; }
+
+  update(dt) {
+    // SEATED: Character-level only. The health, the stagger clock, the distance cull, the frustum cull
+    // and the animator — everything a body needs — and NOT the AI, which would try to walk him home.
+    if (this.seated) { Character.prototype.update.call(this, dt); return; }
+    // INSIDE THE SALOON (the saloon-call, below): past the batwings he is fiction — invisible,
+    // untickable, waiting out his drink on the traveller's clock.
+    if (this._inSaloon) return;
+    // WALKING A GOAL (saloon-call): dismounted, crossing the street to the batwings or back to his
+    // horse. Whisker-steered, then his errand's callback fires and the traveller moves him on.
+    if (this._goal) {
+      const g = this._goal;
+      const dx = g.x - this.position.x, dz = g.z - this.position.z, L = Math.hypot(dx, dz);
+      if (L < 1.4) { const then = g.then; this._goal = null; this.play('idle'); then?.(); }
+      else {
+        const sd = this.walkDir(_dir.set(dx / L, 0, dz / L), dt);
+        this.heading = Math.atan2(sd.x, sd.z);
+        this.root.rotation.y = this.heading;
+        this.move(sd, 1.8, dt);
+        this.play('walk');
+      }
+      return;
+    }
+    super.update(dt);          // in the dirt: he is a townsman again, and NPC does the rest
+  }
+
+  // A MAN IN THE SADDLE DOES NOT RUN AWAY. HIS HORSE DOES.
+  // scare() is what a gunshot, a body in the street or a shut level crossing does to a townsman
+  // (npc.js alarmTown → scare → flee on foot). A seated man cannot flee on foot, and a rider who
+  // dismounts to jog away from a bang is a puppet. So the fright is passed to the animal under him,
+  // which is where a fright belongs: it BOLTS (see MountedTraveller.spook).
+  scare(x, z, secs = 2.5, force = false) {
+    if (!this.alive) return;
+    if (this.seated) { this.mount?.spook(x, z, secs); return; }
+    super.scare(x, z, secs, force);
+  }
+
+  // SHOT OFF THE HORSE. He goes into the dirt FIRST and dies there — because NPC.die() reads his
+  // position for the crime report and for the purse, and a purse that spills at saddle height hangs in
+  // the air a metre and a half over the road.
+  die() {
+    if (!this.alive) return;
+    this.mount?.unseat();
+    super.die();
+  }
+}
+
+export class MountedTraveller {
+  constructor(game, def) {
+    this.game = game;
+    this.def = def;
+    const rt = MC.routes[def.route];
+    if (!rt) throw new Error(`[rider] ${def.id}: no such route '${def.route}'`);
+    this.road = rt.pts;
+    this.built = rt.built;                      // where the road runs through a town: keep the BVH on
+    this.routeName = def.route;
+    this.dir = def.dir ?? 1;
+    const last = this.road.length - 1;
+    this._start = Math.max(0, Math.min(last, Math.round((def.start ?? 0) * last)));
+    this._wp = Math.max(0, Math.min(last, this._start + this.dir));
+    this.pauseT = 0;
+    this.bolt = 0;
+    this._home = false;
+    this._day = true;    // the sky starts at 10:00 (world/sky.js). A bolt can call _advance before the
+                         // daylight branch has ever run, and an undefined `_day` there would send a
+                         // frightened horse "home" at ten in the morning.
+    this.spot = { out: Math.random() * 3, along: (Math.random() - 0.5) * 16 };   // a horse wants more room
+  }
+
+  async load(clips) {
+    const g = this.game;
+    const p = this.road[this._start];
+    const horse = new Horse(g, { x: p.x, z: p.z, heading: 0, saddle: true, coat: this.def.coat });
+    await horse._buildModel();                      // the ctor already put it on the ground at (x,z)
+    horse.heading = Math.atan2(this.road[this._wp].x - p.x, this.road[this._wp].z - p.z);
+    this.horse = horse;
+
+    const rider = new Rider(g, { ...this.def, roam: { x: p.x, z: p.z, r: 0 } }, clips);
+    await rider.load();
+    // THE DEFERRED FOOT-GROUNDING MUST NOT RUN. Character.load() has already measured his feetDrop from
+    // the BIND pose, which is the right answer; the re-measure at t+0.5 s would measure him in the SEATED
+    // pose, find his boots up in the stirrups, and lift the whole man half a metre off his own horse.
+    // (riding.js never hits this because the player is not re-measured while he is mounted.)
+    rider._grounded = true;
+    rider.seated = true;
+    rider.mount = this;
+    this.rider = rider;
+
+    // The seated pose is a RETARGET — a retarget mid-gunfight is a stall, so it is baked HERE, on the
+    // loading screen, and never again. Cached per source FBX (see _poses).
+    const src = rider.modelUrl;
+    if (!_poses.has(src)) _poses.set(src, (await makeSeatedPose(rider.root, BIPED_TO_SYNTY)).pose);
+    this.pose = _poses.get(src);
+    this.pbone = {};
+    for (const b of realBonesOf(rider.root)) this.pbone[b.name] = b;
+
+    // EVERYTHING IS BUILT — only now does the world find out about them. Publish the horse before it is
+    // whole and a load that throws halfway leaves game.horses holding an animal marked `rider`: it can
+    // never graze, can never be mounted, and nothing will ever tick it, because the thing that was
+    // going to is the thing that threw.
+    horse.rider = this;                             // ridden → the horse skips its own graze/wander AI
+    g.scene.add(horse.root);
+    g.scene.add(rider.root);
+    g.horses.push(horse);                           // …now the steering, the shove and the trample see it
+    g.npcs.push(rider);                             // …and the bullet, the law, the alarm and the stage
+    this._seat();
+    return this;
+  }
+
+  // WHERE HE IS. Always — on screen or off, drawn or not. His `position` is what combat.js aims a
+  // bullet at, what crime.js measures a witness by, and what the stagecoach's look-ahead brakes for,
+  // and a rider whose body is one place while his position is another is a rider you cannot shoot.
+  _place() {
+    const h = this.horse, r = this.rider;
+    h.saddlePos(r.root.position, SADDLE);      // getWorldPosition walks the horse's root: no stale bone
+    r.root.rotation.y = h.heading;
+    r.heading = h.heading;                     // the minimap arrow and faceToward read this
+  }
+
+  // …and how he SITS. The baked seated pose, then his hands two-bone-IK'd onto the horse's rein bones
+  // — exactly what riding.js does for the player, on the same horse. Only worth doing when he is
+  // actually being drawn: it is four solves and a matrix refresh, and nobody can see a hidden man's grip.
+  _pose() {
+    const h = this.horse, r = this.rider;
+    for (const n in this.pose) { const b = this.pbone[n]; if (b) b.quaternion.copy(this.pose[n]); }
+    if (!h.reinL || !h.reinR) return;
+    r.root.updateMatrixWorld(true);                          // pose applied → refresh before the arm IK
+    h.reinL.getWorldPosition(_tl);
+    h.reinR.getWorldPosition(_tr);
+    twoBoneIK(this.pbone.Shoulder_L, this.pbone.Elbow_L, this.pbone.Hand_L, _tl);
+    twoBoneIK(this.pbone.Shoulder_R, this.pbone.Elbow_R, this.pbone.Hand_R, _tr);
+  }
+
+  _seat() { this._place(); this._pose(); }
+
+  // Something frightened the horse — a shot, a body in the street, a train on the crossing. It runs,
+  // AWAY, at a canter, for a few seconds; if the fright is ahead of it on the road it turns round
+  // first. Then it remembers it has somewhere to be. (This is the mounted answer to npc.js's flee,
+  // and it is the reason a rider is not just a townsman with an expensive hat.)
+  spook(x, z, secs = 2.5) {
+    if (!this.rider.alive) return;
+    const first = this.bolt <= 0;
+    this.bolt = Math.max(this.bolt, Math.min(secs, BOLT_SECS));
+    this.pauseT = 0;
+    this._home = false;
+    // WHICH WAY TO RUN IS DECIDED ONCE, AT THE BANG. A gunfight is a dozen alarmTown calls in four
+    // seconds and a man standing on a level crossing is frightened off it every frame he is still on
+    // it — and a horse that re-chooses its direction on every one of them turns round, turns round
+    // again, and dies exactly where it was standing.
+    if (!first) return;
+    const h = this.horse;
+    const away = (h.position.x - x) * Math.sin(h.heading) + (h.position.z - z) * Math.cos(h.heading);
+    if (away < 0) this._turnBack();     // the fright is in FRONT of him — he does not gallop into it
+  }
+
+  // A rider who is shot goes into the dirt beside his horse, and the horse — reins slack, a shot going
+  // off behind its ears — bolts. Same beat as the coach's team (coach.js _boltTeam), same reason.
+  unseat() {
+    const r = this.rider, h = this.horse;
+    if (!r.seated) return;
+    r.seated = false;
+    // Down beside the horse, on the ground, with his own feet back under him: his model still carries
+    // the feetDrop Character.load() measured from the bind, so the root going to the terrain puts his
+    // boots on it. The death clip then plays on an ordinary standing body.
+    const bx = h.position.x + Math.cos(h.heading) * 1.3;
+    const bz = h.position.z - Math.sin(h.heading) * 1.3;
+    r.setPosition(bx, this.game.world.groundAt(bx, bz), bz);
+    r.root.rotation.set(0, h.heading, 0);
+    r._visualY = undefined;                       // let the descent smoother re-latch where he landed
+    // The bones are LEFT where the sit left them, and are not reset to identity: _seat() stops running
+    // the moment he is unseated, and the death clip his Animator is about to play (VILLAGER_CLIPS
+    // carries a full-body one) writes every bone in it. Identity is not the bind pose — snapping the
+    // skeleton to it would break every bone the clip does not happen to name.
+    this.bolt = BOLT_SECS;
+  }
+
+  // PULLED FROM THE SADDLE. The player walked up and stole the horse (main.js E-scan). The rider
+  // lands on his feet beside it and bolts on foot; horse.rider goes null, so update() returns early
+  // from here on and the horse is free for riding.mount() to take. Returns the horse to mount.
+  dismountForTheft(threatX, threatZ) {
+    if (!this.rider.seated) return null;
+    this.unseat();                 // rider to the dirt, seated = false — now an ordinary foot NPC
+    this.horse.rider = null;       // decouple: the loop below stops touching horse and rider
+    this.rider.scare?.(threatX, threatZ, 6, true);   // on his feet now, scare = flee on foot
+    return this.horse;
+  }
+
+  update(dt) {
+    const g = this.game, h = this.horse, r = this.rider;
+
+    // ONCE THE TRAVELLER NO LONGER OWNS THE HORSE, IT LETS GO ENTIRELY. horse.rider goes null when the
+    // rider is shot and the animal runs itself out — OR it becomes the PLAYER when he steals the horse
+    // (dismountForTheft). Either way it is not `this` any more, and the moment it isn't we stop: keep
+    // driving it and the ride controller fights us over the gait (legs freeze) while _place/_pose drag
+    // the thrown rider back onto the saddle. horse.js's own AI or the player's Riding ticks it now.
+    if (h.rider !== this) return;
+
+    // A DEAD MAN'S HORSE. It bolts — and it does so wherever it is, whether or not you are watching,
+    // because a horse left with `rider` set is a horse that never grazes again and cannot be mounted.
+    // Once it has run itself out, main.js's frustum net and horse.js's ambient AI take it from there,
+    // and it grazes wherever it fetched up. A riderless horse standing on an empty road is the most
+    // eloquent thing a road can have.
+    if (!r.alive) {
+      if (this.bolt > 0) {
+        this.bolt -= dt;
+        this._drive(h, BOLT, 0, dt, true);
+        h.mixer?.update(dt);                  // 4½ seconds of one horse: not worth a cull test
+        if (this.bolt <= 0) { h.rider = null; h.speed = 0; h.anchor = { x: h.position.x, z: h.position.z }; }
+      }
+      h._mixerTicked = true;                  // (once released, main.js's net takes its visibility back)
+      return;
+    }
+
+    // ── THE CULL, AND IT IS THE WALKERS' CULL, NOT A SECOND ONE ────────────────────────────────
+    // PAST cullDist he FREEZES, exactly as npc.js freezes a townsman past aiRange: hidden, no AI, no
+    // terrain sample, one dist2D a frame. That is what makes twenty-five extra bodies affordable.
+    // INSIDE it he keeps riding EVEN WHEN OFF SCREEN — the frustum only stops him being DRAWN and
+    // SKINNED. Freeze him on the frustum instead and a rider you glance away from is a rider standing
+    // in exactly the same place when you glance back, which is entity.js's stated "no pop" contract
+    // broken. So the two tests do different jobs, and this is the line that keeps them apart.
+    const pd = g.player ? dist2D(h.position.x, h.position.z, g.player.position.x, g.player.position.z) : 1e9;
+    if (pd > roadCull(g)) {
+      if (h.model) h.model.visible = false;
+      h._mixerTicked = true;                      // …and don't skin a horse nobody can see
+      return;
+    }
+    // Inside the cull, his visibility IS the rider's: Character.update already frustum-tested the man
+    // in the saddle this frame (main.js ticks game.npcs before this loop), and the horse sits inside
+    // his 2.2 m body sphere. One cull, not two. main.js's own horse net skips ridden horses — which is
+    // exactly why this line has to exist.
+    const shown = !!r.model?.visible;
+    if (h.model) h.model.visible = shown;
+
+    // A SHUT LEVEL CROSSING IS A FRIGHT, NOT A NEGOTIATION — the same guard the walkers read. Asked
+    // only when he is NOT already running from it, or spook() would be re-deciding his direction every
+    // frame he stood on the rails.
+    if (this.bolt <= 0) {
+      const xing = railShut(g, h.position.x, h.position.z);
+      if (xing) this.spook(xing.at.x, xing.at.z, 3);
+    }
+
+    // ── THE SALOON CALL ──────────────────────────────────────────────────────────────────────────
+    // A rider passing Dustwater with the bar pouring sometimes turns in for one: hitch at the rail,
+    // walk to the batwings, a drink's worth of minutes inside, back out, swing up, ride on. Rolled
+    // ONCE per approach (reset when he's clear of town), never while bolting or after dark's ride home.
+    if (this._saloon) { this._saloonTick(dt, shown); return; }
+    if (this.bolt <= 0 && !this._home) {
+      const dS = dist2D(h.position.x, h.position.z, -11, 10);
+      if (dS < 45 && !this._saloonTried) {
+        this._saloonTried = true;
+        if (Math.random() < 0.45 && MC.venueOpen(g.world.sky?.hour ?? 12)) {
+          this._saloon = { phase: 'ride', hitch: SALOON_HITCH[(_hitchNext++) % SALOON_HITCH.length] };
+        }
+      } else if (dS > 90) this._saloonTried = false;
+    }
+
+    let speed = 0, turn = 0;
+    if (this.bolt > 0) {
+      this.bolt -= dt;
+      // It runs down the ROAD, not off across the desert — and at 9 m/s it eats a 25 m leg in under
+      // three seconds, so it has to keep taking the next one or it circles the waypoint it overshot.
+      laneTarget(_tgt, this.road, this._wp, this.dir, LANE, this.spot);
+      if (dist2D(h.position.x, h.position.z, _tgt.x, _tgt.z) <= ARRIVE * 1.6) this._advance();
+      turn = this._steer(dt);                     // sets _steerMul (reins in on a hard turn)
+      speed = BOLT * (this._steerMul ?? 1);
+    } else {
+      const hour = g.world.sky?.hour ?? 10;
+      const day = hour >= DAWN && hour < DUSK;
+      const last = this.road.length - 1;
+      if (day !== this._day) {
+        this._day = day;
+        if (!day) this.dir = this._wp * 2 <= last ? -1 : 1;                              // home, by the nearer end
+        else if (this._home) { this._home = false; this.dir = this._wp <= 0 ? 1 : -1; }  // …and out again at first light
+      }
+      if (this._home) speed = 0;                        // stood at the rail at the end of his road
+      else if (this.pauseT > 0) { this.pauseT -= dt; speed = 0; }
+      else {
+        laneTarget(_tgt, this.road, this._wp, this.dir, LANE, this.spot);
+        if (dist2D(h.position.x, h.position.z, _tgt.x, _tgt.z) <= ARRIVE) this._advance();
+        else { turn = this._steer(dt); speed = TROT * (h._steerSlow ? 0.6 : 1) * (this._steerMul ?? 1); }   // rein in while boxed-in
+      }
+    }
+
+    // STUCK BACKSTOP. A horse pinned on a static corner the whiskers can't clear used to grind there
+    // forever — the mount had NO give-up. The A* path is the proper way round; this catches what it
+    // can't (grid still baking, an unreachable goal, a dynamic pin): if we mean to move but haven't in
+    // 1.4 s, drop the held path and skip to the next road leg. Same backstop traveller.js gives a walker.
+    if (speed > 0.1) {
+      this._stuckT = (this._stuckT ?? 0) + dt;
+      if (this._stuckT >= 1.4) {
+        const moved = dist2D(h.position.x, h.position.z, this._lastSX ?? h.position.x, this._lastSZ ?? h.position.z);
+        this._lastSX = h.position.x; this._lastSZ = h.position.z; this._stuckT = 0;
+        if (moved < 0.5) { this._rtPath = null; if (this.bolt <= 0) this._advance(); }
+      }
+    } else { this._stuckT = 0; this._lastSX = h.position.x; this._lastSZ = h.position.z; }
+
+    this._drive(h, speed, turn, dt, this.bolt > 0 || this.built[this._wp]);
+    // THE GAIT TICKS BEFORE THE SEAT, and riding.js says why: read the saddle bone before the mixer has
+    // advanced it and the horse's fore-aft surge and tilt reach the rider a frame late, which reads as
+    // "the saddle moves but he doesn't". Hidden, there is no tick and the bone is last-drawn — but
+    // saddlePos walks the horse's ROOT, so he still rides with it, centimetres out and nobody looking.
+    if (shown) h.mixer?.update(dt);
+    h._mixerTicked = true;                     // either we ticked it, or it must not be ticked at all
+    this._place();                             // he rides with the horse whether or not he is drawn…
+    if (shown) this._pose();                   // …but only a man being LOOKED at needs his grip solved
+  }
+
+  // THE SALOON CALL's clock (see update). Phases: ride → (dismount) → walk → drink → return → resume.
+  // While the man drinks, the horse stands the rail like the town's own — idle mixer, no seat solve.
+  _saloonTick(dt, shown) {
+    const s = this._saloon, h = this.horse, r = this.rider, g = this.game;
+    if (!r.alive) { this._saloon = null; return; }               // shot on his way to a drink — update()'s death path owns it next frame
+    if (s.phase === 'ride') {
+      const d = dist2D(h.position.x, h.position.z, s.hitch.x, s.hitch.z);
+      if (d > 2.4) {
+        const sd = Character.prototype.walkDir.call(h, _dir.set((s.hitch.x - h.position.x) / d, 0, (s.hitch.z - h.position.z) / d), dt);
+        const m = mountedTurn(h.heading, h.position.x, h.position.z, h.position.x + sd.x, h.position.z + sd.z, Math.max(0.8, h.speed), HORSE_RMIN, TURN_RATE);
+        this._drive(h, TROT * 0.8 * m.speedMul, m.turn, dt, true);
+        if (shown) h.mixer?.update(dt);
+        h._mixerTicked = true;
+        this._place(); if (shown) this._pose();
+        return;
+      }
+      // pulled up at the rail: step down (the CALM dismount — unseat() is the shot man's, it bolts the horse)
+      h.speed = 0;
+      r.seated = false;
+      const bx = h.position.x + Math.cos(h.heading) * 1.3, bz = h.position.z - Math.sin(h.heading) * 1.3;
+      r.setPosition(bx, g.world.groundAt(bx, bz), bz);
+      r.root.rotation.set(0, h.heading, 0);
+      r._visualY = undefined;
+      r._goal = { x: -10.6, z: 10, then: () => { r._inSaloon = true; if (r.root) r.root.visible = false; } };
+      s.phase = 'walk'; s.dwell = 26 + Math.random() * 22;
+    } else if (s.phase === 'walk') {
+      if (r._inSaloon) s.phase = 'drink';
+    } else if (s.phase === 'drink') {
+      s.dwell -= dt;
+      if (s.dwell <= 0) {
+        r._inSaloon = false;
+        if (r.root) r.root.visible = true;
+        r.setPosition(-10.6, g.world.groundAt(-10.6, 10), 10);
+        const bx = h.position.x + Math.cos(h.heading) * 1.3, bz = h.position.z - Math.sin(h.heading) * 1.3;
+        r._goal = { x: bx, z: bz, then: () => { r.seated = true; this._saloon = null; } };   // swing up, ride on
+        s.phase = 'return';
+      }
+    }
+    // walk/drink/return: the horse stands the rail — idle gait, breathing mixer, no rider to place
+    h.play?.('idle');
+    if (shown) h.mixer?.update(dt);
+    h._mixerTicked = true;
+  }
+
+  // Point him at the lane target, but let the WHISKERS bend it — the same steering the walkers use,
+  // probed from the HORSE (which stands on the ground) and not from the saddle (which is a metre and a
+  // half in the air, where the fences are not). horse.js already borrows walkDir/_probeSteer for its
+  // grazers; this is the same borrow.
+  _steer(dt) {
+    const h = this.horse, g = this.game;
+    laneTarget(_tgt, this.road, this._wp, this.dir, LANE, this.spot);
+    let aimX = _tgt.x, aimZ = _tgt.z;
+    // LINE-FOLLOWING, NOT NODE-HOMING. Aiming AT the waypoint's lane point makes the steering error
+    // blow up as he closes on it — a half-metre of lateral drift is a few degrees at 20 m and thirty
+    // at three — so he over-turns, crosses the line, and the next node hauls him back: the
+    // left-right-left diagonals Nick watched. Project onto the LEG instead and chase a carrot a
+    // fixed distance ahead ALONG it: the correction stays proportional to the drift, and the line
+    // he rides is the road's own.
+    const pw = this._wp - this.dir;
+    if (pw >= 0 && pw < this.road.length) {
+      laneTarget(_prevT, this.road, pw, this.dir, LANE, this.spot);
+      const ex = _tgt.x - _prevT.x, ez = _tgt.z - _prevT.z, L2 = ex * ex + ez * ez;
+      if (L2 > 4) {
+        const L = Math.sqrt(L2);
+        const t = clamp(((h.position.x - _prevT.x) * ex + (h.position.z - _prevT.z) * ez) / L2, 0, 1);
+        const tc = Math.min(1, t + 7.0 / L);          // the carrot: 7 m ahead along the leg, never past the node
+        aimX = _prevT.x + ex * tc; aimZ = _prevT.z + ez * tc;
+      }
+    }
+    // STATIC-obstacle pathing, but only where the capsule is even on — inside BVH_R of the player or on
+    // a built-up stretch. Out on the open road _drive is terrain-follow only (it rides THROUGH a fence
+    // harmlessly, unseen), so there is nothing to route around and we keep the cheap straight aim. When
+    // the grid says the road ahead is blocked, steerCarrot holds an A* path round it (the settlement's
+    // own baked grid — reused, not re-baked) and hands back a look-ahead carrot to curve onto.
+    const pd = g.player ? dist2D(h.position.x, h.position.z, g.player.position.x, g.player.position.z) : 1e9;
+    if (pd < BVH_R || this.built[this._wp]) {
+      const centre = nearestEndpoint(this.road, h.position.x, h.position.z);
+      if (steerCarrot(this, g, centre, h.position.x, h.position.z, _tgt.x, _tgt.z, _aim,
+        { dt, arrive: ARRIVE, lookahead: clamp(h.speed * 0.5, 2.5, 4.5), wide: true })) { aimX = _aim.x; aimZ = _aim.z; }
+    } else { this._rtPath = null; }
+    // WHISKERS bend the aim for DYNAMIC things (people, other horses), probed from the HORSE — on the
+    // ground where the fences are, not from the saddle a metre and a half up in the air.
+    const dx = aimX - h.position.x, dz = aimZ - h.position.z, L = Math.hypot(dx, dz) || 1;
+    const sd = Character.prototype.walkDir.call(h, _dir.set(dx / L, 0, dz / L), dt);
+    // Pure-pursuit turn with a real minimum radius: TURN_RATE alone (an uncapped gain) let a boxed-in
+    // horse spin on the spot and snap straight back into the rail. mountedTurn caps it at wmax =
+    // speed/Rmin and reins the pace in on a hard heading error, so it slows and curves round instead.
+    const m = mountedTurn(h.heading, h.position.x, h.position.z, h.position.x + sd.x, h.position.z + sd.z, Math.max(0.6, h.speed), HORSE_RMIN, TURN_RATE);
+    this._steerMul = m.speedMul;
+    return m.turn;
+  }
+
+  // Move the animal. Inside 45 m of the player — and ALWAYS through a town, and always while it is
+  // bolting — that is the full capsule controller (horse.driveMove: BVH + terrain-follow + gait + bob).
+  // Out on the open road, where the whiskers are already off (entity.js walkDir) and the going is
+  // graded, straight and empty, it is terrain-follow only: the trade horse.js's own ambient grazers
+  // make, for the reason they state ("NO BVH… a needless cost").
+  _drive(h, speed, turn, dt, hard = false) {
+    const g = this.game;
+    const pd = g.player ? dist2D(h.position.x, h.position.z, g.player.position.x, g.player.position.z) : 1e9;
+    if (pd < BVH_R || hard) { h.driveMove(speed, turn, dt); return; }
+    h.speed = speed;
+    h.heading += turn * dt;
+    h.position.x += Math.sin(h.heading) * speed * dt;
+    h.position.z += Math.cos(h.heading) * speed * dt;
+    h.position.y = g.world.groundAt(h.position.x, h.position.z);
+    h.root.quaternion.setFromAxisAngle(UP, h.heading);
+    if (!h.airborne) h.play(h.gaitFor(Math.abs(speed)));
+    h._applyBob(dt);
+  }
+
+  _turnBack() {
+    this.dir = -this.dir;
+    this._wp = Math.max(0, Math.min(this.road.length - 1, this._wp + this.dir));
+  }
+
+  _advance() {
+    const next = this._wp + this.dir;
+    if (next < 0 || next >= this.road.length) {
+      if (!this._day) { this._home = true; return; }
+      this.dir = -this.dir;
+      this.pauseT = 3 + Math.random() * 5;      // he stands at the rail a while before he rides back
+      this._wp += this.dir;
+      return;
+    }
+    this._wp = next;
+  }
+}