@aura3d/animation 1.4.0 → 1.4.2

package/src/LocomotionKit.ts

@@ -1,89 +0,0 @@
-import { BlendTree1D, type BlendTreeWeight } from "./BlendTree.js";
-import { createLocomotionAnimationStateGraph } from "./AnimationStateGraph.js";
-import type { AnimationStateBlend, AnimationStateMachine } from "./AnimationStateMachine.js";
-import type { FootIkRig } from "./FootIk.js";
-
-/**
- * Composable locomotion kit: maps a scalar movement speed into a discrete locomotion state
- * (idle/walk/run) plus blended clip weights, using the real `BlendTree1D` and
- * `createLocomotionAnimationStateGraph` primitives. This is the deterministic, browser-free
- * core a `character-controller` template wires to a physics `CharacterController`, input, and
- * an `AnimationController` crossfade.
- */
-export interface LocomotionKitOptions<TClipId extends string = string> {
-  readonly idleClip: TClipId;
-  readonly walkClip: TClipId;
-  readonly runClip: TClipId;
-  /** Speed at which the walk clip reaches full weight (default 1). */
-  readonly walkSpeed?: number;
-  /** Speed at which the run clip reaches full weight (default 4). */
-  readonly runSpeed?: number;
-  /** Speed above which the character is considered moving (default 0.05). */
-  readonly movingThreshold?: number;
-  /** Speed at/above which the character is considered running (default = runSpeed, so state stays coherent with the blend). */
-  readonly runningThreshold?: number;
-  /** Optional foot-IK rig so locomotion can ground feet on uneven terrain (no foot sliding). */
-  readonly footIkRig?: FootIkRig;
-}
-
-export interface LocomotionKitSample<TClipId extends string = string> {
-  readonly speed: number;
-  readonly state: string;
-  readonly moving: boolean;
-  readonly running: boolean;
-  readonly clipWeights: ReadonlyArray<{ readonly clip: TClipId; readonly weight: number }>;
-  /**
-   * Inertialized blend between the previously-active discrete state and the current one. When the
-   * state graph switches (e.g. walk→run), the previous state's clip fades out on a critically-damped
-   * curve instead of snapping — momentum-preserving idle↔walk↔run transitions.
-   */
-  readonly stateTransition: AnimationStateBlend;
-}
-
-export interface LocomotionKit<TClipId extends string = string> {
-  readonly graph: AnimationStateMachine;
-  /** Optional foot-IK rig hook; call `footIk.solveFootPlacement(...)` to ground feet. */
-  readonly footIk: FootIkRig | undefined;
-  /** Blend clip weights for a speed (sum ~= 1), independent of the discrete state graph. */
-  blendWeights(speed: number): ReadonlyArray<BlendTreeWeight<TClipId>>;
-  /** Advance the state graph and produce the full locomotion sample for a speed. */
-  sample(speed: number, delta?: number): LocomotionKitSample<TClipId>;
-}
-
-export function createLocomotionKit<TClipId extends string = string>(options: LocomotionKitOptions<TClipId>): LocomotionKit<TClipId> {
-  const walkSpeed = options.walkSpeed ?? 1;
-  const runSpeed = options.runSpeed ?? 4;
-  const movingThreshold = options.movingThreshold ?? 0.05;
-  const runningThreshold = options.runningThreshold ?? runSpeed;
-
-  const tree = new BlendTree1D<TClipId>([
-    { value: options.idleClip, threshold: 0 },
-    { value: options.walkClip, threshold: walkSpeed },
-    { value: options.runClip, threshold: runSpeed }
-  ]);
-  const graph = createLocomotionAnimationStateGraph();
-
-  return {
-    graph,
-    footIk: options.footIkRig,
-    blendWeights(speed: number) {
-      return tree.weights(Math.max(0, speed));
-    },
-    sample(speed: number, delta = 1 / 30): LocomotionKitSample<TClipId> {
-      const clamped = Math.max(0, speed);
-      const moving = clamped > movingThreshold;
-      const running = clamped >= runningThreshold;
-      graph.setParameter("isMoving", moving);
-      graph.setParameter("isRunning", running);
-      const state = graph.update(delta);
-      return {
-        speed: clamped,
-        state,
-        moving,
-        running,
-        clipWeights: tree.weights(clamped).map((weight) => ({ clip: weight.value, weight: weight.weight })),
-        stateTransition: graph.stateBlend()
-      };
-    }
-  };
-}

