sindicate 0.2.0 → 0.4.0

package/src/systems/horse.js

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