@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/aim.d.ts

@@ -0,0 +1,43 @@
+import { type Pose, type Skeleton } from './pose.js';
+export interface AimOffsetDesc {
+    /** Joints from the base of the chain to the one that aims (the head), ancestors first. */
+    joints: ArrayLike<number>;
+    /** Share of the turn per joint, normalised to sum 1. Default: equal shares. */
+    weights?: ArrayLike<number>;
+    /** Largest yaw (radians) either way. Default `Math.PI / 2`. */
+    maxYaw?: number;
+    /** Largest pitch (radians) either way. Default `Math.PI / 3`. */
+    maxPitch?: number;
+    /** The aiming joint's local axis that should point at the target. Default `[0, 0, 1]`. */
+    forward?: ArrayLike<number>;
+    /** Skeleton-space up: yaw turns about it, pitch about the side axis. Default `[0, 1, 0]`. */
+    up?: ArrayLike<number>;
+}
+export interface AimOffsetOptions {
+    /** 0..1 blend against the sampled rotations. Default 1. */
+    weight?: number;
+}
+/** An aim chain with its scratch, from `createAimOffset`; `yaw`/`pitch` are the last applied. */
+export interface AimOffset {
+    readonly joints: Int16Array;
+    readonly weights: Float32Array;
+    readonly maxYaw: number;
+    readonly maxPitch: number;
+    readonly forward: Float32Array;
+    readonly up: Float32Array;
+    /** The clamped yaw of the last `applyAimOffset` (radians, + toward the side axis). */
+    yaw: number;
+    /** The clamped pitch of the last `applyAimOffset` (radians, + toward `up`). */
+    pitch: number;
+    /** @internal the input local rotations per joint (for `weight`). */
+    readonly saved: Float32Array;
+}
+/** Validate and allocate an aim chain; call once. Weights are normalised to sum 1. */
+export declare function createAimOffset(skeleton: Skeleton, desc: AimOffsetDesc): AimOffset;
+/**
+ * Turn the chain of `aim` so the last joint's forward points at `targetWorld`, yaw and pitch
+ * each clamped, the turn shared by the joints' weights. The pivot is the last joint; the
+ * reference forward is that joint's as sampled (an aim offset of zero leaves the pose as it
+ * is). `weight` slerps every joint against its sampled rotation. No allocation.
+ */
+export declare function applyAimOffset(pose: Pose, skeleton: Skeleton, worldPose: Float32Array, aim: AimOffset, targetWorld: ArrayLike<number>, instanceWorld: Float32Array | null, opts?: AimOffsetOptions): void;

package/dist/anim/aim.js

