@bitefoundry/retrieviewer 0.0.2 → 0.0.4

package/vendor/procedural-animals/src/core/motion/swimmer.js

@@ -1,1047 +0,0 @@
-// Swimmer motion engine (fish, sharks): a travelling body wave on a spine chain, steering by body
-// bends, paired fins that scull and fold, gill covers and mouth that pump, 3D swimming inside the
-// water volume between the bed `ground(x, z)` and the surface `water(x, z)`.
-//
-// Model. The spine chain (snout -> spine0 .. spineN -> caudal tip, core/rig/swimmer.js) is rebuilt
-// every frame from segment angles, so segment lengths never change (no stretch):
-//   * body wave: lateral displacement y(u, t) = A(u) sin(2 pi (phi - u / lambda)), u = arc length /
-//     body length; the phase phi integrates the tail-beat frequency (motion from phase, continuous
-//     when the frequency changes); A(u) = amp/2 * L * envelope(u) with envelope exp(k (u - 1))
-//     (carangiform) or u^p (thunniform: stiff front, all motion in the peduncle and tail);
-//   * steering: the body bends into an arc (C-bend) proportional to the yaw rate and inversely to
-//     the speed (it follows its own path), distributed along the flexible part of the body;
-//   * recoil: the mass-weighted mean orientation of the body is the heading and the mass-weighted
-//     centre is state.position, so the head yaws against the tail beat as in real fish;
-//   * vertical plane: rest pitch of every segment from the bind pose (an up-turned heterocercal
-//     shark tail just works), plus action arches (leap, death droop), plus the path pitch.
-// Fins: pectorals scull at low speed (flap + row + feather from a fin phase) and fold flat against
-// the body as the speed rises; they flare to brake and on the inside of turns; pelvic fins spread when
-// slow; gill covers flare with each breath while the mouth opens in counter-phase (buccal pump).
-// The water column: the fish keeps a clearance above the bed and below the surface (soft steering)
-// and a hard skin-extent clamp (bone-local skin extents measured from the mesh at start) so the skin
-// never cuts the bed or breaks the surface unless it is leaping. Out of the water it flies
-// ballistically and splashes back ('takeoff' / 'land' events).
-// Shores (water(x, z) null or shallower than the body: a lake in a landscape): the fish turns away from
-// water too shallow ahead and never swims into it; a leap is aimed short enough to come down in deep
-// water; a body that still comes down on dry ground (or is placed there) is beached: it flops and
-// slides back toward the nearest water ('beach' event, state.beached, gait 'flop') and swims on there.
-// Lessons from the cheetah: continuous solves, soft limits, springs for secondary motion, zero-dt
-// safety, no allocations in the hot path.
-//
-// ------------------------------------------------------------------------------------------------
-// species.motion schema (all optional; speeds in body lengths per second, BL/s; L = snout -> caudal
-// tip along the chain of this individual; `variants: { key: { ...overrides } }` merges per
-// params.variant, e.g. fish trout / goldfish, shark white / blacktip)
-// ------------------------------------------------------------------------------------------------
-// speeds      { name: BL/s } named speeds (default { scull: 0.4, cruise: 1.5, sprint: 4 }); the engine
-//             exposes them in m/s for this individual (animal.gears)
-// maxSpeed    BL/s top sustained speed from move();  burstSpeed BL/s peak of burst / attack / hit
-// minSpeed    BL/s: obligate ram ventilators (sharks) never drop below it: they patrol in slow circles
-// patrolRadius BL: radius of that patrol circle (default 0 = the tightest turn)
-// accel, decel  BL/s^2 (decel is also the drag of a gliding fish)
-// turnRate    rad/s yaw rate at rest; turnRadius: minimum turning radius at speed (BL)
-// wave        rows [v BL/s, f Hz, amp (tail-tip peak-to-peak / L), lambda (L), pect 0..1 (pectoral
-//             sculling activity), pf Hz (pectoral beat), fold 0..1 (pectorals folded)], sorted by v.
-//             From Bainbridge (1958): f = (U/L + 1) / 0.75 above ~2 BL/s, amp ~0.2 L.
-// envelope    { exp: k } (a = e^(k (u-1)), carangiform, default k = 3.5) or { pow: p } (thunniform,
-//             p ~ 2.5); head: 0..1 extra head yaw (added to recoil)
-// flex        [u0, u1]: where the body can bend for steering (fraction of L), default [0.15, 0.95]
-// caudalStiff 0..1: how much the caudal fin stays a flat plate continuing the peduncle (default 0.6)
-// bend        max total C-bend of a turn (rad), cBend: max C-start bend (rad)
-// bank        max roll in turns (rad);  bankGain: roll per unit of lateral acceleration (default 0.12;
-//             sharks bank into turns ~1-1.4);  pitchMax: max climb pitch (rad);  hover: vertical hover speed (BL/s)
-// strandRoll  rad: the roll of a body stranded on dry ground (default 1.3: a bony fish lies on its side;
-//             a broad shark ~0.25, on its belly)
-// clearance   distance kept from the bed and the surface (BL); cruiseDepth: preferred height above
-//             the bed when spawned (BL)
-// pectoral    { rest: [abduct, row, feather] deg, flap, row, feather: sculling amplitudes (deg),
-//               fold: deg against the body at speed, flare: deg when braking, alternate: 0..1
-//               (0 = both fins in phase, 1 = alternating, hovering goldfish), stiff: 0..1 (sharks:
-//               hydrofoils that do not scull) }
-// pelvic      { rest: deg abduct, spread: deg when slow, fold: deg at speed }
-// breath      { rate Hz, operculum deg flare, mouth 0..1 buccal gape, ram: BL/s above which the
-//               pumping fades (ram ventilation), slits: true for sharks (no gill covers) }
-// jaw         { gape deg (max mouth opening), protrude (BL, upper jaw protrusion), protrudeDir: [x, y, z]
-//               bind-space direction of the protrusion (default [0, -0.3, 1]; sharks forward and down) }
-// actions     { burst: { turn deg, speed BL/s }, jump: { height BL }, eat: { style 'suction' |
-//               'bottom', lunge BL }, drink: { reach BL (surface gulp if the surface is closer) },
-//               attack: { lunge BL, headLift rad (snout lift on the bite), shake (head shakes after the
-//               bite), eye: 'roll' | 'nictitate' (eye protection on the bite) }, eat: { style 'tear' too
-//               (bite, head lift, shakes: sharks) }, jump: { bite: bool (breach with a bite), roll rad
-//               (rotation in the air) }, sleep: { style 'bottom' | 'hover' | 'side' }, lie: { style },
-//               death: { float: bool, roll rad (final roll, default pi/2 = on its side) } }
-// state extras: eyeRoll 0..1 (white shark: the eye rolls back on the bite), nictitate 0..1 (membrane)
-// ------------------------------------------------------------------------------------------------
-import * as THREE from 'three';
-import { TAU, clamp, lerp, smooth, angDiff, Spring, writeFrame, prng, tv } from './common.js';
-import { SwimmerActions, createSwimParams } from './swimmerActions.js';
-
-const DEFAULTS = {
-  speeds: { scull: 0.4, cruise: 1.5, sprint: 4 },
-  maxSpeed: 6, burstSpeed: 10, minSpeed: 0, patrolRadius: 0, accel: 12, decel: 5, turnRate: 3.2, turnRadius: 0.35,
-  wave: [
-    [0, 0.8, 0.03, 1.0, 1.0, 1.5, 0],
-    [0.5, 1.9, 0.1, 0.95, 0.6, 1.8, 0.3],
-    [1.5, 3.3, 0.17, 0.9, 0.15, 2.0, 0.75],
-    [3, 5.3, 0.2, 0.85, 0, 2, 1],
-    [6, 9.3, 0.2, 0.8, 0, 2, 1],
-    [10, 14.7, 0.21, 0.75, 0, 2, 1],
-  ],
-  envelope: { exp: 3.5 }, flex: [0.15, 0.97], bend: 1.4, cBend: 2.6, bank: 0.35, bankGain: 0.12, pitchMax: 0.9, hover: 0.35,
-  clearance: 0.12, cruiseDepth: 0.6,
-  pectoral: { rest: [0, 0, 0], flap: 22, row: 18, feather: 25, fold: 26, flare: 55, alternate: 0.3, stiff: 0 },
-  pelvic: { rest: 0, spread: 10, fold: 14 },
-  breath: { rate: 1.2, operculum: 9, mouth: 0.18, ram: 2.5, slits: false },
-  jaw: { gape: 28, protrude: 0.02 },
-  actions: {},
-};
-
-const _m = new THREE.Matrix4(), _m2 = new THREE.Matrix4(), _q = new THREE.Quaternion(), _q2 = new THREE.Quaternion();
-const _v1 = new THREE.Vector3(), _v2 = new THREE.Vector3(), _v3 = new THREE.Vector3();
-
-function isObj(x) { return x && typeof x === 'object' && !Array.isArray(x); }
-function merge(a, b) {
-  if (!isObj(b)) return b === undefined ? a : b;
-  const o = { ...(isObj(a) ? a : {}) };
-  for (const [k, v] of Object.entries(b)) o[k] = isObj(v) && isObj(o[k]) ? merge(o[k], v) : v;
-  return o;
-}
-
-function resolveConfig(species, data) {
-  const base = species.motion || {};
-  const variant = data.params?.variant;
-  let spec = merge(DEFAULTS, { ...base, variants: undefined });
-  if (variant && base.variants && base.variants[variant]) spec = merge(spec, base.variants[variant]);
-  // named speeds replace the defaults (a species' gears are its own, e.g. a shark has no 'scull')
-  spec.speeds = (variant && base.variants?.[variant]?.speeds) || base.speeds || DEFAULTS.speeds;
-  const J = {};
-  for (const [k, v] of Object.entries(data.joints)) J[k] = new THREE.Vector3(v[0], v[1], v[2]);
-  const names = data.bones.map((b) => b.name);
-  const spine = names.filter((n) => /^spine\d+$/.test(n)).sort((a, b) => +a.slice(5) - +b.slice(5));
-  const caudal = names.filter((n) => /^caudal\d+$/.test(n)).sort((a, b) => +a.slice(6) - +b.slice(6));
-  if (!spine.length || !J.snout) throw new Error('procedural-animals swimmer: the rig needs snout, spine0..N (core/rig/swimmer.js)');
-  const chainBones = [...spine, ...caudal];
-  const bIndex = Object.fromEntries(names.map((n, i) => [n, i]));
-  const chainJ = chainBones.map((n) => J[data.bones[bIndex[n]].headJ]);
-  chainJ.push(J[data.bones[bIndex[chainBones[chainBones.length - 1]]].tailJ]);
-  const n = chainBones.length;
-  const segLen = new Float64Array(n), restPitch = new Float64Array(n), restYaw = new Float64Array(n);
-  for (let i = 0; i < n; i++) {
-    const d = _v1.copy(chainJ[i + 1]).sub(chainJ[i]);
-    segLen[i] = d.length();
-    restPitch[i] = Math.atan2(d.y, Math.hypot(d.x, d.z));
-    restYaw[i] = Math.atan2(d.x, -d.z);
-  }
-  const hd = _v1.copy(J.snout).sub(chainJ[0]);
-  const headLen = hd.length(), headPitch = Math.atan2(hd.y, Math.hypot(hd.x, hd.z));
-  // arc positions (from the snout) and body length
-  const sJ = new Float64Array(n + 1);
-  sJ[0] = headLen;
-  for (let i = 0; i < n; i++) sJ[i + 1] = sJ[i] + segLen[i];
-  const L = sJ[n];
-  const cfg = {
-    caudalStart: spine.length,
-    spec, J, L, n, chainBones, chainJ, segLen, restPitch, restYaw, headLen, headPitch, sJ, bIndex,
-    uJ: Float64Array.from(sJ, (s) => s / L),
-    gears: Object.fromEntries(Object.entries(spec.speeds).map(([k, v]) => [k, v * L])),
-    maxSpeed: spec.maxSpeed * L, burstSpeed: spec.burstSpeed * L, minSpeed: spec.minSpeed * L,
-    accel: spec.accel * L, decel: spec.decel * L,
-    hover: spec.hover * L, clearance: spec.clearance * L,
-    actions: spec.actions || {},
-  };
-  // amplitude envelope and bend distribution per joint
-  const env = spec.envelope || {};
-  const envAt = (u) => (env.pow ? Math.pow(Math.max(0, u), env.pow) : Math.exp((env.exp ?? 3.5) * (u - 1)));
-  cfg.envJ = Float64Array.from(cfg.uJ, envAt);
-  const [f0, f1] = spec.flex || [0.15, 0.97];
-  const bw = new Float64Array(n);
-  let bs = 0;
-  for (let i = 0; i < n; i++) {
-    const u = (cfg.uJ[i] + cfg.uJ[i + 1]) / 2;
-    bw[i] = smooth(f0 - 0.1, f0 + 0.1, u) * (1 - smooth(f1 - 0.05, f1 + 0.08, u)) * (0.5 + 0.5 * Math.sqrt(envAt(u)));
-    bs += bw[i];
-  }
-  for (let i = 0; i < n; i++) bw[i] /= bs || 1;
-  cfg.bendW = bw;
-  return cfg;
-}
-
-export function createSwimmerMotion(ctx) { return new SwimmerMotion(ctx); }
-
-export class SwimmerMotion {
-  constructor({ species, data, skeleton, ground, water, position, heading = 0, emit }) {
-    this.species = species;
-    this.cfg = resolveConfig(species, data);
-    const cfg = this.cfg;
-    this.sk = skeleton;
-    this.data = data;
-    this.ground = ground || (() => 0);
-    this.water = typeof water === 'function' ? water : null;
-    this.emit = emit || (() => {});
-    this.rand = prng((data.seed || 1) * 7919 + 29);
-    this.bone = {};
-    for (let i = 0; i < data.bones.length; i++) this.bone[data.bones[i].name] = skeleton.bones[i];
-    this.chainBoneObjs = cfg.chainBones.map((nm) => this.bone[nm]);
-    this.isChain = new Uint8Array(data.bones.length);
-    for (const nm of [...cfg.chainBones, 'head']) this.isChain[cfg.bIndex[nm]] = 1;
-    // ---- public contract
-    this.input = { speed: 0, heading, climb: 0, look: null, follow: null, target: null, targetSpeed: cfg.gears.cruise ?? cfg.L, crouch: 0, gait: null };
-    this.pos = new THREE.Vector3();
-    this.velocity = new THREE.Vector3();
-    this.heading = heading;
-    this.speed = 0;
-    this.lookTarget = new THREE.Vector3();
-    this.state = {
-      position: this.pos, heading, speed: 0, velocity: this.velocity, gait: 'stand', grounded: true,
-      action: null, posture: 'stand', eyelid: 0, eyeRoll: 0, nictitate: 0, lookTarget: null, inWater: true, depth: 0, pitch: 0, roll: 0,
-      stats: { gait: 'stand', freq: 0, duty: 0 },
-      legs: [],
-    };
-    this.headPose = { position: new THREE.Vector3(), quaternion: new THREE.Quaternion() };
-    this.debug = { targets: Array.from({ length: 6 }, () => new THREE.Vector3()) };
-    this.gears = cfg.gears;
-    this.gaits = Object.keys(cfg.gears);
-    this.lod = 0;
-    this.frame = 0;
-    this.time = 0;
-    // ---- dynamic state
-    this.pitch = 0; this.roll = 0; this.yawRate = 0; this.accS = 0;
-    this.pitchS = new Spring(0); this.rollS = new Spring(0); this.yawS = new Spring(0);
-    this.bendS = new Spring(0); this.archS = new Spring(0);
-    this.ampS = new Spring(0); this.freqS = new Spring(0.8); this.lamS = new Spring(1);
-    this.pectS = new Spring(1); this.pfS = new Spring(1.5); this.foldS = new Spring(0); this.flareS = new Spring(0);
-    this.pelS = new Spring(0);
-    this.gapeS = new Spring(0); this.protS = new Spring(0); this.opS = new Spring(0);
-    this.lookYawS = new Spring(0); this.lookPitchS = new Spring(0);
-    this.headLiftS = new Spring(0); this.eyeRollS = new Spring(0); this.nictS = new Spring(0);
-    this.turnSideS = new Spring(0);
-    this.phase = this.rand(); this.pPhase = this.rand(); this.bPhase = this.rand();
-    this.vy = 0; // vertical velocity (m/s) beyond the path pitch: hovering, sinking, ballistic flight
-    this.vh = 0; // horizontal speed in flight
-    this.air = false;
-    this.beached = false; // out of the water on dry ground: flopping back toward the nearest water
-    this.surfaceY = Infinity; // last known water surface (null callbacks keep the last value)
-    this.lift = 0; // hard clamp correction carried to the next frame
-    this.P = createSwimParams();
-    // ---- preallocated pose buffers
-    const n = cfg.n;
-    this.th = new Float64Array(n); this.ph = new Float64Array(n); this.yw = new Float64Array(n + 1);
-    this.Q = Array.from({ length: n + 2 }, () => new THREE.Vector3()); // Q[0] = spine0 ... Q[n] = tail tip, Q[n+1] = snout (local)
-    this.W = Array.from({ length: n + 2 }, () => new THREE.Vector3()); // world
-    this.D = Array.from({ length: n + 1 }, () => new THREE.Vector3()); // world bone directions (last = head)
-    this.X = Array.from({ length: n + 1 }, () => new THREE.Vector3()); // world lateral axes
-    this.basis = { F: new THREE.Vector3(), U: new THREE.Vector3(), Lf: new THREE.Vector3() };
-    this.gh = new Float64Array(3); // ground samples (snout, middle, tail)
-    // ---- mass weights, skin extents, children
-    this._measure(data);
-    this._children(data);
-    this.attachmentPoints = this._attachments(data);
-    this.actionsLayer = new SwimmerActions(this);
-    this.actions = this.actionsLayer.names;
-    this.reset(position || new THREE.Vector3(), heading);
-  }
-
-  // skin extents of every bone in its own bind frame (from the mesh), and a mass per chain segment
-  _measure(data) {
-    const cfg = this.cfg, sk = this.sk, nB = data.bones.length;
-    const ext = new Float64Array(nB * 6);
-    for (let b = 0; b < nB; b++) { ext[b * 6] = ext[b * 6 + 2] = ext[b * 6 + 4] = Infinity; ext[b * 6 + 1] = ext[b * 6 + 3] = ext[b * 6 + 5] = -Infinity; }
-    const massA = new Float64Array(nB * 4); // body-only lateral / dorsoventral extents (no fins)
-    for (let b = 0; b < nB; b++) { massA[b * 4] = massA[b * 4 + 2] = Infinity; massA[b * 4 + 1] = massA[b * 4 + 3] = -Infinity; }
-    const inv = sk.inverses || sk.bind.map((m) => m.clone().invert());
-    const p = new THREE.Vector3();
-    for (let v = 0; v < data.nV; v++) {
-      if (data.coat[v * 4 + 3] < 0.5) continue;
-      let bb = data.skinIndex[v * 4], bw = data.skinWeight[v * 4];
-      for (let k = 1; k < 4; k++) if (data.skinWeight[v * 4 + k] > bw) { bw = data.skinWeight[v * 4 + k]; bb = data.skinIndex[v * 4 + k]; }
-      p.set(data.pos[v * 3], data.pos[v * 3 + 1], data.pos[v * 3 + 2]).applyMatrix4(inv[bb]);
-      const o = bb * 6;
-      if (p.x < ext[o]) ext[o] = p.x; if (p.x > ext[o + 1]) ext[o + 1] = p.x;
-      if (p.y < ext[o + 2]) ext[o + 2] = p.y; if (p.y > ext[o + 3]) ext[o + 3] = p.y;
-      if (p.z < ext[o + 4]) ext[o + 4] = p.z; if (p.z > ext[o + 5]) ext[o + 5] = p.z;
-      if (Math.round(data.tint[v * 4 + 3]) !== 11) {
-        const q = bb * 4;
-        if (p.x < massA[q]) massA[q] = p.x; if (p.x > massA[q + 1]) massA[q + 1] = p.x;
-        if (p.z < massA[q + 2]) massA[q + 2] = p.z; if (p.z > massA[q + 3]) massA[q + 3] = p.z;
-      }
-    }
-    // the bone itself (head .. tail joint) is part of the body: fin tips are joints too
-    for (let b = 0; b < nB; b++) {
-      const bl = data.bones[b], h = data.joints[bl.headJ], t = data.joints[bl.tailJ];
-      const len = Math.hypot(t[0] - h[0], t[1] - h[1], t[2] - h[2]);
-      const o = b * 6;
-      if (!Number.isFinite(ext[o])) { ext[o] = ext[o + 1] = ext[o + 4] = ext[o + 5] = 0; ext[o + 2] = ext[o + 3] = 0; }
-      ext[o] = Math.min(ext[o], 0); ext[o + 1] = Math.max(ext[o + 1], 0);
-      ext[o + 2] = Math.min(ext[o + 2], 0); ext[o + 3] = Math.max(ext[o + 3], len);
-      ext[o + 4] = Math.min(ext[o + 4], 0); ext[o + 5] = Math.max(ext[o + 5], 0);
-    }
-    // ellipse / box extents: centre + half size per bone, local X (lateral), Y (along), Z (third)
-    this.ext = new Float64Array(nB * 6);
-    for (let b = 0; b < nB; b++) {
-      const o = b * 6;
-      this.ext[o] = (ext[o] + ext[o + 1]) / 2; this.ext[o + 1] = (ext[o + 1] - ext[o]) / 2;
-      this.ext[o + 2] = (ext[o + 2] + ext[o + 3]) / 2; this.ext[o + 3] = (ext[o + 3] - ext[o + 2]) / 2;
-      this.ext[o + 4] = (ext[o + 4] + ext[o + 5]) / 2; this.ext[o + 5] = (ext[o + 5] - ext[o + 4]) / 2;
-    }
-    // mass per chain segment (+ head as the last entry): cross-section area x length
-    const n = cfg.n;
-    this.mass = new Float64Array(n + 1);
-    const area = (b) => {
-      const q = b * 4;
-      const hx = Number.isFinite(massA[q]) ? (massA[q + 1] - massA[q]) / 2 : 0, hz = Number.isFinite(massA[q + 2]) ? (massA[q + 3] - massA[q + 2]) / 2 : 0;
-      return Math.max(1e-8, hx * hz);
-    };
-    let tot = 0;
-    for (let i = 0; i < n; i++) { this.mass[i] = area(cfg.bIndex[cfg.chainBones[i]]) * cfg.segLen[i]; tot += this.mass[i]; }
-    this.mass[n] = area(cfg.bIndex.head) * cfg.headLen * 1.3; tot += this.mass[n];
-    for (let i = 0; i <= n; i++) this.mass[i] /= tot;
-    // extents of the whole bind body below / above the centre (for spawning and clearance)
-    let lo = Infinity, hi = -Infinity;
-    for (let v = 0; v < data.nV; v++) { const y = data.pos[v * 3 + 1]; if (y < lo) lo = y; if (y > hi) hi = y; }
-    this.bindLow = lo; this.bindHigh = hi;
-    this.nB = nB;
-  }
-
-  // children of the chain: jaw, upper jaw, gill covers, paired fins (bind-space rotation axes)
-  _children(data) {
-    const J = this.cfg.J, sk = this.sk, bi = this.cfg.bIndex;
-    const V = (a) => (J[a] ? J[a].clone() : null);
-    const mk = (name, pivotJ, axes) => {
-      const i = bi[name];
-      if (i === undefined) return null;
-      const b = data.bones[i];
-      const pi = bi[b.parent];
-      const base = J[pivotJ || b.headJ];
-      const A = new THREE.Matrix4().copy(sk.inverses ? sk.inverses[pi] : sk.bind[pi].clone().invert()).multiply(new THREE.Matrix4().makeTranslation(base.x, base.y, base.z));
-      const C0 = sk.bind[i].clone().setPosition(0, 0, 0);
-      return { name, i, pi, bone: sk.bones[i], parent: sk.bones[pi], A, C0, axes, q: new THREE.Quaternion(), t: new THREE.Vector3(), M: new THREE.Matrix4() };
-    };
-    const axis = (a, b) => a && b ? new THREE.Vector3().copy(a).cross(b).normalize() : null;
-    this.kids = [];
-    // lower jaw: rotates down about the hinge
-    if (J.jawHinge && J.jawTip && bi.jaw !== undefined) {
-      const j = V('jawTip').sub(J.jawHinge).normalize();
-      this.kids.push(this.jaw = mk('jaw', 'jawHinge', { open: axis(j, new THREE.Vector3(0, -1, 0)) }));
-    }
-    if (bi.upperJaw !== undefined) this.kids.push(this.upperJaw = mk('upperJaw', null, {}));
-    this.opercula = [];
-    this.pecs = [];
-    this.pels = [];
-    for (const [S, s] of [['L', 1], ['R', -1]]) {
-      const out = new THREE.Vector3(s, 0, 0);
-      if (bi['operculum' + S] !== undefined) {
-        const e = V('opEdge' + S).sub(J['opHinge' + S]).normalize();
-        const k = mk('operculum' + S, null, { flare: axis(e, out) });
-        this.kids.push(k); this.opercula.push(k);
-      }
-      if (bi['pectoral' + S] !== undefined) {
-        const d = V('pecTip' + S).sub(J['pecBase' + S]).normalize();
-        const k = mk('pectoral' + S, null, { ab: axis(d, out), row: axis(d, new THREE.Vector3(0, 0, 1)), long: d.clone(), s });
-        this.kids.push(k); this.pecs.push(k);
-      }
-      if (bi['pelvic' + S] !== undefined) {
-        const d = V('pelTip' + S).sub(J['pelBase' + S]).normalize();
-        const k = mk('pelvic' + S, null, { ab: axis(d, out), long: d.clone(), s });
-        this.kids.push(k); this.pels.push(k);
-      }
-    }
-    this.kids = this.kids.filter(Boolean);
-    // children of the head must be posed after it; others after their spine bone (chain first)
-  }
-
-  _attachments(data) {
-    const J = this.cfg.J, sk = this.sk, bi = this.cfg.bIndex;
-    const at = (bone, p) => {
-      const i = bi[bone];
-      if (i === undefined || !p) return null;
-      const inv = sk.inverses ? sk.inverses[i] : sk.bind[i].clone().invert();
-      return { bone, local: new THREE.Matrix4().makeTranslation(p.x, p.y, p.z).premultiply(inv) };
-    };
-    let headP = J.snout.clone().lerp(this.cfg.chainJ[0], 0.5);
-    if (data.eyes?.length) { headP = new THREE.Vector3(); for (const e of data.eyes) headP.add(new THREE.Vector3(...e.c)); headP.multiplyScalar(1 / data.eyes.length); }
-    const k = Math.min(this.cfg.n - 1, Math.round(this.cfg.n * 0.3));
-    const back = this.cfg.chainJ[k].clone();
-    back.y = this.bindHigh;
-    const out = { mouth: at('head', J.snout), head: at('head', headP), back: at(this.cfg.chainBones[k], back) };
-    for (const kk of Object.keys(out)) if (!out[kk]) delete out[kk];
-    this._headLocal = at('head', headP)?.local || new THREE.Matrix4();
-    return out;
-  }
-
-  // ----------------------------------------------------------------- environment
-  groundAt(x, z) { const h = this.ground(x, z); return Number.isFinite(h) ? h : 0; }
-  surfaceAt(x, z) {
-    if (!this.water) return Infinity;
-    const w = this.water(x, z);
-    if (w !== null && w !== undefined && Number.isFinite(w)) this.surfaceY = w;
-    return this.surfaceY;
-  }
-  // depth of the water column at (x, z): 0 where water(x, z) gives no surface (dry land); Infinity
-  // without a water callback
-  waterDepth(x, z) {
-    if (!this.water) return Infinity;
-    const w = this.water(x, z);
-    if (w === null || w === undefined || !Number.isFinite(w)) return 0;
-    return w - this.groundAt(x, z);
-  }
-  // the water a body of this size can swim in: deeper than its own height (centre to belly + back)
-  swimDepth() { return 0.8 * (this.cBelow + this.cAbove) + this.cfg.clearance; }
-  // heading (rad) toward water at least `need` deep: the candidate nearest to `h0` among 24 directions
-  // at distance r (null when none)
-  wetHeading(h0, r, need) {
-    for (let k = 0; k <= 12; k++) {
-      for (const sgn of k === 0 || k === 12 ? [1] : [1, -1]) {
-        const h = h0 + sgn * k * (Math.PI / 12);
-        if (this.waterDepth(this.pos.x + Math.sin(h) * r, this.pos.z + Math.cos(h) * r) >= need) return h;
-      }
-    }
-    return null;
-  }
-  // the nearest water at least `need` deep: rings of 16 directions out to `rMax` (null when none)
-  nearestWater(need, rMax) {
-    const L = this.cfg.L;
-    for (let r = 0.25 * L; r <= rMax; r *= 1.3) {
-      let best = null, bd = -1;
-      for (let k = 0; k < 16; k++) {
-        const h = (k / 16) * Math.PI * 2;
-        const d = this.waterDepth(this.pos.x + Math.sin(h) * r, this.pos.z + Math.cos(h) * r);
-        if (d >= need && d > bd) { bd = d; best = h; }
-      }
-      if (best !== null) return { heading: best, dist: r };
-    }
-    return null;
-  }
-
-  // allowed range of the centre height at (x, z): bed + below-extent + clearance .. surface - above-extent - clearance
-  depthRange(x, z, out) {
-    const c = this.cfg, cl = c.clearance;
-    const g = this.groundAt(x, z), s = this.surfaceAt(x, z);
-    const below = this.cBelow, above = this.cAbove;
-    out.lo = g + below + cl;
-    out.hi = s - above - cl * 0.8;
-    if (out.hi < out.lo) out.hi = out.lo = Math.max(g + below + cl * 0.2, Math.min(out.lo, s - above));
-    return out;
-  }
-
-  reset(p, heading = this.heading) {
-    const cfg = this.cfg;
-    this.heading = heading; this.input.heading = heading;
-    this.speed = 0; this.velocity.set(0, 0, 0); this.vy = 0; this.yawRate = 0;
-    // centre of mass of the bind pose relative to the bind root, and the body's vertical extents
-    this.poseLocal(0);
-    let cy = 0;
-    for (let i = 0; i < cfg.n; i++) cy += this.mass[i] * (cfg.chainJ[i].y + cfg.chainJ[i + 1].y) / 2;
-    cy += this.mass[cfg.n] * (cfg.chainJ[0].y + cfg.J.snout.y) / 2;
-    this.cBelow = cy - this.bindLow; this.cAbove = this.bindHigh - cy;
-    this.pos.copy(p);
-    const r = this.depthRange(p.x, p.z, {});
-    const want = this.groundAt(p.x, p.z) + this.cBelow + cfg.spec.cruiseDepth * cfg.L;
-    if (!(p.y > r.lo && p.y < r.hi)) this.pos.y = clamp(Math.min(want, r.hi), r.lo, Math.max(r.lo, r.hi));
-    this.wantY = this.pos.y;
-    this.pitchS.reset(0); this.rollS.reset(0); this.yawS.reset(0); this.bendS.reset(0); this.archS.reset(0);
-    this.lift = 0; this.air = false;
-    this.beached = !!this.water && this.waterDepth(p.x, p.z) < 0.5 * (this.cBelow + this.cAbove);
-    if (this.beached) { this.pos.y = this.groundAt(p.x, p.z) + this.cBelow; this._strandSide = 1; }
-    this._init = true;
-  }
-
-  // ----------------------------------------------------------------- public API
-  play(name, opts) { return this.actionsLayer.play(name, opts || {}); }
-  stop(name) { this.actionsLayer.stop(name); }
-  setLod(level) { this.lod = clamp(level | 0, 0, 2); return this; }
-  dispose() { this.actionsLayer.clear(); }
-
-  update(dt) {
-    if (!(dt > 1e-4) || !Number.isFinite(dt)) dt = 1e-4;
-    dt = Math.min(dt, 1 / 20);
-    this.frame++;
-    this.time += dt;
-    this.drive(dt);
-    this.actionsLayer.update(dt);
-    this.step(dt);
-    this.pose(dt);
-    this.publish();
-  }
-
-  // steering input -> wanted speed, heading and height
-  drive(dt) {
-    const inp = this.input, cfg = this.cfg, L = cfg.L;
-    this.wantSpeed = clamp(inp.speed || 0, 0, cfg.maxSpeed);
-    this.wantHeading = inp.heading ?? this.heading;
-    this.wantPitch = clamp(inp.climb || 0, -1, 1) * cfg.spec.pitchMax;
-    this.wantVy = clamp(inp.climb || 0, -1, 1) * cfg.hover;
-    this.targetY = null;
-    if (inp.target && !inp.follow) {
-      const t = inp.target;
-      const dx = t.x - this.pos.x, dz = t.z - this.pos.z, dy = t.y - this.pos.y;
-      const d = Math.hypot(dx, dz, dy);
-      const stopR = 0.4 * L + 0.05 * this.speed;
-      if (d < stopR) { inp.target = null; inp.speed = 0; this.wantSpeed = 0; this.emit('arrive', {}); }
-      else {
-        const want = Math.atan2(dx, dz);
-        inp.heading = want;
-        this.wantHeading = want;
-        this.wantPitch = clamp(Math.atan2(dy, Math.hypot(dx, dz)), -cfg.spec.pitchMax, cfg.spec.pitchMax);
-        this.targetY = t.y;
-        const brake = Math.sqrt(Math.max(0, 2 * cfg.decel * 0.7 * (d - stopR)));
-        this.wantSpeed = Math.min(inp.targetSpeed || cfg.gears.cruise || L, cfg.maxSpeed, brake + 0.1 * L);
-      }
-    }
-    if (this.actionsLayer.holdsStill()) {
-      if (this.wantSpeed > 0.05 * L && !inp.follow) this.actionsLayer.requestStand();
-      this.wantSpeed = 0; this.wantPitch = 0; this.wantVy = 0;
-      this.wantHeading = this.heading;
-    } else if (!inp.follow && this.wantSpeed < 0.05 * L) {
-      // turn toward a look target behind
-      const lt = inp.look;
-      if (lt) {
-        const want = Math.atan2(lt.x - this.pos.x, lt.z - this.pos.z);
-        const off = angDiff(this.heading, want);
-        if (Math.abs(off) > 0.7) this._turnTo = want;
-        else if (this._turnTo !== undefined && Math.abs(off) < 0.2) this._turnTo = undefined;
-        if (this._turnTo !== undefined) { this.wantHeading = this._turnTo; inp.heading = this._turnTo; }
-      } else this._turnTo = undefined;
-    }
-    // obligate ram ventilators keep swimming: slow circles when asked to stop
-    if (cfg.minSpeed > 0 && this.wantSpeed < cfg.minSpeed && !inp.follow && this.P.alive > 0.5) {
-      this.wantSpeed = cfg.minSpeed;
-      // circle at patrolRadius (the heading controller turns at 5 x the heading error)
-      if (!inp.target) this.wantHeading = this.heading + (cfg.spec.patrolRadius > 0 ? Math.max(this.speed, cfg.minSpeed) / (cfg.spec.patrolRadius * L * 5) : 0.25);
-    }
-    this.avoidShore();
-  }
-
-  // shores: water too shallow for the body ahead (or dry land) turns the fish toward deep water and,
-  // close in, slows it down so it can turn inside its turning radius. Only where water(x, z) ends or
-  // the bed rises into the body's height (an open water column never triggers it).
-  avoidShore() {
-    if (!this.water || this.air || this.beached || this.input.follow) return;
-    const L = this.cfg.L, need = this.swimDepth();
-    const v = Math.max(this.speed, this.wantSpeed);
-    const h = this.heading;
-    const near = 0.6 * L + v * 0.6, far = 1.0 * L + v * 1.5;
-    const dNear = this.waterDepth(this.pos.x + Math.sin(h) * near, this.pos.z + Math.cos(h) * near);
-    const dFar = this.waterDepth(this.pos.x + Math.sin(h) * far, this.pos.z + Math.cos(h) * far);
-    // also where the fish is asked to go
-    const hw = this.wantHeading;
-    const dWant = this.waterDepth(this.pos.x + Math.sin(hw) * far, this.pos.z + Math.cos(hw) * far);
-    this.shore = 0;
-    if (dFar >= need && dNear >= need && dWant >= need) return;
-    const okWant = dWant >= need && this.waterDepth(this.pos.x + Math.sin(hw) * near, this.pos.z + Math.cos(hw) * near) >= need;
-    const hNew = okWant ? hw : this.wetHeading(hw, far, need) ?? this.wetHeading(hw, near, need) ?? this.nearestWater(need, 6 * L)?.heading;
-    if (hNew === null || hNew === undefined) return;
-    this.wantHeading = hNew;
-    this.input.heading = hNew;
-    // close to the shore and still heading at it: brake to turn tighter
-    const urgency = dNear < need ? 1 : dFar < need ? 0.5 : 0;
-    this.shore = urgency;
-    if (urgency > 0) this.wantSpeed = Math.min(this.wantSpeed, Math.max(this.cfg.minSpeed || 0, (urgency > 0.9 ? 0.4 : 0.9) * L));
-  }
-
-  // ----------------------------------------------------------------- simulation
-  step(dt) {
-    const cfg = this.cfg, inp = this.input, P = this.P, L = cfg.L, sp = cfg.spec;
-    const rng = this._rng || (this._rng = {});
-    // ---- follow: an external body places the fish
-    if (inp.follow) {
-      const fv = inp.follow.velocity, fp = inp.follow.position;
-      const v3 = Math.hypot(fv.x, fv.y, fv.z);
-      this.speed = v3;
-      if (Math.hypot(fv.x, fv.z) > 0.02 * L) this.wantHeading = inp.follow.heading ?? Math.atan2(fv.x, fv.z);
-      else if (inp.follow.heading !== null && inp.follow.heading !== undefined) this.wantHeading = inp.follow.heading;
-      const err = angDiff(this.heading, this.wantHeading);
-      const yr = clamp(err * 8, -sp.turnRate * 2, sp.turnRate * 2);
-      this.yawRate = this.yawS.step(yr, 18, dt);
-      this.heading += this.yawRate * dt;
-      this.pitch = this.pitchS.step(v3 > 0.05 * L ? clamp(Math.atan2(fv.y, Math.hypot(fv.x, fv.z)), -sp.pitchMax, sp.pitchMax) : 0, 6, dt);
-      // velocity feed-forward + a stiff pull toward the followed point (smooths a jittery body)
-      const r = this.depthRange(fp.x, fp.z, rng);
-      const ty = fp.y > r.lo && fp.y < r.hi ? fp.y : clamp(this.pos.y, r.lo, Math.max(r.lo, r.hi));
-      const k = 1 - Math.exp(-dt * 25);
-      this.pos.x += fv.x * dt; this.pos.z += fv.z * dt; this.pos.y += fv.y * dt;
-      this.pos.x += (fp.x - this.pos.x) * k; this.pos.z += (fp.z - this.pos.z) * k; this.pos.y += (ty - this.pos.y) * (1 - Math.exp(-dt * 6));
-      this.velocity.copy(fv);
-      this.air = false;
-      this.advancePhases(dt);
-      return;
-    }
-    if (this.beached) { this.stepBeached(dt); return; }
-    // ---- speed (with a smoothed acceleration: no jerk pops)
-    const want = lerp(this.wantSpeed, P.speed, P.speedW);
-    if (!this.air) {
-      const dv = want - this.speed;
-      const aCmd = clamp(dv * 6, -cfg.decel * (1 + 2 * P.brake), cfg.accel * (1 + P.accelK));
-      this.accS += (aCmd - this.accS) * (1 - Math.exp(-dt * 14));
-      this.speed = Math.max(0, this.speed + this.accS * dt);
-      if (this.speed < 1e-4 && want <= 0) { this.speed = 0; if (this.accS < 0) this.accS = 0; }
-    }
-    // ---- heading: wanted yaw rate from the heading error, limited by the turning radius at speed
-    let wantH = this.wantHeading;
-    if (P.headingW > 0) wantH = this.wantHeading + angDiff(this.wantHeading, P.heading) * P.headingW;
-    const err = angDiff(this.heading, wantH);
-    const vmin = 0.6 * L;
-    const yMax = Math.min(sp.turnRate * (1 + P.turnK), (Math.max(this.speed, vmin) / (sp.turnRadius * L)));
-    const yr = clamp(err * 5, -yMax, yMax) + P.yawRate;
-    this.yawRate = this.yawS.step(yr, 12 * (1 + P.turnK), dt);
-    if (!this.air) this.heading += this.yawRate * dt;
-    // ---- pitch and height: climb input, targets, clearance to the bed and the surface
-    const r = this.depthRange(this.pos.x, this.pos.z, rng);
-    let wantP = this.wantPitch;
-    // look ahead: the bed rising in front makes the fish climb
-    const la = L * 0.8 + this.speed * 0.5;
-    const fx = Math.sin(this.heading), fz = Math.cos(this.heading);
-    const r2 = this.depthRange(this.pos.x + fx * la, this.pos.z + fz * la, this._r2 || (this._r2 = {}));
-    const lo = Math.max(r.lo, r2.lo), hi = Math.min(r.hi, r2.hi) < lo ? lo : Math.min(r.hi, r2.hi);
-    if (this.targetY !== null) this.wantY = clamp(this.targetY, lo, hi);
-    else if (Math.abs(this.wantVy) > 1e-4 || Math.abs(this.wantPitch) > 1e-3) this.wantY = this.pos.y;
-    this.wantY = clamp(this.wantY ?? this.pos.y, lo, hi);
-    // keep the height: pitch toward the wanted height at speed, hover up / down when slow
-    const dyW = this.wantY - this.pos.y;
-    const fast = smooth(0.15 * L, 0.8 * L, this.speed);
-    if (Math.abs(this.wantPitch) < 1e-3) wantP = clamp(Math.atan2(dyW * 2, Math.max(L, this.speed * 1.2)), -0.5, 0.5) * fast;
-    wantP = lerp(wantP, P.pitch, P.pitchW);
-    // near the bed / surface limits, only allow pitching away from them
-    if (this.pos.y <= lo + 0.02 * L) wantP = Math.max(wantP, 0);
-    if (this.pos.y >= hi - 0.02 * L && !P.breach) wantP = Math.min(wantP, 0);
-    this.pitch = this.air ? this.pitch : this.pitchS.step(wantP, 5 * (1 + P.pitchK), dt);
-    // ---- velocity
-    const cp = Math.cos(this.pitch), spn = Math.sin(this.pitch);
-    const surf = this.surfaceAt(this.pos.x, this.pos.z);
-    if (this.air) {
-      // ballistic: the horizontal speed is kept, gravity bends the path, the body follows it
-      this.vy -= 9.81 * dt;
-      this.pitch = this.pitchS.step(Math.atan2(this.vy, Math.max(0.1 * L, this.vh)), 7, dt);
-    } else {
-      // hover: slow vertical swimming toward the wanted height (climb input when slow); settle / sink
-      const hoverV = clamp(this.wantVy + dyW * 1.5 * (1 - fast), -cfg.hover, cfg.hover) * (1 - fast);
-      const vyT = lerp(hoverV, P.vy, P.vyW);
-      this.vy += (vyT - this.vy) * (1 - Math.exp(-dt * 4));
-    }
-    const hs = this.air ? this.vh : this.speed * cp;
-    this.velocity.set(fx * hs, this.air ? this.vy : this.speed * spn + this.vy, fz * hs);
-    this.velocity.x += P.push.x; this.velocity.z += P.push.z; this.velocity.y += P.push.y;
-    const ox = this.pos.x, oz = this.pos.z;
-    this.pos.addScaledVector(this.velocity, dt);
-    // ---- shores: never swim into water shallower than the body (the move is undone; a push or an
-    // action may still drive the fish there, it then stops at the edge)
-    if (!this.air && this.water) {
-      const need = this.swimDepth();
-      const dN = this.waterDepth(this.pos.x, this.pos.z);
-      if (dN < need && dN < this.waterDepth(ox, oz)) {
-        this.pos.x = ox; this.pos.z = oz;
-        this.speed *= Math.exp(-dt * 6);
-      }
-    }
-    // ---- in / out of the water
-    const top = this.pos.y + this.cAbove * 0.2;
-    const gNow = this.groundAt(this.pos.x, this.pos.z);
-    const wetNow = this.waterDepth(this.pos.x, this.pos.z);
-    if (!this.air && top > surf && (P.breach || this.vy + this.speed * spn > 0.8 * L) && this.water) {
-      this.air = true;
-      this.vy = this.speed * spn + this.vy;
-      this.vh = this.speed * cp;
-      this.aimLeap(surf);
-      this.emit('takeoff', { position: this.pos.clone(), speed: this.speed });
-    } else if (this.air && this.pos.y - this.cBelow < gNow + 0.02 * L && wetNow < 0.5 * (this.cBelow + this.cAbove)) {
-      // came down on dry ground (or in water too shallow to swim): beached
-      this.air = false;
-      this.beached = true;
-      this.pos.y = Math.max(this.pos.y, gNow + this.cBelow);
-      this.emit('beach', { position: this.pos.clone(), speed: Math.hypot(this.vy, this.vh) });
-      this.speed = 0; this.vy = 0; this.vh = 0; this.accS = 0;
-      this.actionsLayer.onLand?.();
-      this._toWater = null; this._toWaterT = 0; this._strandSide = this.rand() < 0.5 ? -1 : 1;
-      this.advancePhases(dt);
-      return;
-    } else if (this.air && this.pos.y < surf - this.cBelow * 0.3 && wetNow > 0) {
-      this.air = false;
-      this.emit('land', { position: this.pos.clone(), speed: Math.abs(this.vy), splash: true });
-      this.actionsLayer.onLand?.();
-      // continue along the current pitch with the same velocity; the water drag slows it (actions brake)
-      const c2 = Math.max(0.3, Math.cos(this.pitch));
-      this.speed = this.vh / c2;
-      this.vy = this.vy - this.speed * Math.sin(this.pitch);
-      this.accS = 0;
-    }
-    if (!this.air) {
-      // soft limits: the controller should never get here, but a sinking corpse or a strong push can
-      const rr = this.depthRange(this.pos.x, this.pos.z, rng);
-      const loY = P.groundW > 0 ? lerp(rr.lo, rr.lo - cfg.clearance, P.groundW) : rr.lo;
-      if (this.pos.y < loY) { this.pos.y += (loY - this.pos.y) * (1 - Math.exp(-dt * 10)); this.vy = Math.max(this.vy, 0); }
-      if (this.pos.y > rr.hi && !P.breach && !P.surfaceOK) { this.pos.y += (rr.hi - this.pos.y) * (1 - Math.exp(-dt * 10)); this.vy = Math.min(this.vy, 0); }
-    }
-    // ---- bank into turns (+ action roll)
-    const bank = clamp(-this.yawRate * Math.max(this.speed, 0.3 * L) / L * (sp.bankGain ?? 0.12), -sp.bank, sp.bank);
-    this.roll = this.rollS.step(lerp(bank, P.roll, P.rollW), 4 * (1 + P.rollK), dt);
-    this.advancePhases(dt);
-  }
-
-  // a leap out of the water comes down in water deep enough: the horizontal speed is cut so the
-  // landing point (and half a body length past it) stays over deep water along the heading
-  aimLeap(surf) {
-    const L = this.cfg.L, g = 9.81, need = this.swimDepth();
-    const yLand = surf - 0.3 * this.cBelow;
-    const tF = (this.vy + Math.sqrt(Math.max(0, this.vy * this.vy + 2 * g * Math.max(0, this.pos.y - yLand)))) / g;
-    if (!(tF > 1e-3) || !(this.vh > 0)) return;
-    const fx = Math.sin(this.heading), fz = Math.cos(this.heading);
-    const D = this.vh * tF, step = 0.2 * L;
-    let ok = 0;
-    for (let d = 0; d <= D + 1e-6; d += step) {
-      if (this.waterDepth(this.pos.x + fx * (d + 0.5 * L), this.pos.z + fz * (d + 0.5 * L)) < need) break;
-      ok = d;
-    }
-    if (ok < D) this.vh = Math.max(0, ok) / tF;
-  }
-
-  // beached: the body lies on the ground and flops (strong, slow tail beats, a rocking roll) while it
-  // slides toward the nearest water; deep enough there, it swims on
-  stepBeached(dt) {
-    const cfg = this.cfg, L = cfg.L;
-    const need = 0.6 * (this.cBelow + this.cAbove);
-    this._toWaterT = (this._toWaterT || 0) - dt;
-    if (!this._toWater || this._toWaterT <= 0) {
-      this._toWater = this.nearestWater(need, 30 * L);
-      this._toWaterT = 0.5;
-    }
-    const to = this._toWater;
-    const alive = this.P.alive > 0.5;
-    const flop = alive ? clamp(0.3 * L, 0.3, 1.2) : 0;
-    if (to && alive) {
-      const err = angDiff(this.heading, to.heading);
-      this.yawRate = this.yawS.step(clamp(err * 2, -0.9, 0.9), 8, dt);
-      this.heading += this.yawRate * dt;
-      // slides toward the water (not only along the body: it flips and rolls its way there)
-      this.pos.x += Math.sin(to.heading) * flop * dt;
-      this.pos.z += Math.cos(to.heading) * flop * dt;
-    } else this.yawRate = this.yawS.step(0, 8, dt);
-    this.speed = flop;
-    this.wantSpeed = 0;
-    // lying on the ground (the skin clamp keeps it on the bed), level, rocking with the beats
-    const g = this.groundAt(this.pos.x, this.pos.z);
-    this.vy -= 9.81 * dt;
-    this.pos.y += this.vy * dt;
-    if (this.pos.y < g + this.cBelow) { this.pos.y = g + this.cBelow; this.vy = 0; }
-    this.pitch = this.pitchS.step(0, 5, dt);
-    const side = (cfg.spec.strandRoll ?? 1.3) * this._strandSide;
-    this.roll = this.rollS.step(side + (alive ? 0.3 * Math.sin(this.phase * Math.PI * 2) : 0), 6, dt);
-    this.velocity.set(to && alive ? Math.sin(to.heading) * flop : 0, 0, to && alive ? Math.cos(to.heading) * flop : 0);
-    // back in the water
-    if (this.waterDepth(this.pos.x, this.pos.z) >= need) {
-      this.beached = false;
-      this.speed = flop; this.vy = 0; this.accS = 0;
-      this.wantY = this.pos.y;
-      this.emit('land', { position: this.pos.clone(), speed: flop, splash: true });
-    }
-    this.advancePhases(dt);
-  }
-
-  advancePhases(dt) {
-    const cfg = this.cfg, P = this.P, L = cfg.L, sp = cfg.spec;
-    const vbl = this.speed / L;
-    const row = this._row || (this._row = new Float64Array(6));
-    tableAt6(sp.wave, vbl, row);
-    const fl = this.beached && P.alive > 0.5 ? 1 : 0;
-    const f = row[0] * P.freqK + P.freqAdd + fl * 1.2;
-    this.freqS.step(f, 8, dt);
-    this.ampS.step(fl ? Math.max(row[1] * 2.2, 0.45) : row[1] * P.ampK * (this.air ? 0.6 : 1), 6, dt);
-    this.lamS.step(row[2], 4, dt);
-    this.pectS.step(row[3] * P.pectK, 5, dt);
-    this.pfS.step(row[4], 4, dt);
-    this.foldS.step(clamp(row[5] + P.fold, 0, 1), 6, dt);
-    this.phase += Math.max(0, this.freqS.x) * dt;
-    if (this.phase > 1e4) this.phase -= 1e4;
-    this.pPhase += this.pfS.x * dt * (0.4 + 0.6 * this.pectS.x);
-    const bRate = sp.breath.rate * P.breathRate * (1 + P.stress * 0.9);
-    this.bPhase += bRate * dt;
-    this.stressDecay(dt);
-  }
-  stressDecay(dt) { this.P.stress *= 1; void dt; }
-
-  // ----------------------------------------------------------------- pose
-  // Local chain: segment angles -> joint positions (spine0 at the origin; body frame x = left, y = up,
-  // z = forward) -> centred on the mass centre.
-  poseLocal(dt) {
-    const cfg = this.cfg, n = cfg.n, P = this.P, L = cfg.L, sp = cfg.spec;
-    const th = this.th, ph = this.ph, yw = this.yw, Q = this.Q, m = this.mass;
-    const amp = dt > 0 ? this.ampS.x : 0, lam = Math.max(0.3, this.lamS.x);
-    const phi = this.phase;
-    // lateral wave displacement at each joint (0 = spine0 ... n = tail tip)
-    for (let j = 0; j <= n; j++) {
-      const u = cfg.uJ[j];
-      yw[j] = 0.5 * amp * L * cfg.envJ[j] * Math.sin(TAU * (phi - u / lam));
-    }
-    // the caudal fin is a fairly stiff plate hinged at the peduncle: past the caudal base the wave
-    // gives way to the peduncle's own slope (a thunniform tail is fully stiff)
-    const jb = cfg.caudalStart, cs = sp.caudalStiff ?? 0.6;
-    if (jb > 0 && jb < n && cs > 0) {
-      const slope = (yw[jb] - yw[jb - 1]) / cfg.segLen[jb - 1];
-      for (let j = jb + 1; j <= n; j++) yw[j] += (yw[jb] + slope * (cfg.sJ[j] - cfg.sJ[jb]) - yw[j]) * cs;
-    }
-    // steering bend (+ action C-bend) distributed over the flexible body, and the action arch
-    const bend = dt > 0 ? this.bendS.x : 0, arch = dt > 0 ? this.archS.x : 0;
-    let cum = 0, mean = 0;
-    for (let i = 0; i < n; i++) {
-      const dy = (yw[i + 1] - yw[i]) / cfg.segLen[i];
-      th[i] = Math.asin(clamp(dy, -0.95, 0.95)) + cfg.restYaw[i];
-      cum += bend * cfg.bendW[i];
-      th[i] += cum - bend * cfg.bendW[i] * 0.5;
-      ph[i] = cfg.restPitch[i] - arch * cfg.bendW[i] * n * (cfg.uJ[i] - 0.45) * 1.2 + P.droop * cfg.bendW[i] * n * Math.max(0, cfg.uJ[i] - 0.5);
-      mean += th[i] * m[i];
-    }
-    // head: continues the first trunk segment, turned by the look yaw
-    const headTh0 = th[0] - (P.headWave * (yw[1] - yw[0])) / cfg.segLen[0];
-    mean += headTh0 * m[n];
-    for (let i = 0; i < n; i++) th[i] -= mean;
-    this.headTh = headTh0 - mean + (dt > 0 ? this.lookYawS.x + P.headShake : 0);
-    this.headPh = cfg.headPitch + (dt > 0 ? this.lookPitchS.x + this.headLiftS.x : 0) + arch * 0.15;
-    // integrate joint positions (backward from spine0)
-    Q[0].set(0, 0, 0);
-    for (let i = 0; i < n; i++) {
-      const c = Math.cos(ph[i]);
-      Q[i + 1].set(Q[i].x + cfg.segLen[i] * Math.sin(th[i]) * c, Q[i].y + cfg.segLen[i] * Math.sin(ph[i]), Q[i].z - cfg.segLen[i] * Math.cos(th[i]) * c);
-    }
-    const hc = Math.cos(this.headPh);
-    Q[n + 1].set(-cfg.headLen * Math.sin(this.headTh) * hc, cfg.headLen * Math.sin(this.headPh), cfg.headLen * Math.cos(this.headTh) * hc);
-    // mass centre
-    let cx = 0, cy = 0, cz = 0;
-    for (let i = 0; i < n; i++) { cx += m[i] * (Q[i].x + Q[i + 1].x) * 0.5; cy += m[i] * (Q[i].y + Q[i + 1].y) * 0.5; cz += m[i] * (Q[i].z + Q[i + 1].z) * 0.5; }
-    cx += m[n] * Q[n + 1].x * 0.5; cy += m[n] * Q[n + 1].y * 0.5; cz += m[n] * Q[n + 1].z * 0.5;
-    for (let j = 0; j <= n + 1; j++) Q[j].set(Q[j].x - cx, Q[j].y - cy, Q[j].z - cz);
-    this.bindCom = this.bindCom || new THREE.Vector3(cfg.chainJ[0].x + cx, cfg.chainJ[0].y + cy, cfg.chainJ[0].z + cz);
-    void sp;
-  }
-
-  pose(dt) {
-    const cfg = this.cfg, n = cfg.n, P = this.P, sp = cfg.spec, L = cfg.L;
-    // ---- secondary springs
-    const turnBend = clamp(this.yawRate / Math.max(this.speed, 0.5 * L) * L * 0.75, -sp.bend, sp.bend);
-    this.bendS.step(turnBend * (1 - P.bendHold) + P.bend, 14 * (1 + P.bendK), dt);
-    this.archS.step(P.arch, 7, dt);
-    // look: the head turns only with the body; a little yaw from a slight bend, pitch from the body
-    const lt = this.input.look || P.look;
-    let lyaw = 0, lpit = 0;
-    if (lt && P.lookW > 0) {
-      const dx = lt.x - this.pos.x, dz = lt.z - this.pos.z, dy = lt.y - this.pos.y;
-      lyaw = clamp(angDiff(this.heading, Math.atan2(dx, dz)), -0.6, 0.6) * 0.22 * P.lookW;
-      lpit = clamp(Math.atan2(dy, Math.hypot(dx, dz)), -0.5, 0.5) * 0.15 * P.lookW;
-      this.lookTarget.copy(lt);
-      this.state.lookTarget = this.lookTarget;
-    } else this.state.lookTarget = null;
-    this.lookYawS.step(lyaw, 5, dt); this.lookPitchS.step(lpit, 5, dt);
-    this.headLiftS.step(P.headLift, 14, dt);
-    this.eyeRollS.step(P.eyeRoll, 22, dt); this.nictS.step(P.nictitate, 22, dt);
-    this.poseLocal(dt);
-    // ---- world basis: heading, pitch, roll
-    const B = this.basis, h = this.heading, p = this.pitch, r = this.roll;
-    const ch = Math.cos(h), shh = Math.sin(h), cp = Math.cos(p), spp = Math.sin(p);
-    const F = B.F.set(shh * cp, spp, ch * cp);
-    const L0 = _v1.set(ch, 0, -shh);
-    const U0 = _v2.crossVectors(F, L0);
-    const cr = Math.cos(r), sr = Math.sin(r);
-    B.Lf.copy(L0).multiplyScalar(cr).addScaledVector(U0, sr);
-    B.U.copy(U0).multiplyScalar(cr).addScaledVector(L0, -sr);
-    const Q = this.Q, W = this.W, o = this.pos;
-    for (let j = 0; j <= n + 1; j++) {
-      const q = Q[j];
-      W[j].set(o.x + q.x * B.Lf.x + q.y * B.U.x + q.z * F.x, o.y + q.x * B.Lf.y + q.y * B.U.y + q.z * F.y, o.z + q.x * B.Lf.z + q.y * B.U.z + q.z * F.z);
-    }
-    // lateral axes of the segments (body-local (cos th, 0, sin th)) and of the head
-    for (let i = 0; i < n; i++) {
-      const c = Math.cos(this.th[i]), s = Math.sin(this.th[i]);
-      this.X[i].set(c * B.Lf.x + s * F.x, c * B.Lf.y + s * F.y, c * B.Lf.z + s * F.z);
-    }
-    {
-      const c = Math.cos(this.headTh), s = Math.sin(this.headTh);
-      this.X[n].set(c * B.Lf.x + s * F.x, c * B.Lf.y + s * F.y, c * B.Lf.z + s * F.z);
-    }
-    // ---- bed contact (lying, dead): conform the chain to the uneven bed
-    if (P.conform > 0.001) this.conform(P.conform);
-    // ---- write the chain
-    for (let i = 0; i < n; i++) {
-      this.D[i].copy(W[i + 1]).sub(W[i]);
-      writeFrame(this.chainBoneObjs[i].matrixWorld, W[i], this.D[i], this.X[i]);
-    }
-    this.D[n].copy(W[n + 1]).sub(W[0]);
-    writeFrame(this.bone.head.matrixWorld, W[0], this.D[n], this.X[n]);
-    // ---- children: jaw, gill covers, fins
-    this.poseChildren(dt);
-    // ---- hard clamp: skin extents against the bed and the surface
-    this.clampToWater();
-    // ---- head pose (eyes, attachments)
-    _m.multiplyMatrices(this.bone.head.matrixWorld, this._headLocal);
-    this.headPose.position.setFromMatrixPosition(_m);
-    this.headPose.quaternion.setFromRotationMatrix(this.bone.head.matrixWorld);
-    const dbg = this.debug.targets;
-    dbg[0].copy(W[n]); dbg[1].copy(W[n + 1]); dbg[2].copy(this.pos);
-    if (this.state.lookTarget) dbg[3].copy(this.state.lookTarget);
-  }
-
-  conform(w) {
-    const cfg = this.cfg, n = cfg.n, W = this.W;
-    const dl = this._dl || (this._dl = new Float64Array(n + 2)), d2 = this._d2 || (this._d2 = new Float64Array(n + 2));
-    // the body's lowest skin under each joint, from the bone extents in the current orientation
-    for (let j = 0; j <= n + 1; j++) {
-      const bi = j === n + 1 ? cfg.bIndex.head : cfg.bIndex[cfg.chainBones[Math.min(n - 1, j)]];
-      const e = this.ext, oo = bi * 6;
-      const X = j === n + 1 ? this.X[n] : this.X[Math.min(n - 1, j)];
-      // local Z of the bone frame ~ X x Y; use the body up rotated with the roll
-      const Z = _v3.crossVectors(X, j === n + 1 ? _v1.copy(W[n + 1]).sub(W[0]).normalize() : _v1.copy(W[Math.min(n, j + 1)]).sub(W[Math.min(n - 1, j)]).normalize());
-      const below = Math.sqrt((e[oo + 1] * X.y) ** 2 + (e[oo + 5] * Z.y) ** 2) - (e[oo] * X.y + e[oo + 4] * Z.y);
-      const g = this.groundAt(W[j].x, W[j].z);
-      dl[j] = g + below + 0.004 * cfg.L - W[j].y;
-    }
-    // smooth the corrections along the chain (snout = n + 1 sits before spine0): no kinks
-    for (let it = 0; it < 3; it++) {
-      for (let j = 0; j <= n; j++) {
-        const prev = j === 0 ? dl[n + 1] : dl[j - 1], next = j === n ? dl[n] : dl[j + 1];
-        d2[j] = 0.25 * prev + 0.5 * dl[j] + 0.25 * next;
-      }
-      d2[n + 1] = 0.5 * dl[n + 1] + 0.5 * dl[0];
-      for (let j = 0; j <= n + 1; j++) dl[j] = d2[j];
-    }
-    for (let j = 0; j <= n + 1; j++) W[j].y += dl[j] * w;
-  }
-
-  poseChildren(dt) {
-    const cfg = this.cfg, P = this.P, sp = cfg.spec, L = cfg.L;
-    const vbl = this.speed / L;
-    // breathing: gill covers out, mouth open in counter-phase; fades with ram ventilation
-    const ram = 1 - smooth(sp.breath.ram * 0.5, sp.breath.ram * 1.2, vbl) * 0.8;
-    const b = Math.sin(TAU * this.bPhase);
-    const bAmp = P.breathAmp * ram * (1 + P.stress * 0.8);
-    const opT = (0.5 + 0.5 * b) * bAmp + P.opFlare;
-    this.opS.step(opT, 18, dt);
-    const gapeT = clamp((0.5 - 0.5 * b) * sp.breath.mouth * bAmp + P.gape, 0, 1.2);
-    this.gapeS.step(gapeT, P.gapeFast ? 45 : 16, dt);
-    this.protS.step(P.protrude, 30, dt);
-    const D2R = Math.PI / 180;
-    for (const k of this.kids) {
-      const q = k.q.identity();
-      k.t.set(0, 0, 0);
-      if (k === this.jaw) {
-        q.setFromAxisAngle(k.axes.open, this.gapeS.x * sp.jaw.gape * D2R);
-      } else if (k === this.upperJaw) {
-        const pd = sp.jaw.protrudeDir;
-        if (pd) k.t.set(pd[0], pd[1], pd[2]); else k.t.set(0, -0.3, 1);
-        k.t.normalize().multiplyScalar(this.protS.x * sp.jaw.protrude * L);
-      } else if (k.axes.flare) {
-        q.setFromAxisAngle(k.axes.flare, this.opS.x * sp.breath.operculum * D2R);
-      } else if (k.axes.row) {
-        // pectoral: sculling (flap + row + feather) when slow, folded at speed, flared to brake
-        const pc = sp.pectoral, s = k.axes.s;
-        const alt = s > 0 ? 0 : pc.alternate * 0.5;
-        const ph = TAU * (this.pPhase + alt);
-        const act = this.pectS.x * (1 - pc.stiff) * P.pectAmp;
-        const fold = this.foldS.x;
-        const turnIn = clamp(this.yawRate * s * 0.5, -1, 1); // inside fin of a turn flares
-        const flare = clamp(this.flareS.step(Math.max(P.flare, P.brake * 0.9, turnIn * 0.5 * (1 - fold)), 10, dt), 0, 1.2);
-        const ab = (pc.rest[0] * (1 - fold) - pc.fold * fold + pc.flap * act * Math.sin(ph) + (pc.flare - pc.rest[0]) * flare + P.pectAb) * D2R;
-        const row = (pc.rest[1] + pc.row * act * Math.sin(ph + 1.3) + 20 * flare) * D2R;
-        const fe = (pc.rest[2] + pc.feather * act * Math.cos(ph) + 30 * flare) * D2R;
-        q.setFromAxisAngle(k.axes.ab, ab);
-        q.multiply(_q.setFromAxisAngle(k.axes.row, row));
-        q.multiply(_q.setFromAxisAngle(k.axes.long, fe * s));
-      } else if (k.axes.ab) {
-        // pelvic: spread when slow and braking, folded at speed
-        const pv = sp.pelvic;
-        const fold = this.foldS.x;
-        if (k.axes.s > 0) this.pelS.step(20 * P.flare + P.pelvicAb, 8, dt);
-        const ab = (pv.rest + pv.spread * (1 - fold) - pv.fold * fold + this.pelS.x + 3 * Math.sin(TAU * this.pPhase * 0.5) * this.pectS.x) * D2R;
-        q.setFromAxisAngle(k.axes.ab, ab);
-      }
-      // M = parentWorld * A * T(t) * R * C0
-      _m.makeRotationFromQuaternion(q);
-      _m.multiply(k.C0);
-      _m.setPosition(_m.elements[12] + k.t.x, _m.elements[13] + k.t.y, _m.elements[14] + k.t.z);
-      k.bone.matrixWorld.multiplyMatrices(k.parent.matrixWorld, k.A).multiply(_m);
-    }
-  }
-
-  // skin extents of every bone against the bed (and the surface when swimming)
-  clampToWater() {
-    const cfg = this.cfg, n = cfg.n, W = this.W, sk = this.sk, e = this.ext;
-    if (this.lod >= 2 && (this.frame & 1)) { if (this.liftCarry) this.shiftAll(this.liftCarry); return; }
-    // ground under the snout, the middle and the tail; interpolated along the body
-    const gS = this.groundAt(W[n + 1].x, W[n + 1].z), gT = this.groundAt(W[n].x, W[n].z), gM = this.groundAt(this.pos.x, this.pos.z);
-    const surf = this.air || this.beached ? Infinity : this.surfaceAt(this.pos.x, this.pos.z);
-    const fx = W[n + 1].x - W[n].x, fz = W[n + 1].z - W[n].z;
-    const fl2 = fx * fx + fz * fz || 1e-9;
-    let need = -Infinity, over = -Infinity;
-    const nb = this.nB;
-    const margin = 0.002 * cfg.L;
-    for (let b = 0; b < nb; b++) {
-      const me = sk.bones[b].matrixWorld.elements, oo = b * 6;
-      if (e[oo + 1] === 0 && e[oo + 5] === 0) continue;
-      // centre of the skin box in world, and the vertical half extent (elliptic in X/Z, box along Y)
-      const cx = e[oo], cy = e[oo + 2], cz = e[oo + 4];
-      const wy = me[13] + cx * me[1] + cy * me[5] + cz * me[9];
-      // chain bones: elliptic cross-section; fins and head parts: box (flat fans reach their corners)
-      const half = this.isChain[b] ? Math.sqrt((e[oo + 1] * me[1]) ** 2 + (e[oo + 5] * me[9]) ** 2) + Math.abs(e[oo + 3] * me[5])
-        : Math.abs(e[oo + 1] * me[1]) + Math.abs(e[oo + 3] * me[5]) + Math.abs(e[oo + 5] * me[9]);
-      const wx = me[12] + cx * me[0] + cy * me[4] + cz * me[8], wz = me[14] + cx * me[2] + cy * me[6] + cz * me[10];
-      const t = clamp(((wx - W[n].x) * fx + (wz - W[n].z) * fz) / fl2, 0, 1);
-      // along the body the bed is interpolated from three samples; fins and head parts stick out
-      // sideways (on a slope that matters when lying on the side), so they sample their own spot
-      const g = !this.isChain[b] && this.lod === 0 ? this.groundAt(wx, wz) : t < 0.5 ? lerp(gT, gM, t * 2) : lerp(gM, gS, t * 2 - 1);
-      const d = g + margin - (wy - half);
-      if (d > need) need = d;
-      const u = wy + half - (surf - margin);
-      if (u > over) over = u;
-    }
-    let shift = 0;
-    if (need > 0) shift = need;
-    else if (over > 0 && !this.P.breach && !this.P.surfaceOK) shift = -Math.min(over, -need);
-    this.liftCarry = shift;
-    if (shift !== 0) {
-      this.shiftAll(shift);
-      this.pos.y += shift;
-      if (shift > 0) this.vy = Math.max(this.vy, 0); else this.vy = Math.min(this.vy, 0);
-    }
-  }
-  shiftAll(dy) {
-    for (const b of this.sk.bones) b.matrixWorld.elements[13] += dy;
-    for (const w of this.W) w.y += dy;
-  }
-
-  // ----------------------------------------------------------------- state
-  publish() {
-    const st = this.state, cfg = this.cfg, L = cfg.L;
-    st.heading = this.heading;
-    st.speed = this.speed;
-    st.pitch = this.pitch; st.roll = this.roll;
-    const vbl = this.speed / L;
-    let g = 'stand';
-    if (vbl > 0.08) {
-      const G = cfg.gears;
-      const names = this.gaits;
-      g = names[0];
-      for (let i = 1; i < names.length; i++) if (this.speed > (G[names[i - 1]] + G[names[i]]) / 2) g = names[i];
-    }
-    st.stats.gait = g;
-    st.stats.freq = Math.max(0.05, this.freqS.x);
-    st.gait = this.air ? 'jump' : this.beached ? 'flop' : g;
-    st.grounded = !this.air;
-    st.inWater = !this.air && !this.beached;
-    st.beached = this.beached;
-    const s = this.surfaceY;
-    st.depth = Number.isFinite(s) ? s - this.pos.y : Infinity;
-    st.breaching = this.air || this.P.breach > 0.01 || this.P.surfaceOK > 0.01;
-    st.eyelid = 0;
-    st.eyeRoll = clamp(this.eyeRollS.x, 0, 1);
-    st.nictitate = clamp(this.nictS.x, 0, 1);
-    st.action = this.actionsLayer.current();
-    st.posture = this.actionsLayer.posture;
-  }
-}
-
-// row lookup: rows [v, a, b, c, d, e, f] -> out[0..5], smoothstep blend
-function tableAt6(rows, v, out) {
-  let i = 0;
-  while (i < rows.length - 2 && v > rows[i + 1][0]) i++;
-  const a = rows[i], b = rows[Math.min(i + 1, rows.length - 1)];
-  const t = b === a ? 0 : clamp((v - a[0]) / (b[0] - a[0]), 0, 1);
-  const s = t * t * (3 - 2 * t);
-  for (let k = 0; k < 6; k++) out[k] = lerp(a[k + 1], b[k + 1], k === 0 ? t : s);
-  return out;
-}
-void tv; void _v3; void _m2; void _q2;