@driftengine/animation 3.61.0

package/dist/rigid.js

@@ -0,0 +1,92 @@
+import { sampleClip } from './clip.js';
+import { createPose } from './pose.js';
+/**
+ * Rigid TRS: a clip driving a node's transform, with no skeleton and no palette anywhere.
+ *
+ * A door swinging, a lift rising, a turntable turning — geometry that moves as a whole rather than
+ * deforming. It is the cheapest thing animation offers and the one most games reach for first, and
+ * it needs no shader change at all.
+ *
+ * **This module is the only place this package touches core**, which is what makes the peer
+ * dependency load-bearing rather than declared. A node is core's, a pose is this package's, and
+ * this is the one line between them — kept in a module of its own so the rest of the package
+ * stays a pure function of time over typed arrays and could be tested with core absent.
+ */
+/**
+ * Write one joint of a pose onto a node's local transform. Allocates nothing.
+ *
+ * `markMoved` is called because `SceneNode` says at its own fields that writing a transform in
+ * place does not mark it dirty. Omitting it is invisible on the first frame — a fresh node is
+ * dirty already — and shows on the second as a node whose world matrix never catches up, which
+ * reads as an animation that plays once and freezes.
+ */
+export function applyPoseToNode(pose, joint, node) {
+    const t = joint * 3;
+    const r = joint * 4;
+    node.position[0] = pose.translation[t];
+    node.position[1] = pose.translation[t + 1];
+    node.position[2] = pose.translation[t + 2];
+    node.rotation[0] = pose.rotation[r];
+    node.rotation[1] = pose.rotation[r + 1];
+    node.rotation[2] = pose.rotation[r + 2];
+    node.rotation[3] = pose.rotation[r + 3];
+    node.scale[0] = pose.scale[t];
+    node.scale[1] = pose.scale[t + 1];
+    node.scale[2] = pose.scale[t + 2];
+    node.markMoved();
+}
+/**
+ * A clip bound to a list of nodes, one per joint the clip's tracks name.
+ *
+ * The pose is claimed once at construction and reused, so `apply` allocates nothing however often
+ * it runs.
+ */
+export class RigidAnimation {
+    clip;
+    nodes;
+    pose;
+    /**
+     * The distinct joints this clip drives, collected once.
+     *
+     * Iterating `tracks` directly would write a joint's node once per track it has — three times for
+     * a joint carrying translation, rotation and scale — which is correct and is three times the
+     * work every frame. Collected here because the set cannot change: a clip is immutable.
+     */
+    driven = [];
+    /**
+     * @param nodes Indexed by joint. `null` for a joint this scene did not instantiate.
+     */
+    constructor(clip, nodes) {
+        this.clip = clip;
+        this.nodes = nodes;
+        /*
+         * Sized to the highest joint the clip names, not to `nodes.length`, so a caller passing a
+         * short list still gets a pose the sampler can write every track into — the skipping happens
+         * at the node, which is where the caller's intent is, rather than silently at the sample.
+         */
+        let highest = -1;
+        for (const track of clip.tracks) {
+            highest = Math.max(highest, track.joint);
+            if (!this.driven.includes(track.joint))
+                this.driven.push(track.joint);
+        }
+        this.pose = createPose(highest + 1);
+    }
+    /**
+     * Sample at a caller-supplied time and write every bound node. Reads no clock.
+     *
+     * A joint with no node is skipped rather than refused. An imported clip names joints a scene may
+     * not have instantiated, and the right behaviour is the parts that exist moving — the
+     * reliability rules forbid throwing in a frame loop outright, and a missing prop is not a reason
+     * to stop a scene.
+     */
+    apply(timeSec) {
+        sampleClip(this.clip, timeSec, this.pose);
+        for (const joint of this.driven) {
+            const node = this.nodes[joint];
+            if (node === null || node === undefined)
+                continue;
+            applyPoseToNode(this.pose, joint, node);
+        }
+    }
+}

package/dist/rootMotion.d.ts

