@aura3d/animation 1.0.6 → 1.3.0

package/src/FootIk.ts

@@ -0,0 +1,251 @@
+// Runtime foot IK + foot-lock, built on the existing two-bone solver (`solveTwoBoneIk`) plus a
+// ground query (a downward ray). This is "wire up what we already have" — no new solver. It removes
+// foot sliding (foot-lock holds a planted foot in world space during stance and releases it on
+// lift) and grounds characters on uneven terrain (each ankle is pulled to the ground height under
+// it, the hip drops so the lower foot can reach).
+//
+// The animation package stays dependency-free of @aura3d/physics: callers inject a `GroundRaycaster`
+// (the physics package's `groundHeightRaycaster` adapter satisfies this interface, or use the
+// analytic `createHeightFieldGround` here). Pure and deterministic: given the same pose stream and
+// ground, the solved feet and lock state are identical every run.
+
+import { solveTwoBoneIk, type TwoBoneIkResult } from "./IK.js";
+import type { Vec3 } from "./Keyframe.js";
+// `FootIkSample` is the single source-of-truth data shape, defined in (and exported from)
+// SecondaryAnimationFixtures; the runtime here produces that exact shape.
+import type { FootIkSample } from "./SecondaryAnimationFixtures.js";
+
+/** Result of a downward ground query: where the ground is and its surface normal. */
+export interface GroundSample {
+  readonly point: Vec3;
+  readonly normal: Vec3;
+  readonly distance: number;
+}
+
+/** Minimal ground query the rig needs: cast a downward ray and report the first ground hit. */
+export interface GroundRaycaster {
+  raycastDown(origin: Vec3, maxDistance: number): GroundSample | undefined;
+}
+
+/**
+ * Analytic ground query from a height function — deterministic and physics-free, ideal for tests
+ * and procedural terrain. `heightAt` returns the ground height (and optional normal) at an (x, z).
+ */
+export function createHeightFieldGround(heightAt: (x: number, z: number) => { height: number; normal?: Vec3 }): GroundRaycaster {
+  return {
+    raycastDown(origin: Vec3, maxDistance: number): GroundSample | undefined {
+      const { height, normal } = heightAt(origin[0], origin[2]);
+      const distance = origin[1] - height;
+      if (distance < 0 || distance > maxDistance) return undefined;
+      return { point: [origin[0], height, origin[2]], normal: normal ?? [0, 1, 0], distance };
+    }
+  };
+}
+
+/** One leg: the hip (root), knee (mid), ankle (end), and an optional pole/knee hint. */
+export interface FootLegInput {
+  readonly side: "left" | "right";
+  readonly hip: Vec3;
+  readonly knee: Vec3;
+  readonly ankle: Vec3;
+  readonly pole?: Vec3;
+}
+
+export interface FootIkRigOptions {
+  readonly legs: readonly FootLegInput[];
+  readonly raycaster: GroundRaycaster;
+  /** Height the ankle joint sits above the ground contact point (default 0.035). */
+  readonly ankleHeight?: number;
+  /** How far above the ankle to start the downward ray (default 0.6). */
+  readonly rayStartHeight?: number;
+  /** Max ray distance (default 2). */
+  readonly maxRayDistance?: number;
+  /** Foot is in stance (locks) when its height above the ground target is ≤ this (default 0.02). */
+  readonly plantThreshold?: number;
+  /** Hip-drop factor applied to the deepest required correction (default 0.72, matches fixture). */
+  readonly hipDropFactor?: number;
+}
+
+export interface SolvedLeg {
+  readonly side: "left" | "right";
+  readonly sample: FootIkSample;
+  /** Solved joint chain (write these back onto the skeleton). */
+  readonly hip: Vec3;
+  readonly knee: Vec3;
+  readonly ankle: Vec3;
+  /** True while the foot is locked to a world position (stance). */
+  readonly locked: boolean;
+  readonly reached: boolean;
+}
+
+export interface FootIkSolveResult {
+  readonly feet: readonly SolvedLeg[];
+  /** Vertical hip offset (≤ 0) so the lower planted foot can reach the ground. */
+  readonly hipOffset: number;
+  readonly groundedFeet: number;
+  readonly averageTargetError: number;
+}
+
+interface LegLockState {
+  locked: boolean;
+  lockedPosition: Vec3;
+}
+
+export interface FootIkRig {
+  /**
+   * Solve foot placement for the current pose. Pass updated leg transforms (e.g. sampled from the
+   * animation) via `pose.legs`, or omit to reuse the legs the rig was created with. Optionally
+   * override the ground query for this frame.
+   */
+  solveFootPlacement(pose?: { legs?: readonly FootLegInput[] }, groundQuery?: GroundRaycaster): FootIkSolveResult;
+  /** Whether a given side is currently foot-locked. */
+  isLocked(side: "left" | "right"): boolean;
+  /** Clear all foot-lock state (e.g. on teleport / respawn). */
+  reset(): void;
+}
+
+/** Create a foot-IK rig. Foot-lock state persists across `solveFootPlacement` calls. */
+export function createFootIkRig(options: FootIkRigOptions): FootIkRig {
+  const ankleHeight = options.ankleHeight ?? 0.035;
+  const rayStartHeight = options.rayStartHeight ?? 0.6;
+  const maxRayDistance = options.maxRayDistance ?? 2;
+  const plantThreshold = options.plantThreshold ?? 0.02;
+  const hipDropFactor = options.hipDropFactor ?? 0.72;
+  let legs = options.legs;
+  const locks = new Map<"left" | "right", LegLockState>();
+
+  function lockFor(side: "left" | "right"): LegLockState {
+    let state = locks.get(side);
+    if (!state) {
+      state = { locked: false, lockedPosition: [0, 0, 0] };
+      locks.set(side, state);
+    }
+    return state;
+  }
+
+  return {
+    solveFootPlacement(pose, groundQuery) {
+      const raycaster = groundQuery ?? options.raycaster;
+      if (pose?.legs) legs = pose.legs;
+      const solved: SolvedLeg[] = [];
+      let deepestCorrection = 0;
+      for (const leg of legs) {
+        const lock = lockFor(leg.side);
+        const result = solveLeg(leg, lock, raycaster, { ankleHeight, rayStartHeight, maxRayDistance, plantThreshold });
+        solved.push(result);
+        deepestCorrection = Math.max(deepestCorrection, Math.max(0, result.sample.verticalCorrection));
+      }
+      const hipOffset = round(-deepestCorrection * hipDropFactor);
+      const groundedFeet = solved.filter((leg) => leg.sample.grounded).length;
+      const averageTargetError = solved.length === 0
+        ? 0
+        : round(solved.reduce((sum, leg) => sum + leg.sample.targetError, 0) / solved.length);
+      return { feet: solved, hipOffset, groundedFeet, averageTargetError };
+    },
+    isLocked(side) {
+      return locks.get(side)?.locked ?? false;
+    },
+    reset() {
+      locks.clear();
+    }
+  };
+}
+
+interface SolveParams {
+  readonly ankleHeight: number;
+  readonly rayStartHeight: number;
+  readonly maxRayDistance: number;
+  readonly plantThreshold: number;
+}
+
+function solveLeg(leg: FootLegInput, lock: LegLockState, raycaster: GroundRaycaster, params: SolveParams): SolvedLeg {
+  const sourceAnkle = leg.ankle;
+  const ground = raycaster.raycastDown(
+    [sourceAnkle[0], sourceAnkle[1] + params.rayStartHeight, sourceAnkle[2]],
+    params.rayStartHeight + params.maxRayDistance
+  );
+
+  if (!ground) {
+    // No ground under the foot (airborne / off the edge): release the lock and pass the pose through.
+    lock.locked = false;
+    return {
+      side: leg.side,
+      sample: {
+        side: leg.side,
+        sourceFoot: sourceAnkle,
+        plantedFoot: sourceAnkle,
+        groundNormal: [0, 1, 0],
+        grounded: false,
+        verticalCorrection: 0,
+        targetError: 0
+      },
+      hip: leg.hip,
+      knee: leg.knee,
+      ankle: sourceAnkle,
+      locked: false,
+      reached: true
+    };
+  }
+
+  const groundTargetY = ground.point[1] + params.ankleHeight;
+  const heightAboveGround = sourceAnkle[1] - groundTargetY;
+  const inStance = heightAboveGround <= params.plantThreshold;
+
+  let target: Vec3;
+  if (inStance) {
+    if (!lock.locked) {
+      // Just entered stance: plant the foot at the ground point under it.
+      lock.locked = true;
+      lock.lockedPosition = [sourceAnkle[0], groundTargetY, sourceAnkle[2]];
+    }
+    // Hold the locked world position so the foot does not slide while it should be stationary.
+    target = lock.lockedPosition;
+  } else {
+    // Swing phase: release the lock; the foot follows above the ground under it.
+    lock.locked = false;
+    target = [sourceAnkle[0], Math.max(sourceAnkle[1], groundTargetY), sourceAnkle[2]];
+  }
+
+  // Blend IK in fully during stance, fade out across the swing so the leg returns to the clip pose.
+  const weight = inStance ? 1 : clamp(1 - heightAboveGround / 0.25, 0, 1);
+  const solved: TwoBoneIkResult = solveTwoBoneIk({
+    root: leg.hip,
+    mid: leg.knee,
+    end: leg.ankle,
+    target,
+    pole: leg.pole,
+    weight
+  });
+
+  const verticalCorrection = round(sourceAnkle[1] - target[1]);
+  const targetError = round(solved.endDistanceToTarget);
+  return {
+    side: leg.side,
+    sample: {
+      side: leg.side,
+      sourceFoot: roundVec(sourceAnkle),
+      plantedFoot: roundVec(target),
+      groundNormal: roundVec(ground.normal),
+      grounded: inStance,
+      verticalCorrection,
+      targetError
+    },
+    hip: leg.hip,
+    knee: roundVec(solved.mid),
+    ankle: roundVec(solved.end),
+    locked: lock.locked,
+    reached: solved.reached
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(4));
+}
+
+function roundVec(value: Vec3): Vec3 {
+  return [round(value[0]), round(value[1]), round(value[2])];
+}

