@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/compress.js

@@ -0,0 +1,339 @@
+/**
+ * Clip compression: fewer keyframes and smaller ones, so a wardrobe of animations fits.
+ *
+ * `compressClip` keeps, per channel, only the keys a linear fit cannot reproduce within a
+ * tolerance (Ramer–Douglas–Peucker over the sampled curve: start from the two end keys, add
+ * the key with the largest error until every dropped key is within tolerance), collapses a
+ * channel whose keys never change to one key and drops it entirely when that value is the
+ * skeleton's rest (with `skeleton`). `quantizeClip` packs rotation keys into three `uint16`
+ * per key (smallest-three, `AnimationChannel.packed`), which `sampleChannel` reads directly.
+ * Both allocate (they build new clips); call them at load or in a bake step. `CUBICSPLINE`
+ * channels are copied unchanged by both.
+ */
+import { channelComponents, unpackQuat } from './clip.js';
+import { POSE_NODE_FLOATS } from './pose.js';
+/** Keyframe bytes of a clip: `times`, `values` and `packed` over every channel. */
+export function clipBytes(clip) {
+    let bytes = 0;
+    for (const ch of clip.channels) {
+        bytes += ch.times.byteLength + ch.values.byteLength + (ch.packed?.byteLength ?? 0);
+    }
+    return bytes;
+}
+const qa = new Float32Array(4);
+const qb = new Float32Array(4);
+/**
+ * The angle between two unit quaternions at `values[a..]` and `values[b..]`, from the chord
+ * (`2·asin(|q₁ ∓ q₂| / 2)`), which keeps its precision near zero where `acos(dot)` does not.
+ */
+function quatAngle(values, a, b) {
+    const dot = values[a] * values[b] +
+        values[a + 1] * values[b + 1] +
+        values[a + 2] * values[b + 2] +
+        values[a + 3] * values[b + 3];
+    const s = dot < 0 ? -1 : 1;
+    const dx = values[a] - s * values[b];
+    const dy = values[a + 1] - s * values[b + 1];
+    const dz = values[a + 2] - s * values[b + 2];
+    const dw = values[a + 3] - s * values[b + 3];
+    return 2 * Math.asin(Math.min(1, Math.hypot(dx, dy, dz, dw) / 2));
+}
+/** Largest absolute component gap between keys `a` and `b` (`comps` each). */
+function maxGap(values, a, b, comps) {
+    let m = 0;
+    for (let i = 0; i < comps; i++)
+        m = Math.max(m, Math.abs(values[a + i] - values[b + i]));
+    return m;
+}
+/**
+ * The error of key `k` against the linear (slerp for rotations) fit between keys `i` and `j`.
+ */
+function fitError(ch, comps, i, j, k) {
+    const times = ch.times;
+    const values = ch.values;
+    const span = times[j] - times[i];
+    const u = span > 0 ? (times[k] - times[i]) / span : 0;
+    const rotation = ch.path === 'rotation';
+    if (ch.interpolation === 'STEP') {
+        // A step channel holds key i until key j: the dropped key must equal key i.
+        return rotation
+            ? quatAngle(values, i * comps, k * comps)
+            : maxGap(values, i * comps, k * comps, comps);
+    }
+    if (rotation) {
+        slerpInto(qa, values, i * comps, values, j * comps, u);
+        for (let c = 0; c < 4; c++)
+            qb[c] = values[k * comps + c];
+        return angleBetween(qa, qb);
+    }
+    let m = 0;
+    for (let c = 0; c < comps; c++) {
+        const fit = (1 - u) * values[i * comps + c] + u * values[j * comps + c];
+        m = Math.max(m, Math.abs(fit - values[k * comps + c]));
+    }
+    return m;
+}
+function angleBetween(a, b) {
+    for (let i = 0; i < 4; i++)
+        qab[i] = a[i];
+    for (let i = 0; i < 4; i++)
+        qab[4 + i] = b[i];
+    return quatAngle(qab, 0, 4);
+}
+const qab = new Float64Array(8);
+/** Shortest-arc slerp of two quaternions (no dependence on `quat.ts` scratch). */
+function slerpInto(out, a, ao, b, bo, t) {
+    let bx = b[bo];
+    let by = b[bo + 1];
+    let bz = b[bo + 2];
+    let bw = b[bo + 3];
+    let cos = a[ao] * bx + a[ao + 1] * by + a[ao + 2] * bz + a[ao + 3] * bw;
+    if (cos < 0) {
+        cos = -cos;
+        bx = -bx;
+        by = -by;
+        bz = -bz;
+        bw = -bw;
+    }
+    let s0;
+    let s1;
+    if (cos > 0.9995) {
+        s0 = 1 - t;
+        s1 = t;
+    }
+    else {
+        const theta = Math.acos(cos);
+        const sin = Math.sin(theta);
+        s0 = Math.sin((1 - t) * theta) / sin;
+        s1 = Math.sin(t * theta) / sin;
+    }
+    out[0] = s0 * a[ao] + s1 * bx;
+    out[1] = s0 * a[ao + 1] + s1 * by;
+    out[2] = s0 * a[ao + 2] + s1 * bz;
+    out[3] = s0 * a[ao + 3] + s1 * bw;
+    const len = Math.hypot(out[0], out[1], out[2], out[3]) || 1;
+    for (let i = 0; i < 4; i++)
+        out[i] = out[i] / len;
+}
+function toleranceOf(ch, opts) {
+    switch (ch.path) {
+        case 'translation':
+            return opts.positionError ?? 1e-3;
+        case 'rotation':
+            return opts.rotationError ?? 1e-3;
+        case 'scale':
+            return opts.scaleError ?? 1e-3;
+        default:
+            return opts.weightError ?? 1e-3;
+    }
+}
+/** Keys of `ch` (STEP or LINEAR) to keep, ascending, by RDP within `tol`. */
+function keepKeys(ch, comps, tol) {
+    const n = ch.times.length;
+    if (n <= 2) {
+        const all = [];
+        for (let i = 0; i < n; i++)
+            all.push(i);
+        return all;
+    }
+    const keep = new Uint8Array(n);
+    keep[0] = 1;
+    keep[n - 1] = 1;
+    const stack = [0, n - 1];
+    while (stack.length > 0) {
+        const j = stack.pop();
+        const i = stack.pop();
+        if (j - i < 2)
+            continue;
+        let worst = -1;
+        let worstErr = tol;
+        for (let k = i + 1; k < j; k++) {
+            const e = fitError(ch, comps, i, j, k);
+            if (e > worstErr) {
+                worstErr = e;
+                worst = k;
+            }
+        }
+        if (worst < 0)
+            continue;
+        keep[worst] = 1;
+        stack.push(i, worst, worst, j);
+    }
+    const out = [];
+    for (let i = 0; i < n; i++)
+        if (keep[i])
+            out.push(i);
+    return out;
+}
+/** Whether every key of `ch` equals its first within `tol`. */
+function isConstant(ch, comps, tol) {
+    const n = ch.times.length;
+    for (let k = 1; k < n; k++) {
+        const e = ch.path === 'rotation'
+            ? quatAngle(ch.values, 0, k * comps)
+            : maxGap(ch.values, 0, k * comps, comps);
+        if (e > tol)
+            return false;
+    }
+    return true;
+}
+/** Whether key 0 of `ch` is the node's rest value within `tol`. */
+function isRest(ch, tol, skeleton) {
+    const n = skeleton.parents.length;
+    if (ch.node < 0 || ch.node >= n)
+        return false;
+    const o = ch.node * POSE_NODE_FLOATS;
+    const rest = skeleton.rest;
+    switch (ch.path) {
+        case 'translation':
+            return (Math.abs(ch.values[0] - rest[o]) <= tol &&
+                Math.abs(ch.values[1] - rest[o + 1]) <= tol &&
+                Math.abs(ch.values[2] - rest[o + 2]) <= tol);
+        case 'rotation': {
+            for (let i = 0; i < 4; i++)
+                qa[i] = rest[o + 3 + i];
+            for (let i = 0; i < 4; i++)
+                qb[i] = ch.values[i];
+            return angleBetween(qa, qb) <= tol;
+        }
+        case 'scale':
+            return (Math.abs(ch.values[0] - rest[o + 7]) <= tol &&
+                Math.abs(ch.values[1] - rest[o + 8]) <= tol &&
+                Math.abs(ch.values[2] - rest[o + 9]) <= tol);
+        default:
+            return false;
+    }
+}
+/**
+ * A copy of `clip` with the keys a linear fit reproduces within tolerance removed, constant
+ * channels collapsed (and dropped when they equal the rest of `skeleton`), and the keyframe
+ * byte counts before and after. Packed channels are decoded first; `CUBICSPLINE` channels and
+ * events are copied as they are. Allocates.
+ */
+export function compressClip(clip, opts = {}) {
+    const dropConstant = opts.dropConstant ?? true;
+    const channels = [];
+    for (const src of clip.channels) {
+        const ch = src.packed ? unpackChannel(src) : src;
+        const comps = channelComponents(ch);
+        const n = ch.times.length;
+        if (ch.interpolation === 'CUBICSPLINE' || n === 0 || comps === 0) {
+            channels.push({ ...ch, times: ch.times.slice(), values: ch.values.slice() });
+            continue;
+        }
+        const tol = toleranceOf(ch, opts);
+        if (dropConstant && isConstant(ch, comps, tol)) {
+            if (opts.skeleton && isRest(ch, tol, opts.skeleton))
+                continue;
+            channels.push({
+                node: ch.node,
+                path: ch.path,
+                interpolation: 'STEP',
+                times: new Float32Array([ch.times[0]]),
+                values: ch.values.slice(0, comps),
+            });
+            continue;
+        }
+        const keys = keepKeys(ch, comps, tol);
+        const times = new Float32Array(keys.length);
+        const values = new Float32Array(keys.length * comps);
+        for (let i = 0; i < keys.length; i++) {
+            const k = keys[i];
+            times[i] = ch.times[k];
+            for (let c = 0; c < comps; c++)
+                values[i * comps + c] = ch.values[k * comps + c];
+        }
+        channels.push({ node: ch.node, path: ch.path, interpolation: ch.interpolation, times, values });
+    }
+    const out = { name: clip.name, duration: clip.duration, channels };
+    if (clip.events)
+        out.events = clip.events.map((e) => ({ ...e }));
+    return { clip: out, before: clipBytes(clip), after: clipBytes(out) };
+}
+/** A float copy of a packed rotation channel. */
+function unpackChannel(ch) {
+    const n = ch.times.length;
+    const values = new Float32Array(n * 4);
+    for (let k = 0; k < n; k++)
+        unpackQuat(ch.packed, k, values, k * 4);
+    return { node: ch.node, path: ch.path, interpolation: ch.interpolation, times: ch.times, values };
+}
+const PACK_SCALE = 32767 / Math.SQRT2;
+/**
+ * Encode the unit quaternion at `q[o..o+4)` as three `uint16` at `out[b..b+3)` in the
+ * smallest-three form `unpackQuat` decodes: the quaternion is flipped so its largest
+ * component is positive, that component's index goes to bit 15 of words 0 and 1, and the
+ * other three components, each within ±1/√2, fill the low 15 bits of the words in order.
+ */
+export function packQuat(q, o, out, b) {
+    let largest = 0;
+    let mag = 0;
+    for (let i = 0; i < 4; i++) {
+        const a = Math.abs(q[o + i]);
+        if (a > mag) {
+            mag = a;
+            largest = i;
+        }
+    }
+    const sign = q[o + largest] < 0 ? -1 : 1;
+    let w = 0;
+    for (let i = 0; i < 4; i++) {
+        if (i === largest)
+            continue;
+        let c = q[o + i] * sign;
+        c = Math.min(Math.SQRT1_2, Math.max(-Math.SQRT1_2, c));
+        let bits = Math.round((c + Math.SQRT1_2) * PACK_SCALE);
+        bits = Math.min(0x7fff, Math.max(0, bits));
+        if (w === 0)
+            bits |= (largest >> 1) << 15;
+        else if (w === 1)
+            bits |= (largest & 1) << 15;
+        out[b + w] = bits;
+        w++;
+    }
+}
+/**
+ * A copy of `clip` whose `STEP`/`LINEAR` rotation channels carry `packed` keys (three
+ * `uint16` each, `packQuat`) and an empty `values`; other channels are copied. `'none'`
+ * copies everything. Allocates.
+ */
+export function quantizeClip(clip, opts) {
+    const channels = [];
+    for (const src of clip.channels) {
+        const packable = opts.rotation === 'smallest-three' &&
+            src.path === 'rotation' &&
+            src.interpolation !== 'CUBICSPLINE';
+        if (!packable) {
+            const ch = { ...src, times: src.times.slice(), values: src.values.slice() };
+            if (src.packed)
+                ch.packed = src.packed.slice();
+            channels.push(ch);
+            continue;
+        }
+        if (src.packed) {
+            channels.push({
+                ...src,
+                times: src.times.slice(),
+                values: new Float32Array(0),
+                packed: src.packed.slice(),
+            });
+            continue;
+        }
+        const n = src.times.length;
+        const packed = new Uint16Array(n * 3);
+        for (let k = 0; k < n; k++)
+            packQuat(src.values, k * 4, packed, k * 3);
+        channels.push({
+            node: src.node,
+            path: src.path,
+            interpolation: src.interpolation,
+            times: src.times.slice(),
+            values: new Float32Array(0),
+            packed,
+        });
+    }
+    const out = { name: clip.name, duration: clip.duration, channels };
+    if (clip.events)
+        out.events = clip.events.map((e) => ({ ...e }));
+    return out;
+}

