@aura3d/animation 1.0.6

package/src/MotionQuality.ts

@@ -0,0 +1,156 @@
+export interface AnimationMotionSample {
+  readonly timeSeconds: number;
+  readonly tracksApplied?: number;
+  readonly skinningPalettesUpdated?: number;
+  readonly stride?: number;
+  readonly animatedSubjects?: number;
+}
+
+export interface AnimationMotionQualityReport {
+  readonly sampleCount: number;
+  readonly timeRangeSeconds: number;
+  readonly activeTrackFrames: number;
+  readonly activeSkinningFrames: number;
+  readonly animatedSubjectFrames: number;
+  readonly averageStride: number;
+  readonly poseDiversityScore: number;
+  readonly healthy: boolean;
+}
+
+export interface AnimationMotionQualityOptions {
+  readonly maxSamples?: number;
+  readonly minimumSamples?: number;
+  readonly minimumTimeRangeSeconds?: number;
+  readonly minimumPoseDiversityScore?: number;
+}
+
+export class AnimationMotionQualityTracker {
+  private readonly maxSamples: number;
+  private readonly minimumSamples: number;
+  private readonly minimumTimeRangeSeconds: number;
+  private readonly minimumPoseDiversityScore: number;
+  private readonly samples: AnimationMotionSample[] = [];
+
+  constructor(options: AnimationMotionQualityOptions = {}) {
+    this.maxSamples = positiveInteger(options.maxSamples ?? 180, "maxSamples");
+    this.minimumSamples = positiveInteger(options.minimumSamples ?? 8, "minimumSamples");
+    this.minimumTimeRangeSeconds = nonNegativeFinite(options.minimumTimeRangeSeconds ?? 0.18, "minimumTimeRangeSeconds");
+    this.minimumPoseDiversityScore = nonNegativeFinite(options.minimumPoseDiversityScore ?? 0.08, "minimumPoseDiversityScore");
+  }
+
+  record(sample: AnimationMotionSample): AnimationMotionQualityReport {
+    validateSample(sample);
+    this.samples.push(sample);
+    if (this.samples.length > this.maxSamples) {
+      this.samples.shift();
+    }
+    return this.report();
+  }
+
+  report(): AnimationMotionQualityReport {
+    return summarizeAnimationMotion(this.samples, {
+      minimumSamples: this.minimumSamples,
+      minimumTimeRangeSeconds: this.minimumTimeRangeSeconds,
+      minimumPoseDiversityScore: this.minimumPoseDiversityScore
+    });
+  }
+
+  reset(): void {
+    this.samples.length = 0;
+  }
+}
+
+export function summarizeAnimationMotion(
+  samples: readonly AnimationMotionSample[],
+  options: Pick<AnimationMotionQualityOptions, "minimumSamples" | "minimumTimeRangeSeconds" | "minimumPoseDiversityScore"> = {}
+): AnimationMotionQualityReport {
+  const minimumSamples = positiveInteger(options.minimumSamples ?? 8, "minimumSamples");
+  const minimumTimeRangeSeconds = nonNegativeFinite(options.minimumTimeRangeSeconds ?? 0.18, "minimumTimeRangeSeconds");
+  const minimumPoseDiversityScore = nonNegativeFinite(options.minimumPoseDiversityScore ?? 0.08, "minimumPoseDiversityScore");
+  const ordered = samples.slice().sort((left, right) => left.timeSeconds - right.timeSeconds);
+  const sampleCount = ordered.length;
+  if (sampleCount === 0) {
+    return emptyReport();
+  }
+
+  const firstTime = ordered[0]!.timeSeconds;
+  const lastTime = ordered[sampleCount - 1]!.timeSeconds;
+  const timeRangeSeconds = Math.max(0, lastTime - firstTime);
+  const activeTrackFrames = ordered.filter((sample) => (sample.tracksApplied ?? 0) > 0).length;
+  const activeSkinningFrames = ordered.filter((sample) => (sample.skinningPalettesUpdated ?? 0) > 0).length;
+  const animatedSubjectFrames = ordered.filter((sample) => (sample.animatedSubjects ?? 0) > 0).length;
+  const strides = ordered.map((sample) => Math.abs(sample.stride ?? 0));
+  const averageStride = strides.reduce((sum, value) => sum + value, 0) / sampleCount;
+  const poseDiversityScore = computePoseDiversity(ordered);
+  return {
+    sampleCount,
+    timeRangeSeconds: round(timeRangeSeconds),
+    activeTrackFrames,
+    activeSkinningFrames,
+    animatedSubjectFrames,
+    averageStride: round(averageStride),
+    poseDiversityScore: round(poseDiversityScore),
+    healthy: sampleCount >= minimumSamples
+      && timeRangeSeconds >= minimumTimeRangeSeconds
+      && poseDiversityScore >= minimumPoseDiversityScore
+      && (activeTrackFrames > 0 || activeSkinningFrames > 0 || animatedSubjectFrames > 0)
+  };
+}
+
+function computePoseDiversity(samples: readonly AnimationMotionSample[]): number {
+  if (samples.length < 2) return 0;
+  let diversity = 0;
+  for (let index = 1; index < samples.length; index += 1) {
+    const previous = samples[index - 1]!;
+    const current = samples[index]!;
+    diversity += Math.abs(current.timeSeconds - previous.timeSeconds);
+    diversity += Math.abs((current.tracksApplied ?? 0) - (previous.tracksApplied ?? 0)) * 0.01;
+    diversity += Math.abs((current.skinningPalettesUpdated ?? 0) - (previous.skinningPalettesUpdated ?? 0)) * 0.01;
+    diversity += Math.abs((current.stride ?? 0) - (previous.stride ?? 0));
+    diversity += Math.abs((current.animatedSubjects ?? 0) - (previous.animatedSubjects ?? 0)) * 0.02;
+  }
+  return diversity;
+}
+
+function validateSample(sample: AnimationMotionSample): void {
+  nonNegativeFinite(sample.timeSeconds, "timeSeconds");
+  optionalNonNegativeFinite(sample.tracksApplied, "tracksApplied");
+  optionalNonNegativeFinite(sample.skinningPalettesUpdated, "skinningPalettesUpdated");
+  optionalNonNegativeFinite(sample.stride, "stride");
+  optionalNonNegativeFinite(sample.animatedSubjects, "animatedSubjects");
+}
+
+function optionalNonNegativeFinite(value: number | undefined, label: string): void {
+  if (value !== undefined) nonNegativeFinite(value, label);
+}
+
+function nonNegativeFinite(value: number, label: string): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`Animation motion ${label} must be finite and non-negative.`);
+  }
+  return value;
+}
+
+function positiveInteger(value: number, label: string): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(`Animation motion ${label} must be a positive integer.`);
+  }
+  return value;
+}
+
+function emptyReport(): AnimationMotionQualityReport {
+  return {
+    sampleCount: 0,
+    timeRangeSeconds: 0,
+    activeTrackFrames: 0,
+    activeSkinningFrames: 0,
+    animatedSubjectFrames: 0,
+    averageStride: 0,
+    poseDiversityScore: 0,
+    healthy: false
+  };
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(4));
+}