@@ -0,0 +1,74 @@
+import type { AnimationClip } from '@driftengine/drft';
+import type { Pose } from './pose.ts';
+/**
+ * Root motion: how far the root travelled between two sample times, handed to the caller.
+ *
+ * **The point is that the character moves and the pose does not.** A walk cycle authored with a
+ * moving root plays as a character sliding forward inside its own transform, and the rig then
+ * fights whatever the game does with that transform. Root motion splits the two: `extractRootMotion`
+ * answers the interval's displacement so a controller can apply it, and `stripRootMotion` pins the
+ * pose's root so the displacement is not applied twice.
+ *
+ * **A pure function of the clip and two times, with no clock of its own** — the same contract
+ * `sampleClip` makes and for the same reason. A recorded intent stream replays bit-identically
+ * only if every step of the pose pipeline is a function of a time the caller supplies.
+ *
+ * ## The convention, and what it costs
+ *
+ * The delta is expressed **in the root's own frame at the earlier time**, so a caller applies it as
+ *
+ * ```
+ * position = position + worldRotation * motion.translation
+ * worldRotation = worldRotation * motion.rotation
+ * ```
+ *
+ * which composes: stepping a clip in sixtieths and applying each delta arrives where one query
+ * over the whole span says it should, and a character that has turned walks along its own forward
+ * axis rather than along the clip's. The rejected alternative is a delta in the clip's own space,
+ * which is one subtraction shorter and drags every turned character sideways.
+ *
+ * **What it gives up** is a vertical bob authored on the root: it leaves the pose along with
+ * everything else and becomes motion the caller applies. A caller whose height is owned by a
+ * physics controller ignores `translation[1]` — and then the bob is in neither the pose nor the
+ * position, which is a real loss and the reason this is written down rather than discovered. **What
+ * would make it wrong** is a consumer wanting per-axis control, and the honest answer then is a mask
+ * on the extraction rather than a second convention.
+ */
+/** A root's displacement over an interval. Three floats and a quaternion, both caller-owned. */
+export interface RootMotion {
+    /** Three floats, in the root's frame at the earlier of the two times. */
+    readonly translation: Float32Array;
+    /** Four floats, xyzw, in the order `gl-matrix` uses. */
+    readonly rotation: Float32Array;
+}
+/** A zero displacement, ready to be written into. Identity rather than zeroed, as `createPose` is. */
+export declare function createRootMotion(): RootMotion;
+/**
+ * Write the root's displacement between `fromSec` and `toSec` into `out`. Allocates nothing.
+ *
+ * **Loops are accumulated rather than subtracted**, which is the whole difficulty. Sampling the
+ * root at both times and subtracting answers a full stride *backwards* every time the clip wraps,
+ * because the root snaps from the end of the cycle to the start of it. So the interval is split at
+ * every loop boundary it crosses and the pieces are composed.
+ *
+ * `toSec` before `fromSec` is a clip running backwards and answers the negated motion, because a
+ * transition played in reverse is a real caller — the same reason `wrapTime` handles a negative
+ * time rather than assuming one cannot arrive.
+ *
+ * Cost is linear in the number of whole cycles between the two times. A fixed-step caller crosses
+ * at most one boundary a frame, so that count is zero or one; a query spanning a hundred cycles
+ * composes a hundred times, which is arithmetic rather than a hazard.
+ */
+export declare function extractRootMotion(clip: AnimationClip, rootJoint: number, fromSec: number, toSec: number, out: RootMotion): void;
+/**
+ * Pin a sampled pose's root to the value the clip authored at time zero.
+ *
+ * The other half of the capability: whatever `extractRootMotion` handed the caller has to leave the
+ * pose, or the character moves twice. Pinned to the clip's own first value rather than to the rest
+ * pose, so a root authored a metre off the origin keeps its offset — resting it would drop every
+ * character to the floor of its rig on the first frame.
+ *
+ * A joint that is not the root is left exactly as it was found, which is the same layering rule
+ * `sampleClip` and `retargetPose` both keep.
+ */
+export declare function stripRootMotion(clip: AnimationClip, rootJoint: number, pose: Pose): void;

package/dist/rootMotion.js

