@sage-rsc/talking-head-react 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A reusable React component for 3D talking avatars with lip-sync and text-to-speech",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/lib/talkinghead.mjs

@@ -2214,38 +2214,35 @@ class TalkingHead {
       console.log('Original position stored:', this.originalPosition);
     }
     
-    // Move avatar UP initially to compensate for FBX animation downward movement
-    // Set a higher base position so FBX animations land in the center
-    const upwardOffset = 2.0; // Even more upward movement
-    
+    // Lock the avatar at its CURRENT position (don't move it)
     this.lockedPosition = {
-      x: 0, // Keep centered horizontally
-      y: upwardOffset, // Set to the upward offset directly
-      z: 0  // Keep centered horizontally
+      x: this.armature.position.x,
+      y: this.armature.position.y,
+      z: this.armature.position.z
     };
     
-    // Set the avatar to the higher position
-    this.armature.position.set(
-      this.lockedPosition.x,
-      this.lockedPosition.y,
-      this.lockedPosition.z
-    );
-    
-    console.log('BEFORE: Avatar position was:', this.armature.position.x, this.armature.position.y, this.armature.position.z);
-    console.log('AFTER: Avatar position moved up and locked at:', this.lockedPosition);
-    console.log('Current view:', this.viewName);
+    console.log('Avatar position locked at current position:', this.lockedPosition);
   }
 
   /**
-   * Unlock avatar position and reset to center.
+   * Unlock avatar position and restore original position.
    */
   unlockAvatarPosition() {
-    if (this.armature) {
-      // Reset avatar to center (0,0,0) when animation finishes
+    if (this.armature && this.originalPosition) {
+      // Restore avatar to its original position before locking
+      this.armature.position.set(
+        this.originalPosition.x,
+        this.originalPosition.y,
+        this.originalPosition.z
+      );
+      console.log('Avatar position restored to original:', this.originalPosition);
+    } else if (this.armature) {
+      // Fallback: reset to center if no original position was stored
       this.armature.position.set(0, 0, 0);
       console.log('Avatar position reset to center (0,0,0)');
     }
     this.lockedPosition = null;
+    this.originalPosition = null; // Clear original position after unlock
     console.log('Avatar position unlocked');
   }
 
@@ -2254,31 +2251,13 @@ class TalkingHead {
    */
   maintainLockedPosition() {
     if (this.lockedPosition && this.armature) {
-      // Allow some downward movement but prevent excessive movement
-      // This lets FBX animations move the avatar down to the correct position
-      const currentY = this.armature.position.y;
-      const minY = this.lockedPosition.y - 2.0; // Allow up to 2.0 units down from locked position
-      const maxY = this.lockedPosition.y + 0.1; // Prevent moving up too much
-      
-      if (currentY < minY) {
-        // If moved too far down, bring it back up
-        this.armature.position.set(
-          this.lockedPosition.x,
-          minY,
-          this.lockedPosition.z
-        );
-      } else if (currentY > maxY) {
-        // If moved too far up, bring it back down
-        this.armature.position.set(
-          this.lockedPosition.x,
-          maxY,
-          this.lockedPosition.z
-        );
-      }
-      
-      // Always maintain X and Z position
-      this.armature.position.x = this.lockedPosition.x;
-      this.armature.position.z = this.lockedPosition.z;
+      // Enforce the locked position - keep avatar exactly where it was locked
+      // This prevents FBX animations from moving the avatar
+      this.armature.position.set(
+        this.lockedPosition.x,
+        this.lockedPosition.y,
+        this.lockedPosition.z
+      );
     }
   }
 
@@ -5361,38 +5340,279 @@ class TalkingHead {
     return boneNames;
   }
 
+  /**
+   * Map bone names from different naming conventions to avatar bone names
+   * @param {string} fbxBoneName - Bone name from FBX animation
+   * @param {Set<string>} availableBones - Set of available bone names in avatar
+   * @returns {string|null} Mapped bone name or null if no match found
+   */
+  mapBoneName(fbxBoneName, availableBones) {
+    // Direct match first
+    if (availableBones.has(fbxBoneName)) {
+      return fbxBoneName;
+    }
+
+    // Remove common prefixes
+    let normalized = fbxBoneName;
+    
+    // Remove CC_Base prefix (Character Creator)
+    if (normalized.startsWith('CC_Base_')) {
+      normalized = normalized.replace('CC_Base_', '');
+    }
+    
+    // Remove mixamorig prefix (Mixamo)
+    normalized = normalized.replace(/^mixamorig/i, '');
+    
+    // Try direct match after prefix removal
+    if (availableBones.has(normalized)) {
+      return normalized;
+    }
+
+    // Handle numbered bones (e.g., Spine01 -> Spine1)
+    if (normalized.match(/^Spine\d+$/)) {
+      const num = normalized.match(/\d+/)?.[0];
+      if (num) {
+        const mapped = `Spine${parseInt(num)}`;
+        if (availableBones.has(mapped)) {
+          return mapped;
+        }
+        // Try Spine1 if Spine01, Spine2 if Spine02+
+        if (num === '01' && availableBones.has('Spine1')) {
+          return 'Spine1';
+        }
+        if (parseInt(num) >= 2 && availableBones.has('Spine2')) {
+          return 'Spine2';
+        }
+      }
+    }
+
+    // Handle twist bones (ignore them, they're usually not in standard skeletons)
+    if (normalized.includes('Twist')) {
+      return null;
+    }
+
+    // Mapping rules for common bone name patterns
+    const mappings = {
+      // Spine mapping
+      'Spine01': 'Spine1',
+      'Spine02': 'Spine2',
+      'Spine03': 'Spine2',
+      
+      // Left arm mapping
+      'L_Upperarm': 'LeftArm',
+      'L_Forearm': 'LeftForeArm',
+      'L_Hand': 'LeftHand',
+      'L_Shoulder': 'LeftShoulder',
+      'L_Index1': 'LeftHandIndex1',
+      'L_Index2': 'LeftHandIndex2',
+      'L_Index3': 'LeftHandIndex3',
+      'L_Middle1': 'LeftHandMiddle1',
+      'L_Middle2': 'LeftHandMiddle2',
+      'L_Middle3': 'LeftHandMiddle3',
+      'L_Ring1': 'LeftHandRing1',
+      'L_Ring2': 'LeftHandRing2',
+      'L_Ring3': 'LeftHandRing3',
+      'L_Pinky1': 'LeftHandPinky1',
+      'L_Pinky2': 'LeftHandPinky2',
+      'L_Pinky3': 'LeftHandPinky3',
+      'L_Thumb1': 'LeftHandThumb1',
+      'L_Thumb2': 'LeftHandThumb2',
+      'L_Thumb3': 'LeftHandThumb3',
+      
+      // Right arm mapping
+      'R_Upperarm': 'RightArm',
+      'R_Forearm': 'RightForeArm',
+      'R_Hand': 'RightHand',
+      'R_Shoulder': 'RightShoulder',
+      'R_Index1': 'RightHandIndex1',
+      'R_Index2': 'RightHandIndex2',
+      'R_Index3': 'RightHandIndex3',
+      'R_Middle1': 'RightHandMiddle1',
+      'R_Middle2': 'RightHandMiddle2',
+      'R_Middle3': 'RightHandMiddle3',
+      'R_Ring1': 'RightHandRing1',
+      'R_Ring2': 'RightHandRing2',
+      'R_Ring3': 'RightHandRing3',
+      'R_Pinky1': 'RightHandPinky1',
+      'R_Pinky2': 'RightHandPinky2',
+      'R_Pinky3': 'RightHandPinky3',
+      'R_Thumb1': 'RightHandThumb1',
+      'R_Thumb2': 'RightHandThumb2',
+      'R_Thumb3': 'RightHandThumb3',
+      
+      // Leg mapping
+      'L_Thigh': 'LeftUpLeg',
+      'L_Calf': 'LeftLeg',
+      'L_Foot': 'LeftFoot',
+      'R_Thigh': 'RightUpLeg',
+      'R_Calf': 'RightLeg',
+      'R_Foot': 'RightFoot',
+    };
+
+    // Try mapping
+    if (mappings[normalized]) {
+      const mapped = mappings[normalized];
+      if (availableBones.has(mapped)) {
+        return mapped;
+      }
+    }
+
+    // Pattern-based matching for CC_Base and similar naming conventions
+    const lowerNormalized = normalized.toLowerCase();
+    
+    // Pattern: R_Index1/2/3 -> RightHandIndex1/2/3
+    const indexMatch = lowerNormalized.match(/^[rl]_index(\d+)$/);
+    if (indexMatch) {
+      const digit = indexMatch[1];
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}HandIndex${digit}`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Pinky1/2/3 -> RightHandPinky1/2/3
+    const pinkyMatch = lowerNormalized.match(/^[rl]_pinky(\d+)$/);
+    if (pinkyMatch) {
+      const digit = pinkyMatch[1];
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}HandPinky${digit}`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Ring1/2/3 -> RightHandRing1/2/3
+    const ringMatch = lowerNormalized.match(/^[rl]_ring(\d+)$/);
+    if (ringMatch) {
+      const digit = ringMatch[1];
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}HandRing${digit}`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Middle1/2/3 -> RightHandMiddle1/2/3
+    const middleMatch = lowerNormalized.match(/^[rl]_middle(\d+)$/);
+    if (middleMatch) {
+      const digit = middleMatch[1];
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}HandMiddle${digit}`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Thumb1/2/3 -> RightHandThumb1/2/3
+    const thumbMatch = lowerNormalized.match(/^[rl]_thumb(\d+)$/);
+    if (thumbMatch) {
+      const digit = thumbMatch[1];
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}HandThumb${digit}`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Upperarm -> RightArm
+    if (lowerNormalized.match(/^[rl]_upperarm/)) {
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}Arm`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Forearm -> RightForeArm
+    if (lowerNormalized.match(/^[rl]_forearm/)) {
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}ForeArm`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+    
+    // Pattern: R_Hand -> RightHand
+    if (lowerNormalized.match(/^[rl]_hand$/)) {
+      const side = lowerNormalized.startsWith('r') ? 'Right' : 'Left';
+      const candidate = `${side}Hand`;
+      if (availableBones.has(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Try case-insensitive exact match
+    for (const boneName of availableBones) {
+      if (boneName.toLowerCase() === lowerNormalized) {
+        return boneName;
+      }
+    }
+
+    return null; // No mapping found
+  }
+
   /**
    * Filter animation tracks to only include bones that exist in the avatar
+   * Maps bone names from different naming conventions to avatar bone names
    * @param {THREE.AnimationClip} clip - Animation clip to filter
    * @param {Set<string>} availableBones - Set of available bone names
-   * @returns {THREE.AnimationClip} Filtered animation clip
+   * @returns {THREE.AnimationClip} Filtered animation clip with mapped bone names
    */
   filterAnimationTracks(clip, availableBones) {
     const validTracks = [];
     const missingBones = new Set();
+    const mappedBones = new Map(); // Track mappings for logging
     
     clip.tracks.forEach(track => {
       // Extract bone name from track name (e.g., "CC_Base_R_Index3.position" -> "CC_Base_R_Index3")
       const trackNameParts = track.name.split('.');
-      const boneName = trackNameParts[0];
+      const fbxBoneName = trackNameParts[0];
+      const property = trackNameParts[1]; // position, quaternion, rotation, etc.
+      
+      // Try to map the bone name
+      const mappedBoneName = this.mapBoneName(fbxBoneName, availableBones);
       
-      if (availableBones.has(boneName)) {
-        validTracks.push(track);
+      if (mappedBoneName) {
+        // Create a new track with the mapped bone name
+        const newTrackName = `${mappedBoneName}.${property}`;
+        
+        // Clone the track and update its name
+        const newTrack = track.clone();
+        newTrack.name = newTrackName;
+        
+        validTracks.push(newTrack);
+        
+        // Track mappings for logging
+        if (fbxBoneName !== mappedBoneName) {
+          mappedBones.set(fbxBoneName, mappedBoneName);
+        }
       } else {
-        missingBones.add(boneName);
+        missingBones.add(fbxBoneName);
       }
     });
     
+    // Log results
+    if (mappedBones.size > 0) {
+      console.info(`FBX animation "${clip.name}": Mapped ${mappedBones.size} bone(s) to avatar skeleton:`, 
+        Array.from(mappedBones.entries()).slice(0, 5).map(([from, to]) => `${from} → ${to}`).join(', '),
+        mappedBones.size > 5 ? '...' : '');
+    }
+    
     if (missingBones.size > 0) {
-      console.warn(`FBX animation "${clip.name}" contains tracks for ${missingBones.size} bone(s) not found in avatar skeleton:`, Array.from(missingBones).slice(0, 10).join(', '), missingBones.size > 10 ? '...' : '');
-      console.info(`Filtered ${clip.tracks.length} tracks down to ${validTracks.length} valid tracks`);
-    } else if (validTracks.length > 0) {
-      console.info(`FBX animation "${clip.name}" is fully compatible: all ${validTracks.length} tracks match avatar skeleton`);
+      console.warn(`FBX animation "${clip.name}" contains tracks for ${missingBones.size} bone(s) that couldn't be mapped:`, 
+        Array.from(missingBones).slice(0, 10).join(', '), 
+        missingBones.size > 10 ? '...' : '');
+    }
+    
+    if (validTracks.length > 0) {
+      console.info(`Filtered ${clip.tracks.length} tracks down to ${validTracks.length} valid tracks (${mappedBones.size} mapped)`);
+    } else {
+      console.error(`No valid tracks found for animation "${clip.name}". All bones are missing or couldn't be mapped.`);
     }
     
     // Create a new clip with only valid tracks
     if (validTracks.length === 0) {
-      console.error(`No valid tracks found for animation "${clip.name}". All bones are missing from avatar skeleton.`);
       return null;
     }