@aura3d/animation 1.4.0 → 1.4.2

package/src/RootMotion.ts

@@ -1,124 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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

@@ -1,210 +0,0 @@
-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 provides the deterministic FootIkSample/SpringBoneSample telemetry shapes and oracle values; the real runtimes now live in FootIk.ts (two-bone foot IK + foot-lock on solveTwoBoneIk + a ground query) and SpringBones.ts (integrated spring chain). The fixture still does not claim retargeting, general full-body IK, cloth/hair simulation, Unity Animation Rigging parity, or Unreal Control Rig parity.",
-    blockedClaims: [
-      "full-body IK solver parity",
-      "runtime retargeting 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

@@ -1,78 +0,0 @@
-import { Bone, type BoneDescriptor } from "./Bone.js";
-import { multiplyMat4, type Mat4, type Vec3 } 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));
-  }
-
-  /** World-space positions (translation component of each bone's world matrix). */
-  boneWorldPositions(): readonly Vec3[] {
-    return this.worldMatrices().map((m) => [m[12]!, m[13]!, m[14]!] as Vec3);
-  }
-
-  /**
-   * Ordered descendant chain from a bone (by name or index), following the first child at each
-   * level. Returns bone indices root-first — the input to {@link createSpringChain} (use the
-   * matching {@link boneWorldPositions} as the rest pose). Members tagged `springChain` are honored;
-   * the walk stops at the first leaf or when a child is no longer part of the chain.
-   */
-  springChainIndices(root: string | number): readonly number[] {
-    const rootIndex = typeof root === "number" ? root : this.bones.findIndex((b) => b.name === root);
-    if (rootIndex < 0 || rootIndex >= this.bones.length) {
-      throw new Error(`Spring chain root ${String(root)} not found in skeleton.`);
-    }
-    const chain: number[] = [rootIndex];
-    let current = rootIndex;
-    for (;;) {
-      const childIndex = this.bones.findIndex((b, i) => i > current && b.parentIndex === current);
-      if (childIndex < 0) break;
-      chain.push(childIndex);
-      current = childIndex;
-    }
-    return chain;
-  }
-
-  /**
-   * Write solved spring-chain world positions back onto the bones as local translations (relative
-   * to each bone's solved parent), so the deformed chain renders. `chainIndices` and `positions`
-   * are root-first and aligned.
-   */
-  writeSpringChainBack(chainIndices: readonly number[], positions: readonly Vec3[]): void {
-    if (chainIndices.length !== positions.length) {
-      throw new Error("Spring chain indices and positions must align.");
-    }
-    for (let i = 1; i < chainIndices.length; i += 1) {
-      const boneIndex = chainIndices[i]!;
-      const parentPos = positions[i - 1]!;
-      const pos = positions[i]!;
-      this.bones[boneIndex]!.translation = [pos[0] - parentPos[0], pos[1] - parentPos[1], pos[2] - parentPos[2]];
-    }
-  }
-}

package/src/Skinning.ts

@@ -1,18 +0,0 @@
-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 };
-}