@@ -0,0 +1,182 @@
+import { sampleTrack, wrapTime } from './clip.js';
+/** A zero displacement, ready to be written into. Identity rather than zeroed, as `createPose` is. */
+export function createRootMotion() {
+    const motion = { translation: new Float32Array(3), rotation: new Float32Array(4) };
+    motion.rotation[3] = 1;
+    return motion;
+}
+/**
+ * Write the root's displacement between `fromSec` and `toSec` into `out`. Allocates nothing.
+ *
+ * **Loops are accumulated rather than subtracted**, which is the whole difficulty. Sampling the
+ * root at both times and subtracting answers a full stride *backwards* every time the clip wraps,
+ * because the root snaps from the end of the cycle to the start of it. So the interval is split at
+ * every loop boundary it crosses and the pieces are composed.
+ *
+ * `toSec` before `fromSec` is a clip running backwards and answers the negated motion, because a
+ * transition played in reverse is a real caller — the same reason `wrapTime` handles a negative
+ * time rather than assuming one cannot arrive.
+ *
+ * Cost is linear in the number of whole cycles between the two times. A fixed-step caller crosses
+ * at most one boundary a frame, so that count is zero or one; a query spanning a hundred cycles
+ * composes a hundred times, which is arithmetic rather than a hazard.
+ */
+export function extractRootMotion(clip, rootJoint, fromSec, toSec, out) {
+    identity(out);
+    const duration = clip.durationSec;
+    const translation = findTrack(clip, rootJoint, 'translation');
+    const rotation = findTrack(clip, rootJoint, 'rotation');
+    if (translation === null && rotation === null)
+        return;
+    /* A clip with no duration wraps every time to the same instant, so nothing moved. */
+    if (!(duration > 0))
+        return;
+    const from = wrapTime(fromSec, duration);
+    const to = wrapTime(toSec, duration);
+    const crossings = Math.floor(toSec / duration) - Math.floor(fromSec / duration);
+    if (crossings === 0) {
+        composeSegment(translation, rotation, from, to, out);
+        return;
+    }
+    /*
+     * Forwards: the tail of the current cycle, then whole cycles, then the head of the last one.
+     * Backwards is the same walk with the two ends of the clip exchanged, which is what makes the
+     * negative case the negation of the positive rather than a second implementation.
+     */
+    const forwards = crossings > 0;
+    const open = forwards ? 0 : duration;
+    const close = forwards ? duration : 0;
+    composeSegment(translation, rotation, from, close, out);
+    const whole = Math.abs(crossings) - 1;
+    for (let cycle = 0; cycle < whole; cycle++) {
+        composeSegment(translation, rotation, open, close, out);
+    }
+    composeSegment(translation, rotation, open, to, out);
+}
+/**
+ * Pin a sampled pose's root to the value the clip authored at time zero.
+ *
+ * The other half of the capability: whatever `extractRootMotion` handed the caller has to leave the
+ * pose, or the character moves twice. Pinned to the clip's own first value rather than to the rest
+ * pose, so a root authored a metre off the origin keeps its offset — resting it would drop every
+ * character to the floor of its rig on the first frame.
+ *
+ * A joint that is not the root is left exactly as it was found, which is the same layering rule
+ * `sampleClip` and `retargetPose` both keep.
+ */
+export function stripRootMotion(clip, rootJoint, pose) {
+    const translation = findTrack(clip, rootJoint, 'translation');
+    if (translation !== null)
+        sampleTrack(translation, 0, pose.translation, rootJoint * 3);
+    const rotation = findTrack(clip, rootJoint, 'rotation');
+    if (rotation !== null)
+        sampleTrack(rotation, 0, pose.rotation, rootJoint * 4);
+}
+/**
+ * The track for one joint and one path, or null.
+ *
+ * A linear scan rather than an index, because a clip carries a few dozen tracks and this runs twice
+ * per extraction — building a map would allocate one per clip and have to be invalidated when a
+ * caller swaps a clip in place, which is worse than sixty comparisons.
+ */
+function findTrack(clip, joint, path) {
+    for (const track of clip.tracks) {
+        if (track.joint === joint && track.path === path)
+            return track;
+    }
+    return null;
+}
+/** Compose one segment's local delta onto `out`. `t0` and `t1` are in range and not wrapped. */
+function composeSegment(translation, rotation, t0, t1, out) {
+    FROM_T.fill(0);
+    TO_T.fill(0);
+    if (translation !== null) {
+        sampleTrack(translation, t0, FROM_T, 0);
+        sampleTrack(translation, t1, TO_T, 0);
+    }
+    identityInto(FROM_R);
+    identityInto(TO_R);
+    if (rotation !== null) {
+        sampleTrack(rotation, t0, FROM_R, 0);
+        sampleTrack(rotation, t1, TO_R, 0);
+    }
+    /* The segment's delta in the root's frame at `t0`: rotate the world difference back by the
+       earlier orientation, and take the rotation that carries the earlier onto the later. */
+    for (let c = 0; c < 3; c++)
+        SEG_T[c] = TO_T[c] - FROM_T[c];
+    conjugateInto(FROM_R, INVERSE);
+    rotateVector(INVERSE, SEG_T);
+    multiplyInto(INVERSE, TO_R, SEG_R);
+    /* `out` then this segment: the segment's translation is expressed in the frame `out` ends in,
+       so it is rotated by `out`'s rotation before it is added. */
+    rotateVector(out.rotation, SEG_T);
+    for (let c = 0; c < 3; c++) {
+        out.translation[c] = out.translation[c] + SEG_T[c];
+    }
+    multiplyInto(out.rotation, SEG_R, COMPOSED);
+    for (let c = 0; c < 4; c++)
+        out.rotation[c] = COMPOSED[c];
+}
+function identity(out) {
+    out.translation.fill(0);
+    identityInto(out.rotation);
+}
+function identityInto(quaternion) {
+    quaternion[0] = 0;
+    quaternion[1] = 0;
+    quaternion[2] = 0;
+    quaternion[3] = 1;
+}
+/** The inverse of a unit quaternion. Not normalised: every source here is a sampled unit. */
+function conjugateInto(quaternion, out) {
+    out[0] = -quaternion[0];
+    out[1] = -quaternion[1];
+    out[2] = -quaternion[2];
+    out[3] = quaternion[3];
+}
+/** Quaternion product `a * b` into `out`. `out` must not alias either input. */
+function multiplyInto(a, b, out) {
+    const ax = a[0];
+    const ay = a[1];
+    const az = a[2];
+    const aw = a[3];
+    const bx = b[0];
+    const by = b[1];
+    const bz = b[2];
+    const bw = b[3];
+    out[0] = aw * bx + ax * bw + ay * bz - az * by;
+    out[1] = aw * by - ax * bz + ay * bw + az * bx;
+    out[2] = aw * bz + ax * by - ay * bx + az * bw;
+    out[3] = aw * bw - ax * bx - ay * by - az * bz;
+}
+/**
+ * Rotate a three-vector by a unit quaternion, in place.
+ *
+ * `v + 2w(q x v) + 2(q x (q x v))`, written out rather than built from a matrix: a matrix would be
+ * nine floats of scratch to save two cross products, and this runs four times a frame per
+ * character.
+ */
+function rotateVector(quaternion, vector) {
+    const qx = quaternion[0];
+    const qy = quaternion[1];
+    const qz = quaternion[2];
+    const qw = quaternion[3];
+    const vx = vector[0];
+    const vy = vector[1];
+    const vz = vector[2];
+    const tx = 2 * (qy * vz - qz * vy);
+    const ty = 2 * (qz * vx - qx * vz);
+    const tz = 2 * (qx * vy - qy * vx);
+    vector[0] = vx + qw * tx + (qy * tz - qz * ty);
+    vector[1] = vy + qw * ty + (qz * tx - qx * tz);
+    vector[2] = vz + qw * tz + (qx * ty - qy * tx);
+}
+/* Module scope, claimed once: an extraction runs per character per frame. */
+const FROM_T = new Float32Array(3);
+const TO_T = new Float32Array(3);
+const SEG_T = new Float32Array(3);
+const FROM_R = new Float32Array(4);
+const TO_R = new Float32Array(4);
+const SEG_R = new Float32Array(4);
+const INVERSE = new Float32Array(4);
+const COMPOSED = new Float32Array(4);

