@driftengine/animation 3.61.0

package/src/pose.ts

@@ -0,0 +1,60 @@
+/**
+ * A pose: one transform per joint, as three flat arrays rather than an array of objects.
+ *
+ * **Structure-of-arrays because a pose is bulk data on a hot path.** A rig is sixty to ninety
+ * joints and a scene holds several characters, so a pose per character per frame as objects is
+ * exactly the allocation the performance rules forbid. Three typed arrays are claimed once and
+ * written in place for the character's whole life, and the palette they resolve into is
+ * contiguous for the same reason.
+ *
+ * What it costs is that reading one joint is three indexed reads rather than a property access.
+ * What would make it wrong is a caller needing to hold a single joint's transform as a value —
+ * which `blend.ts`'s `setJoint` answers by writing rather than by handing one out.
+ */
+
+export interface Pose {
+  /** Three floats a joint. */
+  readonly translation: Float32Array;
+  /** Four floats a joint, xyzw, in the order `gl-matrix` uses. */
+  readonly rotation: Float32Array;
+  /** Three floats a joint. */
+  readonly scale: Float32Array;
+}
+
+/**
+ * A pose sized for `jointCount` joints, already at rest.
+ *
+ * **At rest rather than zeroed**, and that is a correctness matter rather than a convenience.
+ * A zero quaternion normalises to NaN and a zero scale collapses every vertex the joint touches,
+ * so a caller who allocates a pose and forgets to rest it would get a rig that vanishes rather
+ * than one that stands still. The same reasoning `vertexDefaults.ts` gives for handing an absent
+ * tangent `(1, 0, 0, 1)` instead of zero: the safe default is a usable value, never a sentinel
+ * that arithmetic turns into NaN.
+ */
+export function createPose(jointCount: number): Pose {
+  const pose: Pose = {
+    translation: new Float32Array(jointCount * 3),
+    rotation: new Float32Array(jointCount * 4),
+    scale: new Float32Array(jointCount * 3),
+  };
+  restPose(jointCount, pose);
+  return pose;
+}
+
+/**
+ * Write the rest pose — no translation, identity rotation, unit scale — into an existing pose.
+ *
+ * Separate from `createPose` so a caller can return a pose to rest without allocating a second
+ * one, which is what a state machine does when it re-enters a state.
+ */
+export function restPose(jointCount: number, out: Pose): void {
+  out.translation.fill(0);
+  out.scale.fill(1);
+  for (let j = 0; j < jointCount; j++) {
+    const at = j * 4;
+    out.rotation[at] = 0;
+    out.rotation[at + 1] = 0;
+    out.rotation[at + 2] = 0;
+    out.rotation[at + 3] = 1;
+  }
+}

package/src/retarget.ts

@@ -0,0 +1,105 @@
+import type { Pose } from './pose.ts';
+import type { Skeleton } from './skeleton.ts';
+
+/**
+ * Playing one skeleton's clip on another.
+ *
+ * **Rotations transfer and translations do not, and that is the whole of it.** Two rigs of
+ * different proportions share joint *orientations* and not bone lengths, so copying a translation
+ * puts the taller rig's limbs inside its own body. The root is the exception, because that is
+ * where locomotion lives — a walk whose root did not move would be a moonwalk.
+ *
+ * What this does not do is retarget between *different topologies*: a rig with a split spine
+ * playing a clip from one with a single spine needs a decision about how to distribute the
+ * rotation, and that decision belongs to whoever knows what the character is. This matches by
+ * name, transfers what matches, and says what did not.
+ */
+
+export interface RetargetMap {
+  /** Source joint index to target joint index, or -1 where the target has no such joint. */
+  readonly indices: Int16Array;
+  /** Source joint names the target does not have, in source order. */
+  readonly unmatched: readonly string[];
+}
+
+/**
+ * Match two skeletons by joint name.
+ *
+ * **Exact matching, and no name database.** A table of "hips means Hips means pelvis" rots
+ * silently and its failure is a limb that does not move, which no test of this engine could catch
+ * — the same argument the gamepad layer makes for shipping no device database. A consumer whose
+ * two rigs disagree about capitalisation knows that and can rename; this engine guessing would be
+ * wrong in a way they could not see.
+ */
+export function buildRetargetMap(from: Skeleton, to: Skeleton): RetargetMap {
+  const byName = new Map<string, number>();
+  to.joints.forEach((joint, at) => {
+    /* First wins, so a rig with two joints of one name maps to the earlier — the one nearer the
+       root, since joints are sorted parents-first. */
+    if (!byName.has(joint.name)) byName.set(joint.name, at);
+  });
+
+  const indices = new Int16Array(from.jointCount);
+  const unmatched: string[] = [];
+  from.joints.forEach((joint, at) => {
+    const found = byName.get(joint.name);
+    if (found === undefined) {
+      indices[at] = -1;
+      unmatched.push(joint.name);
+      return;
+    }
+    indices[at] = found;
+  });
+
+  /*
+   * Reported rather than acted on. Whether a missing joint is a broken import, a deliberately
+   * simpler rig, or something to substitute for is a product decision — the same line `rebind`
+   * draws when it reports the actions it displaced rather than deciding about them.
+   */
+  return { indices, unmatched };
+}
+
+/**
+ * Write `source`, played on `from`, onto `to` in `out`. Allocates nothing.
+ *
+ * A joint the target has and the source does not is **left exactly as it was found**, so a
+ * character with a tail wearing a clip from one without keeps its tail wherever its own idle put
+ * it rather than snapping to rest. That is the layering `sampleClip` provides one level down, and
+ * it is what lets a retargeted clip be laid over a base pose.
+ */
+export function retargetPose(
+  map: RetargetMap,
+  from: Skeleton,
+  source: Pose,
+  to: Skeleton,
+  out: Pose,
+): void {
+  for (let j = 0; j < from.jointCount; j++) {
+    const target = map.indices[j] ?? -1;
+    /*
+     * The `-1` is the real guard; the upper bound is unreachable from a map `buildRetargetMap`
+     * produced, since it only ever names a joint the target has. Kept for a hand-built map, and
+     * said so rather than left to read as load-bearing — perturbing it away leaves every test
+     * green, which is how that was established.
+     */
+    if (target < 0 || target >= to.jointCount) continue;
+
+    const sourceAt = j * 4;
+    const targetAt = target * 4;
+    for (let c = 0; c < 4; c++)
+      out.rotation[targetAt + c] = source.rotation[sourceAt + c] as number;
+
+    /*
+     * The root's translation, and only the root's. Everything below it is placed by its parent, so
+     * a bone length is the target rig's own fact — copying the source's would rebuild the target
+     * as the source, one joint at a time, which is precisely what retargeting exists to avoid.
+     */
+    if ((to.joints[target]?.parent ?? -1) < 0) {
+      const sourceT = j * 3;
+      const targetT = target * 3;
+      for (let c = 0; c < 3; c++) {
+        out.translation[targetT + c] = source.translation[sourceT + c] as number;
+      }
+    }
+  }
+}

