@driftengine/animation 3.61.0

package/dist/blendTree.js

@@ -0,0 +1,171 @@
+import { sampleClip } from './clip.js';
+import { blendPoses } from './blend.js';
+import { createPose } from './pose.js';
+export class BlendTree {
+    root;
+    bind;
+    parameters = new Map();
+    /**
+     * One scratch pose per interior node, claimed at construction.
+     *
+     * A tree evaluates depth-first and every interior node needs somewhere to put its two operands,
+     * so without these `evaluate` would allocate per node per frame. Keyed by the node object
+     * itself, which is stable because a tree is immutable.
+     */
+    scratch = new Map();
+    /**
+     * Which names are clocks, so one cannot quietly be both.
+     *
+     * A parameter is a blend input and a clock is a time; one number doing both jobs is a rig that
+     * responds to the wrong dial, which reads as a broken tree rather than as a name used twice.
+     * `clock: 'speed'` written while meaning "the speed drives the blend" is the slip this catches.
+     */
+    clocks = new Set();
+    /**
+     * @param bind The bind pose, or omitted for one whose channels start at rest.
+     *
+     * **Supply it whenever the clips are rotation-only, which is most of them.** `sampleClip` leaves
+     * a channel no track mentions exactly as it found it, so a rotation-only clip preserves whatever
+     * translations the pose already held. `blendPoses` cannot do that — it interpolates *every*
+     * channel of two poses — so without a bind pose here the scratch poses start at zero translation
+     * and every joint collapses onto its parent's origin the moment a tree or a transition is
+     * involved. Found by building a demo scene with it: one figure folded in on itself and the other,
+     * which happened to go through `retargetPose` instead, did not.
+     */
+    constructor(root, jointCount, bind) {
+        this.root = root;
+        this.bind = bind;
+        this.prepare(root, jointCount);
+    }
+    /**
+     * Set a parameter, refusing a name no node declares.
+     *
+     * **Loud rather than ignored.** A typo silently does nothing, and what a consumer then sees is
+     * an animation that will not respond — a symptom a long way from the misspelling that caused it,
+     * and one no test of theirs would catch. What it costs is that a caller cannot set a parameter
+     * ahead of building the tree that uses it.
+     */
+    set(parameter, value) {
+        if (!this.parameters.has(parameter)) {
+            throw new Error(`BlendTree: no node in this tree takes a parameter called "${parameter}"`);
+        }
+        this.parameters.set(parameter, value);
+    }
+    /**
+     * Sample the whole tree at `timeSec` into `out`. Allocates nothing.
+     *
+     * `timeSec` is the clock for every node that did not name one of its own, so a tree of ordinary
+     * clips behaves exactly as it did before clocks existed.
+     */
+    evaluate(timeSec, out) {
+        this.walk(this.root, timeSec, out);
+    }
+    /** A scratch pose starting from the bind pose where one was given, or at rest where none was. */
+    blank(jointCount) {
+        const pose = createPose(jointCount);
+        if (this.bind !== undefined) {
+            pose.translation.set(this.bind.translation.subarray(0, pose.translation.length));
+            pose.rotation.set(this.bind.rotation.subarray(0, pose.rotation.length));
+            pose.scale.set(this.bind.scale.subarray(0, pose.scale.length));
+        }
+        return pose;
+    }
+    /** Collect parameter names and claim scratch, once, so evaluation allocates nothing. */
+    prepare(node, jointCount) {
+        if (node.kind === 'clip') {
+            if (node.clock !== undefined) {
+                if (this.parameters.has(node.clock) && !this.clocks.has(node.clock)) {
+                    throw new Error(`BlendTree: "${node.clock}" is a blend parameter in this tree and cannot also be a ` +
+                        `clock; one number cannot be both a weight and a time`);
+                }
+                this.clocks.add(node.clock);
+                /* Zero, so a tree evaluates before a caller has set anything — the same start every
+                   blend parameter gets. */
+                this.parameters.set(node.clock, this.parameters.get(node.clock) ?? 0);
+            }
+            return;
+        }
+        if (this.clocks.has(node.parameter)) {
+            throw new Error(`BlendTree: "${node.parameter}" is a clock in this tree and cannot also be a blend ` +
+                `parameter; one number cannot be both a time and a weight`);
+        }
+        this.parameters.set(node.parameter, this.parameters.get(node.parameter) ?? 0);
+        this.scratch.set(node, [this.blank(jointCount), this.blank(jointCount)]);
+        if (node.kind === 'lerp') {
+            this.prepare(node.a, jointCount);
+            this.prepare(node.b, jointCount);
+            return;
+        }
+        if (node.children.length === 0) {
+            throw new Error(`BlendTree: the set on "${node.parameter}" has no children; it needs at least one`);
+        }
+        for (let i = 1; i < node.children.length; i++) {
+            const previous = node.children[i - 1]?.at ?? 0;
+            const current = node.children[i]?.at ?? 0;
+            /*
+             * Ascending stops are what makes the bracketing search a walk rather than a sort, and an
+             * unsorted set does not fail — it picks a neighbouring pair that is not the nearest one and
+             * blends between the wrong two clips, which reads as a rig that responds oddly to a
+             * parameter rather than as a misconfigured tree.
+             */
+            if (current <= previous) {
+                throw new Error(`BlendTree: the set on "${node.parameter}" has stops ${previous} then ${current}; ` +
+                    `they must be ascending`);
+            }
+        }
+        for (const child of node.children)
+            this.prepare(child.node, jointCount);
+    }
+    walk(node, timeSec, out) {
+        if (node.kind === 'clip') {
+            /* Its own clock where it named one, and the frame clock where it did not — which is what
+               every tree written before clocks existed keeps doing, unchanged. */
+            const at = node.clock === undefined ? timeSec : (this.parameters.get(node.clock) ?? 0);
+            sampleClip(node.clip, at, out);
+            return;
+        }
+        const scratch = this.scratch.get(node);
+        if (scratch === undefined)
+            throw new Error('BlendTree: a node was not prepared');
+        const [left, right] = scratch;
+        const value = this.parameters.get(node.parameter) ?? 0;
+        if (node.kind === 'lerp') {
+            this.walk(node.a, timeSec, left);
+            this.walk(node.b, timeSec, right);
+            blendPoses(left, right, value, out);
+            return;
+        }
+        const stops = node.children;
+        const first = stops[0];
+        const last = stops[stops.length - 1];
+        if (first === undefined || last === undefined)
+            throw new Error('BlendTree: an empty set');
+        /*
+         * **A shortcut, not the clamp.** Outside the set these walk one child instead of two, which
+         * halves the work for a parameter parked at an extreme — a character standing still, which is
+         * the common case. The *correctness* is `blendPoses`, which clamps its own weight: deleting
+         * these two returns changes no output, only the work done, and perturbing them proved exactly
+         * that by leaving every assertion green. The comment said they were the clamp until then.
+         */
+        if (value <= first.at) {
+            this.walk(first.node, timeSec, out);
+            return;
+        }
+        if (value >= last.at) {
+            this.walk(last.node, timeSec, out);
+            return;
+        }
+        let upper = 1;
+        while (upper < stops.length - 1 && (stops[upper]?.at ?? 0) < value)
+            upper += 1;
+        const lower = stops[upper - 1];
+        const higher = stops[upper];
+        if (lower === undefined || higher === undefined)
+            throw new Error('BlendTree: a gap in a set');
+        const span = higher.at - lower.at;
+        const t = span > 0 ? (value - lower.at) / span : 0;
+        this.walk(lower.node, timeSec, left);
+        this.walk(higher.node, timeSec, right);
+        blendPoses(left, right, t, out);
+    }
+}