package/src/HumanoidBoneInference.ts

@@ -0,0 +1,323 @@
+import {
+  HUMANOID_BONES,
+  REQUIRED_HUMANOID_BONES,
+  type HumanoidBoneBinding,
+  type HumanoidBoneName,
+  type HumanoidRigDefinition
+} from "./HumanoidRetargeting.js";
+
+/**
+ * Options for {@link inferHumanoidRig}. All optional — sensible defaults match the
+ * conventions found across the free GLB/glTF catalog (Mixamo, Sketchfab/Blender, UE-ish).
+ */
+export interface InferHumanoidRigOptions {
+  /** Id assigned to the produced {@link HumanoidRigDefinition}. Defaults to `"inferred-humanoid"`. */
+  readonly id?: string;
+  /** Human-readable rig name copied onto the definition. */
+  readonly name?: string;
+  /**
+   * Extra alias entries merged on top of the built-in table. Use this for one-off rigs whose
+   * node names don't follow any common convention. Keys are {@link HumanoidBoneName}s; values are
+   * additional name fragments (compared case-insensitively after normalization).
+   */
+  readonly extraAliases?: Partial<Record<HumanoidBoneName, readonly string[]>>;
+  /** Forwarded onto the resulting rig definition. */
+  readonly units?: HumanoidRigDefinition["units"];
+  /** Forwarded onto the resulting rig definition. */
+  readonly facingAxis?: HumanoidRigDefinition["facingAxis"];
+  /** Forwarded onto the resulting rig definition. */
+  readonly scale?: number;
+}
+
+/**
+ * Detail about a single resolved (or unresolved) humanoid slot — exposed via
+ * {@link HumanoidRigInference.matches} so callers can debug ambiguous skeletons.
+ */
+export interface HumanoidBoneMatch {
+  readonly bone: HumanoidBoneName;
+  /** Resolved source node name, when one was found. */
+  readonly node?: string;
+  /** Score of the winning candidate (higher is a more confident match). */
+  readonly score: number;
+  /** Every node name that the alias table considered a plausible candidate for this slot. */
+  readonly candidates: readonly string[];
+}
+
+export interface HumanoidRigInference {
+  readonly rig: HumanoidRigDefinition;
+  readonly matches: readonly HumanoidBoneMatch[];
+  /** Required bones (see {@link REQUIRED_HUMANOID_BONES}) that could not be mapped. */
+  readonly missingRequired: readonly HumanoidBoneName[];
+}
+
+type Side = "left" | "right" | null;
+
+/**
+ * Per-logical-group "core" tokens. These are matched against normalized node names. Side-bearing
+ * groups omit the side here — sidedness is detected separately (`L_`, `Left`, `_l`, `.R`, etc.) so
+ * a single table serves both sides. Keys are *logical groups* (`shoulder`, `upperArm`, …), not
+ * {@link HumanoidBoneName}s; the side-resolved slots are derived below in {@link SLOT_SPECS}.
+ */
+const ALIAS_BY_KEY: Record<string, readonly string[]> = {
+  hips: ["hips", "hip", "pelvis", "root", "cog", "bip01pelvis"],
+  spine: ["spine", "spine0", "spine00", "spine1", "spine01", "abdomen", "lowerback", "torso"],
+  chest: ["chest", "spine2", "spine02", "spine3", "ribcage", "upperback"],
+  upperChest: ["upperchest", "spine3", "spine03", "spine4", "upperchestspine"],
+  neck: ["neck", "neck0", "neck01", "neck1"],
+  head: ["head"],
+  shoulder: ["shoulder", "clavicle", "collar", "scapula"],
+  upperArm: ["upperarm", "armupper", "arm", "uparm", "shoulderarm", "humerus", "armupper01"],
+  lowerArm: ["lowerarm", "armlower", "forearm", "loarm", "elbow", "ulna", "armlower01"],
+  hand: ["hand", "wrist", "palm"],
+  upperLeg: ["upperleg", "legupper", "thigh", "upleg", "legupper01", "femur"],
+  lowerLeg: ["lowerleg", "leglower", "calf", "shin", "leg", "loleg", "knee", "leglower01", "tibia"],
+  foot: ["foot", "ankle"],
+  toes: ["toe", "toes", "toebase", "ball"]
+};
+
+/** Logical (side-stripped) classification for each humanoid slot. */
+interface SlotSpec {
+  readonly bone: HumanoidBoneName;
+  readonly aliasKey: string;
+  readonly side: Side;
+  /** Bones that are required for a usable rig (used to compute `missingRequired`). */
+  readonly required: boolean;
+}
+
+const REQUIRED_SET = new Set<HumanoidBoneName>(REQUIRED_HUMANOID_BONES);
+
+const SLOT_SPECS: readonly SlotSpec[] = ([
+  { bone: "hips", aliasKey: "hips", side: null },
+  { bone: "spine", aliasKey: "spine", side: null },
+  { bone: "chest", aliasKey: "chest", side: null },
+  { bone: "upperChest", aliasKey: "upperChest", side: null },
+  { bone: "neck", aliasKey: "neck", side: null },
+  { bone: "head", aliasKey: "head", side: null },
+  { bone: "leftShoulder", aliasKey: "shoulder", side: "left" },
+  { bone: "leftUpperArm", aliasKey: "upperArm", side: "left" },
+  { bone: "leftLowerArm", aliasKey: "lowerArm", side: "left" },
+  { bone: "leftHand", aliasKey: "hand", side: "left" },
+  { bone: "rightShoulder", aliasKey: "shoulder", side: "right" },
+  { bone: "rightUpperArm", aliasKey: "upperArm", side: "right" },
+  { bone: "rightLowerArm", aliasKey: "lowerArm", side: "right" },
+  { bone: "rightHand", aliasKey: "hand", side: "right" },
+  { bone: "leftUpperLeg", aliasKey: "upperLeg", side: "left" },
+  { bone: "leftLowerLeg", aliasKey: "lowerLeg", side: "left" },
+  { bone: "leftFoot", aliasKey: "foot", side: "left" },
+  { bone: "leftToes", aliasKey: "toes", side: "left" },
+  { bone: "rightUpperLeg", aliasKey: "upperLeg", side: "right" },
+  { bone: "rightLowerLeg", aliasKey: "lowerLeg", side: "right" },
+  { bone: "rightFoot", aliasKey: "foot", side: "right" },
+  { bone: "rightToes", aliasKey: "toes", side: "right" }
+] as ReadonlyArray<{ bone: HumanoidBoneName; aliasKey: string; side: Side }>).map(
+  (spec): SlotSpec => ({ ...spec, required: REQUIRED_SET.has(spec.bone) })
+);
+
+interface NormalizedNode {
+  readonly raw: string;
+  /** Lowercased, namespace-stripped (`mixamorig:`), separator-collapsed. */
+  readonly canon: string;
+  /** Side detected from prefixes/suffixes/tokens. */
+  readonly side: Side;
+}
+
+const NAMESPACE_RE = /^(?:mixamorig\d*:|mixamorig\d*|bip\d*\s*|biped\s*|armature[|:_]?)/i;
+
+function stripNamespace(name: string): string {
+  let out = name;
+  // Blender/glTF skinned hierarchies often prefix `Armature|` or `Armature/`.
+  out = out.replace(/^armature[|/]/i, "");
+  out = out.replace(NAMESPACE_RE, "");
+  return out;
+}
+
+/** Collapse to alphanumerics only, lowercased — `L_Arm_Upper.01` -> `larmupper01`. */
+function canonicalize(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function detectSide(raw: string): Side {
+  const lower = raw.toLowerCase();
+  // Explicit word boundaries first (left/right) — these are unambiguous.
+  if (/(^|[^a-z])left([^a-z]|$)|leftarm|leftleg|lefthand|leftfoot|leftshoulder|leftupleg/.test(lower)) return "left";
+  if (/(^|[^a-z])right([^a-z]|$)|rightarm|rightleg|righthand|rightfoot|rightshoulder|rightupleg/.test(lower)) return "right";
+  // Side prefixes: L_, R_, l., r.  and suffixes: _l, _r, .l, .r, _L, name ends in L/R
+  if (/(^|[^a-z])l[_.\- ]/.test(lower) || /[_.\- ]l($|[^a-z])/.test(lower)) return "left";
+  if (/(^|[^a-z])r[_.\- ]/.test(lower) || /[_.\- ]r($|[^a-z])/.test(lower)) return "right";
+  // Leading single side letter directly glued to a part: "LShoulder", "RArm", "L_Leg".
+  if (/^l(?=[a-z0-9])/.test(lower) && !/^le(?!ft)/.test(lower) && !/^lo/.test(lower) && !/^la(?!rm)/.test(lower)) {
+    // crude: only treat leading "l" as side when followed by a known limb-ish token.
+    if (/^l(shoulder|arm|upperarm|lowerarm|forearm|hand|wrist|leg|upperleg|lowerleg|thigh|calf|shin|foot|ankle|toe|clav|coll)/.test(lower)) {
+      return "left";
+    }
+  }
+  if (/^r(?=[a-z0-9])/.test(lower)) {
+    if (/^r(shoulder|arm|upperarm|lowerarm|forearm|hand|wrist|leg|upperleg|lowerleg|thigh|calf|shin|foot|ankle|toe|clav|coll)/.test(lower)) {
+      return "right";
+    }
+  }
+  return null;
+}
+
+function normalizeNode(raw: string): NormalizedNode {
+  const stripped = stripNamespace(raw);
+  return {
+    raw,
+    canon: canonicalize(stripped),
+    side: detectSide(stripped) ?? detectSide(raw)
+  };
+}
+
+/**
+ * Score how well `node` fits `aliasKey`. Returns 0 for no match. Higher = better.
+ * The score rewards: exact-token equality, longer alias fragments (more specific), and earlier
+ * occurrence in the name. This lets `spine2`/`chest` win the chest slot over a generic `spine`.
+ */
+function scoreCandidate(node: NormalizedNode, aliasKey: string, aliases: readonly string[]): number {
+  let best = 0;
+  for (const alias of aliases) {
+    const a = canonicalize(alias);
+    if (a.length === 0) continue;
+    const idx = node.canon.indexOf(a);
+    if (idx < 0) continue;
+    // Base: specificity by alias length.
+    let score = 10 + a.length * 2;
+    // Exact match (whole canon equals alias) is the strongest signal.
+    if (node.canon === a) score += 40;
+    // Side bones: a side-stripped exact-ish match where the remainder is only side tokens.
+    const remainder = node.canon.replace(a, "");
+    if (remainder.length <= 2) score += 15;
+    // Prefer matches that appear toward the end (the "leaf" semantic token) for limb parts,
+    // but prefer earlier for spine/hips where the root token leads.
+    score += Math.max(0, 6 - idx);
+    if (score > best) best = score;
+  }
+  // De-emphasize generic "spine" matching when the name clearly carries a chest/upperchest digit.
+  if (aliasKey === "spine" && /(spine[2-9]|spine0[2-9])/.test(node.canon)) {
+    best = Math.max(0, best - 12);
+  }
+  return best;
+}
+
+/**
+ * Infer a {@link HumanoidRigDefinition} from a flat list of skeleton node names.
+ *
+ * Strategy: each humanoid slot has a side-agnostic alias table plus an L/R/Left/Right side tag.
+ * For every slot we score all candidate nodes (filtered by detected side when the slot is sided),
+ * pick the highest-scoring one, and forbid reusing a node across slots. Conventions covered:
+ * Mixamo (`mixamorig:Hips`/`LeftArm`), Sketchfab/Blender (`Hip_00`, `Spine1..3`, `L_Shoulder`,
+ * `L_Arm_Upper_01`, `L_Leg_Upper_01`, `L_Hand`, `L_Foot`), and UE-ish (`pelvis`, `upperarm_l`,
+ * `thigh_r`, `calf_l`).
+ *
+ * Each produced {@link HumanoidBoneBinding} carries `name` (the resolved node) and `aliases`
+ * (the other plausible candidates for that slot), wiring the previously-unread `aliases` field.
+ */
+export function inferHumanoidRigDetailed(
+  nodeNames: readonly string[],
+  options: InferHumanoidRigOptions = {}
+): HumanoidRigInference {
+  const nodes = nodeNames.map(normalizeNode);
+  const used = new Set<string>();
+  const bones: Partial<Record<HumanoidBoneName, HumanoidBoneBinding>> = {};
+  const matches: HumanoidBoneMatch[] = [];
+
+  // Process required + more-specific slots first so generic "spine"/"leg" don't steal nodes that a
+  // more specific slot (chest/upperChest/lowerLeg) wants. We sort by a static priority.
+  const ordered = [...SLOT_SPECS].sort((a, b) => slotPriority(a.bone) - slotPriority(b.bone));
+
+  for (const spec of ordered) {
+    const aliasList = mergeAliases(spec, options.extraAliases);
+    const candidates: { node: NormalizedNode; score: number }[] = [];
+
+    for (const node of nodes) {
+      if (used.has(node.raw)) continue;
+      if (spec.side && node.side && node.side !== spec.side) continue;
+      // For sided slots, skip nodes with no detectable side only if a sided alternative exists.
+      const score = scoreCandidate(node, spec.aliasKey, aliasList);
+      if (score <= 0) continue;
+      // Penalize sided slot matching a side-less node (ambiguous).
+      const adjusted = spec.side && !node.side ? score - 8 : score;
+      if (adjusted <= 0) continue;
+      candidates.push({ node, score: adjusted });
+    }
+
+    candidates.sort((a, b) => b.score - a.score);
+    const winner = candidates[0];
+    const candidateNames = candidates.map((c) => c.node.raw);
+
+    if (winner) {
+      used.add(winner.node.raw);
+      bones[spec.bone] = {
+        name: winner.node.raw,
+        aliases: candidateNames.slice(1)
+      };
+      matches.push({ bone: spec.bone, node: winner.node.raw, score: winner.score, candidates: candidateNames });
+    } else {
+      matches.push({ bone: spec.bone, score: 0, candidates: [] });
+    }
+  }
+
+  const missingRequired = REQUIRED_HUMANOID_BONES.filter((bone) => !bones[bone]);
+
+  const rig: HumanoidRigDefinition = {
+    id: options.id ?? "inferred-humanoid",
+    ...(options.name !== undefined ? { name: options.name } : {}),
+    bones,
+    ...(options.scale !== undefined ? { scale: options.scale } : {}),
+    ...(options.units !== undefined ? { units: options.units } : {}),
+    ...(options.facingAxis !== undefined ? { facingAxis: options.facingAxis } : {}),
+    metadata: { inferred: true, inferredFromNodeCount: nodeNames.length }
+  };
+
+  return { rig, matches, missingRequired };
+}
+
+/** Convenience wrapper returning just the rig definition. */
+export function inferHumanoidRig(
+  nodeNames: readonly string[],
+  options: InferHumanoidRigOptions = {}
+): HumanoidRigDefinition {
+  return inferHumanoidRigDetailed(nodeNames, options).rig;
+}
+
+function mergeAliases(spec: SlotSpec, extra?: Partial<Record<HumanoidBoneName, readonly string[]>>): readonly string[] {
+  const base = ALIAS_BY_KEY[spec.aliasKey] ?? [];
+  const extraForBone = extra?.[spec.bone] ?? [];
+  return extraForBone.length > 0 ? [...extraForBone, ...base] : base;
+}
+
+/**
+ * Lower number = resolved earlier. More-specific slots resolve first so they claim their nodes
+ * before generic siblings (e.g. `chest` before `spine`, `lowerLeg` before `upperLeg` before the
+ * generic `leg` token shared by both).
+ */
+function slotPriority(bone: HumanoidBoneName): number {
+  const table: Partial<Record<HumanoidBoneName, number>> = {
+    hips: 0,
+    head: 1,
+    upperChest: 2,
+    chest: 3,
+    neck: 4,
+    leftHand: 5,
+    rightHand: 5,
+    leftFoot: 6,
+    rightFoot: 6,
+    leftToes: 7,
+    rightToes: 7,
+    leftShoulder: 8,
+    rightShoulder: 8,
+    leftLowerArm: 9,
+    rightLowerArm: 9,
+    leftUpperArm: 10,
+    rightUpperArm: 10,
+    leftLowerLeg: 11,
+    rightLowerLeg: 11,
+    leftUpperLeg: 12,
+    rightUpperLeg: 12,
+    spine: 13
+  };
+  return table[bone] ?? 20;
+}
+
+/** Re-exported for callers wanting to enumerate which slots inference targets. */
+export const INFERABLE_HUMANOID_BONES: readonly HumanoidBoneName[] = HUMANOID_BONES;