sindicate 0.1.0 → 0.4.0

package/src/systems/seatedRider.js

@@ -0,0 +1,396 @@
+// A MAN SAT ON SOMETHING — the driver on the box, the guard beside him, the fares inside.
+//
+// All of them are the same problem: take a standing western body, sit it down, and put its boots
+// and its fists WHERE THIS PARTICULAR SEAT PUTS THEM. So there is one class, tuned once in
+// /coachtest.html, and everybody who sits reuses it verbatim — the mate on the box is the driver
+// with a different x, and a passenger is the driver with his hands in his lap.
+//
+// TWO THINGS THAT COST ME A DAY, WRITTEN DOWN SO NOBODY PAYS AGAIN:
+//
+// 1. THE TARGETS ARE IN THE RIDER'S OWN SPACE, NOT THE VEHICLE'S. Author them against the coach
+//    and they are one man's numbers: the fellow sat beside him reaches for thin air, and a fare
+//    facing backwards reaches through the wall. Against his own pivot they are a POSTURE — "fists
+//    forward and a little up, boots forward and down" — and a posture is portable. That is what
+//    lets the same six numbers seat every man on the vehicle.
+//
+// 2. A TARGET OUT OF REACH IS NOT A POSE, IT IS A POINTED STICK. twoBoneIK cannot put a hand where
+//    an arm does not go; it straightens the limb and AIMS it. Two foot targets 0.36m apart, seen
+//    from a hip 1.5m away (a leg is 0.84m), differ by 13 degrees — so both boots land in nearly
+//    the same place and every width slider in the world does nothing. That was the "feet are
+//    connecting to each other" bug, and it is why the reach clamp below is not an optimisation.
+import * as THREE from 'three/webgpu';
+import { instantiate } from '../core/assets.js';
+import { makeSeatedPose, twoBoneIK, BIPED_TO_SYNTY } from './riding.js';
+// Seat posture numbers are GAME data (tuned in /coachtest.html) — register at boot,
+// BEFORE any rider is seated: setSeatRig(coachRigJson). SEAT/LEGS are live bindings:
+// importers see the registered values the moment registration runs.
+const SEAT_FALLBACK = {
+  reins: { x: 0, y: 1.08, z: 0.42 },
+  feet: { x: 0, y: 0.18, z: 0.40 },
+  lap: { x: 0, y: 0.93, z: 0.22 },
+  width: { hands: 0.28, feet: 0.34, knees: 0.16 },
+};
+const LEGS_FALLBACK = { hip: 1.35, knee: 1.45, ankle: 0.25, spread: 0.12 };
+export function setSeatRig(rig) {
+  SEAT = rig?.seat ?? SEAT_FALLBACK;
+  LEGS = rig?.seat?.legs ?? LEGS_FALLBACK;
+}
+
+// The seat posture, in the rider's own space. Authored in /coachtest.html; the fallback
+// is only for a rig file that predates it.
+export let SEAT = SEAT_FALLBACK;
+
+// A PASSENGER IS THE DRIVER WITH HIS HANDS DOWN. Only the man holding the reins holds the reins;
+// the mate beside him and the fares inside rest their hands in their laps. Same seat, same boots,
+// same widths — one different hand target. Sharing the feet/width objects BY REFERENCE is
+// deliberate: tune the boots once in the bench and every man on the coach moves with them.
+// The hand-posed bones, split by WHO they belong to. Legs and spine are the same man sitting down,
+// whoever he is — but the driver's arms are on the reins and everyone else's are in their lap, so
+// those two sets can never be shared. Merged here, once, into the flat map solve() applies.
+export function driverFk(p = SEAT) {
+  const f = p.fk ?? {};
+  return { ...(f.legs ?? f), ...(f.spine ?? {}), ...(f.driverArms ?? {}) };
+}
+export function paxFk(p = SEAT) {
+  const f = p.fk ?? {};
+  return { ...(f.legs ?? f), ...(f.spine ?? {}), ...(f.paxArms ?? {}) };
+}
+
+export function passengerPosture(p = SEAT) {
+  return { reins: p.lap ?? p.reins, feet: p.feet, width: p.width, handRot: p.lapRot, legs: p.legs, fk: paxFk(p) };
+}
+export function driverPosture(p = SEAT) {
+  return { reins: p.reins, feet: p.feet, width: p.width, handRot: p.reinRot, legs: p.legs, fk: driverFk(p) };
+}
+// A DEAD MAN DOES NOT HOLD THE REINS. The hand-posed driver arms (fk.driverArms) are a GRIP —
+// leave them on and a corpse drives the coach with his fists up, which is the single most
+// ridiculous thing this file could ship. So a dead rider wears the passenger arms with the target
+// dropped below his lap and splayed: the reins fall out of his hands and his arms hang. Solved
+// ONCE at the moment of death, then frozen (see SeatedRider.slump).
+export function limpPosture(p = SEAT) {
+  const pax = passengerPosture(p);
+  const lap = pax.reins ?? { x: 0, y: 0.93, z: 0.22 };
+  return {
+    ...pax,
+    reins: { x: lap.x ?? 0, y: (lap.y ?? 0.93) - 0.26, z: (lap.z ?? 0.22) - 0.06 },
+    width: { ...(p.width ?? {}), hands: (p.width?.hands ?? 0.28) + 0.16 },
+  };
+}
+
+// WHERE HIS FEET WOULD BE IF HE STOOD UP — the datum combat.js measures a head from.
+//
+// combat.js calls a round a headshot when hitY = bulletY - position.y >= HEAD_Y (1.5), and scores
+// the hit VFX at position.y + 1.62. Both numbers assume a STANDING body: feet on the ground, head
+// at ~1.56 (measured off the player's own Head bone). A seat pivot is NOT that datum, and you
+// cannot eyeball what it is: the seated pose only ROTATES bones, so this man's hips stay at their
+// standing height above the model origin and his folded boots end up ABOVE it — on the driver's
+// box, his head is 1.556 above his pivot and his ankles are +0.522. Feed combat the seat height
+// and his whole body sits 1.5m over the line: every round through the driver's hat scored as a
+// HEADSHOT, and so did one through his boot.
+//
+// So ask HIS OWN HEAD BONE where the ground under him would be (bodies and seats differ; the
+// driver's answer is not the backward-facing fare's) and publish that. Then HEAD_Y lands on his
+// collar and 1.62 lands exactly on his head bone, and every number in combat.js means what it
+// says. Measured, never guessed — the clamp below is a seatbelt, not a value.
+const STAND_HEAD = 1.62;
+const SLUMP_SECS = 0.6;     // how long he takes to fold. A body falls; it does not lie down.
+const SLUMP_PITCH = 1.2;    // radians forward, over his own knees (his own axes — the model, not the pivot)
+const _hp = new THREE.Vector3(), _pp = new THREE.Vector3();
+
+const _t = new THREE.Vector3(), _l = new THREE.Vector3(), _r = new THREE.Vector3();
+const _root = new THREE.Vector3(), _mid = new THREE.Vector3(), _end = new THREE.Vector3();
+const _axis = new THREE.Vector3(), _q = new THREE.Quaternion(), _qp = new THREE.Quaternion();
+const _qi = new THREE.Quaternion();
+const _e = new THREE.Euler(), _qh = new THREE.Quaternion();
+const _cur = new THREE.Vector3(), _want = new THREE.Vector3(), _pole = new THREE.Vector3();
+
+// Which way the joints break, in the rider's own space (+Z is the way he faces).
+const ELBOW_POLE = new THREE.Vector3(0, -1, -0.35).normalize();  // elbow down and back
+const _lx = new THREE.Vector3(), _lz = new THREE.Vector3(), _qw = new THREE.Quaternion();
+
+// A seated leg, in degrees-you-can-picture (stored as radians). Tuned in /coachtest.html.
+export let LEGS = LEGS_FALLBACK;
+
+// Turn a bone about an axis given in WORLD space, leaving its parent alone.
+function turn(bone, worldAxis, angle) {
+  if (!bone || Math.abs(angle) < 1e-5) return;
+  _q.setFromAxisAngle(worldAxis, angle);
+  bone.parent.getWorldQuaternion(_qp);
+  _qi.copy(_qp).invert();
+  bone.quaternion.premultiply(_qp).premultiply(_q).premultiply(_qi);
+  bone.updateWorldMatrix(false, true);
+}
+
+// Pull a target inside the limb's reach. Reach is measured from the CURRENT pose (bones move), and
+// 0.95 of it, never 1.0 — at full stretch the limb is straight, the knee has NO bend plane to
+// speak of, and the two cross-products twoBoneIK builds it from are cross-products of parallel
+// vectors: pure noise. Rotate such a rider 180 degrees and the noise lands the other way, which is
+// precisely how the two backward-facing fares ended up with their knees on backwards.
+function clampReach(root, mid, end, target) {
+  root.getWorldPosition(_root); mid.getWorldPosition(_mid); end.getWorldPosition(_end);
+  const reach = (_root.distanceTo(_mid) + _mid.distanceTo(_end)) * 0.95;
+  const d = _root.distanceTo(target);
+  if (d > reach && d > 1e-6) target.copy(_root).addScaledVector(_t.copy(target).sub(_root).divideScalar(d), reach);
+  return target;
+}
+
+// POINT THE KNEE. twoBoneIK gets the foot to the target but says nothing about WHICH WAY the knee
+// bends — the bend plane falls out of whatever cross-products the current pose happens to produce,
+// and near full extension those are cross-products of near-parallel vectors, i.e. noise. So don't
+// leave it to chance: spin the whole limb about the hip→foot line (the one axis the foot doesn't
+// care about — it stays exactly where the IK put it) until the knee points where we SAY it points.
+//
+// `poleWorld` is the direction the knee should aim, in world space. `extra` is the knee-width
+// splay, added on top. This is what makes a rotated rider bend the same way as an unrotated one:
+// the pole is HIS forward, so it turns with him.
+function aimPole(upper, mid, end, poleWorld, extra) {
+  if (!upper || !mid || !end) return;
+  upper.getWorldPosition(_root); mid.getWorldPosition(_mid); end.getWorldPosition(_end);
+  _axis.copy(_end).sub(_root);
+  if (_axis.lengthSq() < 1e-8) return;
+  _axis.normalize();
+  // where the knee points now, and where we want it — both flattened onto the plane the hinge
+  // sweeps (i.e. with the component along the hip→foot line removed)
+  _cur.copy(_mid).sub(_root).addScaledVector(_axis, -_mid.clone().sub(_root).dot(_axis));
+  _want.copy(poleWorld).addScaledVector(_axis, -poleWorld.dot(_axis));
+  if (_cur.lengthSq() < 1e-8 || _want.lengthSq() < 1e-8) return;
+  _cur.normalize(); _want.normalize();
+  let ang = Math.acos(Math.max(-1, Math.min(1, _cur.dot(_want))));
+  if (_cur.clone().cross(_want).dot(_axis) < 0) ang = -ang;     // signed, about the hinge axis
+  ang += extra || 0;
+  if (Math.abs(ang) < 1e-4) return;
+  _q.setFromAxisAngle(_axis, ang);
+  upper.parent.getWorldQuaternion(_qp);
+  _qi.copy(_qp).invert();
+  upper.quaternion.premultiply(_qp).premultiply(_q).premultiply(_qi);
+  upper.updateWorldMatrix(false, true);
+}
+
+export class SeatedRider {
+  // parent: what he is sitting IN (the coach root). seat: {x,y,z,ry} in that parent's space.
+  static async create(parent, def, seat, posture = SEAT) {
+    const model = await instantiate(def.src, { keep: def.keep, texture: def.tex, scale: 0.01 });
+    model.scale.setScalar(0.01);
+    const pivot = new THREE.Group();
+    pivot.position.set(seat.x, seat.y, seat.z);
+    // BAKE THE POSE FACING FORWARD, TURN HIM AFTERWARDS.
+    // makeSeatedPose reads the body through its WORLD matrix, so a rider who is already spun to
+    // face backwards bakes his own heading into the pose — the identical disease that made the
+    // townsfolk come out contorted (retarget.js captureBind). Two men, same seat data, different
+    // poses, and no amount of tuning reconciles them: one of them is wearing a rotation. So he
+    // faces +Z while the pose is taken, and only then does he turn round to face his seat.
+    pivot.rotation.y = 0;
+    pivot.add(model);
+    parent.add(pivot);
+    pivot.updateWorldMatrix(true, true);
+    const r = new SeatedRider(pivot, model, posture);
+    r.def = def;                          // who he is, for anything that wants to name him
+    try {
+      const { pose, pbone } = await makeSeatedPose(model, BIPED_TO_SYNTY);
+      // the STANDING bind of the leg chain — the angles below are measured from a man stood up
+      for (const n of ['UpperLeg_L', 'LowerLeg_L', 'Ankle_L', 'UpperLeg_R', 'LowerLeg_R', 'Ankle_R']) {
+        if (pbone[n]) r.bind[n] = pbone[n].quaternion.clone();
+      }
+      for (const [n, q] of Object.entries(pose)) pbone[n]?.quaternion.copy(q);
+      r.bones = pbone;
+      r.pose = pose;
+      r._measureSide();          // ask THIS body which side its "_L" bones are on
+    } catch (e) { console.warn('[seat] seated pose failed — he stands', e); }
+    pivot.rotation.y = seat.ry ?? 0;      // NOW he can turn round
+    pivot.updateWorldMatrix(true, true);
+    // NO SOLVE HERE. The caller may still be seeding the posture from this very body (the bench
+    // does exactly that), and solving against a half-filled posture aims his limbs at his own
+    // origin. Everyone who owns a rider solves him every frame anyway.
+    return r;
+  }
+
+  // HATS OFF INSIDE. A Synty body wears its hat as part of the one mesh, so there is no hat node to
+  // switch off — but the hat has its OWN BONE, and a bone scaled to nothing takes its vertices with
+  // it. Costs no draw call, no material, no rebuild: the hat simply stops existing.
+  hat(on) {
+    for (const n of ['Hat', 'Head_Hat', 'Attach_Hat', 'Hat_01']) {
+      const b = this.bones?.[n];
+      if (b) { b.scale.setScalar(on ? 1 : 1e-4); return true; }
+    }
+    return false;
+  }
+
+  constructor(pivot, model, posture) {
+    this.pivot = pivot;
+    this.model = model;
+    this.posture = posture;
+    this.bones = null;
+    this.pose = null;
+    this.side = 1;               // +1 when the bones named _L live at +x (set by _measureSide)
+    this.bind = {};              // the standing leg chain — what the leg angles are measured from
+    this.baseRot = model.rotation.clone();   // what "sitting up straight" is — the slump is measured from it
+
+    // ---- THE SHOOTABLE CONTRACT (combat.js tests these exactly as it tests an outlaw) --------
+    // He is a child of a moving coach and has no world position of his own, so he is GIVEN one:
+    // a single Vector3, refreshed every frame by Coach._syncRiders (no allocation, no matrix
+    // walk — the same rotate-the-offset arithmetic the horse colliders already use).
+    this.position = new THREE.Vector3();
+    this.feetDrop = 0.06;        // pivot → standing datum; re-measured off his own head bone on the first solve
+    this.civilian = true;        // a fare is not an outlaw — shooting him is a crime
+    this.alive = true;
+    this.maxHealth = 40;         // he is a passenger, not a gunfighter: one good round does it
+    this.health = 40;
+    this.slumpT = -1;            // -1 = upright; 0..1 = folding over
+    this.game = null;            // set by the coach that owns him
+    this.coach = null;
+    this.role = 'fare';          // 'driver' | 'mate' | 'fare' — decides the purse and who bolts the team
+  }
+
+  // He takes a hit the same way everyone else does — minus the parts a man bolted to a bench
+  // cannot do. `opts.knockback` is deliberately IGNORED: a coach at a canter is not the place to
+  // shove a body 0.35m sideways through the box he is sitting in. He absorbs it and he folds.
+  takeDamage(amount, fromPos = null, opts = {}) {
+    if (!this.alive) return;
+    this.health -= amount;
+    this.game?.audio?.play('hurt');
+    if (this.health <= 0) this.die(opts.attacker ?? null);
+  }
+
+  die(killer = null) {
+    if (!this.alive) return;
+    this.alive = false;
+    this.posture = limpPosture(SEAT);   // the reins fall out of his hands...
+    this.solve();                       // ...one last solve to put them there, and then never again
+    this.slumpT = 0;                    // ...and he starts to go over
+    this._slumpRoll = (Math.random() < 0.5 ? -1 : 1) * (0.18 + Math.random() * 0.25);
+    this.coach?._crewDown(this, killer);
+  }
+
+  // The fold. Runs INSTEAD of solve() once he's dead: the bones stay exactly where that last limp
+  // solve left them and the whole man tips over his own hips (the model's origin), in HIS OWN axes
+  // — so a backwards-facing fare falls forward onto his own knees and not out through the roof.
+  slump(dt) {
+    if (this.slumpT >= 1) return;                       // down, and staying down — nothing left to do per frame
+    this.slumpT = Math.min(1, this.slumpT + dt / SLUMP_SECS);
+    const k = this.slumpT * this.slumpT * (3 - 2 * this.slumpT);   // ease — the fall accelerates then settles
+    this.model.rotation.x = this.baseRot.x + k * SLUMP_PITCH;
+    this.model.rotation.z = this.baseRot.z + k * (this._slumpRoll ?? 0.2);
+    this.model.position.y = -k * 0.06;                  // and he sinks into the bench as he goes
+  }
+
+  // Measure the standing datum off his own head bone, once, from the SOLVED pose (a bone read
+  // before the pose is applied is a bone in the T-pose, and a T-posed head is not where his head
+  // is). Measured on the box: head +1.556 above the pivot → a drop of 0.06, i.e. the datum lands a
+  // whisker under the seat pivot. The clamp is a seatbelt for a body that hands us a nonsense head
+  // (or none): it must never let a rider publish a datum that makes his boots a headshot.
+  _measureDatum() {
+    const head = this.bones?.Head ?? this.bones?.Neck;
+    if (!head) { this._datum = true; return; }
+    head.getWorldPosition(_hp);
+    this.pivot.getWorldPosition(_pp);
+    this.feetDrop = Math.max(-0.35, Math.min(1.35, STAND_HEAD - (_hp.y - _pp.y)));
+    this._datum = true;
+  }
+
+  // WHICH SIDE IS HIS LEFT? Do not assume. In this rig the bones NAMED _L sit at POSITIVE x in the
+  // body's own space (Hand_L x = +0.58, Hand_R x = -0.63) — the opposite of the convention I'd have
+  // bet on. Assume it and every left limb gets sent to his right: the arms and legs cross, which is
+  // exactly what they did. So ask the skeleton, once, and let the body tell you which way it is
+  // built. Measured off the RAW seated pose, before any IK has had a chance to move anything.
+  _measureSide() {
+    const B = this.bones;
+    if (!B.Hand_L || !B.Hand_R) { this.side = 1; return; }
+    this.model.updateWorldMatrix(true, true);
+    const xl = this.pivot.worldToLocal(B.Hand_L.getWorldPosition(new THREE.Vector3())).x;
+    const xr = this.pivot.worldToLocal(B.Hand_R.getWorldPosition(new THREE.Vector3())).x;
+    this.side = xl >= xr ? 1 : -1;      // +1 when "_L" means +x
+  }
+
+  // One limb: reset is the caller's job (see solve). lr is 'L' or 'R'; the actual sign comes from
+  // the body (_measureSide), never from a guess about the rig's handedness.
+  _limb(a, b, c, localTarget, lr, width, poleLocal, splayAngle) {
+    const B = this.bones;
+    if (!B[a] || !B[b] || !B[c]) return;
+    const side = (lr === 'L' ? 1 : -1) * this.side;
+    _l.set(localTarget.x + side * width / 2, localTarget.y, localTarget.z);
+    this.pivot.localToWorld(_l);
+    clampReach(B[a], B[b], B[c], _l);
+    twoBoneIK(B[a], B[b], B[c], _l);
+    // the pole is given in HIS space and rotated into the world, so a fare facing backwards bends
+    // his knees toward HIS front, not toward the coach's
+    _pole.copy(poleLocal).applyQuaternion(this.pivot.getWorldQuaternion(_qh));
+    aimPole(B[a], B[b], B[c], _pole, side * (splayAngle || 0));
+  }
+
+  // Roll/pitch/yaw both wrists, mirrored. Pitch (x) is the same on both hands; yaw and roll flip,
+  // because a left hand and a right hand are reflections, not copies.
+  _wrists(r) {
+    for (const [n, m] of [['Hand_L', this.side], ['Hand_R', -this.side]]) {
+      const b = this.bones[n];
+      if (!b) continue;
+      _e.set(r.x ?? 0, (r.y ?? 0) * m, (r.z ?? 0) * m);
+      b.quaternion.multiply(_qh.setFromEuler(_e));
+    }
+  }
+
+  // THE LEGS ARE POSED, NOT SOLVED.
+  //
+  // I tried to place the boots with an IK target and it was the wrong tool. IK gives you the FOOT
+  // and infers everything else — which knee bend, which way the shin twists, where the toe ends up
+  // pointing. Near full extension that inference is unstable (cross-products of near-parallel
+  // vectors: noise), so the leg juddered as you dragged the target, and because the noise is in
+  // WORLD space, a man facing backwards inferred a different answer and sat there with his feet on
+  // backwards. You cannot hand-tune your way out of that; the instability is in the method.
+  //
+  // A seated leg is four angles and every animator on earth knows what they are: how far the thigh
+  // comes up, how far the knee folds, where the foot points, how far the knees are apart. So say
+  // them. Applied to the STANDING bind (legs straight down), not to the horse-sit, so the numbers
+  // mean what they say — and applied in the RIDER'S OWN axes, so a backwards-facing fare bends his
+  // knees toward HIS front. Deterministic: same input, same pose, every frame, every heading.
+  _legs(L) {
+    const B = this.bones, P = this.pivot;
+    P.getWorldQuaternion(_qw);
+    const X = _lx.set(1, 0, 0).applyQuaternion(_qw);   // his lateral axis: pitch and knee-fold turn about this
+    const Z = _lz.set(0, 0, 1).applyQuaternion(_qw);   // his forward axis: the knees splay about this
+    for (const lr of ['L', 'R']) {
+      const s = (lr === 'L' ? 1 : -1) * this.side;
+      const up = B[`UpperLeg_${lr}`], lo = B[`LowerLeg_${lr}`], an = B[`Ankle_${lr}`];
+      if (!up || !lo) continue;
+      // back to STANDING for the leg chain — the seated pose above is for his spine and arms
+      for (const b of [up, lo, an]) if (b && this.bind[b.name]) b.quaternion.copy(this.bind[b.name]);
+      up.updateWorldMatrix(false, true);
+      turn(up, Z, -s * L.spread);      // knees apart
+      turn(up, X, -L.hip);             // thigh forward and up
+      turn(lo, X, L.knee);             // knee folds, shin drops
+      if (an) turn(an, X, L.ankle);    // and the boot sits flat on the board
+    }
+  }
+
+  // Call every frame the rider is visible. Cheap: four two-bone solves, no mixer.
+  solve() {
+    if (!this.bones || !this.pose) return;
+    // RE-SEAT THE BASE POSE FIRST, EVERY TIME. twoBoneIK rotates a bone from wherever it already
+    // is, so solving on top of yesterday's solve compounds — measured at 0.22m of drift per frame,
+    // which is a man shaking himself to pieces. From a fixed start it is dead still (0.0000m).
+    for (const [n, q] of Object.entries(this.pose)) this.bones[n]?.quaternion.copy(q);
+    this.model.updateWorldMatrix(true, true);
+    const P = this.posture;
+    // legs first — the arms hang off the spine, which hangs off the hips
+    this._legs(P.legs ?? LEGS);
+    this.model.updateWorldMatrix(true, true);
+    this._limb('Shoulder_L', 'Elbow_L', 'Hand_L', P.reins, 'L', P.width.hands, ELBOW_POLE, 0);
+    this._limb('Shoulder_R', 'Elbow_R', 'Hand_R', P.reins, 'R', P.width.hands, ELBOW_POLE, 0);
+    // HAND-POSED BONES WIN. If someone sat in the bench and turned a knee until it looked right,
+    // that is the answer — no solver gets to overrule it. This is the escape hatch from every
+    // clever thing above, and it is applied last precisely so it cannot be argued with.
+    if (P.fk) {
+      for (const [n, q] of Object.entries(P.fk)) {
+        const b = this.bones[n];
+        if (b) b.quaternion.set(q.x ?? q[0], q.y ?? q[1], q.z ?? q[2], q.w ?? q[3]);
+      }
+      this.model.updateWorldMatrix(true, true);
+    }
+    // AIM THE WRISTS. twoBoneIK puts the hand WHERE you asked and leaves it pointing wherever the
+    // arm happened to leave it — which is why a man resting his hands in his lap can end up palms-
+    // up like he's begging. Turn the wrist afterwards, mirrored about the body's centreline so the
+    // two hands stay a pair rather than both rolling the same way.
+    if (P.handRot) this._wrists(P.handRot);
+    // ...and now that he is actually SITTING, ask him where his head is (once).
+    if (!this._datum) this._measureDatum();
+  }
+}