package/src/MotionMatchingFixtures.ts

@@ -1,254 +0,0 @@
-import type { Vec3 } from "./Keyframe.js";
-
-export interface MotionMatchingFixtureOptions {
-  readonly currentPosition?: Vec3;
-  readonly moveDirection?: Vec3;
-  readonly facingDirection?: Vec3;
-  readonly speed?: number;
-  readonly elapsedSeconds?: number;
-  readonly previousPoseId?: string;
-  readonly seed?: number;
-}
-
-export interface MotionMatchingTrajectorySample {
-  readonly time: number;
-  readonly position: Vec3;
-  readonly direction: Vec3;
-}
-
-export interface MotionMatchingPoseCandidate {
-  readonly id: string;
-  readonly clip: "idle" | "walk" | "run" | "strafe" | "turn" | "jump";
-  readonly time: number;
-  readonly tags: readonly string[];
-  readonly rootVelocity: Vec3;
-  readonly footLeft: Vec3;
-  readonly footRight: Vec3;
-  readonly trajectory: readonly MotionMatchingTrajectorySample[];
-}
-
-export interface MotionMatchingCandidateScore {
-  readonly poseId: string;
-  readonly clip: MotionMatchingPoseCandidate["clip"];
-  readonly tags: readonly string[];
-  readonly velocityCost: number;
-  readonly facingCost: number;
-  readonly trajectoryCost: number;
-  readonly continuityCost: number;
-  readonly totalCost: number;
-}
-
-export interface MotionMatchingFixtureSample {
-  readonly id: "external-parity-old-branch-motion-matching-fixture";
-  readonly source: "origin-master-motion-matching-system-adapted";
-  readonly databasePoseCount: number;
-  readonly candidateScores: readonly MotionMatchingCandidateScore[];
-  readonly selectedPoseId: string;
-  readonly selectedClip: MotionMatchingPoseCandidate["clip"];
-  readonly selectedTags: readonly string[];
-  readonly selectedTime: number;
-  readonly transitioned: boolean;
-  readonly blendWeight: number;
-  readonly transitionDurationSeconds: number;
-  readonly queryTrajectory: readonly MotionMatchingTrajectorySample[];
-  readonly querySpeed: number;
-  readonly queryFacingAlignment: number;
-  readonly bestCost: number;
-  readonly secondBestCost: number;
-  readonly costMargin: number;
-  readonly hash: string;
-  readonly claimBoundary: string;
-}
-
-const predictionTimes = [0.2, 0.45, 0.75] as const;
-
-export function sampleMotionMatchingFixture(options: MotionMatchingFixtureOptions = {}): MotionMatchingFixtureSample {
-  const seed = options.seed ?? 0x3d2025;
-  if (!Number.isInteger(seed)) throw new RangeError("Motion matching fixture seed must be an integer.");
-  const currentPosition = vec3(options.currentPosition ?? [0, 0, 0], "currentPosition");
-  const moveDirection = normalize(vec3(options.moveDirection ?? [1, 0, 0.18], "moveDirection"));
-  const facingDirection = normalize(vec3(options.facingDirection ?? [1, 0, 0], "facingDirection"));
-  const speed = clamp(finite(options.speed ?? 0.74, "speed"), 0, 1);
-  const elapsedSeconds = Math.max(0, finite(options.elapsedSeconds ?? 0, "elapsedSeconds"));
-  const maxSpeed = 6.2;
-  const queryVelocity = scale(moveDirection, speed * maxSpeed);
-  const queryTrajectory = predictionTimes.map((time) => ({
-    time,
-    position: roundVec3(add(currentPosition, scale(queryVelocity, time))),
-    direction: roundVec3(normalize(lerpVec3(moveDirection, facingDirection, Math.min(1, time * 0.8))))
-  }));
-  const database = createMotionDatabase(seed);
-  const previousPoseId = options.previousPoseId ?? database[0]?.id ?? "idle-0";
-  const scored = database
-    .map((candidate) => scoreCandidate(candidate, queryVelocity, facingDirection, queryTrajectory, previousPoseId))
-    .sort((left, right) => left.totalCost - right.totalCost);
-  const selected = scored[0];
-  if (!selected) throw new Error("Motion matching fixture database is empty.");
-  const selectedPose = database.find((candidate) => candidate.id === selected.poseId);
-  if (!selectedPose) throw new Error("Motion matching fixture selected an unknown pose.");
-  const secondBestCost = scored[1]?.totalCost ?? selected.totalCost;
-  const transitioned = selected.poseId !== previousPoseId;
-  const transitionDurationSeconds = 0.18;
-  const blendWeight = transitioned ? clamp(elapsedSeconds / transitionDurationSeconds, 0, 1) : 1;
-  return {
-    id: "external-parity-old-branch-motion-matching-fixture",
-    source: "origin-master-motion-matching-system-adapted",
-    databasePoseCount: database.length,
-    candidateScores: scored.slice(0, 6),
-    selectedPoseId: selected.poseId,
-    selectedClip: selected.clip,
-    selectedTags: selected.tags,
-    selectedTime: selectedPose.time,
-    transitioned,
-    blendWeight: Number(blendWeight.toFixed(4)),
-    transitionDurationSeconds,
-    queryTrajectory,
-    querySpeed: Number(length(queryVelocity).toFixed(4)),
-    queryFacingAlignment: Number(dot(moveDirection, facingDirection).toFixed(4)),
-    bestCost: selected.totalCost,
-    secondBestCost,
-    costMargin: Number((secondBestCost - selected.totalCost).toFixed(5)),
-    hash: hashMotionFixture(scored, queryTrajectory),
-    claimBoundary: "Deterministic pose-database scoring, trajectory prediction, tag filtering, continuity cost, and transition telemetry adapted from the old motion-matching system; this is bounded runtime evidence, not a full animation database, inertialization, pose application, foot locking, or Unity/Unreal animation middleware parity."
-  };
-}
-
-function createMotionDatabase(seed: number): readonly MotionMatchingPoseCandidate[] {
-  const clips: readonly MotionMatchingPoseCandidate["clip"][] = ["idle", "walk", "run", "strafe", "turn", "jump"];
-  return clips.flatMap((clip, clipIndex) => {
-    const speed = clip === "idle" ? 0 : clip === "walk" ? 2.1 : clip === "run" ? 5.8 : clip === "strafe" ? 3.2 : clip === "turn" ? 0.9 : 3.8;
-    const angle = clip === "strafe" ? Math.PI / 2 : clip === "turn" ? 0.62 : seeded01(seed + clipIndex * 41) * 0.14 - 0.07;
-    const direction: Vec3 = [Math.cos(angle), 0, Math.sin(angle)];
-    return [0, 1, 2].map((poseIndex) => {
-      const time = Number((poseIndex * 0.18 + seeded01(seed + clipIndex * 101 + poseIndex) * 0.04).toFixed(4));
-      const phase = poseIndex / 3;
-      return {
-        id: `${clip}-${poseIndex}`,
-        clip,
-        time,
-        tags: clip === "idle" ? ["idle"] : clip === "jump" ? ["action", "airborne"] : ["locomotion", clip],
-        rootVelocity: roundVec3(scale(direction, speed * (0.92 + phase * 0.12))),
-        footLeft: roundVec3([-0.16, Math.sin(phase * Math.PI * 2) * 0.08, 0.08]),
-        footRight: roundVec3([0.16, Math.sin((phase + 0.5) * Math.PI * 2) * 0.08, -0.08]),
-        trajectory: predictionTimes.map((predictionTime) => ({
-          time: predictionTime,
-          position: roundVec3(scale(direction, speed * predictionTime)),
-          direction: roundVec3(direction)
-        }))
-      };
-    });
-  });
-}
-
-function scoreCandidate(
-  candidate: MotionMatchingPoseCandidate,
-  queryVelocity: Vec3,
-  facingDirection: Vec3,
-  queryTrajectory: readonly MotionMatchingTrajectorySample[],
-  previousPoseId: string
-): MotionMatchingCandidateScore {
-  const velocityCost = distance(candidate.rootVelocity, queryVelocity);
-  const facingCost = 1 - clamp(dot(normalize(candidate.trajectory[0]?.direction ?? [1, 0, 0]), facingDirection), -1, 1);
-  const trajectoryCost = queryTrajectory.reduce((sum, query, index) => {
-    const candidateSample = candidate.trajectory[index] ?? candidate.trajectory[candidate.trajectory.length - 1]!;
-    return sum + distance(candidateSample.position, subtract(query.position, queryTrajectory[0]?.position ?? [0, 0, 0]));
-  }, 0) / Math.max(1, queryTrajectory.length);
-  const continuityCost = candidate.id === previousPoseId ? 0 : candidate.clip === previousPoseId.split("-")[0] ? 0.12 : 0.34;
-  const totalCost = velocityCost * 0.46 + facingCost * 1.2 + trajectoryCost * 0.38 + continuityCost;
-  return {
-    poseId: candidate.id,
-    clip: candidate.clip,
-    tags: candidate.tags,
-    velocityCost: Number(velocityCost.toFixed(5)),
-    facingCost: Number(facingCost.toFixed(5)),
-    trajectoryCost: Number(trajectoryCost.toFixed(5)),
-    continuityCost: Number(continuityCost.toFixed(5)),
-    totalCost: Number(totalCost.toFixed(5))
-  };
-}
-
-function hashMotionFixture(scores: readonly MotionMatchingCandidateScore[], trajectory: readonly MotionMatchingTrajectorySample[]): string {
-  let hash = 0x811c9dc5;
-  for (const score of scores) {
-    for (const char of `${score.poseId}:${score.totalCost}:${score.velocityCost}`) {
-      hash ^= char.charCodeAt(0);
-      hash = Math.imul(hash, 0x01000193) >>> 0;
-    }
-  }
-  for (const sample of trajectory) {
-    for (const value of [sample.time, ...sample.position, ...sample.direction]) {
-      const scaled = Math.round(value * 10_000);
-      hash ^= scaled & 0xff;
-      hash = Math.imul(hash, 0x01000193) >>> 0;
-      hash ^= (scaled >>> 8) & 0xff;
-      hash = Math.imul(hash, 0x01000193) >>> 0;
-    }
-  }
-  return hash.toString(16).padStart(8, "0");
-}
-
-function vec3(value: readonly number[], label: string): Vec3 {
-  if (value.length !== 3 || value.some((entry) => !Number.isFinite(entry))) {
-    throw new RangeError(`Motion matching fixture ${label} must contain three finite numbers.`);
-  }
-  return [value[0]!, value[1]!, value[2]!];
-}
-
-function roundVec3(value: Vec3): Vec3 {
-  return [Number(value[0].toFixed(4)), Number(value[1].toFixed(4)), Number(value[2].toFixed(4))];
-}
-
-function add(left: Vec3, right: Vec3): Vec3 {
-  return [left[0] + right[0], left[1] + right[1], left[2] + right[2]];
-}
-
-function subtract(left: Vec3, right: Vec3): Vec3 {
-  return [left[0] - right[0], left[1] - right[1], left[2] - right[2]];
-}
-
-function scale(value: Vec3, scalar: number): Vec3 {
-  return [value[0] * scalar, value[1] * scalar, value[2] * scalar];
-}
-
-function lerpVec3(left: Vec3, right: Vec3, weight: number): Vec3 {
-  return [
-    left[0] + (right[0] - left[0]) * weight,
-    left[1] + (right[1] - left[1]) * weight,
-    left[2] + (right[2] - left[2]) * weight
-  ];
-}
-
-function dot(left: Vec3, right: Vec3): number {
-  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
-}
-
-function length(value: Vec3): number {
-  return Math.hypot(value[0], value[1], value[2]);
-}
-
-function distance(left: Vec3, right: Vec3): number {
-  return length(subtract(left, right));
-}
-
-function normalize(value: Vec3): Vec3 {
-  const valueLength = length(value);
-  if (valueLength <= 1e-6) return [1, 0, 0];
-  return scale(value, 1 / valueLength);
-}
-
-function finite(value: number, label: string): number {
-  if (!Number.isFinite(value)) throw new RangeError(`Motion matching fixture ${label} must be finite.`);
-  return value;
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(max, value));
-}
-
-function seeded01(seed: number): number {
-  let value = seed >>> 0;
-  value ^= value << 13;
-  value ^= value >>> 17;
-  value ^= value << 5;
-  return ((value >>> 0) % 10_000) / 10_000;
-}