@@ -0,0 +1,157 @@
+/**
+ * Aim offset: a multi-joint `lookAt`. The yaw and pitch from the last joint's forward axis
+ * toward a world target are clamped, then spread across a chain (spine, spine, head) by
+ * weight, additive on top of the sampled pose. Rotations about one skeleton-space axis add
+ * exactly, so the chain's summed turn reaches the clamped target. Same conventions as `ik.ts`:
+ * reads `worldPose` (the sampled pose's world matrices), writes local rotations into `pose`;
+ * `instanceWorld` is the 3×4 instance matrix or `null` for skeleton-space targets. Allocates
+ * in `createAimOffset`, nothing per call.
+ */
+import { anyPerpendicular, applyDelta, IDENTITY, normalize, rotateByQuat, toSkeleton, transformDir, } from './ik.js';
+import { POSE_NODE_FLOATS, WORLD_NODE_FLOATS } from './pose.js';
+import { quatFromAxisAngle, quatMultiply, quatNormalize, quatSlerp } from './quat.js';
+const EPS = 1e-6;
+/** Validate and allocate an aim chain; call once. Weights are normalised to sum 1. */
+export function createAimOffset(skeleton, desc) {
+    const n = skeleton.parents.length;
+    const joints = Int16Array.from(desc.joints);
+    if (joints.length === 0)
+        throw new Error('AimOffset: at least one joint');
+    for (let i = 0; i < joints.length; i++) {
+        const j = joints[i];
+        if (j < 0 || j >= n)
+            throw new Error(`AimOffset: joint ${j} must be in [0, ${n})`);
+        if (i > 0) {
+            // Each joint descends from the one before it.
+            let p = skeleton.parents[j];
+            while (p >= 0 && p !== joints[i - 1])
+                p = skeleton.parents[p];
+            if (p < 0)
+                throw new Error(`AimOffset: joint ${j} does not descend from ${joints[i - 1]}`);
+        }
+    }
+    const weights = new Float32Array(joints.length);
+    let sum = 0;
+    for (let i = 0; i < joints.length; i++) {
+        const w = desc.weights ? desc.weights[i] : 1;
+        if (w === undefined || w < 0)
+            throw new Error(`AimOffset: weight ${i} must be >= 0`);
+        weights[i] = w;
+        sum += w;
+    }
+    if (sum <= 0)
+        throw new Error('AimOffset: weights sum to 0');
+    for (let i = 0; i < weights.length; i++)
+        weights[i] = weights[i] / sum;
+    const forward = Float32Array.from(desc.forward ?? [0, 0, 1]);
+    const up = Float32Array.from(desc.up ?? [0, 1, 0]);
+    if (normalize(forward) <= EPS || normalize(up) <= EPS)
+        throw new Error('AimOffset: forward and up must be non-zero');
+    return {
+        joints,
+        weights,
+        maxYaw: desc.maxYaw ?? Math.PI / 2,
+        maxPitch: desc.maxPitch ?? Math.PI / 3,
+        forward,
+        up,
+        yaw: 0,
+        pitch: 0,
+        saved: new Float32Array(joints.length * 4),
+    };
+}
+const tgt = new Float32Array(3);
+const fwd = new Float32Array(3);
+const dir = new Float32Array(3);
+const side = new Float32Array(3);
+const flat = new Float32Array(3);
+const qy = new Float32Array(4);
+const qp = new Float32Array(4);
+const q = new Float32Array(4);
+const delta = new Float32Array(4);
+/**
+ * Turn the chain of `aim` so the last joint's forward points at `targetWorld`, yaw and pitch
+ * each clamped, the turn shared by the joints' weights. The pivot is the last joint; the
+ * reference forward is that joint's as sampled (an aim offset of zero leaves the pose as it
+ * is). `weight` slerps every joint against its sampled rotation. No allocation.
+ */
+export function applyAimOffset(pose, skeleton, worldPose, aim, targetWorld, instanceWorld, opts) {
+    const weight = opts?.weight ?? 1;
+    aim.yaw = 0;
+    aim.pitch = 0;
+    if (weight <= 0)
+        return;
+    const joints = aim.joints;
+    const head = joints[joints.length - 1];
+    const wo = head * WORLD_NODE_FLOATS;
+    toSkeleton(tgt, targetWorld, instanceWorld);
+    transformDir(fwd, worldPose, wo, aim.forward);
+    if (normalize(fwd) <= EPS)
+        return;
+    dir[0] = tgt[0] - worldPose[wo + 3];
+    dir[1] = tgt[1] - worldPose[wo + 7];
+    dir[2] = tgt[2] - worldPose[wo + 11];
+    if (normalize(dir) <= EPS)
+        return;
+    // A frame from up and the sampled forward: `flat` is forward levelled, `side` = up × flat.
+    const up = aim.up;
+    const fu = fwd[0] * up[0] + fwd[1] * up[1] + fwd[2] * up[2];
+    flat[0] = fwd[0] - up[0] * fu;
+    flat[1] = fwd[1] - up[1] * fu;
+    flat[2] = fwd[2] - up[2] * fu;
+    if (normalize(flat) <= EPS)
+        anyPerpendicular(flat, up);
+    side[0] = up[1] * flat[2] - up[2] * flat[1];
+    side[1] = up[2] * flat[0] - up[0] * flat[2];
+    side[2] = up[0] * flat[1] - up[1] * flat[0];
+    normalize(side);
+    // Yaw and pitch of the target direction relative to the sampled forward.
+    const dFlat = dir[0] * flat[0] + dir[1] * flat[1] + dir[2] * flat[2];
+    const dSide = dir[0] * side[0] + dir[1] * side[1] + dir[2] * side[2];
+    const dUp = dir[0] * up[0] + dir[1] * up[1] + dir[2] * up[2];
+    const fFlat = Math.hypot(flat[0] * fu - fwd[0], flat[1] * fu - fwd[1], flat[2] * fu - fwd[2]);
+    let yaw = Math.atan2(dSide, dFlat);
+    let pitch = Math.atan2(dUp, Math.hypot(dFlat, dSide)) - Math.atan2(fu, fFlat);
+    if (pitch > Math.PI)
+        pitch -= 2 * Math.PI;
+    if (pitch < -Math.PI)
+        pitch += 2 * Math.PI;
+    const maxYaw = Math.max(0, aim.maxYaw);
+    const maxPitch = Math.max(0, aim.maxPitch);
+    yaw = Math.min(maxYaw, Math.max(-maxYaw, yaw));
+    pitch = Math.min(maxPitch, Math.max(-maxPitch, pitch));
+    aim.yaw = yaw;
+    aim.pitch = pitch;
+    if (yaw === 0 && pitch === 0)
+        return;
+    // One rotation: pitch about the yawed side axis after yaw about up (q = qp · qy). A positive
+    // turn about `side = up × flat` lowers the forward, so pitch goes in negated.
+    quatFromAxisAngle(qy, 0, up[0], up[1], up[2], yaw);
+    rotateByQuat(side, qy, 0);
+    quatFromAxisAngle(qp, 0, side[0], side[1], side[2], -pitch);
+    quatMultiply(q, 0, qp, 0, qy, 0);
+    quatNormalize(q, 0);
+    const w = q[3];
+    const s = Math.sqrt(Math.max(0, 1 - w * w));
+    if (s <= EPS)
+        return;
+    delta[0] = q[0] / s;
+    delta[1] = q[1] / s;
+    delta[2] = q[2] / s;
+    const angle = 2 * Math.atan2(s, w);
+    // Share the angle out along the chain. The joints below the first rotate with it, so each
+    // delta is taken against the parent's sampled matrix (the axis is the same for all).
+    for (let i = 0; i < joints.length; i++) {
+        const j = joints[i];
+        const o = j * POSE_NODE_FLOATS + 3;
+        for (let c = 0; c < 4; c++)
+            aim.saved[i * 4 + c] = pose[o + c];
+        delta[3] = angle * aim.weights[i];
+        const parent = skeleton.parents[j];
+        if (parent < 0)
+            applyDelta(pose, j, delta, IDENTITY, 0, null);
+        else
+            applyDelta(pose, j, delta, worldPose, parent * WORLD_NODE_FLOATS, null);
+        if (weight < 1)
+            quatSlerp(pose, o, aim.saved, i * 4, pose, o, weight);
+    }
+}

