@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/ik.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Inverse kinematics on a `Pose`: an analytic two-bone solver (feet on uneven ground, a hand on
+ * a target) and a one-joint look-at (a head turning to a point). Both run after sampling and
+ * before the final `poseToWorld`: they read the world matrices of the pose as sampled
+ * (`worldPose`, from a `poseToWorld` the caller already ran, so nothing here walks the skeleton
+ * again), and write new local rotations into `pose`. Pure arithmetic; after `createIkChain`
+ * nothing allocates per call.
+ *
+ * Conventions: positions are 3-component `ArrayLike<number>`s; `instanceWorld` is the 3×4
+ * row-major instance matrix (`render/transform.ts`) that places the skeleton in the world, or
+ * `null` when the target is already in skeleton space. Rotations are expressed as deltas in
+ * skeleton space and converted into each joint's parent frame through the parent's world matrix.
+ */
+import { type Pose, type Skeleton } from './pose.js';
+/** The three joints of a two-bone chain: `mid` descends from `root`, `tip` from `mid`. */
+export interface IkChainDesc {
+    root: number;
+    mid: number;
+    tip: number;
+}
+/**
+ * A two-bone chain with its scratch space, from `createIkChain`. Opaque beyond `root`, `mid`,
+ * `tip`; pass it to `twoBoneIk` every frame. A plain `IkChainDesc` works too: `twoBoneIk` builds
+ * and caches a chain per object, so keep the object rather than writing a new literal per call.
+ */
+export interface IkChain extends IkChainDesc {
+    /** @internal nodes from `root` to `tip`, parent before child. */
+    readonly path: Int16Array;
+    /** @internal index of `mid` in `path`. */
+    readonly midIndex: number;
+    /** @internal world matrices of the path nodes, 12 floats each. */
+    readonly world: Float32Array;
+    /** @internal the input local rotations of root and mid (for `weight`). */
+    readonly saved: Float32Array;
+}
+export interface TwoBoneIkOptions {
+    /** 0..1: how far the solved rotations replace the input ones (slerp). Default 1. */
+    weight?: number;
+    /**
+     * Solve passes. One is exact for rigid bones; a second refines when a chain node carries a
+     * non-uniform scale. Default 1.
+     */
+    maxIterations?: number;
+}
+export interface LookAtOptions {
+    /** 0..1 blend against the input rotation. Default 1. */
+    weight?: number;
+    /** The joint's local axis that should point at the target. Default `[0, 0, 1]`. */
+    forward?: ArrayLike<number>;
+    /**
+     * World (skeleton-space) up hint: after aiming, the joint rolls about the new forward so the
+     * direction that was "up" for it stays up, instead of tilting as it turns. Default: none
+     * (the minimal rotation).
+     */
+    up?: ArrayLike<number>;
+    /** Largest angle (radians) the joint turns away from its input forward. Default `Math.PI`. */
+    maxAngle?: number;
+}
+/**
+ * Build a chain for `twoBoneIk` over `skeleton`: validates that `mid` descends from `root` and
+ * `tip` from `mid` (intermediate nodes, such as twist bones, are allowed) and allocates the
+ * scratch space the solver needs. Allocates; call once per chain.
+ */
+export declare function createIkChain(skeleton: Skeleton, chain: IkChainDesc): IkChain;
+export declare const IDENTITY: Float32Array<ArrayBuffer>;
+/** `out = m[mo..] · p` (point, with translation). */
+export declare function transformPoint(out: Float32Array, m: ArrayLike<number>, mo: number, p: ArrayLike<number>): void;
+/** `out = upper3x3(m[mo..]) · d` (direction, no translation); `out` may alias `d`. */
+export declare function transformDir(out: Float32Array, m: ArrayLike<number>, mo: number, d: ArrayLike<number>): void;
+/** A world-space point into skeleton space through the inverse of `instanceWorld`. */
+export declare function toSkeleton(out: Float32Array, p: ArrayLike<number>, instanceWorld: Float32Array | null): void;
+export declare function normalize(a: Float32Array): number;
+/** Any unit vector perpendicular to the unit vector `u`, into `out`. */
+export declare function anyPerpendicular(out: Float32Array, u: Float32Array): void;
+/** The shortest rotation taking unit `a` onto unit `b`, as (unit axis, angle) in `out`. */
+export declare function rotationBetween(out: Float32Array, a: Float32Array, b: Float32Array): void;
+/** Rotate `v` in place by the unit quaternion at `q[qo..]`. */
+export declare function rotateByQuat(v: Float32Array, q: ArrayLike<number>, qo: number): void;
+/** Rotate `p` in place by the (unit axis, angle) delta `d` (Rodrigues). */
+export declare function rotateBy(p: Float32Array, d: Float32Array, angle?: number): void;
+/**
+ * Pre-multiply the local rotation of `node` by the skeleton-space delta `d` (unit axis, angle):
+ * the axis goes through the inverse of the parent's world 3×3 (`parent`, or the identity for a
+ * skeleton root), after an optional extra rotation `pre` of the axis (used when the parent itself
+ * has just been rotated by `pre` and `parent` still holds its old matrix).
+ */
+export declare function applyDelta(pose: Pose, node: number, d: Float32Array, parent: ArrayLike<number>, po: number, pre: Float32Array | null): void;
+/**
+ * Analytic two-bone IK (law of cosines) with a pole vector. Rotates `chain.root` and `chain.mid`
+ * in `pose` so that `chain.tip` reaches `targetWorld`; an unreachable target straightens the
+ * chain towards it (no stretching). `poleWorld` picks the bend side (the mid joint moves towards
+ * it); `null` keeps the chain's current bend plane. `worldPose` is `poseToWorld` of `pose` as it
+ * is on entry (the solver reads it, never rewrites it). `instanceWorld` (3×4 row-major) maps
+ * skeleton space to the space the target and pole are given in. `weight` slerps the result
+ * against the input rotations. No allocation when `chain` is an `IkChain` (or a reused object).
+ */
+export declare function twoBoneIk(pose: Pose, skeleton: Skeleton, worldPose: Float32Array, chain: IkChainDesc, targetWorld: ArrayLike<number>, poleWorld: ArrayLike<number> | null, instanceWorld: Float32Array | null, opts?: TwoBoneIkOptions): void;
+/**
+ * Rotate `joint` in `pose` so that its local `forward` axis points at `targetWorld`, turning at
+ * most `maxAngle` radians away from its input direction and blended by `weight`. With an `up`
+ * hint the joint also rolls so what was up for it stays up. Reads the joint's world matrix from
+ * `worldPose` (`poseToWorld` of the input pose) and its parent's; never rewrites it. No
+ * allocation.
+ */
+export declare function lookAt(pose: Pose, skeleton: Skeleton, worldPose: Float32Array, joint: number, targetWorld: ArrayLike<number>, instanceWorld: Float32Array | null, opts?: LookAtOptions): void;