package/src/MotionQuality.ts

@@ -1,182 +0,0 @@
-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 AnimationAnimationMotionQualityReport extends AnimationMotionQualityReport {
-  readonly kind: "animation-animation-motion-quality";
-  readonly staticPoseRejected: boolean;
-  readonly issues: readonly string[];
-}
-
-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)
-  };
-}
-
-export function summarizeAnimationAnimationMotion(
-  samples: readonly AnimationMotionSample[],
-  options: Pick<AnimationMotionQualityOptions, "minimumSamples" | "minimumTimeRangeSeconds" | "minimumPoseDiversityScore"> = {}
-): AnimationAnimationMotionQualityReport {
-  const base = summarizeAnimationMotion(samples, options);
-  const issues = [
-    base.sampleCount < (options.minimumSamples ?? 8) ? "not enough motion samples" : undefined,
-    base.timeRangeSeconds < (options.minimumTimeRangeSeconds ?? 0.18) ? "motion time range is too short" : undefined,
-    base.poseDiversityScore < (options.minimumPoseDiversityScore ?? 0.08) ? "pose diversity is too low" : undefined,
-    base.activeTrackFrames === 0 && base.activeSkinningFrames === 0 && base.animatedSubjectFrames === 0 ? "no active track, skinning, or subject motion" : undefined
-  ].filter((issue): issue is string => Boolean(issue));
-  return {
-    ...base,
-    kind: "animation-animation-motion-quality",
-    staticPoseRejected: issues.length > 0,
-    issues,
-    healthy: issues.length === 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/RigQuality.ts

@@ -1,101 +0,0 @@
-import {
-  HUMANOID_BONES,
-  type HumanoidBoneName,
-  type HumanoidRigDefinition
-} from "./HumanoidRetargeting.js";
-
-/**
- * Body-acting suitability grade for an (inferred) humanoid rig.
- *
- * - **A** — full humanoid: spine/neck/head, both arms with forearms + hands, both legs with lower
- *   legs + feet. Safe for the full performance vocabulary (gesture, point, walk/run, foot work).
- * - **B** — partial humanoid: enough of the body to act (spine/head + both arms or both legs) but
- *   missing limbs/extremities; the director should avoid the motions that need the missing chain.
- * - **C** — mascot / sparse (~8 mappable nodes): a torso + head + stub arms; head/torso acting only,
- *   no real limb motion.
- * - **D** — not suitable for body acting: no usable skeleton (root/props only).
- */
-export type RigGrade = "A" | "B" | "C" | "D";
-
-export interface RigQualityReport {
-  readonly grade: RigGrade;
-  /** Human-readable justifications for the grade (what was present / missing). */
-  readonly reasons: string[];
-  readonly hasLegs: boolean;
-  readonly hasKnees: boolean;
-  readonly hasAnkles: boolean;
-  readonly hasFeet: boolean;
-  /** Count of canonical humanoid bones that resolve to a real node. */
-  readonly mappedBoneCount: number;
-}
-
-/** A bone counts as mapped when it resolves to a non-empty target node name. */
-function isMapped(rig: HumanoidRigDefinition, bone: HumanoidBoneName): boolean {
-  const binding = rig.bones[bone];
-  return Boolean(binding && typeof binding.name === "string" && binding.name.length > 0);
-}
-
-/**
- * Grade a rig for body-acting suitability. Pure + deterministic — driven only by which canonical
- * {@link HUMANOID_BONES} resolve to nodes, so it works on the output of `inferHumanoidRig` for any
- * skeleton naming convention (Mixamo / Blender / UE / sparse mascot / rich humanoid).
- */
-export function gradeRig(rig: HumanoidRigDefinition): RigQualityReport {
-  const has = (bone: HumanoidBoneName): boolean => isMapped(rig, bone);
-  const mappedBoneCount = HUMANOID_BONES.reduce((n, bone) => (has(bone) ? n + 1 : n), 0);
-
-  // Limb-chain capability (mirrors FootIk's notion of a usable leg chain).
-  const hasLegs = (has("leftUpperLeg") || has("leftLowerLeg")) && (has("rightUpperLeg") || has("rightLowerLeg"));
-  const hasKnees = has("leftLowerLeg") && has("rightLowerLeg");
-  const hasAnkles = has("leftFoot") && has("rightFoot");
-  const hasFeet = hasAnkles; // foot node == ankle/foot joint in the canonical skeleton.
-
-  // Spine / head axis.
-  const hasSpine = has("spine") || has("chest") || has("upperChest");
-  const hasHead = has("head");
-  const hasNeck = has("neck");
-
-  // Arm chains.
-  const hasBothUpperArms = has("leftUpperArm") && has("rightUpperArm");
-  const hasBothForearms = has("leftLowerArm") && has("rightLowerArm");
-  const hasBothHands = has("leftHand") && has("rightHand");
-  const hasBothLowerLegs = has("leftLowerLeg") && has("rightLowerLeg");
-
-  const reasons: string[] = [];
-  reasons.push(`${mappedBoneCount} of ${HUMANOID_BONES.length} canonical humanoid bones mapped`);
-
-  // --- D: no usable skeleton --------------------------------------------------------------------
-  // Without a spine/head axis OR both upper arms there is nothing to act with.
-  if (mappedBoneCount < 5 || (!hasSpine && !hasHead) || (!hasBothUpperArms && !hasLegs)) {
-    reasons.push("not enough body structure to drive body acting (D)");
-    if (!hasSpine && !hasHead) reasons.push("missing spine/head axis");
-    if (!hasBothUpperArms) reasons.push("missing a pair of upper arms");
-    if (!hasLegs) reasons.push("missing a usable pair of legs");
-    return { grade: "D", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
-  }
-
-  // --- A: full humanoid -------------------------------------------------------------------------
-  const fullUpperBody = hasSpine && hasNeck && hasHead && hasBothUpperArms && hasBothForearms && hasBothHands;
-  const fullLowerBody = hasLegs && hasBothLowerLegs && hasFeet;
-  if (mappedBoneCount >= 18 && fullUpperBody && fullLowerBody) {
-    reasons.push("full humanoid: spine/neck/head + both arms (forearms+hands) + both legs (lower legs+feet) (A)");
-    return { grade: "A", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
-  }
-
-  // --- B: partial humanoid ----------------------------------------------------------------------
-  // Enough body to act: a spine/head axis plus at least a full pair of arms OR a full pair of legs.
-  const usableArms = hasBothUpperArms && hasBothForearms;
-  const usableLegs = hasLegs && hasBothLowerLegs;
-  if ((hasSpine || hasHead) && (usableArms || usableLegs) && mappedBoneCount >= 10) {
-    reasons.push("partial humanoid: body acting possible but a limb chain or extremities are missing (B)");
-    if (!fullUpperBody) reasons.push("incomplete upper body (forearms/hands/neck)");
-    if (!fullLowerBody) reasons.push("incomplete lower body (lower legs/feet)");
-    return { grade: "B", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
-  }
-
-  // --- C: mascot / sparse -----------------------------------------------------------------------
-  reasons.push("mascot/sparse rig: head + torso acting only, no real limb chains (C)");
-  if (!usableArms) reasons.push("no usable forearm chain on both arms");
-  if (!usableLegs) reasons.push("no usable lower-leg chain on both legs");
-  return { grade: "C", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
-}