package/dist/anim/foot-ik.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Foot placement: a probe (the game's ground query) under each foot, a pelvis that sinks to the
+ * lowest foot, two-bone IK per leg to hold the feet on the probed ground and a tilt of each foot
+ * onto the ground normal. The animation's floor is the instance origin's plane (`y` of the
+ * instance translation); each foot's lift is the probed height above that plane, clamped to
+ * `[-maxDrop, maxLift]`. Same conventions as `ik.ts`: `worldPose` is `poseToWorld` of the sampled
+ * `pose`, which this rewrites (translations of `pelvis`, rotations of root/mid/tip per foot).
+ * Flat ground at the origin plane leaves the pose untouched, bit for bit. Allocates in
+ * `createFootIk` (the chains and a world buffer), nothing per frame; the probe must not either.
+ */
+import { type IkChain } from './ik.js';
+import { type Pose, type Skeleton } from './pose.js';
+/** One leg: `mid` descends from `root` (hip), `tip` (ankle) from `mid`; `toe` is probed too. */
+export interface FootIkFootDesc {
+    root: number;
+    mid: number;
+    tip: number;
+    /** Optional toe joint: the ground is probed under it as well and the higher hit is used. */
+    toe?: number;
+    /** Skeleton-space direction the knee bends toward when the leg is straight. Default +Z. */
+    bend?: ArrayLike<number>;
+}
+/**
+ * The ground query, in instance (world) space: writes `[y, nx, ny, nz]` for the ground under
+ * `(x, z)` into `out` and returns `true`, or returns `false` for no ground (the foot is left to
+ * the animation). It is called once per foot (twice with a toe) per `applyFootIk`.
+ */
+export type FootIkProbe = (x: number, z: number, out: Float32Array) => boolean;
+export interface FootIkDesc {
+    feet: FootIkFootDesc[];
+    probe: FootIkProbe;
+    /** The joint whose translation sinks toward the lowest foot (hips). */
+    pelvis: number;
+    /** Furthest a foot rises above the animation's floor (world units). Default 0.5. */
+    maxLift?: number;
+    /** Furthest a foot drops below it. Default 0.5. */
+    maxDrop?: number;
+    /** Pelvis smoothing rate per second (exponential approach). Default 12. */
+    blend?: number;
+}
+/** The feet with their scratch, from `createFootIk`. Read `pelvisOffset` and `lift`. */
+export interface FootIk {
+    readonly feet: readonly FootIkFootDesc[];
+    readonly probe: FootIkProbe;
+    readonly pelvis: number;
+    readonly maxLift: number;
+    readonly maxDrop: number;
+    readonly blend: number;
+    /** The current pelvis sink (world units, ≤ 0 going down), smoothed. */
+    pelvisOffset: number;
+    /** Per foot, the clamped ground height above the floor that the foot was placed at. */
+    readonly lift: Float32Array;
+    /** Per foot, 1 when the probe hit. */
+    readonly grounded: Uint8Array;
+    /** @internal */
+    readonly chains: IkChain[];
+    /** @internal per foot, the bend direction (unit, skeleton space). */
+    readonly bends: Float32Array;
+    /** @internal per foot, the ground normal in skeleton space (unit). */
+    readonly normals: Float32Array;
+    /** @internal per foot, the sampled tip position in skeleton space. */
+    readonly tips: Float32Array;
+    /** @internal world matrices of the pose after the pelvis moved. */
+    readonly world: Float32Array;
+}
+/** Validate and allocate; call once. */
+export declare function createFootIk(skeleton: Skeleton, desc: FootIkDesc): FootIk;
+/**
+ * Probe under every foot, sink the pelvis toward the lowest one (smoothed by `blend` over `dt`),
+ * then solve each leg to its ground height and tilt the foot onto the normal. `instanceWorld`
+ * (3×4 row-major, or `null` for the identity) places the skeleton in the probe's space. No
+ * allocation.
+ */
+export declare function applyFootIk(pose: Pose, skeleton: Skeleton, worldPose: Float32Array, footIk: FootIk, instanceWorld: Float32Array | null, dt: number): void;

package/dist/anim/foot-ik.js

@@ -0,0 +1,241 @@
+/**
+ * Foot placement: a probe (the game's ground query) under each foot, a pelvis that sinks to the
+ * lowest foot, two-bone IK per leg to hold the feet on the probed ground and a tilt of each foot
+ * onto the ground normal. The animation's floor is the instance origin's plane (`y` of the
+ * instance translation); each foot's lift is the probed height above that plane, clamped to
+ * `[-maxDrop, maxLift]`. Same conventions as `ik.ts`: `worldPose` is `poseToWorld` of the sampled
+ * `pose`, which this rewrites (translations of `pelvis`, rotations of root/mid/tip per foot).
+ * Flat ground at the origin plane leaves the pose untouched, bit for bit. Allocates in
+ * `createFootIk` (the chains and a world buffer), nothing per frame; the probe must not either.
+ */
+import { applyDelta, createIkChain, IDENTITY, normalize, rotationBetween, transformDir, transformPoint, twoBoneIk, } from './ik.js';
+import { invertAffine, multiplyAffine, POSE_NODE_FLOATS, poseToWorld, WORLD_NODE_FLOATS, } from './pose.js';
+const EPS = 1e-6;
+/** Validate and allocate; call once. */
+export function createFootIk(skeleton, desc) {
+    const n = skeleton.parents.length;
+    if (desc.feet.length === 0)
+        throw new Error('FootIk: at least one foot');
+    if (desc.pelvis < 0 || desc.pelvis >= n)
+        throw new Error(`FootIk: pelvis ${desc.pelvis}`);
+    const chains = [];
+    const bends = new Float32Array(desc.feet.length * 3);
+    for (let i = 0; i < desc.feet.length; i++) {
+        const f = desc.feet[i];
+        chains.push(createIkChain(skeleton, f));
+        if (f.toe !== undefined && (f.toe < 0 || f.toe >= n))
+            throw new Error(`FootIk: toe ${f.toe}`);
+        const b = f.bend ?? [0, 0, 1];
+        bends[i * 3] = b[0];
+        bends[i * 3 + 1] = b[1];
+        bends[i * 3 + 2] = b[2];
+        if (normalize(bends.subarray(i * 3, i * 3 + 3)) <= EPS)
+            throw new Error(`FootIk: bend of foot ${i} must be non-zero`);
+    }
+    return {
+        feet: desc.feet,
+        probe: desc.probe,
+        pelvis: desc.pelvis,
+        maxLift: desc.maxLift ?? 0.5,
+        maxDrop: desc.maxDrop ?? 0.5,
+        blend: desc.blend ?? 12,
+        pelvisOffset: 0,
+        lift: new Float32Array(desc.feet.length),
+        grounded: new Uint8Array(desc.feet.length),
+        chains,
+        bends,
+        normals: new Float32Array(desc.feet.length * 3),
+        tips: new Float32Array(desc.feet.length * 3),
+        world: new Float32Array(n * WORLD_NODE_FLOATS),
+    };
+}
+const hit = new Float32Array(4);
+const inv = new Float32Array(WORLD_NODE_FLOATS);
+const upSk = new Float32Array(3);
+const upN = new Float32Array(3);
+const p = new Float32Array(3);
+const q = new Float32Array(3);
+const nrm = new Float32Array(3);
+const target = new Float32Array(3);
+const pole = new Float32Array(3);
+const delta = new Float32Array(4);
+const undo = new Float32Array(WORLD_NODE_FLOATS);
+const WORLD_UP = new Float32Array([0, 1, 0]);
+/**
+ * Probe under every foot, sink the pelvis toward the lowest one (smoothed by `blend` over `dt`),
+ * then solve each leg to its ground height and tilt the foot onto the normal. `instanceWorld`
+ * (3×4 row-major, or `null` for the identity) places the skeleton in the probe's space. No
+ * allocation.
+ */
+export function applyFootIk(pose, skeleton, worldPose, footIk, instanceWorld, dt) {
+    const feet = footIk.feet;
+    const originY = instanceWorld ? instanceWorld[7] : 0;
+    if (instanceWorld) {
+        invertAffine(inv, 0, instanceWorld, 0);
+        transformDir(upSk, inv, 0, WORLD_UP);
+    }
+    else {
+        upSk[0] = 0;
+        upSk[1] = 1;
+        upSk[2] = 0;
+    }
+    upN[0] = upSk[0];
+    upN[1] = upSk[1];
+    upN[2] = upSk[2];
+    if (normalize(upN) <= EPS)
+        return;
+    // Probe. `lowest` is the pelvis target; `flat` stays true while nothing needs to move.
+    let lowest = 0;
+    let flat = true;
+    for (let i = 0; i < feet.length; i++) {
+        const f = feet[i];
+        const to = f.tip * WORLD_NODE_FLOATS;
+        footIk.tips[i * 3] = worldPose[to + 3];
+        footIk.tips[i * 3 + 1] = worldPose[to + 7];
+        footIk.tips[i * 3 + 2] = worldPose[to + 11];
+        footIk.grounded[i] = 0;
+        footIk.lift[i] = 0;
+        footIk.normals[i * 3] = upN[0];
+        footIk.normals[i * 3 + 1] = upN[1];
+        footIk.normals[i * 3 + 2] = upN[2];
+        let d = Number.NEGATIVE_INFINITY;
+        let got = false;
+        for (let k = 0; k < 2; k++) {
+            const node = k === 0 ? f.tip : f.toe;
+            if (node === undefined)
+                break;
+            const wo = node * WORLD_NODE_FLOATS;
+            p[0] = worldPose[wo + 3];
+            p[1] = worldPose[wo + 7];
+            p[2] = worldPose[wo + 11];
+            if (instanceWorld)
+                transformPoint(q, instanceWorld, 0, p);
+            else
+                q.set(p);
+            if (!footIk.probe(q[0], q[2], hit))
+                continue;
+            const h = hit[0] - originY;
+            if (!got || h > d) {
+                d = h;
+                nrm[0] = hit[1];
+                nrm[1] = hit[2];
+                nrm[2] = hit[3];
+            }
+            got = true;
+        }
+        if (!got)
+            continue;
+        d = Math.min(footIk.maxLift, Math.max(-footIk.maxDrop, d));
+        footIk.grounded[i] = 1;
+        footIk.lift[i] = d;
+        if (instanceWorld)
+            transformDir(nrm, inv, 0, nrm);
+        if (normalize(nrm) > EPS) {
+            footIk.normals[i * 3] = nrm[0];
+            footIk.normals[i * 3 + 1] = nrm[1];
+            footIk.normals[i * 3 + 2] = nrm[2];
+            const dot = nrm[0] * upN[0] + nrm[1] * upN[1] + nrm[2] * upN[2];
+            if (dot < 1 - 1e-6)
+                flat = false;
+        }
+        if (d !== 0)
+            flat = false;
+        if (d < lowest)
+            lowest = d;
+    }
+    // Pelvis: approach the lowest foot exponentially.
+    const k = dt > 0 ? 1 - Math.exp(-footIk.blend * dt) : 1;
+    footIk.pelvisOffset += (lowest - footIk.pelvisOffset) * k;
+    if (Math.abs(footIk.pelvisOffset) < 1e-6)
+        footIk.pelvisOffset = 0;
+    if (flat && footIk.pelvisOffset === 0)
+        return;
+    const offset = footIk.pelvisOffset;
+    if (offset !== 0) {
+        const parent = skeleton.parents[footIk.pelvis];
+        p[0] = upSk[0] * offset;
+        p[1] = upSk[1] * offset;
+        p[2] = upSk[2] * offset;
+        if (parent >= 0) {
+            invertAffine(inv, 0, worldPose, parent * WORLD_NODE_FLOATS);
+            transformDir(p, inv, 0, p);
+        }
+        const po = footIk.pelvis * POSE_NODE_FLOATS;
+        pose[po] = pose[po] + p[0];
+        pose[po + 1] = pose[po + 1] + p[1];
+        pose[po + 2] = pose[po + 2] + p[2];
+    }
+    poseToWorld(skeleton, pose, footIk.world);
+    // Legs: each grounded foot back to its sampled place lifted by its ground height.
+    for (let i = 0; i < feet.length; i++) {
+        if (!footIk.grounded[i])
+            continue;
+        const c = footIk.chains[i];
+        const d = footIk.lift[i];
+        target[0] = footIk.tips[i * 3] + upSk[0] * d;
+        target[1] = footIk.tips[i * 3 + 1] + upSk[1] * d;
+        target[2] = footIk.tips[i * 3 + 2] + upSk[2] * d;
+        // The pole: the knee as it is, nudged toward the bend direction so a straight leg knows
+        // which way to fold.
+        const mo = c.mid * WORLD_NODE_FLOATS;
+        const ro = c.root * WORLD_NODE_FLOATS;
+        const W = footIk.world;
+        const len = Math.hypot(W[mo + 3] - W[ro + 3], W[mo + 7] - W[ro + 7], W[mo + 11] - W[ro + 11]);
+        const nudge = Math.max(len, EPS) * 1e-2;
+        pole[0] = W[mo + 3] + footIk.bends[i * 3] * nudge;
+        pole[1] = W[mo + 7] + footIk.bends[i * 3 + 1] * nudge;
+        pole[2] = W[mo + 11] + footIk.bends[i * 3 + 2] * nudge;
+        twoBoneIk(pose, skeleton, footIk.world, c, target, pole, null);
+    }
+    // Feet: each keeps its sampled orientation (the leg's turn is undone at the ankle), then
+    // tilts onto its ground normal.
+    poseToWorld(skeleton, pose, footIk.world);
+    for (let i = 0; i < feet.length; i++) {
+        if (!footIk.grounded[i])
+            continue;
+        const f = feet[i];
+        const to = f.tip * WORLD_NODE_FLOATS;
+        invertAffine(inv, 0, footIk.world, to);
+        multiplyAffine(undo, 0, worldPose, to, inv, 0);
+        matrixToAxisAngle(delta, undo);
+        const parent = skeleton.parents[f.tip];
+        const po = parent < 0 ? 0 : parent * WORLD_NODE_FLOATS;
+        const pm = parent < 0 ? IDENTITY : footIk.world;
+        applyDelta(pose, f.tip, delta, pm, po, null);
+        nrm[0] = footIk.normals[i * 3];
+        nrm[1] = footIk.normals[i * 3 + 1];
+        nrm[2] = footIk.normals[i * 3 + 2];
+        rotationBetween(delta, upN, nrm);
+        if (Math.abs(delta[3]) < 1e-5)
+            continue;
+        applyDelta(pose, f.tip, delta, pm, po, null);
+    }
+}
+/** The (unit axis, angle) of the rotation in the upper 3×3 of the 3×4 matrix `m`. */
+function matrixToAxisAngle(out, m) {
+    const tr = m[0] + m[5] + m[10];
+    out[0] = m[9] - m[6];
+    out[1] = m[2] - m[8];
+    out[2] = m[4] - m[1];
+    const sin2 = Math.hypot(out[0], out[1], out[2]);
+    if (sin2 <= EPS) {
+        // Identity, or a half turn: take the axis from the symmetric part.
+        if (tr > 0) {
+            out[0] = 1;
+            out[1] = 0;
+            out[2] = 0;
+            out[3] = 0;
+            return;
+        }
+        out[0] = Math.sqrt(Math.max(0, (m[0] + 1) / 2));
+        out[1] = Math.sqrt(Math.max(0, (m[5] + 1) / 2));
+        out[2] = Math.sqrt(Math.max(0, (m[10] + 1) / 2));
+        normalize(out);
+        out[3] = Math.PI;
+        return;
+    }
+    out[0] = out[0] / sin2;
+    out[1] = out[1] / sin2;
+    out[2] = out[2] / sin2;
+    out[3] = Math.atan2(sin2 / 2, (tr - 1) / 2);
+}