package/dist/skeleton.d.ts

@@ -0,0 +1,81 @@
+import type { Joint } from '@driftengine/drft';
+import type { Pose } from './pose.ts';
+/**
+ * A joint hierarchy and the skinning palette it resolves a pose into.
+ *
+ * **A joint is not a `SceneNode`, and that is deliberate.** Core has a transform hierarchy with a
+ * parent, dirty tracking and a derived world matrix, and reusing it here is the obvious move. A
+ * rig is sixty to ninety joints and a scene holds several characters, so a class instance per node
+ * holding its own matrices is the allocation the performance rules forbid — and the palette a
+ * shader reads has to be contiguous anyway, which an object graph is not. A *character* is still a
+ * `SceneNode`; its skeleton hangs off one, and `rigid.ts` is the seam between them.
+ *
+ * What it costs is that a joint cannot be reparented or addressed the way a scene node can. What
+ * would make it wrong is a consumer needing to attach arbitrary scene content to a joint — a sword
+ * in a hand — which is answered by reading the joint's world matrix out rather than by making the
+ * joint a node.
+ */
+export type { Joint } from '@driftengine/drft';
+export declare class Skeleton {
+    readonly joints: readonly Joint[];
+    readonly jointCount: number;
+    /**
+     * Sixteen floats a joint, column-major, claimed once and written in place.
+     *
+     * This is a *skinning* palette rather than a set of world matrices: each entry is the joint's
+     * world transform times its inverse bind, so it takes a vertex from model space to where the
+     * joint has moved it. At the bind pose every entry is identity, whatever the bind pose is, which
+     * is the property `skeleton.test.ts` pins — a reversed multiplication order does not shift a
+     * mesh slightly, it explodes it.
+     */
+    readonly palette: Float32Array;
+    /**
+     * Each joint's world matrix, sixteen floats a joint, resolved on the way to the palette.
+     *
+     * **Public because a palette entry is not a world transform.** An entry is the world matrix
+     * times the joint's inverse bind, which is what a shader needs and is useless to anything asking
+     * *where a joint is* — attaching a sword to a hand, or an IK solver reading a chain. Those want
+     * this. Valid after `applyPose` and meaningless before it.
+     */
+    readonly world: Float32Array;
+    private readonly inverseBind;
+    private readonly worldViews;
+    private readonly paletteViews;
+    private readonly bindViews;
+    /**
+     * @param joints Sorted **parents-first**. Refused otherwise.
+     * @param inverseBind Sixteen floats a joint, column-major, in the same order as `joints`.
+     */
+    constructor(joints: readonly Joint[], inverseBind: Float32Array);
+    /**
+     * Resolve a pose into the palette. Allocates nothing.
+     *
+     * One pass in index order: compose the joint's local matrix from its TRS, multiply by its
+     * parent's already-written world matrix, then by its inverse bind into the palette. The
+     * parents-first ordering the constructor checks is what makes the single pass correct.
+     */
+    /**
+     * Resolve the hierarchy from local matrices rather than from TRS.
+     *
+     * **For a rig whose poses are authored as matrices.** `applyPose` is the right door for
+     * anything that interpolates — a clip, a blend tree, a state machine — because a quaternion is
+     * what you can blend and Euler angles are not. But a rig computed fresh every frame from
+     * gameplay state has no interpolation to do, and forcing it through TRS means decomposing
+     * matrices it just composed: a square root and a branch per joint, and a chance to get the
+     * rotation order wrong that no test of the *engine* can catch.
+     *
+     * The two writers agree, and `skeleton.test.ts` pins that against `applyPose` rather than
+     * asserting it — a caller choosing between them on convenience must not be choosing between two
+     * answers.
+     *
+     * **What it costs** is a second way in, which is a real cost: a reader now has to know both
+     * exist. **What would make it wrong** is a caller reaching for this to avoid learning
+     * quaternions and then wanting to blend — at which point they need `applyPose` and have built
+     * their rig in the one representation that cannot get there.
+     *
+     * @param locals Sixteen floats a joint, column-major, in joint order. Each is the joint's
+     *   transform **relative to its parent**, not its world transform.
+     */
+    applyLocalMatrices(locals: Float32Array): void;
+    applyPose(pose: Pose): void;
+}