package/dist/anim/ik.js

@@ -0,0 +1,435 @@
+/**
+ * Inverse kinematics on a `Pose`: an analytic two-bone solver (feet on uneven ground, a hand on
+ * a target) and a one-joint look-at (a head turning to a point). Both run after sampling and
+ * before the final `poseToWorld`: they read the world matrices of the pose as sampled
+ * (`worldPose`, from a `poseToWorld` the caller already ran, so nothing here walks the skeleton
+ * again), and write new local rotations into `pose`. Pure arithmetic; after `createIkChain`
+ * nothing allocates per call.
+ *
+ * Conventions: positions are 3-component `ArrayLike<number>`s; `instanceWorld` is the 3×4
+ * row-major instance matrix (`render/transform.ts`) that places the skeleton in the world, or
+ * `null` when the target is already in skeleton space. Rotations are expressed as deltas in
+ * skeleton space and converted into each joint's parent frame through the parent's world matrix.
+ */
+import { invertAffine, multiplyAffine, POSE_NODE_FLOATS, WORLD_NODE_FLOATS, writeNodeMatrix, } from './pose.js';
+import { quatFromAxisAngle, quatMultiply, quatNormalize, quatSlerp } from './quat.js';
+const EPS = 1e-6;
+/**
+ * Build a chain for `twoBoneIk` over `skeleton`: validates that `mid` descends from `root` and
+ * `tip` from `mid` (intermediate nodes, such as twist bones, are allowed) and allocates the
+ * scratch space the solver needs. Allocates; call once per chain.
+ */
+export function createIkChain(skeleton, chain) {
+    const { root, mid, tip } = chain;
+    const parents = skeleton.parents;
+    const n = parents.length;
+    if (root < 0 || root >= n || mid < 0 || mid >= n || tip < 0 || tip >= n) {
+        throw new Error(`IkChain: nodes ${root}, ${mid}, ${tip} must be in [0, ${n})`);
+    }
+    const nodes = [];
+    let node = tip;
+    let midIndex = -1;
+    while (node >= 0 && node !== root) {
+        nodes.push(node);
+        node = parents[node];
+    }
+    if (node !== root)
+        throw new Error(`IkChain: tip ${tip} does not descend from root ${root}`);
+    nodes.push(root);
+    nodes.reverse();
+    midIndex = nodes.indexOf(mid);
+    if (midIndex <= 0 || midIndex >= nodes.length - 1) {
+        throw new Error(`IkChain: mid ${mid} must lie strictly between root ${root} and tip ${tip}`);
+    }
+    return {
+        root,
+        mid,
+        tip,
+        path: Int16Array.from(nodes),
+        midIndex,
+        world: new Float32Array(nodes.length * WORLD_NODE_FLOATS),
+        saved: new Float32Array(8),
+    };
+}
+const chains = new WeakMap();
+function chainFor(skeleton, chain) {
+    if ('path' in chain)
+        return chain;
+    let c = chains.get(chain);
+    if (!c || c.root !== chain.root || c.mid !== chain.mid || c.tip !== chain.tip) {
+        c = createIkChain(skeleton, chain);
+        chains.set(chain, c);
+    }
+    return c;
+}
+// Scratch, module level: no allocation per call.
+const inv = new Float32Array(WORLD_NODE_FLOATS);
+const local = new Float32Array(WORLD_NODE_FLOATS);
+const tgt = new Float32Array(3);
+const pol = new Float32Array(3);
+const dir = new Float32Array(3);
+const perp = new Float32Array(3);
+const v = new Float32Array(3);
+const m2 = new Float32Array(3);
+const t1 = new Float32Array(3);
+/** A rotation delta in skeleton space: unit axis, angle. */
+const d1 = new Float32Array(4);
+const d2 = new Float32Array(4);
+const dq = new Float32Array(4);
+const axis = new Float32Array(3);
+const fwd = new Float32Array(3);
+const upw = new Float32Array(3);
+const savedRot = new Float32Array(4);
+export const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]);
+/** `out = m[mo..] · p` (point, with translation). */
+export function transformPoint(out, m, mo, p) {
+    const x = p[0];
+    const y = p[1];
+    const z = p[2];
+    out[0] = m[mo] * x + m[mo + 1] * y + m[mo + 2] * z + m[mo + 3];
+    out[1] = m[mo + 4] * x + m[mo + 5] * y + m[mo + 6] * z + m[mo + 7];
+    out[2] = m[mo + 8] * x + m[mo + 9] * y + m[mo + 10] * z + m[mo + 11];
+}
+/** `out = upper3x3(m[mo..]) · d` (direction, no translation); `out` may alias `d`. */
+export function transformDir(out, m, mo, d) {
+    const x = d[0];
+    const y = d[1];
+    const z = d[2];
+    out[0] = m[mo] * x + m[mo + 1] * y + m[mo + 2] * z;
+    out[1] = m[mo + 4] * x + m[mo + 5] * y + m[mo + 6] * z;
+    out[2] = m[mo + 8] * x + m[mo + 9] * y + m[mo + 10] * z;
+}
+/** A world-space point into skeleton space through the inverse of `instanceWorld`. */
+export function toSkeleton(out, p, instanceWorld) {
+    if (!instanceWorld) {
+        out[0] = p[0];
+        out[1] = p[1];
+        out[2] = p[2];
+        return;
+    }
+    invertAffine(inv, 0, instanceWorld, 0);
+    transformPoint(out, inv, 0, p);
+}
+export function normalize(a) {
+    const len = Math.hypot(a[0], a[1], a[2]);
+    if (len > EPS) {
+        const s = 1 / len;
+        a[0] *= s;
+        a[1] *= s;
+        a[2] *= s;
+    }
+    return len;
+}
+/** Any unit vector perpendicular to the unit vector `u`, into `out`. */
+export function anyPerpendicular(out, u) {
+    const ax = Math.abs(u[0]);
+    const ay = Math.abs(u[1]);
+    const az = Math.abs(u[2]);
+    // Cross with the axis u is least aligned with.
+    if (ax <= ay && ax <= az) {
+        out[0] = 0;
+        out[1] = -u[2];
+        out[2] = u[1];
+    }
+    else if (ay <= az) {
+        out[0] = u[2];
+        out[1] = 0;
+        out[2] = -u[0];
+    }
+    else {
+        out[0] = -u[1];
+        out[1] = u[0];
+        out[2] = 0;
+    }
+    normalize(out);
+}
+/** The shortest rotation taking unit `a` onto unit `b`, as (unit axis, angle) in `out`. */
+export function rotationBetween(out, a, b) {
+    const cx = a[1] * b[2] - a[2] * b[1];
+    const cy = a[2] * b[0] - a[0] * b[2];
+    const cz = a[0] * b[1] - a[1] * b[0];
+    const sin = Math.hypot(cx, cy, cz);
+    const cos = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+    if (sin < EPS) {
+        if (cos >= 0) {
+            out[0] = 1;
+            out[1] = 0;
+            out[2] = 0;
+            out[3] = 0;
+        }
+        else {
+            anyPerpendicular(out, a);
+            out[3] = Math.PI;
+        }
+        return;
+    }
+    out[0] = cx / sin;
+    out[1] = cy / sin;
+    out[2] = cz / sin;
+    out[3] = Math.atan2(sin, cos);
+}
+/** Rotate `v` in place by the unit quaternion at `q[qo..]`. */
+export function rotateByQuat(v, q, qo) {
+    const qx = q[qo];
+    const qy = q[qo + 1];
+    const qz = q[qo + 2];
+    const qw = q[qo + 3];
+    const x = v[0];
+    const y = v[1];
+    const z = v[2];
+    // t = 2 q × v; v' = v + w t + q × t
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    v[0] = x + qw * tx + (qy * tz - qz * ty);
+    v[1] = y + qw * ty + (qz * tx - qx * tz);
+    v[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+/** Rotate `p` in place by the (unit axis, angle) delta `d` (Rodrigues). */
+export function rotateBy(p, d, angle = d[3]) {
+    const kx = d[0];
+    const ky = d[1];
+    const kz = d[2];
+    const x = p[0];
+    const y = p[1];
+    const z = p[2];
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    const dot = (kx * x + ky * y + kz * z) * (1 - c);
+    p[0] = x * c + (ky * z - kz * y) * s + kx * dot;
+    p[1] = y * c + (kz * x - kx * z) * s + ky * dot;
+    p[2] = z * c + (kx * y - ky * x) * s + kz * dot;
+}
+/**
+ * Pre-multiply the local rotation of `node` by the skeleton-space delta `d` (unit axis, angle):
+ * the axis goes through the inverse of the parent's world 3×3 (`parent`, or the identity for a
+ * skeleton root), after an optional extra rotation `pre` of the axis (used when the parent itself
+ * has just been rotated by `pre` and `parent` still holds its old matrix).
+ */
+export function applyDelta(pose, node, d, parent, po, pre) {
+    if (d[3] === 0)
+        return;
+    axis[0] = d[0];
+    axis[1] = d[1];
+    axis[2] = d[2];
+    if (pre)
+        rotateBy(axis, pre, -pre[3]);
+    invertAffine(inv, 0, parent, po);
+    transformDir(axis, inv, 0, axis);
+    if (normalize(axis) <= EPS)
+        return;
+    quatFromAxisAngle(dq, 0, axis[0], axis[1], axis[2], d[3]);
+    const o = node * POSE_NODE_FLOATS + 3;
+    quatMultiply(pose, o, dq, 0, pose, o);
+    quatNormalize(pose, o);
+}
+/** Recompute the chain's world matrices from `pose`, the root's parent read from `worldPose`. */
+function refreshChain(c, skeleton, pose, worldPose) {
+    const path = c.path;
+    for (let i = 0; i < path.length; i++) {
+        const node = path[i];
+        const o = i * WORLD_NODE_FLOATS;
+        if (i === 0) {
+            const p = skeleton.parents[node];
+            if (p < 0)
+                writeNodeMatrix(c.world, o, pose, node * POSE_NODE_FLOATS);
+            else {
+                writeNodeMatrix(local, 0, pose, node * POSE_NODE_FLOATS);
+                multiplyAffine(c.world, o, worldPose, p * WORLD_NODE_FLOATS, local, 0);
+            }
+        }
+        else {
+            writeNodeMatrix(local, 0, pose, node * POSE_NODE_FLOATS);
+            multiplyAffine(c.world, o, c.world, o - WORLD_NODE_FLOATS, local, 0);
+        }
+    }
+}
+/**
+ * Analytic two-bone IK (law of cosines) with a pole vector. Rotates `chain.root` and `chain.mid`
+ * in `pose` so that `chain.tip` reaches `targetWorld`; an unreachable target straightens the
+ * chain towards it (no stretching). `poleWorld` picks the bend side (the mid joint moves towards
+ * it); `null` keeps the chain's current bend plane. `worldPose` is `poseToWorld` of `pose` as it
+ * is on entry (the solver reads it, never rewrites it). `instanceWorld` (3×4 row-major) maps
+ * skeleton space to the space the target and pole are given in. `weight` slerps the result
+ * against the input rotations. No allocation when `chain` is an `IkChain` (or a reused object).
+ */
+export function twoBoneIk(pose, skeleton, worldPose, chain, targetWorld, poleWorld, instanceWorld, opts) {
+    const weight = opts?.weight ?? 1;
+    if (weight <= 0)
+        return;
+    const iterations = Math.max(1, opts?.maxIterations ?? 1);
+    const c = chainFor(skeleton, chain);
+    const path = c.path;
+    const last = path.length - 1;
+    const rootO = c.root * POSE_NODE_FLOATS + 3;
+    const midO = c.mid * POSE_NODE_FLOATS + 3;
+    for (let i = 0; i < 4; i++) {
+        c.saved[i] = pose[rootO + i];
+        c.saved[4 + i] = pose[midO + i];
+    }
+    for (let i = 0; i <= last; i++) {
+        const wo = path[i] * WORLD_NODE_FLOATS;
+        c.world.set(worldPose.subarray(wo, wo + WORLD_NODE_FLOATS), i * WORLD_NODE_FLOATS);
+    }
+    toSkeleton(tgt, targetWorld, instanceWorld);
+    if (poleWorld)
+        toSkeleton(pol, poleWorld, instanceWorld);
+    const W = c.world;
+    const mo = c.midIndex * WORLD_NODE_FLOATS;
+    const to = last * WORLD_NODE_FLOATS;
+    for (let iter = 0; iter < iterations; iter++) {
+        const rx = W[3];
+        const ry = W[7];
+        const rz = W[11];
+        const mx = W[mo + 3];
+        const my = W[mo + 7];
+        const mz = W[mo + 11];
+        const tx = W[to + 3];
+        const ty = W[to + 7];
+        const tz = W[to + 11];
+        const a = Math.hypot(mx - rx, my - ry, mz - rz);
+        const b = Math.hypot(tx - mx, ty - my, tz - mz);
+        if (a <= EPS || b <= EPS)
+            break;
+        dir[0] = tgt[0] - rx;
+        dir[1] = tgt[1] - ry;
+        dir[2] = tgt[2] - rz;
+        const d = normalize(dir);
+        if (d <= EPS)
+            break;
+        // Out of reach: straight towards the target (cos 1); too close: folded (cos ±1).
+        const reach = Math.max(d, Math.abs(a - b), EPS);
+        const cos = d >= a + b ? 1 : Math.min(1, Math.max(-1, (a * a + reach * reach - b * b) / (2 * a * reach)));
+        const sin = Math.sqrt(Math.max(0, 1 - cos * cos));
+        // Bend direction: the pole (or the current mid) projected off the root→target line.
+        if (poleWorld) {
+            v[0] = pol[0] - rx;
+            v[1] = pol[1] - ry;
+            v[2] = pol[2] - rz;
+        }
+        else {
+            v[0] = mx - rx;
+            v[1] = my - ry;
+            v[2] = mz - rz;
+        }
+        let along = v[0] * dir[0] + v[1] * dir[1] + v[2] * dir[2];
+        perp[0] = v[0] - dir[0] * along;
+        perp[1] = v[1] - dir[1] * along;
+        perp[2] = v[2] - dir[2] * along;
+        if (normalize(perp) <= 1e-4) {
+            if (poleWorld) {
+                // Pole on the line: fall back to the chain's own bend, then to anything perpendicular.
+                v[0] = mx - rx;
+                v[1] = my - ry;
+                v[2] = mz - rz;
+                along = v[0] * dir[0] + v[1] * dir[1] + v[2] * dir[2];
+                perp[0] = v[0] - dir[0] * along;
+                perp[1] = v[1] - dir[1] * along;
+                perp[2] = v[2] - dir[2] * along;
+            }
+            if (normalize(perp) <= 1e-4)
+                anyPerpendicular(perp, dir);
+        }
+        // Where the mid joint must be, then the root rotation that puts it there.
+        m2[0] = rx + dir[0] * a * cos + perp[0] * a * sin;
+        m2[1] = ry + dir[1] * a * cos + perp[1] * a * sin;
+        m2[2] = rz + dir[2] * a * cos + perp[2] * a * sin;
+        v[0] = (mx - rx) / a;
+        v[1] = (my - ry) / a;
+        v[2] = (mz - rz) / a;
+        perp[0] = (m2[0] - rx) / a;
+        perp[1] = (m2[1] - ry) / a;
+        perp[2] = (m2[2] - rz) / a;
+        rotationBetween(d1, v, perp);
+        // The tip after the root rotation, then the mid rotation that brings it to the target.
+        t1[0] = tx - rx;
+        t1[1] = ty - ry;
+        t1[2] = tz - rz;
+        rotateBy(t1, d1);
+        t1[0] = t1[0] + rx - m2[0];
+        t1[1] = t1[1] + ry - m2[1];
+        t1[2] = t1[2] + rz - m2[2];
+        normalize(t1);
+        v[0] = tgt[0] - m2[0];
+        v[1] = tgt[1] - m2[1];
+        v[2] = tgt[2] - m2[2];
+        if (normalize(v) <= EPS) {
+            d2[3] = 0;
+        }
+        else
+            rotationBetween(d2, t1, v);
+        const rootParent = skeleton.parents[c.root];
+        if (rootParent < 0)
+            applyDelta(pose, c.root, d1, IDENTITY, 0, null);
+        else
+            applyDelta(pose, c.root, d1, worldPose, rootParent * WORLD_NODE_FLOATS, null);
+        applyDelta(pose, c.mid, d2, W, mo - WORLD_NODE_FLOATS, d1);
+        if (iter + 1 < iterations)
+            refreshChain(c, skeleton, pose, worldPose);
+    }
+    if (weight < 1) {
+        quatSlerp(pose, rootO, c.saved, 0, pose, rootO, weight);
+        quatSlerp(pose, midO, c.saved, 4, pose, midO, weight);
+    }
+}
+const DEFAULT_FORWARD = new Float32Array([0, 0, 1]);
+/**
+ * Rotate `joint` in `pose` so that its local `forward` axis points at `targetWorld`, turning at
+ * most `maxAngle` radians away from its input direction and blended by `weight`. With an `up`
+ * hint the joint also rolls so what was up for it stays up. Reads the joint's world matrix from
+ * `worldPose` (`poseToWorld` of the input pose) and its parent's; never rewrites it. No
+ * allocation.
+ */
+export function lookAt(pose, skeleton, worldPose, joint, targetWorld, instanceWorld, opts) {
+    const weight = opts?.weight ?? 1;
+    if (weight <= 0)
+        return;
+    const maxAngle = opts?.maxAngle ?? Math.PI;
+    const wo = joint * WORLD_NODE_FLOATS;
+    toSkeleton(tgt, targetWorld, instanceWorld);
+    transformDir(fwd, worldPose, wo, opts?.forward ?? DEFAULT_FORWARD);
+    if (normalize(fwd) <= EPS)
+        return;
+    v[0] = tgt[0] - worldPose[wo + 3];
+    v[1] = tgt[1] - worldPose[wo + 7];
+    v[2] = tgt[2] - worldPose[wo + 11];
+    if (normalize(v) <= EPS)
+        return;
+    rotationBetween(d1, fwd, v);
+    d1[3] = Math.min(d1[3], Math.max(0, maxAngle));
+    if (d1[3] === 0)
+        return;
+    const o = joint * POSE_NODE_FLOATS + 3;
+    for (let i = 0; i < 4; i++)
+        savedRot[i] = pose[o + i];
+    const parent = skeleton.parents[joint];
+    const pm = parent < 0 ? IDENTITY : worldPose;
+    const po = parent < 0 ? 0 : parent * WORLD_NODE_FLOATS;
+    applyDelta(pose, joint, d1, pm, po, null);
+    const up = opts?.up;
+    if (up) {
+        // The up hint off the old forward, carried along by the aim, against the hint off the new
+        // forward: the roll between them is the twist that keeps "up" up.
+        upw[0] = up[0];
+        upw[1] = up[1];
+        upw[2] = up[2];
+        let along = upw[0] * fwd[0] + upw[1] * fwd[1] + upw[2] * fwd[2];
+        t1[0] = upw[0] - fwd[0] * along;
+        t1[1] = upw[1] - fwd[1] * along;
+        t1[2] = upw[2] - fwd[2] * along;
+        rotateBy(fwd, d1);
+        if (normalize(t1) > EPS) {
+            rotateBy(t1, d1);
+            along = upw[0] * fwd[0] + upw[1] * fwd[1] + upw[2] * fwd[2];
+            m2[0] = upw[0] - fwd[0] * along;
+            m2[1] = upw[1] - fwd[1] * along;
+            m2[2] = upw[2] - fwd[2] * along;
+            if (normalize(m2) > EPS) {
+                rotationBetween(d2, t1, m2);
+                applyDelta(pose, joint, d2, pm, po, null);
+            }
+        }
+    }
+    if (weight < 1)
+        quatSlerp(pose, o, savedRot, 0, pose, o, weight);
+}

package/dist/anim/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@thunderclap-engine/engine/anim`: keyframe clips (glTF sampler semantics) sampled into poses,
+ * blended and cross-faded by a mixer, resolved into node world matrices and skin joint matrices.
+ * Pure arithmetic, no GPU, no allocations per frame.
+ */
+export type { AimOffset, AimOffsetDesc, AimOffsetOptions } from './aim.js';
+export { applyAimOffset, createAimOffset } from './aim.js';
+export type { AnimationChannel, AnimationClip, AnimationEvent, AnimBlendMode, ChannelPath, ClipCursor, Interpolation, } from './clip.js';
+export { channelComponents, clipDuration, createClipCursor, findKeyframe, sampleChannel, sampleClip, sampleWeights, unpackQuat, } from './clip.js';
+export type { CompressClipOptions, CompressedClip, QuantizeClipOptions } from './compress.js';
+export { clipBytes, compressClip, packQuat, quantizeClip } from './compress.js';
+export type { FootIk, FootIkDesc, FootIkFootDesc, FootIkProbe } from './foot-ik.js';
+export { applyFootIk, createFootIk } from './foot-ik.js';
+export type { AnimGraph, AnimGraphBlend1D, AnimGraphBlend2D, AnimGraphBlendPoint, AnimGraphBlendPoint2D, AnimGraphBlendState, AnimGraphClipState, AnimGraphDesc, AnimGraphListener, AnimGraphMatchDesc, AnimGraphParams, AnimGraphStateDesc, AnimGraphTransition, } from './graph.js';
+export { createAnimGraph } from './graph.js';
+export type { IkChain, IkChainDesc, LookAtOptions, TwoBoneIkOptions } from './ik.js';
+export { createIkChain, lookAt, twoBoneIk } from './ik.js';
+export type { FindBestFrameOptions, PoseFeatures, PoseFeaturesOptions, PoseMatch } from './match.js';
+export { buildPoseFeatures, findBestFrame, rootSpacePositions } from './match.js';
+export type { AnimationEventListener, AnimationMixerOptions, AnimPlayOptions, } from './mixer.js';
+export { AnimationAction, AnimationMixer } from './mixer.js';
+export type { MorphBlender, MorphLayout, MorphTarget } from './morph.js';
+export { createMorphBlender } from './morph.js';
+export type { Pose, Skeleton } from './pose.js';
+export { blendPose, copyPose, createPose, inverseBindFromRest, invertAffine, jointCount, multiplyAffine, nodeCount, POSE_NODE_FLOATS, poseToWorld, skinMatrices, validateSkeleton, WORLD_NODE_FLOATS, writeNodeMatrix, } from './pose.js';
+export { quatDot, quatFromAxisAngle, quatFromEuler, quatFromMat3, quatIdentity, quatMultiply, quatNlerp, quatNormalize, quatSlerp, } from './quat.js';
+export type { RetargetClipOptions, RetargetMap, RetargetOptions } from './retarget.js';
+export { createRetargetMap, normalizeJointName, retargetClip, retargetPose } from './retarget.js';
+export type { RootMotionDelta, RootMotionOptions, RootMotionSplit } from './root-motion.js';
+export { applyRootMotionDelta, extractRootMotion } from './root-motion.js';
+export type { SkinPoseSource, SkinPoseTarget } from './skin-pose.js';
+export { skinPose } from './skin-pose.js';
+export type { Socket, SocketLocal } from './socket.js';
+export { attachTransform, createSocket, socketWorld } from './socket.js';
+export type { SpringCapsule, SpringChain, SpringChainDesc, SpringCollider, SpringSphere, } from './spring-chain.js';
+export { createSpringChain, updateSpringChain } from './spring-chain.js';

package/dist/anim/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@thunderclap-engine/engine/anim`: keyframe clips (glTF sampler semantics) sampled into poses,
+ * blended and cross-faded by a mixer, resolved into node world matrices and skin joint matrices.
+ * Pure arithmetic, no GPU, no allocations per frame.
+ */
+export { applyAimOffset, createAimOffset } from './aim.js';
+export { channelComponents, clipDuration, createClipCursor, findKeyframe, sampleChannel, sampleClip, sampleWeights, unpackQuat, } from './clip.js';
+export { clipBytes, compressClip, packQuat, quantizeClip } from './compress.js';
+export { applyFootIk, createFootIk } from './foot-ik.js';
+export { createAnimGraph } from './graph.js';
+export { createIkChain, lookAt, twoBoneIk } from './ik.js';
+export { buildPoseFeatures, findBestFrame, rootSpacePositions } from './match.js';
+export { AnimationAction, AnimationMixer } from './mixer.js';
+export { createMorphBlender } from './morph.js';
+export { blendPose, copyPose, createPose, inverseBindFromRest, invertAffine, jointCount, multiplyAffine, nodeCount, POSE_NODE_FLOATS, poseToWorld, skinMatrices, validateSkeleton, WORLD_NODE_FLOATS, writeNodeMatrix, } from './pose.js';
+export { quatDot, quatFromAxisAngle, quatFromEuler, quatFromMat3, quatIdentity, quatMultiply, quatNlerp, quatNormalize, quatSlerp, } from './quat.js';
+export { createRetargetMap, normalizeJointName, retargetClip, retargetPose } from './retarget.js';
+export { applyRootMotionDelta, extractRootMotion } from './root-motion.js';
+export { skinPose } from './skin-pose.js';
+export { attachTransform, createSocket, socketWorld } from './socket.js';
+export { createSpringChain, updateSpringChain } from './spring-chain.js';

package/dist/anim/match.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pose matching: a transition starts the target clip at the frame nearest the pose it leaves,
+ * instead of at 0, so a walk→run blend does not snap a planted foot to the other leg.
+ *
+ * `buildPoseFeatures` samples a clip at a fixed rate and stores, per sample, the root-space
+ * position and velocity of a few joints (feet, hands, head). `findBestFrame` compares a pose's
+ * world matrices (plus per-joint velocities) against every sample and returns the time of the
+ * cheapest one. Root space is the frame of one node (the first root by default) so a clip's
+ * baked travel and the instance's placement drop out. Allocates at build; the query allocates
+ * nothing when given an `out`.
+ */
+import { type AnimationClip } from './clip.js';
+import { type Skeleton } from './pose.js';
+export interface PoseFeaturesOptions {
+    /** Node indices whose position and velocity make up a feature (feet, hands, head). */
+    joints: ArrayLike<number>;
+    /** Samples per second along the clip. Default 30. */
+    sampleRate?: number;
+    /** The node whose frame is "root space". Default: the first node with no parent. */
+    root?: number;
+}
+/** Per-sample joint positions and velocities of one clip, from `buildPoseFeatures`. */
+export interface PoseFeatures {
+    readonly clip: AnimationClip;
+    readonly joints: Int16Array;
+    readonly root: number;
+    /** Sample times, ascending from 0. */
+    readonly times: Float32Array;
+    /** `6 × joints` floats per sample: `px py pz vx vy vz` per joint, root space. */
+    readonly data: Float32Array;
+    /** Floats per sample (`6 × joints`). */
+    readonly stride: number;
+}
+export interface FindBestFrameOptions {
+    /** Weight of the velocity term (s²; a velocity gap of 1 m/s costs this much). Default 0.05. */
+    velocityWeight?: number;
+}
+/** The result of `findBestFrame`: the clip time of the cheapest sample and its cost. */
+export interface PoseMatch {
+    time: number;
+    cost: number;
+}
+/** @internal The first node with no parent (0 when none). */
+export declare function firstRoot(skeleton: Skeleton): number;
+/**
+ * Sample `clip` on `skeleton` every `1 / sampleRate` seconds (the last sample at the clip's
+ * duration) and record, per sample and per joint of `opts.joints`, the joint's root-space
+ * position and velocity (finite difference to the next sample; the last sample wraps to the
+ * first, as a looping clip does). Allocates; call at load.
+ */
+export declare function buildPoseFeatures(clip: AnimationClip, skeleton: Skeleton, opts: PoseFeaturesOptions): PoseFeatures;
+/**
+ * Root-space positions of `joints` (3 floats each into `out`) from a pose's world matrices:
+ * what a velocity for `findBestFrame` is the time derivative of. Allocation-free.
+ */
+export declare function rootSpacePositions(poseWorld: Float32Array, root: number, joints: ArrayLike<number>, out: Float32Array): void;
+/**
+ * The sample of `features` nearest a pose: `poseWorld` is `poseToWorld` of that pose (skeleton
+ * space; the root node's matrix in it defines root space), `velocity` holds the root-space
+ * velocity of each feature joint (`3 × joints` floats in `features.joints` order: the
+ * derivative of `rootSpacePositions`, so the root's own travel drops out), or `null` to match
+ * on positions alone. Cost per sample is the summed squared position gap plus `velocityWeight`
+ * times the summed squared velocity gap. Writes and returns `out` (a shared object when none
+ * is given). No allocation with `out`.
+ */
+export declare function findBestFrame(features: PoseFeatures, poseWorld: Float32Array, velocity: ArrayLike<number> | null, opts?: FindBestFrameOptions, out?: PoseMatch): PoseMatch;