package/src/systems/skybirds.js

@@ -0,0 +1,129 @@
+// Sky birds: one flock = ONE VAT InstancedMesh (like herd.js, but airborne). Each bird flies its own
+// slow orbit around the flock's centre, banking into the turn and mixing flap and glide. Resident for
+// life, one draw call per flock.
+//
+// Nick asked for eagles by name, so these are eagles — the pack ships Eagle_Flying and a perched
+// Eagle_Idle, and the badlands are the right country for them. NO SEAGULLS: this county is eight
+// hundred miles from the sea, and fable's flock (which is where this is ported from) is a gull flock.
+//
+// TWO DIFFERENCES FROM FABLE'S:
+//   • THE FLOCK CAN BE ANCHORED. Fable's flock centre drifts after the player forever, so there are
+//     always birds overhead. That is right for a coastal town and wrong for a county: an eagle that
+//     follows you into the saloon is not an eagle. An `over: {x,z}` flock circles ITS OWN ground —
+//     the badlands, the quarry — and you ride to it. The drifting kind is kept for the one flock that
+//     should be everywhere (a pair of high birds, the kind you always see in an empty sky).
+//   • The gate is the flock's own radius, not a hardcoded 400 m.
+import * as THREE from 'three/webgpu';
+import { vatMaterial } from './vat.js';
+
+const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _p = new THREE.Vector3(), _e = new THREE.Euler();
+
+export class Flock {
+  // `over: {x,z}` = circle THIS ground and stay there. Omit it and the flock trails the player.
+  constructor(game, species, count = 6, { alt = 40, spread = 60, over = null } = {}) {
+    this.game = game;
+    this.over = over;
+    this.scale = species.scale;
+    this.ci = species.clipIndex;
+    this._scl = new THREE.Vector3(this.scale, this.scale, this.scale);
+
+    const geo = species.geometry.clone();
+    const aClip = new Float32Array(count), aPhase = new Float32Array(count), aTint = new Float32Array(count * 3);
+    const aClipAttr = new THREE.InstancedBufferAttribute(aClip, 1);
+    aClipAttr.setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('aClip', aClipAttr);
+    geo.setAttribute('aPhase', new THREE.InstancedBufferAttribute(aPhase, 1));
+    geo.setAttribute('aTint', new THREE.InstancedBufferAttribute(aTint, 3));
+    if (species.layers > 1) geo.setAttribute('aLayer', new THREE.InstancedBufferAttribute(new Float32Array(count), 1));
+    this.aClip = aClip; this._aClipAttr = aClipAttr;
+    this.mesh = new THREE.InstancedMesh(geo, vatMaterial(species.vat, species.albedo, species.layers), count);
+    this.mesh.name = 'flock:eagle';
+
+    this.centre = new THREE.Vector3();
+    this.alt = alt;
+    this.birds = [];
+    for (let i = 0; i < count; i++) {
+      this.birds.push({
+        r: spread * (0.35 + Math.random() * 0.65),                       // orbit radius
+        a: Math.random() * Math.PI * 2,                                  // orbit angle
+        w: (0.05 + Math.random() * 0.06) * (Math.random() < 0.5 ? 1 : -1), // rad/s, either way — a raptor turns SLOWLY
+        h: alt * (0.7 + Math.random() * 0.6),                            // altitude above the ground under it
+        bob: Math.random() * Math.PI * 2,
+      });
+      aPhase[i] = Math.random() * 6;
+      // an eagle GLIDES; it does not flap its way across a county. Two in three are on the glide slot.
+      aClip[i] = Math.random() < 0.34 ? (this.ci.walk ?? 0) : (this.ci.idle ?? 0);
+      const b = 0.9 + Math.random() * 0.2;
+      aTint[i * 3] = b; aTint[i * 3 + 1] = b; aTint[i * 3 + 2] = b;
+    }
+    this._clipT = 1.5;
+
+    if (over) {
+      // an anchored flock never leaves its own sky — so it gets a real bounding sphere and is culled
+      // like anything else. A drifting one is always near the player by construction.
+      const gy = game.world?.groundAt?.(over.x, over.z) ?? 0;
+      this.mesh.boundingSphere = new THREE.Sphere(new THREE.Vector3(over.x, gy + alt, over.z), spread + alt + 30);
+      this.mesh.frustumCulled = true;
+      this.gate2 = (spread + 700) ** 2;   // eagles are the one thing you are MEANT to see from far off
+    } else {
+      this.mesh.frustumCulled = false;
+      this.gate2 = Infinity;
+    }
+
+    // Place every instance in its sky NOW. An anchored flock's update() early-returns while the
+    // player is far (the gate) BEFORE it ever runs the placement loop — so without this its instances
+    // sit at the identity matrix, i.e. at (0,0,0), flapping in the ground, until you finally ride up
+    // to it (Nick: "birds at 0,0,0 in the floor"). Culling then hides them by their bounding sphere.
+    const cx = over?.x ?? 0, cz = over?.z ?? 0;
+    this.centre.set(cx, 0, cz);
+    for (let i = 0; i < count; i++) {
+      const b = this.birds[i];
+      const x = cx + Math.cos(b.a) * b.r, z = cz + Math.sin(b.a) * b.r;
+      const y = (game.world?.groundAt?.(x, z) ?? 0) + b.h;
+      _m.compose(_p.set(x, y, z), _q.identity(), this._scl);
+      this.mesh.setMatrixAt(i, _m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+
+  update(dt, playerPos) {
+    this.mesh.material.userData.uTime.value += dt;   // the VAT clock — without it the bake is frozen on frame 0
+    const c = this.centre;
+    if (this.over) {
+      c.set(this.over.x, 0, this.over.z);
+      const dx = playerPos.x - c.x, dz = playerPos.z - c.z;
+      if (dx * dx + dz * dz > this.gate2) return;    // nobody within sight of that sky
+    } else {
+      if (!this._init) { this._init = true; c.set(playerPos.x + 40, 0, playerPos.z - 60); }
+      // drift the flock centre toward the player's country — never snap
+      const dx = playerPos.x - c.x, dz = playerPos.z - c.z, d = Math.hypot(dx, dz);
+      if (d > 90) { const k = Math.min(3, d / 120) * 4 * dt; c.x += (dx / d) * k; c.z += (dz / d) * k; }
+    }
+
+    // occasionally a bird switches glide ↔ flap. That is all "soaring" is.
+    this._clipT -= dt;
+    if (this._clipT <= 0) {
+      this._clipT = 1.4 + Math.random() * 2.6;
+      const i = (Math.random() * this.birds.length) | 0;
+      this.aClip[i] = this.aClip[i] === (this.ci.idle ?? 0) ? (this.ci.walk ?? 0) : (this.ci.idle ?? 0);
+      this._aClipAttr.needsUpdate = true;
+    }
+
+    const g = this.game.world;
+    for (let i = 0; i < this.birds.length; i++) {
+      const b = this.birds[i];
+      b.a += b.w * dt;
+      b.bob += dt;
+      const x = c.x + Math.cos(b.a) * b.r;
+      const z = c.z + Math.sin(b.a) * b.r;
+      const y = g.groundAt(x, z) + b.h + Math.sin(b.bob * 0.35) * 4.0;   // the long slow rise and fall of a thermal
+      // heading = the orbit's tangent; the bank rolls INTO the turn
+      const vx = -Math.sin(b.a) * b.w, vz = Math.cos(b.a) * b.w;
+      const heading = Math.atan2(vx, vz) + Math.PI;   // +PI: the rig faces −Z, so without this it flies tail-first
+      const bank = Math.max(-0.5, Math.min(0.5, b.w * b.r * 0.09));
+      _m.compose(_p.set(x, y, z), _q.setFromEuler(_e.set(0, heading, bank)), this._scl);
+      this.mesh.setMatrixAt(i, _m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+}