package/src/Retargeting.ts

@@ -0,0 +1,29 @@
+import { Matrix4 } from "@aura3d/math";
+
+export interface RetargetBoneMap {
+  readonly source: string;
+  readonly target: string;
+  readonly scale?: number;
+}
+
+export interface RetargetPoseInput {
+  readonly sourcePose: ReadonlyMap<string, Matrix4>;
+  readonly boneMap: readonly RetargetBoneMap[];
+}
+
+export function retargetPose(input: RetargetPoseInput): Map<string, Matrix4> {
+  const output = new Map<string, Matrix4>();
+  for (const mapping of input.boneMap) {
+    const source = input.sourcePose.get(mapping.source);
+    if (!source) continue;
+    const elements = [...source.elements];
+    const scale = mapping.scale ?? 1;
+    if (scale !== 1) {
+      elements[12] *= scale;
+      elements[13] *= scale;
+      elements[14] *= scale;
+    }
+    output.set(mapping.target, new Matrix4(elements as unknown as Matrix4["elements"]));
+  }
+  return output;
+}

package/src/RootMotion.ts

@@ -0,0 +1,124 @@
+import type { AnimationClip } from "./AnimationClip.js";
+import type { AnimationTrack } from "./AnimationTrack.js";
+import type { Vec3 } from "./Keyframe.js";
+
+export type RootMotionExtractionDescriptor = {
+  readonly target?: string;
+  readonly fromTime: number;
+  readonly toTime: number;
+  readonly loop?: boolean;
+};
+
+export type RootMotionSample = {
+  readonly target: string;
+  readonly fromTime: number;
+  readonly toTime: number;
+  readonly looped: boolean;
+  readonly delta: Vec3;
+};
+
+export type RootMotionTarget = {
+  position: [number, number, number];
+};
+
+const defaultRootMotionTarget = "root.position";
+
+export function extractRootMotion(clip: AnimationClip, descriptor: RootMotionExtractionDescriptor): RootMotionSample {
+  const target = descriptor.target ?? defaultRootMotionTarget;
+  if (!Number.isFinite(descriptor.fromTime) || !Number.isFinite(descriptor.toTime)) {
+    throw new Error("Root motion times must be finite.");
+  }
+  const track = clip.tracks.find((candidate) => candidate.target === target);
+  if (!track) {
+    throw new Error(`Root motion track "${target}" was not found.`);
+  }
+  if (track.valueType !== "vector3") {
+    throw new Error(`Root motion track "${target}" must be a vector3 track.`);
+  }
+
+  const loop = descriptor.loop ?? false;
+  const delta = loop
+    ? extractLoopingDelta(track, clip.duration, descriptor.fromTime, descriptor.toTime)
+    : subtractVec3(
+        sampleVec3(track, clampTime(descriptor.toTime, clip.duration)),
+        sampleVec3(track, clampTime(descriptor.fromTime, clip.duration))
+      );
+
+  return {
+    target,
+    fromTime: descriptor.fromTime,
+    toTime: descriptor.toTime,
+    looped: loop,
+    delta
+  };
+}
+
+export function applyRootMotion(target: RootMotionTarget, sample: RootMotionSample, scale = 1): RootMotionTarget {
+  if (!Number.isFinite(scale)) {
+    throw new Error("Root motion scale must be finite.");
+  }
+  target.position = [
+    target.position[0] + sample.delta[0] * scale,
+    target.position[1] + sample.delta[1] * scale,
+    target.position[2] + sample.delta[2] * scale
+  ];
+  return target;
+}
+
+function extractLoopingDelta(track: AnimationTrack, duration: number, fromTime: number, toTime: number): Vec3 {
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error("Looping root motion requires a positive clip duration.");
+  }
+
+  let effectiveTo = toTime;
+  if (effectiveTo < fromTime) {
+    effectiveTo += Math.ceil((fromTime - effectiveTo) / duration) * duration;
+  }
+
+  const fromCycle = Math.floor(fromTime / duration);
+  const toCycle = Math.floor(effectiveTo / duration);
+  const fromWrapped = wrapTime(fromTime, duration);
+  const toWrapped = wrapTime(effectiveTo, duration);
+
+  if (fromCycle === toCycle) {
+    return subtractVec3(sampleVec3(track, toWrapped), sampleVec3(track, fromWrapped));
+  }
+
+  const cycleDelta = subtractVec3(sampleVec3(track, duration), sampleVec3(track, 0));
+  const firstPartial = subtractVec3(sampleVec3(track, duration), sampleVec3(track, fromWrapped));
+  const wholeCycles = Math.max(0, toCycle - fromCycle - 1);
+  const finalPartial = subtractVec3(sampleVec3(track, toWrapped), sampleVec3(track, 0));
+  return addVec3(addVec3(firstPartial, scaleVec3(cycleDelta, wholeCycles)), finalPartial);
+}
+
+function clampTime(time: number, duration: number): number {
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new Error("Root motion clip duration must be finite and non-negative.");
+  }
+  return Math.max(0, Math.min(duration, time));
+}
+
+function wrapTime(time: number, duration: number): number {
+  const wrapped = time % duration;
+  return wrapped < 0 ? wrapped + duration : wrapped;
+}
+
+function sampleVec3(track: AnimationTrack, time: number): Vec3 {
+  const value = track.sample(time);
+  if (!Array.isArray(value) || value.length !== 3 || value.some((component) => typeof component !== "number" || !Number.isFinite(component))) {
+    throw new Error(`Root motion track "${track.target}" sampled an invalid vector3 value.`);
+  }
+  return [value[0], value[1], value[2]];
+}
+
+function addVec3(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+
+function subtractVec3(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+
+function scaleVec3(a: Vec3, scale: number): Vec3 {
+  return [a[0] * scale, a[1] * scale, a[2] * scale];
+}

package/src/SceneAnimationBridge.ts

@@ -0,0 +1,80 @@
+import type { AnimationValue } from "./Keyframe.js";
+
+export type SceneAnimationNode = {
+  name?: string;
+  position?: [number, number, number];
+  rotation?: [number, number, number, number];
+  scale?: [number, number, number];
+  weights?: number[];
+  setPosition?: (value: readonly [number, number, number]) => void;
+  setRotation?: (value: readonly [number, number, number, number]) => void;
+  setScale?: (value: readonly [number, number, number]) => void;
+  setWeights?: (value: readonly number[]) => void;
+};
+
+export class SceneAnimationBridge {
+  private readonly nodes = new Map<string, SceneAnimationNode>();
+
+  register(name: string, node: SceneAnimationNode): void {
+    if (name.trim().length === 0) {
+      throw new Error("Scene animation target name cannot be empty.");
+    }
+    this.nodes.set(name, node);
+  }
+
+  setAnimationValue(target: string, value: AnimationValue): void {
+    const [nodeName, property] = target.split(".");
+    if (!nodeName || !property) {
+      throw new Error(`Invalid scene animation target ${target}.`);
+    }
+    const node = this.nodes.get(nodeName);
+    if (!node) {
+      throw new Error(`Missing scene animation target ${nodeName}.`);
+    }
+    if (property === "position" || property === "translation") {
+      writeVec3(node, "position", "setPosition", value);
+    } else if (property === "rotation") {
+      writeQuat(node, value);
+    } else if (property === "scale") {
+      writeVec3(node, "scale", "setScale", value);
+    } else if (property === "weights") {
+      writeWeights(node, value);
+    } else {
+      throw new Error(`Unsupported scene animation property ${property}.`);
+    }
+  }
+}
+
+function writeWeights(node: SceneAnimationNode, value: AnimationValue): void {
+  if (!Array.isArray(value) || value.some((weight) => typeof weight !== "number" || !Number.isFinite(weight))) {
+    throw new Error("weights animation value must be a finite number array.");
+  }
+  const weights = value.map((weight) => Math.max(0, Math.min(1, weight)));
+  if (node.setWeights) {
+    node.setWeights(weights);
+  } else {
+    node.weights = weights;
+  }
+}
+
+function writeVec3(node: SceneAnimationNode, property: "position" | "scale", setter: "setPosition" | "setScale", value: AnimationValue): void {
+  if (!Array.isArray(value) || value.length !== 3) {
+    throw new Error(`${property} animation value must be a vec3.`);
+  }
+  if (node[setter]) {
+    node[setter](value as [number, number, number]);
+  } else {
+    node[property] = [value[0], value[1], value[2]];
+  }
+}
+
+function writeQuat(node: SceneAnimationNode, value: AnimationValue): void {
+  if (!Array.isArray(value) || value.length !== 4) {
+    throw new Error("rotation animation value must be a quaternion.");
+  }
+  if (node.setRotation) {
+    node.setRotation(value as [number, number, number, number]);
+  } else {
+    node.rotation = [value[0], value[1], value[2], value[3]];
+  }
+}

package/src/SecondaryAnimationFixtures.ts

@@ -0,0 +1,212 @@
+import type { Vec3 } from "./Keyframe";
+
+export interface SecondaryAnimationFixtureOptions {
+  readonly stridePhase?: number;
+  readonly rootHeight?: number;
+  readonly velocity?: Vec3;
+  readonly terrainSlope?: number;
+  readonly deltaSeconds?: number;
+  readonly seed?: number;
+}
+
+export interface FootIkSample {
+  readonly side: "left" | "right";
+  readonly sourceFoot: Vec3;
+  readonly plantedFoot: Vec3;
+  readonly groundNormal: Vec3;
+  readonly grounded: boolean;
+  readonly verticalCorrection: number;
+  readonly targetError: number;
+}
+
+export interface SpringBoneSample {
+  readonly chainName: "ponytail";
+  readonly boneCount: number;
+  readonly stiffness: number;
+  readonly damping: number;
+  readonly collisionRadius: number;
+  readonly substeps: number;
+  readonly gravity: Vec3;
+  readonly wind: Vec3;
+  readonly rootPosition: Vec3;
+  readonly tipPosition: Vec3;
+  readonly maxDisplacement: number;
+  readonly collisionContacts: number;
+}
+
+export interface SecondaryAnimationFixture {
+  readonly source: "origin-master-foot-ik-spring-bone-adapted";
+  readonly footIk: {
+    readonly feet: readonly FootIkSample[];
+    readonly hipOffset: number;
+    readonly averageTargetError: number;
+    readonly groundedFeet: number;
+    readonly terrainSlope: number;
+  };
+  readonly springBone: SpringBoneSample;
+  readonly productionReadiness: {
+    readonly footPlacementTelemetry: boolean;
+    readonly hipAdjustmentTelemetry: boolean;
+    readonly springChainTelemetry: boolean;
+    readonly collisionTelemetry: boolean;
+    readonly deterministicReplay: boolean;
+  };
+  readonly hash: string;
+  readonly claimBoundary: string;
+  readonly blockedClaims: readonly string[];
+}
+
+export function sampleSecondaryAnimationFixture(options: SecondaryAnimationFixtureOptions = {}): SecondaryAnimationFixture {
+  const stridePhase = wrap01(options.stridePhase ?? 0.35);
+  const rootHeight = clamp(options.rootHeight ?? 1.08, 0.4, 2.4);
+  const velocity = options.velocity ?? [0.9, 0, 0.22];
+  const terrainSlope = clamp(options.terrainSlope ?? 0.18, -0.7, 0.7);
+  const deltaSeconds = clamp(options.deltaSeconds ?? 1 / 60, 1 / 240, 1 / 10);
+  const seed = integerSeed(options.seed ?? 0x3d2025);
+  const groundNormal = normalize([-terrainSlope, 1, 0.08]);
+  const left = footSample("left", stridePhase, rootHeight, terrainSlope, groundNormal, velocity, seed);
+  const right = footSample("right", wrap01(stridePhase + 0.5), rootHeight, terrainSlope, groundNormal, velocity, seed + 17);
+  const feet = [left, right] as const;
+  const averageTargetError = round(feet.reduce((sum, foot) => sum + foot.targetError, 0) / feet.length);
+  const hipOffset = round(-Math.max(...feet.map((foot) => Math.max(0, foot.verticalCorrection))) * 0.72);
+  const springBone = springSample(rootHeight, velocity, deltaSeconds, seed);
+  const fixture = {
+    source: "origin-master-foot-ik-spring-bone-adapted" as const,
+    footIk: {
+      feet,
+      hipOffset,
+      averageTargetError,
+      groundedFeet: feet.filter((foot) => foot.grounded).length,
+      terrainSlope: round(terrainSlope)
+    },
+    springBone,
+    productionReadiness: {
+      footPlacementTelemetry: feet.every((foot) => foot.grounded && foot.targetError <= 0.015),
+      hipAdjustmentTelemetry: hipOffset < 0,
+      springChainTelemetry: springBone.boneCount >= 4 && springBone.maxDisplacement > 0,
+      collisionTelemetry: springBone.collisionContacts > 0,
+      deterministicReplay: true
+    },
+    hash: "",
+    claimBoundary: "Secondary animation fixture adapts old foot-IK ground placement and spring-bone secondary motion into deterministic telemetry; it does not claim production foot locking, retargeting, full-body IK, cloth/hair simulation, Unity Animation Rigging parity, or Unreal Control Rig parity.",
+    blockedClaims: [
+      "production foot locking parity",
+      "full-body IK solver parity",
+      "runtime retargeting parity",
+      "production spring-bone collision parity",
+      "Unity Animation Rigging parity",
+      "Unreal Control Rig parity"
+    ] as const
+  };
+  return {
+    ...fixture,
+    hash: stableHash([
+      fixture.footIk.groundedFeet,
+      fixture.footIk.hipOffset,
+      fixture.footIk.averageTargetError,
+      fixture.springBone.maxDisplacement,
+      fixture.springBone.collisionContacts,
+      fixture.springBone.tipPosition.join(",")
+    ].join("|"))
+  };
+}
+
+function footSample(side: "left" | "right", phase: number, rootHeight: number, terrainSlope: number, normal: Vec3, velocity: Vec3, seed: number): FootIkSample {
+  const lateral = side === "left" ? -0.18 : 0.18;
+  const stride = Math.sin(phase * Math.PI * 2) * 0.22 + velocity[0] * 0.06;
+  const lift = Math.max(0, Math.sin(phase * Math.PI * 2)) * 0.08;
+  const jitter = (noise(seed) - 0.5) * 0.01;
+  const x = round(stride + jitter);
+  const z = round(lateral + velocity[2] * 0.04);
+  const sourceY = round(rootHeight - 1.05 + lift);
+  const groundY = round(x * terrainSlope - Math.abs(lateral) * 0.04);
+  const planted: Vec3 = [x, groundY + 0.035, z];
+  const source: Vec3 = [x, sourceY, z];
+  const verticalCorrection = round(sourceY - planted[1]);
+  return {
+    side,
+    sourceFoot: source,
+    plantedFoot: planted,
+    groundNormal: normal,
+    grounded: true,
+    verticalCorrection,
+    targetError: round(Math.abs(planted[1] - (groundY + 0.035)))
+  };
+}
+
+function springSample(rootHeight: number, velocity: Vec3, deltaSeconds: number, seed: number): SpringBoneSample {
+  const stiffness = 0.62;
+  const damping = 0.38;
+  const collisionRadius = 0.08;
+  const substeps = Math.max(1, Math.min(4, Math.ceil(deltaSeconds / (1 / 120))));
+  const rootPosition: Vec3 = [0, round(rootHeight + 0.32), -0.08];
+  const wind: Vec3 = [round(velocity[0] * 0.18 + noise(seed + 9) * 0.05), 0, round(0.1 + velocity[2] * 0.08)];
+  const gravity: Vec3 = [0, -9.81, 0];
+  const displacement = round(Math.hypot(wind[0], wind[2]) * (1 - damping) + 0.055);
+  const rawTip: Vec3 = [
+    round(rootPosition[0] + wind[0] * 0.38),
+    round(rootPosition[1] - 0.42 - displacement * 0.35),
+    round(rootPosition[2] + wind[2] * 0.42)
+  ];
+  const collisionFloor = rootHeight - 0.22;
+  const collisionContacts = rawTip[1] < collisionFloor + collisionRadius ? 1 : 0;
+  const tipPosition: Vec3 = collisionContacts > 0 ? [rawTip[0], round(collisionFloor + collisionRadius), rawTip[2]] : rawTip;
+  return {
+    chainName: "ponytail",
+    boneCount: 5,
+    stiffness,
+    damping,
+    collisionRadius,
+    substeps,
+    gravity,
+    wind,
+    rootPosition,
+    tipPosition,
+    maxDisplacement: round(distance(rootPosition, tipPosition)),
+    collisionContacts
+  };
+}
+
+function wrap01(value: number): number {
+  const wrapped = value - Math.floor(value);
+  return Number.isFinite(wrapped) ? wrapped : 0;
+}
+
+function integerSeed(value: number): number {
+  if (!Number.isInteger(value)) throw new Error("Secondary animation fixture seed must be an integer.");
+  return value;
+}
+
+function normalize(value: Vec3): Vec3 {
+  const length = Math.hypot(value[0], value[1], value[2]);
+  if (length <= 1e-6) return [0, 1, 0];
+  return [round(value[0] / length), round(value[1] / length), round(value[2] / length)];
+}
+
+function distance(left: Vec3, right: Vec3): number {
+  return Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2]);
+}
+
+function noise(seed: number): number {
+  let value = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b);
+  value ^= value >>> 13;
+  value = Math.imul(value, 0xc2b2ae35);
+  return ((value ^ (value >>> 16)) >>> 0) / 0xffffffff;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Number.isFinite(value) ? value : min));
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(4));
+}
+
+function stableHash(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/Skeleton.ts

@@ -0,0 +1,34 @@
+import { Bone, type BoneDescriptor } from "./Bone.js";
+import { multiplyMat4, type Mat4 } from "./Keyframe.js";
+
+export class Skeleton {
+  readonly bones: readonly Bone[];
+
+  constructor(bones: readonly (Bone | BoneDescriptor)[]) {
+    if (bones.length === 0) {
+      throw new Error("Skeleton requires at least one bone.");
+    }
+    this.bones = bones.map((bone) => bone instanceof Bone ? bone : new Bone(bone));
+    for (let index = 0; index < this.bones.length; index += 1) {
+      const parent = this.bones[index]!.parentIndex;
+      if (parent >= index || parent < -1) {
+        throw new Error(`Bone ${this.bones[index]!.name} has invalid parent index ${parent}.`);
+      }
+    }
+  }
+
+  worldMatrices(): readonly Mat4[] {
+    const matrices: Mat4[] = [];
+    for (let index = 0; index < this.bones.length; index += 1) {
+      const bone = this.bones[index]!;
+      const local = bone.localMatrix();
+      matrices[index] = bone.parentIndex >= 0 ? multiplyMat4(matrices[bone.parentIndex]!, local) : local;
+    }
+    return matrices;
+  }
+
+  matrixPalette(): readonly Mat4[] {
+    const worlds = this.worldMatrices();
+    return this.bones.map((bone, index) => multiplyMat4(worlds[index]!, bone.inverseBindMatrix));
+  }
+}

package/src/Skinning.ts

@@ -0,0 +1,18 @@
+import type { Skeleton } from "./Skeleton.js";
+
+export type SkinningPalette = {
+  readonly jointCount: number;
+  readonly matrices: Float32Array;
+};
+
+export function buildSkinningPalette(skeleton: Skeleton, maxJoints = 256): SkinningPalette {
+  const palette = skeleton.matrixPalette();
+  if (palette.length > maxJoints) {
+    throw new Error(`Skeleton has ${palette.length} joints, exceeding max ${maxJoints}.`);
+  }
+  const matrices = new Float32Array(palette.length * 16);
+  for (let index = 0; index < palette.length; index += 1) {
+    matrices.set(palette[index]!, index * 16);
+  }
+  return { jointCount: palette.length, matrices };
+}