package/dist/skeleton.js

@@ -0,0 +1,187 @@
+import { MAX_JOINTS } from '@driftengine/core';
+import { mat4, quat, vec3 } from 'gl-matrix';
+export class Skeleton {
+    joints;
+    jointCount;
+    /**
+     * Sixteen floats a joint, column-major, claimed once and written in place.
+     *
+     * This is a *skinning* palette rather than a set of world matrices: each entry is the joint's
+     * world transform times its inverse bind, so it takes a vertex from model space to where the
+     * joint has moved it. At the bind pose every entry is identity, whatever the bind pose is, which
+     * is the property `skeleton.test.ts` pins — a reversed multiplication order does not shift a
+     * mesh slightly, it explodes it.
+     */
+    palette;
+    /**
+     * Each joint's world matrix, sixteen floats a joint, resolved on the way to the palette.
+     *
+     * **Public because a palette entry is not a world transform.** An entry is the world matrix
+     * times the joint's inverse bind, which is what a shader needs and is useless to anything asking
+     * *where a joint is* — attaching a sword to a hand, or an IK solver reading a chain. Those want
+     * this. Valid after `applyPose` and meaningless before it.
+     */
+    world;
+    inverseBind;
+    /*
+     * One 16-float view per joint into each of the three arrays, built once at construction.
+     *
+     * `gl-matrix` writes through whatever it is handed, so a view lets `applyPose` multiply straight
+     * into the palette with no copy at all. The views exist because `subarray` **is an allocation** —
+     * a new typed-array object every call — and `applyPose` runs per character per frame, which is
+     * exactly where §4's rule about typed-array views bites. Built here, they cost one object per
+     * joint for the skeleton's life and nothing per frame.
+     *
+     * What it costs is three arrays of small objects held for the skeleton's life. What would make it
+     * wrong is a joint count large enough for that to matter, which the 512-joint cap rules out.
+     */
+    worldViews = [];
+    paletteViews = [];
+    bindViews = [];
+    /**
+     * @param joints Sorted **parents-first**. Refused otherwise.
+     * @param inverseBind Sixteen floats a joint, column-major, in the same order as `joints`.
+     */
+    constructor(joints, inverseBind) {
+        /*
+         * Parents before children, checked once here rather than sorted here.
+         *
+         * `applyPose` walks the joints in index order and reads each joint's parent matrix as it goes,
+         * which is only correct on a sorted hierarchy — and a rig that is nearly sorted produces a
+         * skeleton that is wrong in one limb, which reads as a bad animation rather than as a data
+         * error. Sorting is the importer's job because it is the layer that can also remap every index
+         * that names a joint; sorting here would leave a mesh's joint attribute pointing at the old
+         * order. See `gltfSkin.ts`.
+         */
+        for (let j = 0; j < joints.length; j++) {
+            const parent = joints[j].parent;
+            if (parent >= j) {
+                throw new Error(`Skeleton: joint ${j} ("${joints[j].name}") names parent ${parent}, which is ` +
+                    `not before it. Joints must be sorted parents-first, because the palette is resolved ` +
+                    `in index order and a parent read before it is written is a limb in the wrong place.`);
+            }
+            if (parent < -1) {
+                throw new Error(`Skeleton: joint ${j} names parent ${parent}; -1 means "no parent"`);
+            }
+        }
+        /*
+         * The cap is a fact about the palette *texture* — 2048 is WebGL2's guaranteed width and four
+         * texels carry a matrix — so it is defined in core beside the texture and imported here rather
+         * than restated. Two numbers for one decision is the shape that drifts, and this one would
+         * drift silently: a rig between the two would build here and read past the end of a texture row
+         * on the GPU, which draws limbs from whatever memory follows rather than failing.
+         */
+        if (joints.length > MAX_JOINTS) {
+            throw new Error(`Skeleton: ${joints.length} joints exceeds the ${MAX_JOINTS} a palette texture holds. ` +
+                `That is WebGL2's guaranteed texture width rather than this machine's limit.`);
+        }
+        if (inverseBind.length !== joints.length * 16) {
+            throw new Error(`Skeleton: the inverse bind array has ${inverseBind.length} floats for ${joints.length} ` +
+                `joints; expected ${joints.length * 16} (16 per joint, column-major).`);
+        }
+        this.joints = joints;
+        this.jointCount = joints.length;
+        this.inverseBind = inverseBind;
+        this.palette = new Float32Array(joints.length * 16);
+        this.world = new Float32Array(joints.length * 16);
+        for (let j = 0; j < joints.length; j++) {
+            const at = j * 16;
+            this.worldViews.push(this.world.subarray(at, at + 16));
+            this.paletteViews.push(this.palette.subarray(at, at + 16));
+            this.bindViews.push(inverseBind.subarray(at, at + 16));
+        }
+    }
+    /**
+     * Resolve a pose into the palette. Allocates nothing.
+     *
+     * One pass in index order: compose the joint's local matrix from its TRS, multiply by its
+     * parent's already-written world matrix, then by its inverse bind into the palette. The
+     * parents-first ordering the constructor checks is what makes the single pass correct.
+     */
+    /**
+     * Resolve the hierarchy from local matrices rather than from TRS.
+     *
+     * **For a rig whose poses are authored as matrices.** `applyPose` is the right door for
+     * anything that interpolates — a clip, a blend tree, a state machine — because a quaternion is
+     * what you can blend and Euler angles are not. But a rig computed fresh every frame from
+     * gameplay state has no interpolation to do, and forcing it through TRS means decomposing
+     * matrices it just composed: a square root and a branch per joint, and a chance to get the
+     * rotation order wrong that no test of the *engine* can catch.
+     *
+     * The two writers agree, and `skeleton.test.ts` pins that against `applyPose` rather than
+     * asserting it — a caller choosing between them on convenience must not be choosing between two
+     * answers.
+     *
+     * **What it costs** is a second way in, which is a real cost: a reader now has to know both
+     * exist. **What would make it wrong** is a caller reaching for this to avoid learning
+     * quaternions and then wanting to blend — at which point they need `applyPose` and have built
+     * their rig in the one representation that cannot get there.
+     *
+     * @param locals Sixteen floats a joint, column-major, in joint order. Each is the joint's
+     *   transform **relative to its parent**, not its world transform.
+     */
+    applyLocalMatrices(locals) {
+        if (locals.length !== this.jointCount * 16) {
+            throw new Error(`Skeleton: applyLocalMatrices wants sixteen floats a joint — ` +
+                `${this.jointCount * 16} for ${this.jointCount} joints, got ${locals.length}. ` +
+                `A short array leaves the tail joints holding whatever the last frame wrote, which ` +
+                `animates as one limb frozen rather than as an error.`);
+        }
+        for (let j = 0; j < this.jointCount; j++) {
+            const at = j * 16;
+            /* Copied element by element rather than with `subarray`, because a subarray is a new
+               typed-array object every call — the same allocation the views above exist to avoid,
+               and this runs per character per frame beside `applyPose`. */
+            for (let i = 0; i < 16; i++)
+                SCRATCH_LOCAL[i] = locals[at + i];
+            const parent = this.joints[j].parent;
+            const world = this.worldViews[j];
+            if (parent < 0) {
+                world.set(SCRATCH_LOCAL);
+            }
+            else {
+                mat4.multiply(world, this.worldViews[parent], SCRATCH_LOCAL);
+            }
+            mat4.multiply(this.paletteViews[j], world, this.bindViews[j]);
+        }
+    }
+    applyPose(pose) {
+        for (let j = 0; j < this.jointCount; j++) {
+            SCRATCH_T[0] = pose.translation[j * 3];
+            SCRATCH_T[1] = pose.translation[j * 3 + 1];
+            SCRATCH_T[2] = pose.translation[j * 3 + 2];
+            SCRATCH_R[0] = pose.rotation[j * 4];
+            SCRATCH_R[1] = pose.rotation[j * 4 + 1];
+            SCRATCH_R[2] = pose.rotation[j * 4 + 2];
+            SCRATCH_R[3] = pose.rotation[j * 4 + 3];
+            SCRATCH_S[0] = pose.scale[j * 3];
+            SCRATCH_S[1] = pose.scale[j * 3 + 1];
+            SCRATCH_S[2] = pose.scale[j * 3 + 2];
+            mat4.fromRotationTranslationScale(SCRATCH_LOCAL, SCRATCH_R, SCRATCH_T, SCRATCH_S);
+            const parent = this.joints[j].parent;
+            const world = this.worldViews[j];
+            if (parent < 0) {
+                world.set(SCRATCH_LOCAL);
+            }
+            else {
+                mat4.multiply(world, this.worldViews[parent], SCRATCH_LOCAL);
+            }
+            mat4.multiply(this.paletteViews[j], world, this.bindViews[j]);
+        }
+    }
+}
+/*
+ * Module-scope scratch, claimed once for the process rather than per skeleton or per call.
+ *
+ * `applyPose` runs per character per frame, so anything allocated inside it is a garbage collector
+ * in the frame loop. Module scope rather than instance fields because these hold nothing between
+ * calls and one set serves every skeleton — the engine is single-threaded on this path, and a
+ * worker gets its own module instance.
+ *
+ * What would make it wrong is `applyPose` ever being re-entered, which would need it to call back
+ * into caller code; it calls only `gl-matrix`.
+ */
+const SCRATCH_T = vec3.create();
+const SCRATCH_S = vec3.create();
+const SCRATCH_R = quat.create();
+const SCRATCH_LOCAL = mat4.create();