package/src/rigid.ts

@@ -0,0 +1,99 @@
+import type { SceneNode } from '@driftengine/core';
+
+import type { AnimationClip } from './clip.ts';
+import { sampleClip } from './clip.ts';
+import type { Pose } from './pose.ts';
+import { createPose } from './pose.ts';
+
+/**
+ * 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: Pose, joint: number, node: SceneNode): void {
+  const t = joint * 3;
+  const r = joint * 4;
+  node.position[0] = pose.translation[t] as number;
+  node.position[1] = pose.translation[t + 1] as number;
+  node.position[2] = pose.translation[t + 2] as number;
+  node.rotation[0] = pose.rotation[r] as number;
+  node.rotation[1] = pose.rotation[r + 1] as number;
+  node.rotation[2] = pose.rotation[r + 2] as number;
+  node.rotation[3] = pose.rotation[r + 3] as number;
+  node.scale[0] = pose.scale[t] as number;
+  node.scale[1] = pose.scale[t + 1] as number;
+  node.scale[2] = pose.scale[t + 2] as number;
+  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 {
+  private readonly pose: 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.
+   */
+  private readonly driven: number[] = [];
+
+  /**
+   * @param nodes Indexed by joint. `null` for a joint this scene did not instantiate.
+   */
+  constructor(
+    private readonly clip: AnimationClip,
+    private readonly nodes: readonly (SceneNode | null)[],
+  ) {
+    /*
+     * 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: number): void {
+    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/src/rootMotion.ts

@@ -0,0 +1,253 @@
+import type { AnimationClip, JointTrack, TrackPath } from '@driftengine/drft';
+
+import { sampleTrack, wrapTime } from './clip.ts';
+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 function createRootMotion(): RootMotion {
+  const motion: RootMotion = { 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: AnimationClip,
+  rootJoint: number,
+  fromSec: number,
+  toSec: number,
+  out: RootMotion,
+): void {
+  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: AnimationClip, rootJoint: number, pose: Pose): void {
+  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: AnimationClip, joint: number, path: TrackPath): JointTrack | null {
+  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: JointTrack | null,
+  rotation: JointTrack | null,
+  t0: number,
+  t1: number,
+  out: RootMotion,
+): void {
+  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] as number) - (FROM_T[c] as number);
+  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] as number) + (SEG_T[c] as number);
+  }
+  multiplyInto(out.rotation, SEG_R, COMPOSED);
+  for (let c = 0; c < 4; c++) out.rotation[c] = COMPOSED[c] as number;
+}
+
+function identity(out: RootMotion): void {
+  out.translation.fill(0);
+  identityInto(out.rotation);
+}
+
+function identityInto(quaternion: Float32Array): void {
+  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: Float32Array, out: Float32Array): void {
+  out[0] = -(quaternion[0] as number);
+  out[1] = -(quaternion[1] as number);
+  out[2] = -(quaternion[2] as number);
+  out[3] = quaternion[3] as number;
+}
+
+/** Quaternion product `a * b` into `out`. `out` must not alias either input. */
+function multiplyInto(a: Float32Array, b: Float32Array, out: Float32Array): void {
+  const ax = a[0] as number;
+  const ay = a[1] as number;
+  const az = a[2] as number;
+  const aw = a[3] as number;
+  const bx = b[0] as number;
+  const by = b[1] as number;
+  const bz = b[2] as number;
+  const bw = b[3] as number;
+  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: Float32Array, vector: Float32Array): void {
+  const qx = quaternion[0] as number;
+  const qy = quaternion[1] as number;
+  const qz = quaternion[2] as number;
+  const qw = quaternion[3] as number;
+  const vx = vector[0] as number;
+  const vy = vector[1] as number;
+  const vz = vector[2] as number;
+
+  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);