@driftengine/animation 3.61.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.

package/README.md

@@ -0,0 +1,74 @@
+# @driftengine/animation
+
+Skeletons, clips, poses, and the graphs over them.
+
+**Cost: 6.1 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+drifts more than 3% — the number is derived from the same floors that gate asserts, so a README
+quoting a stale one is a red suite rather than a thing somebody notices.
+
+## What it is
+
+A `Skeleton` resolves a `Pose` into a skinning palette. A clip is **sampled as a pure function of a
+time you supply** — `sampleClip(clip, seconds, out)` reads no clock of its own, which is what lets an
+animation be part of a replay rather than something layered on top of one. Above that: `blendPoses`
+and additive layers, a `BlendTree`, a crossfading state machine over parameters you name, two-bone
+IK, morph targets, retargeting by joint name, root motion, and **secondary motion** —
+`sampleSpring(settings, anchorAt, seconds, out)` for one damped spring and `sampleSpringChain` for a
+chain of them, which is hair, a coat, an antenna or a chain reacting to what the subject is doing.
+
+Skinning and morphing run on both backends as vertex-shader permutations, so **a mesh with no rig
+carries none of their instructions**. glTF's skins, animations and morph targets import, and `.drft`
+carries them.
+
+## Things that cost time before they were written down
+
+**A blend needs a bind pose and does not take one.** `blendPoses(a, b, t, out)` has no bind-pose
+parameter — the bind pose belongs to `BlendTree`, which allocates its own scratch poses. Reaching
+for one on `blendPoses` is reading a paraphrase rather than the signature.
+
+**Nothing here allocates per frame, and `out` is why.** Every sampler and every blend fills a
+caller-owned target. A version returning a fresh `Pose` reads better and allocates one per joint per
+frame, which is the shape `AGENTS.md` forbids in a hot path.
+
+**Root motion is two calls and it is a mistake to make only one of them.**
+`extractRootMotion(clip, rootJoint, fromSec, toSec, motion)` answers how far the root travelled, in
+the root's own frame at `fromSec`, so you apply it as `position += worldRotation * motion.translation`
+and `worldRotation = worldRotation * motion.rotation`. Then `stripRootMotion(clip, rootJoint, pose)`
+pins the pose's root to the clip's value at time zero. **Extract without stripping and the character
+moves twice, at exactly double speed, with nothing failing.**
+
+Loops are accumulated rather than subtracted, which is the part you would otherwise have to write
+yourself and get wrong: sampling the root at both times and subtracting answers a full stride
+_backwards_ every time the clip wraps. What it gives up is a vertical bob authored on the root —
+that leaves the pose with everything else and becomes motion you apply, so if your height is owned
+by a physics controller and you ignore `translation[1]`, the bob is in neither.
+
+**Secondary motion is sampled, not advanced, and that is what it is for.** `sampleSpring` takes a
+time and an `anchorAt(t, out)` that must itself be a pure function of the time it is handed. It never
+carries state between calls, so dragging a playhead backwards gives the same pose the forward pass
+gave. The cost is arithmetic per sample instead of per frame: about ninety substeps of a four-multiply
+2x2 for one spring, paid in whichever direction the caller is moving.
+
+**`anchorAt` is called at times before the one you asked for**, going back `springSettleSec(settings)`
+— which is how long the spring takes to forget, `-ln(1e-3) / (ζω)`. An anchor that reads a clock, or
+that answers differently on a second call for one time, breaks the property silently. If yours comes
+from a clip, sample the clip at the time it is handed.
+
+**Damping of exactly 0 throws, and that is not a validation nicety.** An undamped spring rings
+forever, so no lookback is long enough to sample it purely and there is no honest answer to return.
+Anything above zero forgets. 1 is critical damping, which never overshoots; above 1 sags in.
+
+**A chain is `sampleSpringChain`, and it is not the same as calling `sampleSpring` per link.** Each
+link's anchor is where the link above it actually is — lagging and overshooting — so a chain
+remembers longer than any of its links and needs `springChainSettleSec`, which is longer than
+`springSettleSec` and grows with depth. It also has to march on one grid: evaluating a link on its
+own would need its parent at every substep and the grandparent at every substep of each of those,
+which is `steps^depth` anchor calls for the same answer.
+
+## Where to start
+
+`sampleClip` into a `Pose`, `Skeleton.palette` out of it, and `applyPoseToNode` for a rig you want to
+drive without skinning at all.
+
+Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)
+for how the packages divide, and why some features are compiled into core on demand instead.

package/dist/blend.d.ts

@@ -0,0 +1,39 @@
+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 declare function blendPoses(a: Pose, b: Pose, t: number, out: Pose): void;
+/**
+ * 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 declare function addPose(base: Pose, delta: Pose, weight: number, out: Pose): void;
+/**
+ * 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 declare function setJoint(pose: Pose, joint: number, translation: ArrayLike<number>, rotation: ArrayLike<number>, scale: ArrayLike<number>): void;

package/dist/blend.js

@@ -0,0 +1,158 @@
+/**
+ * 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, b, t, out) {
+    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];
+            out.translation[v + c] = from + (b.translation[v + c] - from) * weight;
+            const scaleFrom = a.scale[v + c];
+            out.scale[v + c] = scaleFrom + (b.scale[v + c] - 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, delta, weight, out) {
+    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] + delta.translation[v + c] * w;
+            /* One at weight zero, the delta's own factor at weight one, interpolated between. */
+            const factor = 1 + (delta.scale[v + c] - 1) * w;
+            out.scale[v + c] = base.scale[v + c] * 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, joint, translation, rotation, scale) {
+    const v = joint * 3;
+    const r = joint * 4;
+    for (let c = 0; c < 3; c++) {
+        pose.translation[v + c] = translation[c];
+        pose.scale[v + c] = scale[c];
+    }
+    for (let c = 0; c < 4; c++)
+        pose.rotation[r + c] = rotation[c];
+}
+/**
+ * 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, aAt, b, bAt, t, out, outAt) {
+    let ax = a[aAt];
+    let ay = a[aAt + 1];
+    let az = a[aAt + 2];
+    let aw = a[aAt + 3];
+    const bx = b[bAt];
+    const by = b[bAt + 1];
+    const bz = b[bAt + 2];
+    const bw = b[bAt + 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 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, aAt, b, bAt, out, outAt) {
+    const ax = a[aAt];
+    const ay = a[aAt + 1];
+    const az = a[aAt + 2];
+    const aw = a[aAt + 3];
+    const bx = b[bAt];
+    const by = b[bAt + 1];
+    const bz = b[bAt + 2];
+    const bw = b[bAt + 3];
+    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/dist/blendTree.d.ts

@@ -0,0 +1,115 @@
+import type { AnimationClip } from './clip.ts';
+import type { Pose } 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 declare class BlendTree {
+    private readonly root;
+    private readonly bind?;
+    private readonly parameters;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * @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: BlendNode, jointCount: number, bind?: Pose | undefined);
+    /**
+     * 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;
+    /**
+     * 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;
+    /** A scratch pose starting from the bind pose where one was given, or at rest where none was. */
+    private blank;
+    /** Collect parameter names and claim scratch, once, so evaluation allocates nothing. */
+    private prepare;
+    private walk;
+}