@driftengine/animation 3.61.0

package/dist/stateMachine.js

@@ -0,0 +1,142 @@
+import { blendPoses } from './blend.js';
+import { createPose } from './pose.js';
+export class AnimationStateMachine {
+    transitions;
+    states = new Map();
+    parameters = {};
+    active;
+    /** The state being left while a fade runs, or null when none is. */
+    leaving = null;
+    fadeElapsed = 0;
+    fadeDuration = 0;
+    /** One per side of a fade, claimed at construction so `evaluate` allocates nothing. */
+    fromPose;
+    toPose;
+    /**
+     * Each state's own elapsed time.
+     *
+     * Per state rather than one for the machine, so a looping clip is not restarted every time
+     * something else changes — and so a state re-entered later resumes where its own clip was rather
+     * than wherever the machine happened to be.
+     */
+    elapsed = new Map();
+    /**
+     * @param bind The bind pose, or omitted for one whose channels start at rest.
+     *
+     * The same reason `BlendTree` takes one: a crossfade calls `blendPoses`, which interpolates
+     * every channel, so without a bind pose the two sides of a fade start at zero translation and
+     * the figure folds toward its own origin for the length of the transition.
+     */
+    constructor(states, transitions, jointCount, bind) {
+        this.transitions = transitions;
+        const first = states[0];
+        if (first === undefined)
+            throw new Error('AnimationStateMachine: needs at least one state');
+        for (const state of states) {
+            this.states.set(state.name, state);
+            this.elapsed.set(state.name, 0);
+        }
+        /*
+         * Checked here rather than met at the moment a transition fires. A transition naming a state
+         * that does not exist is a configuration error with exactly one correct outcome, and finding
+         * it at construction is the difference between a message naming the state and a character that
+         * silently never leaves an animation.
+         */
+        for (const transition of transitions) {
+            for (const name of [transition.from, transition.to]) {
+                if (!this.states.has(name)) {
+                    throw new Error(`AnimationStateMachine: a transition names state "${name}", which was not given`);
+                }
+            }
+        }
+        this.active = first;
+        this.fromPose = createPose(jointCount);
+        this.toPose = createPose(jointCount);
+        if (bind !== undefined) {
+            for (const pose of [this.fromPose, this.toPose]) {
+                pose.translation.set(bind.translation.subarray(0, pose.translation.length));
+                pose.rotation.set(bind.rotation.subarray(0, pose.rotation.length));
+                pose.scale.set(bind.scale.subarray(0, pose.scale.length));
+            }
+        }
+    }
+    get current() {
+        return this.active.name;
+    }
+    /** Whether a crossfade is running. A caller wanting to gate input on one asks this. */
+    get transitioning() {
+        return this.leaving !== null;
+    }
+    /**
+     * Set a parameter the transitions read.
+     *
+     * Unlike `BlendTree.set` this accepts any name: the predicates are the consumer's own functions
+     * and this class cannot know which keys they read. The tree below it still refuses a name no node
+     * declares, which is where a typo that matters is caught.
+     */
+    set(parameter, value) {
+        this.parameters[parameter] = value;
+    }
+    /**
+     * Advance by a caller-supplied step: the fade, the active state's clock, and any transition
+     * whose condition now holds.
+     */
+    advance(dtSec) {
+        if (this.leaving === null)
+            this.start();
+        this.elapsed.set(this.active.name, (this.elapsed.get(this.active.name) ?? 0) + dtSec);
+        if (this.leaving === null)
+            return;
+        this.elapsed.set(this.leaving.name, (this.elapsed.get(this.leaving.name) ?? 0) + dtSec);
+        /*
+         * **The frame that triggers a transition advances its fade too.** Starting the fade at zero
+         * and leaving it there until the next call is a one-frame stall at the top of every
+         * transition — invisible at 60 Hz on a long fade and a whole transition on a short one, which
+         * is the case a fade is shortest for.
+         */
+        this.fadeElapsed += dtSec;
+        /*
+         * A running fade completes; it is not re-evaluated against the condition that started it. A
+         * transition interruptible by its own trigger would stutter whenever that parameter sat on its
+         * threshold — which is exactly where a speed parameter spends its time.
+         */
+        if (this.fadeElapsed >= this.fadeDuration)
+            this.leaving = null;
+    }
+    /** Take the first transition out of the active state whose condition holds. */
+    start() {
+        for (const transition of this.transitions) {
+            if (transition.from !== this.active.name)
+                continue;
+            if (!transition.when(this.parameters))
+                continue;
+            const next = this.states.get(transition.to);
+            if (next === undefined)
+                continue;
+            this.leaving = this.active;
+            this.active = next;
+            this.elapsed.set(next.name, 0);
+            this.fadeElapsed = 0;
+            this.fadeDuration = transition.durationSec;
+            /*
+             * A zero-duration transition is a switch. Ended here rather than divided by below, because
+             * the division is what would produce the NaN — and a NaN weight reaches the palette and
+             * takes every vertex it touches.
+             */
+            if (this.fadeDuration <= 0)
+                this.leaving = null;
+            return;
+        }
+    }
+    /** The current pose, crossfaded if a transition is running. Allocates nothing. */
+    evaluate(out) {
+        const activeTime = this.elapsed.get(this.active.name) ?? 0;
+        if (this.leaving === null) {
+            this.active.tree.evaluate(activeTime, out);
+            return;
+        }
+        this.leaving.tree.evaluate(this.elapsed.get(this.leaving.name) ?? 0, this.fromPose);
+        this.active.tree.evaluate(activeTime, this.toPose);
+        blendPoses(this.fromPose, this.toPose, this.fadeElapsed / this.fadeDuration, out);
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@driftengine/animation",
+  "version": "3.61.0",
+  "description": "Skeletons, clips, poses and the graphs over them: sampling as a pure function of a caller-supplied time",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@driftengine/drft": "3.61.0"
+  },
+  "peerDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/animation"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "skeletal-animation",
+    "blend-tree",
+    "inverse-kinematics",
+    "morph-targets",
+    "skinning"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/blend.ts

@@ -0,0 +1,191 @@
+import type { Pose } from './pose.ts';
+
+/**
+ * Combining poses: a blend between two, an additive layer over one, and a joint written directly.
+ *
+ * All three write into a caller-owned pose and allocate nothing, because every one of them runs
+ * per character per frame. All three are pure functions of their inputs — no clock, no RNG — which
+ * is the determinism contract `sampleClip` establishes and which a graph over clips has to keep.
+ */
+
+/**
+ * Blend `a` toward `b` by `t`, into `out`.
+ *
+ * **Clamped rather than extrapolated.** A weight past the ends puts limbs outside their range,
+ * which reads as a broken rig rather than as a weight out of bounds — the same reasoning
+ * `sampleClip` holds at a track's ends for. What it costs is that a caller cannot deliberately
+ * overshoot; what would make it wrong is somebody wanting to, and the honest answer then is a
+ * function that says so in its name.
+ *
+ * Safe when `out` is also `a` or `b`: every component is read before it is written.
+ */
+export function blendPoses(a: Pose, b: Pose, t: number, out: Pose): void {
+  const weight = t < 0 ? 0 : t > 1 ? 1 : t;
+  const joints = out.rotation.length / 4;
+
+  for (let j = 0; j < joints; j++) {
+    const v = j * 3;
+    for (let c = 0; c < 3; c++) {
+      const from = a.translation[v + c] as number;
+      out.translation[v + c] = from + ((b.translation[v + c] as number) - from) * weight;
+      const scaleFrom = a.scale[v + c] as number;
+      out.scale[v + c] = scaleFrom + ((b.scale[v + c] as number) - scaleFrom) * weight;
+    }
+    slerpInto(a.rotation, j * 4, b.rotation, j * 4, weight, out.rotation, j * 4);
+  }
+}
+
+/**
+ * Apply `delta` on top of `base`, scaled by `weight`, into `out`.
+ *
+ * **A delta, not a target**, and the difference is the whole of what additive is for: a wave laid
+ * over a walk has to move the arm relative to wherever the walk put it rather than replace it. So
+ * translation adds, rotation composes, and **scale multiplies** — a scale delta of 1 means
+ * unchanged, where adding would make it double.
+ *
+ * Weight zero is the base untouched, which is what lets a layer fade in from nothing.
+ */
+export function addPose(base: Pose, delta: Pose, weight: number, out: Pose): void {
+  const w = weight < 0 ? 0 : weight;
+  const joints = out.rotation.length / 4;
+
+  for (let j = 0; j < joints; j++) {
+    const v = j * 3;
+    for (let c = 0; c < 3; c++) {
+      out.translation[v + c] =
+        (base.translation[v + c] as number) + (delta.translation[v + c] as number) * w;
+      /* One at weight zero, the delta's own factor at weight one, interpolated between. */
+      const factor = 1 + ((delta.scale[v + c] as number) - 1) * w;
+      out.scale[v + c] = (base.scale[v + c] as number) * factor;
+    }
+
+    /*
+     * The delta's rotation is scaled by sliding it away from identity along the shorter arc, then
+     * composed onto the base. Scaling by slerping from identity rather than by multiplying the
+     * components is what keeps a half-weight delta a half *rotation* instead of a shortened
+     * quaternion that renormalises to the whole of it.
+     */
+    slerpInto(IDENTITY, 0, delta.rotation, j * 4, w > 1 ? 1 : w, SCALED, 0);
+    multiplyInto(base.rotation, j * 4, SCALED, 0, out.rotation, j * 4);
+  }
+}
+
+/**
+ * Write one joint's transform straight into a pose.
+ *
+ * What a solver drives. Track B's ragdolls need a pose to be *data* rather than only the result of
+ * sampling, and this is the whole of that requirement — stated here so the seam exists before the
+ * track that needs it, rather than being retrofitted around a closed type.
+ */
+export function setJoint(
+  pose: Pose,
+  joint: number,
+  translation: ArrayLike<number>,
+  rotation: ArrayLike<number>,
+  scale: ArrayLike<number>,
+): void {
+  const v = joint * 3;
+  const r = joint * 4;
+  for (let c = 0; c < 3; c++) {
+    pose.translation[v + c] = translation[c] as number;
+    pose.scale[v + c] = scale[c] as number;
+  }
+  for (let c = 0; c < 4; c++) pose.rotation[r + c] = rotation[c] as number;
+}
+
+/**
+ * Spherical interpolation between two quaternions held in flat arrays, along the shorter arc.
+ *
+ * The same arithmetic `clip.ts` performs between two keys, over two poses instead — and with the
+ * same hemisphere correction, for the same reason: a quaternion and its negation are one
+ * orientation, so two poses can be numerically far apart while being geometrically close, and
+ * without the flip a limb rotates the long way through the body.
+ *
+ * Not shared with `clip.ts` because that one reads a keyframe stride and this one reads a joint
+ * stride; the arithmetic between them is eight lines, and a shared function taking four offsets
+ * would be harder to read than either. What would make that wrong is a third caller.
+ */
+function slerpInto(
+  a: ArrayLike<number>,
+  aAt: number,
+  b: ArrayLike<number>,
+  bAt: number,
+  t: number,
+  out: Float32Array,
+  outAt: number,
+): void {
+  let ax = a[aAt] as number;
+  let ay = a[aAt + 1] as number;
+  let az = a[aAt + 2] as number;
+  let aw = a[aAt + 3] as number;
+  const bx = b[bAt] as number;
+  const by = b[bAt + 1] as number;
+  const bz = b[bAt + 2] as number;
+  const bw = b[bAt + 3] as number;
+
+  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: number;
+  let s1: number;
+  /* Nearly parallel falls back to a straight blend: `acos` 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. */
+  if (dot > 0.9995) {
+    s0 = 1 - t;
+    s1 = t;
+  } else {
+    const theta = Math.acos(dot);
+    const sinTheta = Math.sin(theta);
+    s0 = Math.sin((1 - t) * theta) / sinTheta;
+    s1 = Math.sin(t * 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;
+  const length = Math.hypot(x, y, z, w);
+  if (length > 0) {
+    x /= length;
+    y /= length;
+    z /= length;
+    w /= length;
+  }
+  out[outAt] = x;
+  out[outAt + 1] = y;
+  out[outAt + 2] = z;
+  out[outAt + 3] = w;
+}
+
+/** Quaternion product, in flat arrays. Safe when `out` overlaps either input. */
+function multiplyInto(
+  a: ArrayLike<number>,
+  aAt: number,
+  b: ArrayLike<number>,
+  bAt: number,
+  out: Float32Array,
+  outAt: number,
+): void {
+  const ax = a[aAt] as number;
+  const ay = a[aAt + 1] as number;
+  const az = a[aAt + 2] as number;
+  const aw = a[aAt + 3] as number;
+  const bx = b[bAt] as number;
+  const by = b[bAt + 1] as number;
+  const bz = b[bAt + 2] as number;
+  const bw = b[bAt + 3] as number;
+  out[outAt] = aw * bx + ax * bw + ay * bz - az * by;
+  out[outAt + 1] = aw * by - ax * bz + ay * bw + az * bx;
+  out[outAt + 2] = aw * bz + ax * by - ay * bx + az * bw;
+  out[outAt + 3] = aw * bw - ax * bx - ay * by - az * bz;
+}
+
+/* Module scope, claimed once: `addPose` runs per character per frame. */
+const IDENTITY = new Float32Array([0, 0, 0, 1]);
+const SCALED = new Float32Array(4);

package/src/blendTree.ts

@@ -0,0 +1,253 @@
+import type { AnimationClip } from './clip.ts';
+import { sampleClip } from './clip.ts';
+import { blendPoses } from './blend.ts';
+import type { Pose } from './pose.ts';
+import { createPose } from './pose.ts';
+
+/**
+ * A tree of clips blended by parameters the game names.
+ *
+ * **The parameters are the consumer's own strings, never an engine enumeration**, for the reason
+ * the input action maps give: a game's verbs are a game's business, and an engine that enumerated
+ * them would be deciding what a character can be doing.
+ *
+ * Evaluation is a pure function of a caller-supplied time and the current parameters. Nothing here
+ * reads a clock, which is the contract `sampleClip` establishes and which a graph over clips has
+ * to keep or the replay story ends one layer up.
+ *
+ * **A parameter is one of two things, and the tree keeps them apart.** A *blend* parameter is a
+ * weight: which children a set brackets, how far a lerp has gone. A *clock* is a time: which
+ * instant of its own clip a node is sampled at, named by a `clip` node's `clock` and defaulting to
+ * the time `evaluate` was given. A name may be one or the other and never both — see `clocks` for
+ * why that is refused rather than allowed.
+ */
+
+export type BlendNode =
+  | {
+      readonly kind: 'clip';
+      readonly clip: AnimationClip;
+      /**
+       * The parameter whose value is this clip's own time, or omitted for the frame clock.
+       *
+       * **A tree had one clock for every node until 2026-08-28, and that cannot express the
+       * canonical blend space.** A locomotion set is stand, walk, run over one speed parameter —
+       * and a stride has to advance with **distance travelled** or the foot slides while the body
+       * passes over it, which is the fact `rootMotion` exists for, while an idle has to advance
+       * with **time**, because somebody standing still is still breathing. On one clock one of the
+       * two is wrong: share the distance and the idle freezes whenever nobody moves, share the time
+       * and the walk skates. Reported from outside, where the workaround was two clocks kept by
+       * hand and a `blendPoses` per overlay — which gives up the declared graph, the scratch poses
+       * claimed at construction, and a state machine's crossfades on top.
+       *
+       * **The value is a time on the clip's own axis, in seconds**, and what advances it is the
+       * caller's business: a stride measured in metres is divided by the metres a cycle covers and
+       * multiplied by the cycle's duration, and an angle turned is the same arithmetic. The engine
+       * does not know about metres, and a parameter that meant metres here would be the engine
+       * deciding what a character is doing.
+       *
+       * **What it gives up** is inheritance: a clock names one clip, so a subtree of four gait
+       * clips names it four times. **What would change that** is a consumer with a subtree deep
+       * enough for the repetition to hide a mistake, and the answer then is a clock on an interior
+       * node that its children inherit — which is a rule about scope, so it is worth having a
+       * reason for rather than adding now.
+       */
+      readonly clock?: string;
+    }
+  | {
+      readonly kind: 'lerp';
+      readonly a: BlendNode;
+      readonly b: BlendNode;
+      readonly parameter: string;
+    }
+  | {
+      readonly kind: 'oneDimensional';
+      readonly children: readonly { readonly at: number; readonly node: BlendNode }[];
+      readonly parameter: string;
+    };
+
+export class BlendTree {
+  private readonly parameters = new Map<string, number>();
+  /**
+   * 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.
+   */
+  private readonly scratch = new Map<BlendNode, [Pose, Pose]>();
+  /**
+   * 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.
+   */
+  private readonly clocks = new Set<string>();
+
+  /**
+   * @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(
+    private readonly root: BlendNode,
+    jointCount: number,
+    private readonly bind?: Pose,
+  ) {
+    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: string, value: number): void {
+    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: number, out: Pose): void {
+    this.walk(this.root, timeSec, out);
+  }
+
+  /** A scratch pose starting from the bind pose where one was given, or at rest where none was. */
+  private blank(jointCount: number): Pose {
+    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. */
+  private prepare(node: BlendNode, jointCount: number): void {
+    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);
+  }
+
+  private walk(node: BlendNode, timeSec: number, out: Pose): void {
+    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);
+  }
+}