package/dist/anim/clip.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Keyframe clips with glTF sampler semantics, sampled into a `Pose`.
+ *
+ * A channel is one glTF animation sampler + target: `times` (seconds, ascending) and `values`
+ * (packed components per key: 3 for translation and scale, 4 for rotation, N for morph
+ * `weights`). `CUBICSPLINE` stores three vectors per key: in-tangent, value, out-tangent
+ * (glTF order). Outside `[times[0], times[last]]` the first or last value holds; looping is the
+ * mixer's job.
+ *
+ * Sampling keeps a per-channel keyframe cursor (`ClipCursor`, one `Uint32Array` per clip, or one
+ * per playing action in the mixer) so a time that moves forward costs O(1) amortised; a jump
+ * falls back to a binary search. Nothing allocates per call.
+ */
+import { type Pose } from './pose.js';
+export type ChannelPath = 'translation' | 'rotation' | 'scale' | 'weights';
+export type Interpolation = 'STEP' | 'LINEAR' | 'CUBICSPLINE';
+export interface AnimationChannel {
+    /** Target node index (into the skeleton / pose). */
+    node: number;
+    path: ChannelPath;
+    interpolation: Interpolation;
+    /** Keyframe times in seconds, ascending. */
+    times: Float32Array;
+    /**
+     * Packed values: `times.length × components` floats, or `× 3` for `CUBICSPLINE`
+     * (in-tangent, value, out-tangent per key).
+     */
+    values: Float32Array;
+    /**
+     * Quantised rotation keys from `quantizeClip` (`compress.ts`): three `uint16` per key in
+     * smallest-three form (`unpackQuat`), read instead of `values` when present. Only on
+     * `rotation` channels with `STEP` or `LINEAR` interpolation.
+     */
+    packed?: Uint16Array;
+}
+/** A named time in a clip; the mixer reports each crossing through `onEvent`. */
+export interface AnimationEvent {
+    time: number;
+    name: string;
+}
+export interface AnimationClip {
+    name: string;
+    /** Seconds. Normally `max(times)` over the channels; the mixer loops at it. */
+    duration: number;
+    channels: AnimationChannel[];
+    events?: AnimationEvent[];
+}
+/** Keyframe cursor per channel, see `createClipCursor`. */
+export type ClipCursor = Uint32Array;
+/** How `sampleClip` writes into the pose. */
+export type AnimBlendMode = 'override' | 'additive';
+/** Components per key of a channel (3, 4, or the morph weight count). */
+export declare function channelComponents(channel: AnimationChannel): number;
+/** A clip whose `duration` is the last keyframe time over its channels (0 when empty). */
+export declare function clipDuration(channels: readonly AnimationChannel[]): number;
+/** A fresh cursor for `clip` (one slot per channel). */
+export declare function createClipCursor(clip: AnimationClip): ClipCursor;
+/**
+ * Index `k` with `times[k] <= t < times[k+1]`, clamped to `[0, n-2]` (`0` for one key). Checks
+ * the hint and the key after it first, then binary-searches.
+ */
+export declare function findKeyframe(times: Float32Array, t: number, hint: number): number;
+/**
+ * Sample one channel at time `t` into `out[o..o+components)`. Rotations are slerped (`LINEAR`)
+ * or normalised (`CUBICSPLINE`). `cursor[ci]` (optional) is the keyframe hint, updated in place.
+ */
+export declare function sampleChannel(channel: AnimationChannel, t: number, out: Float32Array, o: number, cursor?: Uint32Array, ci?: number): void;
+/**
+ * Decode key `key` of a smallest-three packed rotation (`AnimationChannel.packed`) into
+ * `out[o..o+4)`. Each key is three `uint16`: bits 0..14 hold the three smaller components as
+ * `round((c + 1/√2) × 32767/√2)`; bit 15 of words 0 and 1 hold the index of the largest
+ * component, which is rebuilt as `sqrt(1 − Σc²)` (the quaternion was flipped to make it
+ * positive). No allocation.
+ */
+export declare function unpackQuat(packed: Uint16Array, key: number, out: Float32Array, o: number): void;
+/**
+ * Sample every channel of `clip` at `t` into `pose`.
+ *
+ * - `'override'`: each animated component becomes `lerp(pose, sampled, weight)` (slerp for
+ *   rotations); `weight` 1 writes the value outright.
+ * - `'additive'`: the clip's values are deltas. Translation adds `weight × v`, scale multiplies
+ *   by `lerp(1, v, weight)`, rotation post-multiplies `slerp(identity, q, weight)`. A "floating"
+ *   idle on top of a walk is one additive channel on the root.
+ *
+ * `'weights'` (morph) channels are skipped: a pose has no morph slots; sample them with
+ * `sampleWeights`. A channel whose node is outside the pose is skipped. `cursor` defaults to a
+ * cursor shared per clip; pass your own when one clip plays at two times at once (the mixer
+ * does). No allocation.
+ */
+export declare function sampleClip(clip: AnimationClip, t: number, pose: Pose, weight?: number, blend?: AnimBlendMode, cursor?: ClipCursor): void;
+/**
+ * Sample the `'weights'` channel of `clip` targeting `node` at `t` into `out[0..n)`, where `n`
+ * is the channel's weight count (`channelComponents`): the same interpolation as `sampleClip`
+ * (STEP, LINEAR, CUBICSPLINE, hold outside the key range). Returns false, writing nothing, when
+ * the clip has no weights channel for `node`. Throws `RangeError` when `out` is too short.
+ * `cursor` as in `sampleClip`. No allocation.
+ */
+export declare function sampleWeights(clip: AnimationClip, node: number, t: number, out: Float32Array, cursor?: ClipCursor): boolean;