package/dist/clip.d.ts

@@ -0,0 +1,50 @@
+import type { AnimationClip, JointTrack } from '@driftengine/drft';
+import type { Pose } from './pose.ts';
+/**
+ * Keyframed clips, and sampling one into a pose.
+ *
+ * **Sampling is a pure function of a time the caller supplies, and that is a contract rather than
+ * a style.** Nothing on this path reads `performance.now`, `Date.now` or `Math.random`, which is
+ * what lets a recorded intent stream replay bit-identically on another machine. `AGENTS.md` calls
+ * this the determinism boundary and `docs/ARCHITECTURE.md` §5 names animation specifically,
+ * because it is the subsystem where every other engine reaches for a clock.
+ *
+ * What it costs is that a caller has to carry its own time. What would make it wrong is nothing —
+ * a clip that wants wall-clock time can be handed one; the reverse is not recoverable.
+ */
+export type { AnimationClip, JointTrack, TrackPath } from '@driftengine/drft';
+/**
+ * Sample every track into `out`. Pure, allocation-free, and it reads no clock.
+ *
+ * **A joint no track mentions is left exactly as it was found**, which is what makes layering
+ * work: a clip animating one arm can be sampled over a pose already holding the rest of the body.
+ * The alternative — resting untouched joints — would make every partial clip a full-body clip and
+ * silently overwrite whatever it was layered onto.
+ */
+export declare function sampleClip(clip: AnimationClip, timeSec: number, out: Pose): void;
+/**
+ * Sample one track at a time already brought into range, into `target` at `at`.
+ *
+ * **Split out of `sampleClip` so root motion reads the same interpolation rather than a second
+ * copy of it.** Two implementations of one decision drift, and they drift invisibly when they
+ * start identical — which is why this is a shared function and not eight lines repeated in
+ * `rootMotion.ts`. Root motion needs one joint's two tracks at four different times a frame, and
+ * sampling a whole rig four times to read one joint would be the alternative.
+ *
+ * `time` is **not** wrapped here: a caller asking for the value at exactly `durationSec` wants
+ * the last key held, and wrapping would answer the first instead. `sampleClip` wraps before it
+ * calls this; `rootMotion.ts` splits an interval at the loop boundary and asks for both ends.
+ */
+export declare function sampleTrack(track: JointTrack, time: number, target: Float32Array, at: number): void;
+/**
+ * Bring a time into `[0, duration)`.
+ *
+ * `%` is not enough: it answers a negative for a negative input, which would read the wrong pair
+ * of keys rather than looping. A transition running backwards hands in a negative time, so this
+ * is not hypothetical.
+ *
+ * Exported for `rootMotion.ts`, which needs the same wrap and the whole-cycle count that goes
+ * with it — a second definition of "which instant of the clip is this" would be the drift this
+ * repository has been bitten by twice.
+ */
+export declare function wrapTime(timeSec: number, durationSec: number): number;

