@directivegames/genesys.js 3.1.24

package/src/animation/AnimationRetargeting.ts

@@ -0,0 +1,566 @@
+/**
+ * AnimationRetargeting - runtime animation retargeting between different skeleton conventions.
+ *
+ * Uses the UPF GTI AnimationRetargeting algorithm which handles bind pose differences
+ * between skeletons through quaternion space transformations.
+ *
+ * Retargets animation clips from one skeleton format to another using explicit semantic
+ * bone mappings defined in SkeletonProfiles. This enables using animations from external
+ * sources (Mixamo, UE5, etc.) on characters with different bone naming conventions.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Define source and target profiles explicitly in AnimationStateMachineConfig
+ * - Profiles are loaded from JSON assets or referenced by name
+ * - Retargeting happens automatically during external animation loading
+ */
+
+
+import * as THREE from 'three';
+
+import { applyTPose as applyTPoseInternal, AnimationRetargeting as UPFRetargeting } from './retargeting.js';
+// Re-export for external use
+export { applyTPoseInternal as applyTPose };
+import { BoneRole } from './SkeletonProfile.js';
+
+import type { SkeletonProfile } from './SkeletonProfile.js';
+
+/** Default name for synthetic root bones */
+const SYNTHETIC_ROOT_BONE_NAME = 'syntheticRoot';
+
+/**
+ * Result of adding a synthetic root bone to a skeleton.
+ */
+export interface SyntheticRootResult {
+  /** The modified skeleton with synthetic root */
+  skeleton: THREE.Skeleton;
+  /** Name of the synthetic root bone */
+  rootBoneName: string;
+  /** Updated profile with synthetic root mapping */
+  updatedProfile: SkeletonProfile;
+}
+
+/**
+ * Add a synthetic root bone to a skeleton that doesn't have one.
+ *
+ * This modifies the skeleton in-place by:
+ * 1. Creating a new root bone at ground level (0,0,0)
+ * 2. Reparenting the current root (typically hips) to be a child of the new root
+ * 3. Rebuilding the skeleton's bone array and inverse bind matrices
+ *
+ * @param skeleton - The skeleton to modify (will be modified in-place)
+ * @param skinnedMesh - The skinned mesh using this skeleton (will be updated)
+ * @param profile - The skeleton profile (will be cloned and updated)
+ * @param rootBoneName - Name for the synthetic root bone
+ * @returns Result containing the modified skeleton and updated profile
+ */
+export function addSyntheticRootBone(
+  skeleton: THREE.Skeleton,
+  skinnedMesh: THREE.SkinnedMesh,
+  profile: SkeletonProfile,
+  rootBoneName: string = SYNTHETIC_ROOT_BONE_NAME
+): SyntheticRootResult {
+  // Don't add if skeleton already has a root bone
+  const existingRootBone = Object.entries(profile.boneToRole)
+    .find(([, role]) => role === BoneRole.Root);
+  if (existingRootBone) {
+    console.warn(`[AnimationRetargeting] Skeleton already has a root bone: ${existingRootBone[0]}`);
+    return { skeleton, rootBoneName: existingRootBone[0], updatedProfile: profile };
+  }
+
+  const oldBones = skeleton.bones;
+
+  if (oldBones.length === 0) {
+    throw new Error('[AnimationRetargeting] Cannot add synthetic root to empty skeleton');
+  }
+
+  // Find the current root bone (the one with no parent in the skeleton)
+  const currentRoot = oldBones[0];
+
+  // Store the current root's parent (if any, typically the armature or model)
+  const originalParent = currentRoot.parent;
+
+  // Create synthetic root bone at local origin
+  const syntheticRoot = new THREE.Bone();
+  syntheticRoot.name = rootBoneName;
+  syntheticRoot.position.set(0, 0, 0);
+  syntheticRoot.quaternion.identity();
+  syntheticRoot.scale.set(1, 1, 1);
+
+  // Reparent: synthetic root becomes parent of current root
+  // Keep hips' local transform unchanged - it becomes relative to synthetic root
+  if (originalParent) {
+    originalParent.remove(currentRoot);
+    originalParent.add(syntheticRoot);
+  }
+  syntheticRoot.add(currentRoot);
+
+  // Update world matrices
+  syntheticRoot.updateMatrixWorld(true);
+
+  // Build new bone array with synthetic root at index 0
+  const newBones: THREE.Bone[] = [syntheticRoot, ...oldBones];
+
+  // CRITICAL: Update skin indices in the geometry
+  // Since we inserted a bone at index 0, all existing bone indices must shift by +1
+  const geometry = skinnedMesh.geometry;
+  const skinIndexAttr = geometry.getAttribute('skinIndex');
+  if (skinIndexAttr) {
+    const skinIndices = skinIndexAttr.array;
+    for (let i = 0; i < skinIndices.length; i++) {
+      (skinIndices as any)[i] += 1;
+    }
+    skinIndexAttr.needsUpdate = true;
+  }
+
+  // Preserve original boneInverses and prepend identity for synthetic root
+  // The synthetic root is at origin with identity rotation, so its inverse is identity
+  const syntheticRootInverse = new THREE.Matrix4(); // identity
+  const newBoneInverses = [syntheticRootInverse, ...skeleton.boneInverses];
+
+  // Create new skeleton with preserved boneInverses
+  const newSkeleton = new THREE.Skeleton(newBones, newBoneInverses);
+
+  // Update the skinned mesh to use the new skeleton
+  skinnedMesh.bind(newSkeleton, skinnedMesh.bindMatrix);
+
+  // Create updated profile with synthetic root mapping
+  const updatedProfile: SkeletonProfile = {
+    ...profile,
+    boneToRole: {
+      [rootBoneName]: BoneRole.Root,
+      ...profile.boneToRole
+    }
+  };
+
+  console.log(
+    `[AnimationRetargeting] Added synthetic root bone "${rootBoneName}" to skeleton. ` +
+    `New bone count: ${newBones.length}`
+  );
+
+  return {
+    skeleton: newSkeleton,
+    rootBoneName,
+    updatedProfile
+  };
+}
+
+/**
+ * Check if a skeleton needs a synthetic root bone for retargeting from a source that has one.
+ */
+export function needsSyntheticRoot(
+  sourceProfile: SkeletonProfile,
+  targetProfile: SkeletonProfile
+): boolean {
+  const sourceHasRoot = Object.values(sourceProfile.boneToRole).includes(BoneRole.Root);
+  const targetHasRoot = Object.values(targetProfile.boneToRole).includes(BoneRole.Root);
+  return sourceHasRoot && !targetHasRoot;
+}
+
+/**
+ * Add getBoneByName helper to skeleton if it doesn't exist
+ */
+function ensureGetBoneByName(skeleton: THREE.Skeleton): void {
+  if (!(skeleton as any).getBoneByName) {
+    (skeleton as any).getBoneByName = function(name: string) {
+      return this.bones.find((b: THREE.Bone) => b.name === name);
+    };
+  }
+}
+
+/**
+ * Convert SkeletonProfile to the format applyTPose expects
+ */
+function profileToTPoseMap(profile: SkeletonProfile): Record<string, string | undefined> {
+  // Invert boneToRole to get roleToName
+  const roleToName: Partial<Record<BoneRole, string>> = {};
+  for (const [boneName, role] of Object.entries(profile.boneToRole)) {
+    roleToName[role] = boneName;
+  }
+
+  // Map to the semantic keys applyTPose expects
+  return {
+    Hips: roleToName[BoneRole.Hips],
+    Stomach: roleToName[BoneRole.Spine],
+    ShouldersUnion: roleToName[BoneRole.Chest] ?? roleToName[BoneRole.UpperChest],
+    Neck: roleToName[BoneRole.Neck],
+    Head: roleToName[BoneRole.Head],
+    LShoulder: roleToName[BoneRole.LeftShoulder],
+    LArm: roleToName[BoneRole.LeftUpperArm],
+    LElbow: roleToName[BoneRole.LeftLowerArm],
+    LWrist: roleToName[BoneRole.LeftHand],
+    RShoulder: roleToName[BoneRole.RightShoulder],
+    RArm: roleToName[BoneRole.RightUpperArm],
+    RElbow: roleToName[BoneRole.RightLowerArm],
+    RWrist: roleToName[BoneRole.RightHand],
+    LUpLeg: roleToName[BoneRole.LeftUpperLeg],
+    LLeg: roleToName[BoneRole.LeftLowerLeg],
+    LFoot: roleToName[BoneRole.LeftFoot],
+    LToeBase: roleToName[BoneRole.LeftToeBase],
+    RUpLeg: roleToName[BoneRole.RightUpperLeg],
+    RLeg: roleToName[BoneRole.RightLowerLeg],
+    RFoot: roleToName[BoneRole.RightFoot],
+    RToeBase: roleToName[BoneRole.RightToeBase]
+  };
+}
+
+/**
+ * Create a bone name mapping between source and target skeletons using their profiles.
+ * Returns an object compatible with UPF AnimationRetargeting: { sourceRole: targetBoneName }
+ */
+export function createBoneMapping(
+  sourceProfile: SkeletonProfile,
+  targetProfile: SkeletonProfile,
+  sourceSkeleton: THREE.Skeleton,
+  targetSkeleton: THREE.Skeleton
+): Record<string, string> {
+  const mapping: Record<string, string> = {};
+
+  // Build reverse map for source: role -> bone name
+  const sourceRoleToBone = new Map<BoneRole, string>();
+  for (const bone of sourceSkeleton.bones) {
+    const role = sourceProfile.boneToRole[bone.name];
+    if (role) {
+      sourceRoleToBone.set(role, bone.name);
+    }
+  }
+
+  // Build reverse map for target: role -> bone name
+  const targetRoleToBone = new Map<BoneRole, string>();
+  for (const bone of targetSkeleton.bones) {
+    const role = targetProfile.boneToRole[bone.name];
+    if (role) {
+      targetRoleToBone.set(role, bone.name);
+    }
+  }
+
+  // Map source bones to target bones via semantic roles
+  for (const [role, sourceBoneName] of sourceRoleToBone) {
+    const targetBoneName = targetRoleToBone.get(role);
+    if (targetBoneName) {
+      mapping[sourceBoneName] = targetBoneName;
+    }
+  }
+
+  // Note: Root motion is dropped when target has no root bone
+
+  return mapping;
+}
+
+/**
+ * Retarget an animation clip from source skeleton to target skeleton using UPF GTI retargeting.
+ *
+ * @param sourceClip - The animation clip to retarget
+ * @param sourceProfile - Skeleton profile for the source animation
+ * @param targetProfile - Skeleton profile for the target character
+ * @param sourceSkeleton - Source skeleton (from the animation's original GLTF)
+ * @param targetSkeleton - Target skeleton (from the character being animated)
+ * @param targetSkinnedMesh - Target skinned mesh (required by Three.js retargeting)
+ * @returns Retargeted animation clip, or null if retargeting failed
+ */
+export function retargetAnimationClip(
+  sourceClip: THREE.AnimationClip,
+  sourceProfile: SkeletonProfile,
+  targetProfile: SkeletonProfile,
+  sourceSkeleton: THREE.Skeleton,
+  targetSkeleton: THREE.Skeleton,
+  targetSkinnedMesh: THREE.SkinnedMesh
+): THREE.AnimationClip | null {
+  // Build reverse map for source: role -> bone name
+  const sourceRoleToBone = new Map<BoneRole, string>();
+  for (const bone of sourceSkeleton.bones) {
+    const role = sourceProfile.boneToRole[bone.name];
+    if (role) {
+      sourceRoleToBone.set(role, bone.name);
+    }
+  }
+
+  // Create bone mapping using our profile system
+  const boneMapping = createBoneMapping(
+    sourceProfile,
+    targetProfile,
+    sourceSkeleton,
+    targetSkeleton
+  );
+
+  if (Object.keys(boneMapping).length === 0) {
+    console.error('[AnimationRetargeting] Failed to create bone mapping - no bones matched');
+    return null;
+  }
+
+  try {
+    // Add getBoneByName helper method required by applyTPose
+    ensureGetBoneByName(sourceSkeleton);
+    ensureGetBoneByName(targetSkeleton);
+
+    // Convert our profiles to the format applyTPose expects
+    const sourceTPoseMap = profileToTPoseMap(sourceProfile);
+    const targetTPoseMap = profileToTPoseMap(targetProfile);
+
+    // Apply T-Pose to both skeletons for consistent bind poses
+    try {
+      const sourceTPose = applyTPoseInternal(sourceSkeleton, sourceTPoseMap);
+      const targetTPose = applyTPoseInternal(targetSkeleton, targetTPoseMap);
+
+      // Create UPF retargeting instance using CURRENT pose mode to capture the T-Poses
+      const retargeter = new UPFRetargeting(sourceTPose.skeleton, targetTPose.skeleton, {
+        boneNameMap: boneMapping,
+        srcPoseMode: UPFRetargeting.BindPoseModes.CURRENT,
+        trgPoseMode: UPFRetargeting.BindPoseModes.CURRENT,
+        srcEmbedWorldTransforms: true,
+        trgEmbedWorldTransforms: true,
+        positionAxisFlips: targetProfile.positionAxisFlips,
+        hipsPositionAxisFlips: targetProfile.hipsPositionAxisFlips
+      });
+
+      // Retarget the animation
+      const retargetedClip = retargeter.retargetAnimation(sourceClip);
+
+      if (!retargetedClip || retargetedClip.tracks.length === 0) {
+        console.error(`[AnimationRetargeting] Failed to retarget "${sourceClip.name}": no tracks generated`);
+        return null;
+      }
+
+      // CRITICAL: Remove scale tracks to prevent shrinking/deformation
+      const originalTrackCount = retargetedClip.tracks.length;
+      retargetedClip.tracks = retargetedClip.tracks.filter(track => {
+        return !track.name.endsWith('.scale');
+      });
+
+      // Handle root motion incompatibility between source and target
+      const sourceRootBoneName = sourceRoleToBone.get(BoneRole.Root);
+      const targetRootBoneName = targetProfile.boneToRole[targetSkeleton.bones[0]?.name];
+      const targetHipsBoneName = Array.from(Object.entries(targetProfile.boneToRole))
+        .find(([, role]) => role === BoneRole.Hips)?.[0];
+
+      // Case 1: Source has no root bone but target does
+      // Mixamo hips position tracks should NOT be applied to Rigify hips (child of root)
+      if (!sourceRootBoneName && targetRootBoneName === BoneRole.Root && targetHipsBoneName) {
+        const hipsPositionTrackIndex = retargetedClip.tracks.findIndex(track =>
+          track.name.includes(targetHipsBoneName) && track.name.endsWith('.position')
+        );
+
+        if (hipsPositionTrackIndex !== -1) {
+          retargetedClip.tracks.splice(hipsPositionTrackIndex, 1);
+          console.warn(
+            `[AnimationRetargeting] Removed hips position track from "${sourceClip.name}" ` +
+            'because source skeleton lacks a root bone (Mixamo) but target has one (Rigify).'
+          );
+        }
+      }
+
+      // Case 2: Source has root motion but target doesn't
+      const sourceHasRootMotion = sourceRootBoneName &&
+        sourceClip.tracks.some(track =>
+          track.name.includes(sourceRootBoneName) && track.name.endsWith('.position')
+        );
+
+      if (sourceHasRootMotion && targetRootBoneName !== BoneRole.Root) {
+        console.warn(
+          `[AnimationRetargeting] Source animation "${sourceClip.name}" contains root motion. ` +
+          'Root motion tracks are not transferred when target skeleton lacks a root bone. ' +
+          'Consider implementing root motion extraction to model transform.'
+        );
+      }
+
+      // Reset all bone scales to (1,1,1) to prevent accumulated scale issues
+      targetSkeleton.bones.forEach(bone => {
+        bone.scale.set(1, 1, 1);
+      });
+      targetSkeleton.update();
+
+      return retargetedClip;
+
+    } catch (tPoseError) {
+      console.error('[AnimationRetargeting] T-Pose failed, falling back to default bind poses:', tPoseError);
+
+      // Fallback: use default bind poses without T-Pose
+      const retargeter = new UPFRetargeting(sourceSkeleton, targetSkeleton, {
+        boneNameMap: boneMapping,
+        srcPoseMode: UPFRetargeting.BindPoseModes.DEFAULT,
+        trgPoseMode: UPFRetargeting.BindPoseModes.DEFAULT,
+        positionAxisFlips: targetProfile.positionAxisFlips,
+        hipsPositionAxisFlips: targetProfile.hipsPositionAxisFlips
+      });
+
+      // Retarget the animation
+      const retargetedClip = retargeter.retargetAnimation(sourceClip);
+
+      if (!retargetedClip || retargetedClip.tracks.length === 0) {
+        console.error(`[AnimationRetargeting] Failed to retarget "${sourceClip.name}": no tracks generated`);
+        return null;
+      }
+
+      // CRITICAL: Remove scale tracks to prevent shrinking/deformation
+      retargetedClip.tracks = retargetedClip.tracks.filter(track => {
+        return !track.name.endsWith('.scale');
+      });
+
+      targetSkeleton.bones.forEach(bone => {
+        bone.scale.set(1, 1, 1);
+      });
+      targetSkeleton.update();
+
+      return retargetedClip;
+    }
+
+  } catch (error) {
+    console.error(`[AnimationRetargeting] Failed to retarget "${sourceClip.name}":`, error);
+    return null;
+  }
+}
+
+/**
+ * A reusable retargeting session that initializes T-poses once and can retarget multiple clips.
+ * This is more efficient than calling retargetAnimationClip for each clip individually.
+ */
+export class RetargetingSession {
+  private retargeter: InstanceType<typeof UPFRetargeting> | null = null;
+  private sourceRoleToBone = new Map<BoneRole, string>();
+  private targetProfile: SkeletonProfile;
+  private targetSkeleton: THREE.Skeleton;
+  private initialized = false;
+
+  constructor(
+    sourceProfile: SkeletonProfile,
+    targetProfile: SkeletonProfile,
+    sourceSkeleton: THREE.Skeleton,
+    targetSkeleton: THREE.Skeleton
+  ) {
+    this.targetProfile = targetProfile;
+    this.targetSkeleton = targetSkeleton;
+
+    // Build reverse map for source: role -> bone name
+    for (const bone of sourceSkeleton.bones) {
+      const role = sourceProfile.boneToRole[bone.name];
+      if (role) {
+        this.sourceRoleToBone.set(role, bone.name);
+      }
+    }
+
+    // Create bone mapping
+    const boneMapping = createBoneMapping(sourceProfile, targetProfile, sourceSkeleton, targetSkeleton);
+
+    if (Object.keys(boneMapping).length === 0) {
+      console.error('[RetargetingSession] Failed to create bone mapping - no bones matched');
+      return;
+    }
+
+    // Add getBoneByName helper
+    ensureGetBoneByName(sourceSkeleton);
+    ensureGetBoneByName(targetSkeleton);
+
+    // Convert profiles to T-pose map format
+    const sourceTPoseMap = profileToTPoseMap(sourceProfile);
+    const targetTPoseMap = profileToTPoseMap(targetProfile);
+
+    // Apply T-Pose ONCE to both skeletons
+    try {
+      // const sourceTPose = applyTPoseInternal(sourceSkeleton, sourceTPoseMap);
+      // const targetTPose = applyTPoseInternal(targetSkeleton, targetTPoseMap);
+
+      // Create retargeter instance ONCE
+      this.retargeter = new UPFRetargeting(sourceSkeleton, targetSkeleton, {
+        boneNameMap: boneMapping,
+        srcPoseMode: UPFRetargeting.BindPoseModes.CURRENT,
+        trgPoseMode: UPFRetargeting.BindPoseModes.CURRENT,
+        srcEmbedWorldTransforms: true,
+        trgEmbedWorldTransforms: true,
+        positionAxisFlips: targetProfile.positionAxisFlips,
+        hipsPositionAxisFlips: targetProfile.hipsPositionAxisFlips
+      });
+
+      this.initialized = true;
+      console.log('[RetargetingSession] Initialized with T-poses applied once');
+    } catch (error) {
+      console.error('[RetargetingSession] Failed to initialize:', error);
+    }
+  }
+
+  /**
+   * Retarget a single clip using the pre-initialized session.
+   */
+  retargetClip(sourceClip: THREE.AnimationClip): THREE.AnimationClip | null {
+    if (!this.initialized || !this.retargeter) {
+      console.error('[RetargetingSession] Session not initialized');
+      return null;
+    }
+
+    try {
+      const retargetedClip = this.retargeter.retargetAnimation(sourceClip);
+
+      if (!retargetedClip || retargetedClip.tracks.length === 0) {
+        console.error(`[RetargetingSession] Failed to retarget "${sourceClip.name}": no tracks generated`);
+        return null;
+      }
+
+      // Remove scale tracks
+      retargetedClip.tracks = retargetedClip.tracks.filter(track => !track.name.endsWith('.scale'));
+
+      // Handle root motion incompatibility
+      const sourceRootBoneName = this.sourceRoleToBone.get(BoneRole.Root);
+      const targetRootBoneName = this.targetProfile.boneToRole[this.targetSkeleton.bones[0]?.name];
+      const targetHipsBoneName = Array.from(Object.entries(this.targetProfile.boneToRole))
+        .find(([, role]) => role === BoneRole.Hips)?.[0];
+
+      if (!sourceRootBoneName && targetRootBoneName === BoneRole.Root && targetHipsBoneName) {
+        const hipsPositionTrackIndex = retargetedClip.tracks.findIndex(track =>
+          track.name.includes(targetHipsBoneName) && track.name.endsWith('.position')
+        );
+        if (hipsPositionTrackIndex !== -1) {
+          retargetedClip.tracks.splice(hipsPositionTrackIndex, 1);
+        }
+      }
+
+      return retargetedClip;
+    } catch (error) {
+      console.error(`[RetargetingSession] Failed to retarget "${sourceClip.name}":`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Retarget multiple clips using the pre-initialized session.
+   */
+  retargetClips(sourceClips: THREE.AnimationClip[]): Array<{ clip: THREE.AnimationClip | null; success: boolean; originalName: string }> {
+    return sourceClips.map(sourceClip => ({
+      clip: this.retargetClip(sourceClip),
+      success: this.retargetClip(sourceClip) !== null,
+      originalName: sourceClip.name
+    }));
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+}
+
+/**
+ * Batch retarget multiple animation clips.
+ * Uses RetargetingSession internally to apply T-poses only once.
+ */
+export function retargetAnimationClips(
+  sourceClips: THREE.AnimationClip[],
+  sourceProfile: SkeletonProfile,
+  targetProfile: SkeletonProfile,
+  sourceSkeleton: THREE.Skeleton,
+  targetSkeleton: THREE.Skeleton,
+  _targetSkinnedMesh: THREE.SkinnedMesh
+): Array<{ clip: THREE.AnimationClip | null; success: boolean; originalName: string }> {
+  // Create a session that initializes T-poses once
+  const session = new RetargetingSession(sourceProfile, targetProfile, sourceSkeleton, targetSkeleton);
+
+  if (!session.isInitialized()) {
+    return sourceClips.map(clip => ({ clip: null, success: false, originalName: clip.name }));
+  }
+
+  // Retarget all clips using the same session
+  return sourceClips.map(sourceClip => {
+    const retargetedClip = session.retargetClip(sourceClip);
+    return {
+      clip: retargetedClip,
+      success: retargetedClip !== null,
+      originalName: sourceClip.name
+    };
+  });
+}
+

package/src/animation/SkeletonProfile.ts

@@ -0,0 +1,137 @@
+/**
+ * SkeletonProfile - defines bone naming conventions for animation retargeting.
+ *
+ * Skeleton profiles map bone names to semantic roles (e.g., "mixamorigHips" -> Hips),
+ * enabling animation retargeting between different skeleton conventions. Profiles can
+ * be loaded from JSON files or defined programmatically.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Store profile JSON files in assets/animation-profiles/
+ * - Reference profiles explicitly in AnimationStateMachineConfig
+ * - Use built-in profiles (Mixamo, UE5, Standard, etc.) or create custom ones
+ */
+
+/**
+ * Semantic bone roles for humanoid characters.
+ * This is the universal language that different skeletons are mapped to.
+ */
+export enum BoneRole {
+  // Core
+  Root = 'Root',
+  Hips = 'Hips',
+  Spine = 'Spine',
+  Chest = 'Chest',
+  UpperChest = 'UpperChest',
+  Neck = 'Neck',
+  Head = 'Head',
+
+  // Left Arm
+  LeftShoulder = 'LeftShoulder',
+  LeftUpperArm = 'LeftUpperArm',
+  LeftLowerArm = 'LeftLowerArm',
+  LeftHand = 'LeftHand',
+
+  // Right Arm
+  RightShoulder = 'RightShoulder',
+  RightUpperArm = 'RightUpperArm',
+  RightLowerArm = 'RightLowerArm',
+  RightHand = 'RightHand',
+
+  // Left Leg
+  LeftUpperLeg = 'LeftUpperLeg',
+  LeftLowerLeg = 'LeftLowerLeg',
+  LeftFoot = 'LeftFoot',
+  LeftToeBase = 'LeftToeBase',
+
+  // Right Leg
+  RightUpperLeg = 'RightUpperLeg',
+  RightLowerLeg = 'RightLowerLeg',
+  RightFoot = 'RightFoot',
+  RightToeBase = 'RightToeBase',
+
+  // Fingers (Left Hand)
+  LeftHandThumb1 = 'LeftHandThumb1',
+  LeftHandThumb2 = 'LeftHandThumb2',
+  LeftHandThumb3 = 'LeftHandThumb3',
+  LeftHandIndex1 = 'LeftHandIndex1',
+  LeftHandIndex2 = 'LeftHandIndex2',
+  LeftHandIndex3 = 'LeftHandIndex3',
+  LeftHandMiddle1 = 'LeftHandMiddle1',
+  LeftHandMiddle2 = 'LeftHandMiddle2',
+  LeftHandMiddle3 = 'LeftHandMiddle3',
+  LeftHandRing1 = 'LeftHandRing1',
+  LeftHandRing2 = 'LeftHandRing2',
+  LeftHandRing3 = 'LeftHandRing3',
+  LeftHandPinky1 = 'LeftHandPinky1',
+  LeftHandPinky2 = 'LeftHandPinky2',
+  LeftHandPinky3 = 'LeftHandPinky3',
+
+  // Fingers (Right Hand)
+  RightHandThumb1 = 'RightHandThumb1',
+  RightHandThumb2 = 'RightHandThumb2',
+  RightHandThumb3 = 'RightHandThumb3',
+  RightHandIndex1 = 'RightHandIndex1',
+  RightHandIndex2 = 'RightHandIndex2',
+  RightHandIndex3 = 'RightHandIndex3',
+  RightHandMiddle1 = 'RightHandMiddle1',
+  RightHandMiddle2 = 'RightHandMiddle2',
+  RightHandMiddle3 = 'RightHandMiddle3',
+  RightHandRing1 = 'RightHandRing1',
+  RightHandRing2 = 'RightHandRing2',
+  RightHandRing3 = 'RightHandRing3',
+  RightHandPinky1 = 'RightHandPinky1',
+  RightHandPinky2 = 'RightHandPinky2',
+  RightHandPinky3 = 'RightHandPinky3',
+
+  // Head (Optional)
+  RightEye = 'RightEye',
+  LeftEye = 'LeftEye',
+  Jaw = 'Jaw',
+}
+
+/**
+ * Axis flip configuration for position retargeting.
+ * Used to handle coordinate system differences between skeletons.
+ */
+export interface PositionAxisFlips {
+  /** Flip X axis for root motion */
+  x?: boolean;
+  /** Flip Y axis for root motion */
+  y?: boolean;
+  /** Flip Z axis for root motion */
+  z?: boolean;
+}
+
+/**
+ * Skeleton profile - maps bone names to semantic roles.
+ * Can be serialized to/from JSON for asset storage.
+ */
+export interface SkeletonProfile {
+  /** Profile name (e.g., "Mixamo", "UE5", "Standard") */
+  name: string;
+
+  /** Human-readable description */
+  description: string;
+
+  /** Map bone name -> semantic role */
+  boneToRole: Record<string, BoneRole>;
+
+  /** Hip bone name (required for retargeting root motion) */
+  hipBoneName: string;
+
+  /** Optional scale factor for unit conversion (e.g., 0.01 for cm to m) */
+  scale?: number;
+
+  /**
+   * Optional axis flips for root position retargeting.
+   * Used when this profile is the TARGET to correct coordinate system differences.
+   */
+  positionAxisFlips?: PositionAxisFlips;
+
+  /**
+   * Optional axis flips for hips position retargeting.
+   * Separate from root because hips may have different coordinate system.
+   */
+  hipsPositionAxisFlips?: PositionAxisFlips;
+}
+