package/dist/anim/clip.js

@@ -0,0 +1,282 @@
+/**
+ * Keyframe clips with glTF sampler semantics, sampled into a `Pose`.
+ *
+ * A channel is one glTF animation sampler + target: `times` (seconds, ascending) and `values`
+ * (packed components per key: 3 for translation and scale, 4 for rotation, N for morph
+ * `weights`). `CUBICSPLINE` stores three vectors per key: in-tangent, value, out-tangent
+ * (glTF order). Outside `[times[0], times[last]]` the first or last value holds; looping is the
+ * mixer's job.
+ *
+ * Sampling keeps a per-channel keyframe cursor (`ClipCursor`, one `Uint32Array` per clip, or one
+ * per playing action in the mixer) so a time that moves forward costs O(1) amortised; a jump
+ * falls back to a binary search. Nothing allocates per call.
+ */
+import { POSE_NODE_FLOATS } from './pose.js';
+import { quatIdentity, quatMultiply, quatNormalize, quatSlerp } from './quat.js';
+/** Components per key of a channel (3, 4, or the morph weight count). */
+export function channelComponents(channel) {
+    switch (channel.path) {
+        case 'translation':
+        case 'scale':
+            return 3;
+        case 'rotation':
+            return 4;
+        default: {
+            const keys = channel.times.length;
+            if (keys === 0)
+                return 0;
+            const per = channel.values.length / keys;
+            return channel.interpolation === 'CUBICSPLINE' ? per / 3 : per;
+        }
+    }
+}
+/** A clip whose `duration` is the last keyframe time over its channels (0 when empty). */
+export function clipDuration(channels) {
+    let d = 0;
+    for (const c of channels) {
+        const n = c.times.length;
+        if (n > 0)
+            d = Math.max(d, c.times[n - 1]);
+    }
+    return d;
+}
+/** A fresh cursor for `clip` (one slot per channel). */
+export function createClipCursor(clip) {
+    return new Uint32Array(Math.max(1, clip.channels.length));
+}
+const cursors = new WeakMap();
+function cursorFor(clip) {
+    let c = cursors.get(clip);
+    if (!c || c.length < clip.channels.length) {
+        c = createClipCursor(clip);
+        cursors.set(clip, c);
+    }
+    return c;
+}
+/**
+ * Index `k` with `times[k] <= t < times[k+1]`, clamped to `[0, n-2]` (`0` for one key). Checks
+ * the hint and the key after it first, then binary-searches.
+ */
+export function findKeyframe(times, t, hint) {
+    const n = times.length;
+    if (n < 2)
+        return 0;
+    const last = n - 2;
+    const h = Math.min(hint, last);
+    if (times[h] <= t) {
+        if (t < times[h + 1])
+            return h;
+        if (h < last && times[h + 1] <= t && t < times[h + 2])
+            return h + 1;
+        if (h === last)
+            return last;
+    }
+    if (t >= times[n - 1])
+        return last;
+    if (t <= times[0])
+        return 0;
+    let lo = 0;
+    let hi = last;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (times[mid] <= t)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/**
+ * Sample one channel at time `t` into `out[o..o+components)`. Rotations are slerped (`LINEAR`)
+ * or normalised (`CUBICSPLINE`). `cursor[ci]` (optional) is the keyframe hint, updated in place.
+ */
+export function sampleChannel(channel, t, out, o, cursor, ci = 0) {
+    const times = channel.times;
+    const n = times.length;
+    const comps = channelComponents(channel);
+    if (n === 0 || comps === 0)
+        return;
+    const cubic = channel.interpolation === 'CUBICSPLINE';
+    const stride = cubic ? comps * 3 : comps;
+    const k = findKeyframe(times, t, cursor ? cursor[ci] : 0);
+    if (cursor)
+        cursor[ci] = k;
+    const packed = channel.packed;
+    let values = channel.values;
+    let base0 = k * stride + (cubic ? comps : 0);
+    let base1 = (k + 1) * stride + (cubic ? comps : 0);
+    if (packed && channel.path === 'rotation' && !cubic) {
+        // Packed keys: decode the two around `t` into scratch and sample from there.
+        unpackQuat(packed, k, unpacked, 0);
+        if (n > 1)
+            unpackQuat(packed, k + 1, unpacked, 4);
+        values = unpacked;
+        base0 = 0;
+        base1 = 4;
+    }
+    const t0 = times[k];
+    const t1 = n > 1 ? times[k + 1] : t0;
+    if (n > 1 && t >= t1) {
+        // At or past the last key (k is clamped to n-2): hold the last value.
+        for (let i = 0; i < comps; i++)
+            out[o + i] = values[base1 + i];
+        return;
+    }
+    if (n === 1 || t <= t0 || channel.interpolation === 'STEP') {
+        for (let i = 0; i < comps; i++)
+            out[o + i] = values[base0 + i];
+        return;
+    }
+    const td = t1 - t0;
+    const u = (t - t0) / td;
+    if (cubic) {
+        // glTF: p(u) = h00·v0 + h10·td·b0 + h01·v1 + h11·td·a1 (a = in-tangent, b = out-tangent).
+        const u2 = u * u;
+        const u3 = u2 * u;
+        const h00 = 2 * u3 - 3 * u2 + 1;
+        const h10 = (u3 - 2 * u2 + u) * td;
+        const h01 = -2 * u3 + 3 * u2;
+        const h11 = (u3 - u2) * td;
+        const v0 = k * stride + comps;
+        const b0 = v0 + comps;
+        const a1 = (k + 1) * stride;
+        const v1 = a1 + comps;
+        for (let i = 0; i < comps; i++) {
+            out[o + i] =
+                h00 * values[v0 + i] +
+                    h10 * values[b0 + i] +
+                    h01 * values[v1 + i] +
+                    h11 * values[a1 + i];
+        }
+        if (channel.path === 'rotation')
+            quatNormalize(out, o);
+        return;
+    }
+    if (channel.path === 'rotation') {
+        quatSlerp(out, o, values, base0, values, base1, u);
+        return;
+    }
+    const s = 1 - u;
+    for (let i = 0; i < comps; i++)
+        out[o + i] = s * values[base0 + i] + u * values[base1 + i];
+}
+const sample = new Float32Array(4);
+const delta = new Float32Array(4);
+const unpacked = new Float32Array(8);
+/** Scale of a 15-bit smallest-three component: the range is ±1/√2. */
+const PACK_SCALE = 32767 / Math.SQRT2;
+/**
+ * Decode key `key` of a smallest-three packed rotation (`AnimationChannel.packed`) into
+ * `out[o..o+4)`. Each key is three `uint16`: bits 0..14 hold the three smaller components as
+ * `round((c + 1/√2) × 32767/√2)`; bit 15 of words 0 and 1 hold the index of the largest
+ * component, which is rebuilt as `sqrt(1 − Σc²)` (the quaternion was flipped to make it
+ * positive). No allocation.
+ */
+export function unpackQuat(packed, key, out, o) {
+    const b = key * 3;
+    const w0 = packed[b];
+    const w1 = packed[b + 1];
+    const w2 = packed[b + 2];
+    const largest = ((w0 >> 15) << 1) | (w1 >> 15);
+    const a = (w0 & 0x7fff) / PACK_SCALE - Math.SQRT1_2;
+    const c = (w1 & 0x7fff) / PACK_SCALE - Math.SQRT1_2;
+    const d = (w2 & 0x7fff) / PACK_SCALE - Math.SQRT1_2;
+    const rest = 1 - a * a - c * c - d * d;
+    const big = rest > 0 ? Math.sqrt(rest) : 0;
+    // The three small components fill the slots other than `largest`, in order.
+    const s0 = largest === 0 ? 1 : 0;
+    const s1 = largest <= 1 ? 2 : 1;
+    const s2 = largest === 3 ? 2 : 3;
+    out[o + largest] = big;
+    out[o + s0] = a;
+    out[o + s1] = c;
+    out[o + s2] = d;
+}
+/**
+ * Sample every channel of `clip` at `t` into `pose`.
+ *
+ * - `'override'`: each animated component becomes `lerp(pose, sampled, weight)` (slerp for
+ *   rotations); `weight` 1 writes the value outright.
+ * - `'additive'`: the clip's values are deltas. Translation adds `weight × v`, scale multiplies
+ *   by `lerp(1, v, weight)`, rotation post-multiplies `slerp(identity, q, weight)`. A "floating"
+ *   idle on top of a walk is one additive channel on the root.
+ *
+ * `'weights'` (morph) channels are skipped: a pose has no morph slots; sample them with
+ * `sampleWeights`. A channel whose node is outside the pose is skipped. `cursor` defaults to a
+ * cursor shared per clip; pass your own when one clip plays at two times at once (the mixer
+ * does). No allocation.
+ */
+export function sampleClip(clip, t, pose, weight = 1, blend = 'override', cursor = cursorFor(clip)) {
+    const channels = clip.channels;
+    const nodes = (pose.length / POSE_NODE_FLOATS) | 0;
+    for (let ci = 0; ci < channels.length; ci++) {
+        const ch = channels[ci];
+        if (ch.path === 'weights' || ch.node < 0 || ch.node >= nodes)
+            continue;
+        sampleChannel(ch, t, sample, 0, cursor, ci);
+        const o = ch.node * POSE_NODE_FLOATS;
+        if (blend === 'override') {
+            if (ch.path === 'rotation') {
+                if (weight >= 1) {
+                    pose[o + 3] = sample[0];
+                    pose[o + 4] = sample[1];
+                    pose[o + 5] = sample[2];
+                    pose[o + 6] = sample[3];
+                }
+                else
+                    quatSlerp(pose, o + 3, pose, o + 3, sample, 0, weight);
+            }
+            else {
+                const b = ch.path === 'translation' ? o : o + 7;
+                if (weight >= 1) {
+                    pose[b] = sample[0];
+                    pose[b + 1] = sample[1];
+                    pose[b + 2] = sample[2];
+                }
+                else {
+                    const s = 1 - weight;
+                    pose[b] = s * pose[b] + weight * sample[0];
+                    pose[b + 1] = s * pose[b + 1] + weight * sample[1];
+                    pose[b + 2] = s * pose[b + 2] + weight * sample[2];
+                }
+            }
+        }
+        else if (ch.path === 'translation') {
+            pose[o] += weight * sample[0];
+            pose[o + 1] += weight * sample[1];
+            pose[o + 2] += weight * sample[2];
+        }
+        else if (ch.path === 'scale') {
+            pose[o + 7] *= 1 + weight * (sample[0] - 1);
+            pose[o + 8] *= 1 + weight * (sample[1] - 1);
+            pose[o + 9] *= 1 + weight * (sample[2] - 1);
+        }
+        else {
+            quatIdentity(delta, 0);
+            quatSlerp(delta, 0, delta, 0, sample, 0, weight);
+            quatMultiply(pose, o + 3, pose, o + 3, delta, 0);
+            quatNormalize(pose, o + 3);
+        }
+    }
+}
+/**
+ * Sample the `'weights'` channel of `clip` targeting `node` at `t` into `out[0..n)`, where `n`
+ * is the channel's weight count (`channelComponents`): the same interpolation as `sampleClip`
+ * (STEP, LINEAR, CUBICSPLINE, hold outside the key range). Returns false, writing nothing, when
+ * the clip has no weights channel for `node`. Throws `RangeError` when `out` is too short.
+ * `cursor` as in `sampleClip`. No allocation.
+ */
+export function sampleWeights(clip, node, t, out, cursor = cursorFor(clip)) {
+    const channels = clip.channels;
+    for (let ci = 0; ci < channels.length; ci++) {
+        const ch = channels[ci];
+        if (ch.path !== 'weights' || ch.node !== node)
+            continue;
+        const n = channelComponents(ch);
+        if (out.length < n)
+            throw new RangeError(`sampleWeights: ${out.length} slots for ${n} weights`);
+        sampleChannel(ch, t, out, 0, cursor, ci);
+        return true;
+    }
+    return false;
+}

package/dist/anim/compress.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type AnimationClip } from './clip.js';
+import { type Skeleton } from './pose.js';
+export interface CompressClipOptions {
+    /** Largest translation error a dropped key may introduce (units). Default 1e-3. */
+    positionError?: number;
+    /** Largest rotation error a dropped key may introduce (radians). Default 1e-3. */
+    rotationError?: number;
+    /** Largest scale error a dropped key may introduce. Default 1e-3. */
+    scaleError?: number;
+    /** Largest morph-weight error a dropped key may introduce. Default 1e-3. */
+    weightError?: number;
+    /**
+     * Collapse a channel whose keys never change (within the tolerance) to a single key, and
+     * drop it when that value is the node's rest in `skeleton`. Default true.
+     */
+    dropConstant?: boolean;
+    /** The skeleton whose rest decides which constant channels are redundant. */
+    skeleton?: Skeleton;
+}
+/** `compressClip`'s result: the new clip and the keyframe bytes before and after. */
+export interface CompressedClip {
+    clip: AnimationClip;
+    /** Bytes of `times` + `values` (+ `packed`) over the input's channels. */
+    before: number;
+    /** The same over the output's channels. */
+    after: number;
+}
+export interface QuantizeClipOptions {
+    /** `'smallest-three'` packs `STEP`/`LINEAR` rotation channels; `'none'` copies. */
+    rotation: 'smallest-three' | 'none';
+}
+/** Keyframe bytes of a clip: `times`, `values` and `packed` over every channel. */
+export declare function clipBytes(clip: AnimationClip): number;
+/**
+ * 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 declare function compressClip(clip: AnimationClip, opts?: CompressClipOptions): CompressedClip;
+/**
+ * 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 declare function packQuat(q: ArrayLike<number>, o: number, out: Uint16Array, b: number): void;
+/**
+ * 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 declare function quantizeClip(clip: AnimationClip, opts: QuantizeClipOptions): AnimationClip;