package/dist/clip.js

@@ -0,0 +1,171 @@
+/**
+ * Sample every track into `out`. Pure, allocation-free, and it reads no clock.
+ *
+ * **A joint no track mentions is left exactly as it was found**, which is what makes layering
+ * work: a clip animating one arm can be sampled over a pose already holding the rest of the body.
+ * The alternative — resting untouched joints — would make every partial clip a full-body clip and
+ * silently overwrite whatever it was layered onto.
+ */
+export function sampleClip(clip, timeSec, out) {
+    const time = wrapTime(timeSec, clip.durationSec);
+    for (const track of clip.tracks) {
+        const width = track.path === 'rotation' ? 4 : 3;
+        const target = track.path === 'translation'
+            ? out.translation
+            : track.path === 'rotation'
+                ? out.rotation
+                : out.scale;
+        sampleTrack(track, time, target, track.joint * width);
+    }
+}
+/**
+ * Sample one track at a time already brought into range, into `target` at `at`.
+ *
+ * **Split out of `sampleClip` so root motion reads the same interpolation rather than a second
+ * copy of it.** Two implementations of one decision drift, and they drift invisibly when they
+ * start identical — which is why this is a shared function and not eight lines repeated in
+ * `rootMotion.ts`. Root motion needs one joint's two tracks at four different times a frame, and
+ * sampling a whole rig four times to read one joint would be the alternative.
+ *
+ * `time` is **not** wrapped here: a caller asking for the value at exactly `durationSec` wants
+ * the last key held, and wrapping would answer the first instead. `sampleClip` wraps before it
+ * calls this; `rootMotion.ts` splits an interval at the loop boundary and asks for both ends.
+ */
+export function sampleTrack(track, time, target, at) {
+    const keys = track.times.length;
+    if (keys === 0)
+        return;
+    const width = track.path === 'rotation' ? 4 : 3;
+    /*
+     * A single key is a constant, handled before the search so nothing divides by a zero interval.
+     * Held at both ends rather than extrapolated, for the same reason a blend tree clamps: a pose
+     * extrapolated past its last key puts limbs outside their range, which reads as a broken rig
+     * rather than as a time out of bounds.
+     */
+    if (keys === 1 || time <= track.times[0]) {
+        copyKey(track, 0, width, target, at);
+        return;
+    }
+    if (time >= track.times[keys - 1]) {
+        copyKey(track, keys - 1, width, target, at);
+        return;
+    }
+    const upper = upperBound(track.times, time);
+    const lower = upper - 1;
+    const t0 = track.times[lower];
+    const t1 = track.times[upper];
+    /* t1 > t0 here: equal adjacent times would have been caught by one of the two holds above
+       only at the ends, so guard the interior case rather than assuming a well-formed clip. */
+    const span = t1 - t0;
+    const alpha = span > 0 ? (time - t0) / span : 0;
+    if (track.path === 'rotation') {
+        slerpKeys(track, lower, upper, alpha, target, at);
+        return;
+    }
+    const a = lower * width;
+    const b = upper * width;
+    for (let c = 0; c < width; c++) {
+        const from = track.values[a + c];
+        const to = track.values[b + c];
+        target[at + c] = from + (to - from) * alpha;
+    }
+}
+/**
+ * Bring a time into `[0, duration)`.
+ *
+ * `%` is not enough: it answers a negative for a negative input, which would read the wrong pair
+ * of keys rather than looping. A transition running backwards hands in a negative time, so this
+ * is not hypothetical.
+ *
+ * Exported for `rootMotion.ts`, which needs the same wrap and the whole-cycle count that goes
+ * with it — a second definition of "which instant of the clip is this" would be the drift this
+ * repository has been bitten by twice.
+ */
+export function wrapTime(timeSec, durationSec) {
+    if (!(durationSec > 0))
+        return 0;
+    return timeSec - Math.floor(timeSec / durationSec) * durationSec;
+}
+/** The index of the first key strictly after `time`. Binary, because a clip can be long. */
+function upperBound(times, time) {
+    let low = 0;
+    let high = times.length - 1;
+    while (low < high) {
+        const mid = (low + high) >> 1;
+        if (times[mid] > time)
+            high = mid;
+        else
+            low = mid + 1;
+    }
+    return low;
+}
+function copyKey(track, key, width, target, at) {
+    const from = key * width;
+    for (let c = 0; c < width; c++)
+        target[at + c] = track.values[from + c];
+}
+/**
+ * Spherical interpolation between two rotation keys, along the **shorter** arc.
+ *
+ * The hemisphere correction is the whole of it: a quaternion and its negation are the same
+ * orientation, so two keys can be numerically far apart while being geometrically close. Without
+ * the flip a limb rotates the long way through the body, which is the most recognisable animation
+ * defect there is.
+ *
+ * Written out rather than calling `quat.slerp` so nothing has to be copied into a scratch
+ * quaternion and back: this runs per track per joint per frame, and the values live in a flat
+ * array the caller owns.
+ */
+function slerpKeys(track, lower, upper, alpha, target, at) {
+    const a = lower * 4;
+    const b = upper * 4;
+    let ax = track.values[a];
+    let ay = track.values[a + 1];
+    let az = track.values[a + 2];
+    let aw = track.values[a + 3];
+    const bx = track.values[b];
+    const by = track.values[b + 1];
+    const bz = track.values[b + 2];
+    const bw = track.values[b + 3];
+    let dot = ax * bx + ay * by + az * bz + aw * bw;
+    if (dot < 0) {
+        ax = -ax;
+        ay = -ay;
+        az = -az;
+        aw = -aw;
+        dot = -dot;
+    }
+    let s0;
+    let s1;
+    /*
+     * Nearly parallel keys fall back to a straight blend, because `Math.acos` of a value at or past
+     * 1 is 0 or NaN and dividing by `sin(0)` is the NaN that reaches the palette and takes every
+     * vertex the joint touches. The threshold is where the two agree to well within float precision.
+     */
+    if (dot > 0.9995) {
+        s0 = 1 - alpha;
+        s1 = alpha;
+    }
+    else {
+        const theta = Math.acos(dot);
+        const sinTheta = Math.sin(theta);
+        s0 = Math.sin((1 - alpha) * theta) / sinTheta;
+        s1 = Math.sin(alpha * theta) / sinTheta;
+    }
+    let x = s0 * ax + s1 * bx;
+    let y = s0 * ay + s1 * by;
+    let z = s0 * az + s1 * bz;
+    let w = s0 * aw + s1 * bw;
+    /* The straight-blend arm above shortens the quaternion, so normalise rather than assume. */
+    const length = Math.hypot(x, y, z, w);
+    if (length > 0) {
+        x /= length;
+        y /= length;
+        z /= length;
+        w /= length;
+    }
+    target[at] = x;
+    target[at + 1] = y;
+    target[at + 2] = z;
+    target[at + 3] = w;
+}

package/dist/ik.d.ts

@@ -0,0 +1,29 @@
+import type { Pose } from './pose.ts';
+import type { Skeleton } from './skeleton.ts';
+/**
+ * Two-bone inverse kinematics: put a chain's tip on a target, closed form.
+ *
+ * **Closed form rather than iterative**, because two bones and a target are a triangle and a
+ * triangle has an answer. An iterative solver — FABRIK, or gradient descent — earns its keep on
+ * longer chains where there is no closed form; spending iterations on a case with an exact
+ * solution buys nothing and makes the result depend on how many were run, which a replay cannot
+ * tolerate.
+ *
+ * What it does not do is limits, twist or more than two bones. A knee that should not hyperextend
+ * is a constraint this does not know about, and it is a game's decision rather than the engine's —
+ * the same line the state machine draws about a character's verbs.
+ */
+/**
+ * Reach `target` with the chain `root` → `mid` → `tip`, writing the two rotations into `pose`.
+ *
+ * Returns whether the target was reachable. An unreachable one straightens the chain toward it,
+ * which is the behaviour a limb should have: an arm reaching for something too far away extends,
+ * it does not give up or fold.
+ *
+ * `poleHint` decides the one thing the target cannot — which way the joint bends. A world-space
+ * point or direction the mid joint should lean toward; without it, a chain that is already
+ * straight has no plane to bend in and the elbow would flip unpredictably as a character turned.
+ *
+ * The skeleton's world matrices are refreshed as it goes, so they are current when this returns.
+ */
+export declare function solveTwoBone(skeleton: Skeleton, pose: Pose, root: number, mid: number, tip: number, target: ArrayLike<number>, poleHint: ArrayLike<number>): boolean;