@nice2dev/game-engine 1.0.5 → 1.0.10

package/dist/cjs/editor/AnimationRetargeting.js

@@ -0,0 +1,742 @@
+'use strict';
+
+/**
+ * @file AnimationRetargeting.ts
+ * @description Animation Retargeting system for applying animations cross-skeletons
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Skeleton hierarchy definition
+ * - Bone mapping between source and target skeletons
+ * - Auto-mapping based on bone names
+ * - Manual mapping adjustment
+ * - Bone transforms (rotation, position, scale adjustments)
+ * - Animation clip retargeting
+ * - Root motion handling
+ * - Finger/hand mapping for humanoids
+ * - Mirror animations (left/right swap)
+ * - Blend shape mapping
+ * - IK adjustment options
+ */
+// ============================================================
+// Math Utilities
+// ============================================================
+const MathUtils = {
+    vector3Zero() {
+        return { x: 0, y: 0, z: 0 };
+    },
+    vector3One() {
+        return { x: 1, y: 1, z: 1 };
+    },
+    quaternionIdentity() {
+        return { x: 0, y: 0, z: 0, w: 1 };
+    },
+    multiplyQuaternion(a, b) {
+        return {
+            x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+            y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+            z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+            w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+        };
+    },
+    inverseQuaternion(q) {
+        const lengthSq = q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w;
+        if (lengthSq === 0) {
+            return this.quaternionIdentity();
+        }
+        const inv = 1 / lengthSq;
+        return {
+            x: -q.x * inv,
+            y: -q.y * inv,
+            z: -q.z * inv,
+            w: q.w * inv,
+        };
+    },
+    slerpQuaternion(a, b, t) {
+        let dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+        // Ensure shortest path
+        const bNeg = { ...b };
+        if (dot < 0) {
+            dot = -dot;
+            bNeg.x = -bNeg.x;
+            bNeg.y = -bNeg.y;
+            bNeg.z = -bNeg.z;
+            bNeg.w = -bNeg.w;
+        }
+        // Linear interpolation for very close quaternions
+        if (dot > 0.9995) {
+            return this.normalizeQuaternion({
+                x: a.x + t * (bNeg.x - a.x),
+                y: a.y + t * (bNeg.y - a.y),
+                z: a.z + t * (bNeg.z - a.z),
+                w: a.w + t * (bNeg.w - a.w),
+            });
+        }
+        const theta = Math.acos(dot);
+        const sinTheta = Math.sin(theta);
+        const wa = Math.sin((1 - t) * theta) / sinTheta;
+        const wb = Math.sin(t * theta) / sinTheta;
+        return {
+            x: wa * a.x + wb * bNeg.x,
+            y: wa * a.y + wb * bNeg.y,
+            z: wa * a.z + wb * bNeg.z,
+            w: wa * a.w + wb * bNeg.w,
+        };
+    },
+    normalizeQuaternion(q) {
+        const length = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
+        if (length === 0) {
+            return this.quaternionIdentity();
+        }
+        return {
+            x: q.x / length,
+            y: q.y / length,
+            z: q.z / length,
+            w: q.w / length,
+        };
+    },
+    lerpVector3(a, b, t) {
+        return {
+            x: a.x + (b.x - a.x) * t,
+            y: a.y + (b.y - a.y) * t,
+            z: a.z + (b.z - a.z) * t,
+        };
+    },
+    multiplyVector3(v, scalar) {
+        return { x: v.x * scalar, y: v.y * scalar, z: v.z * scalar };
+    },
+    addVector3(a, b) {
+        return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+    },
+    mirrorVector3X(v) {
+        return { x: -v.x, y: v.y, z: v.z };
+    },
+    mirrorQuaternionX(q) {
+        return { x: q.x, y: -q.y, z: -q.z, w: q.w };
+    },
+    eulerToQuaternion(euler) {
+        const c1 = Math.cos(euler.x / 2);
+        const c2 = Math.cos(euler.y / 2);
+        const c3 = Math.cos(euler.z / 2);
+        const s1 = Math.sin(euler.x / 2);
+        const s2 = Math.sin(euler.y / 2);
+        const s3 = Math.sin(euler.z / 2);
+        return {
+            x: s1 * c2 * c3 + c1 * s2 * s3,
+            y: c1 * s2 * c3 - s1 * c2 * s3,
+            z: c1 * c2 * s3 + s1 * s2 * c3,
+            w: c1 * c2 * c3 - s1 * s2 * s3,
+        };
+    },
+};
+// ============================================================
+// Animation Retargeting System
+// ============================================================
+class AnimationRetargeting {
+    constructor() {
+        this.skeletons = new Map();
+        this.profiles = new Map();
+        this.clips = new Map();
+        this.humanoidNamePatterns = this.buildNamePatterns();
+        this.mirrorPairs = this.buildMirrorPairs();
+    }
+    buildNamePatterns() {
+        const patterns = new Map();
+        // Spine
+        patterns.set('Hips', [/hip/i, /pelvis/i, /root/i]);
+        patterns.set('Spine', [/spine/i, /back/i]);
+        patterns.set('Chest', [/chest/i, /spine[_\d]*2/i]);
+        patterns.set('UpperChest', [/upper.*chest/i, /spine[_\d]*3/i]);
+        patterns.set('Neck', [/neck/i]);
+        patterns.set('Head', [/head/i]);
+        // Left Arm
+        patterns.set('LeftShoulder', [/l.*shoulder/i, /left.*shoulder/i, /clavicle.*l/i]);
+        patterns.set('LeftUpperArm', [/l.*upper.*arm/i, /left.*arm/i, /l.*arm/i]);
+        patterns.set('LeftLowerArm', [/l.*forearm/i, /l.*lower.*arm/i, /left.*forearm/i]);
+        patterns.set('LeftHand', [/l.*hand/i, /left.*hand/i, /l.*wrist/i]);
+        // Right Arm
+        patterns.set('RightShoulder', [/r.*shoulder/i, /right.*shoulder/i, /clavicle.*r/i]);
+        patterns.set('RightUpperArm', [/r.*upper.*arm/i, /right.*arm/i, /r.*arm/i]);
+        patterns.set('RightLowerArm', [/r.*forearm/i, /r.*lower.*arm/i, /right.*forearm/i]);
+        patterns.set('RightHand', [/r.*hand/i, /right.*hand/i, /r.*wrist/i]);
+        // Left Leg
+        patterns.set('LeftUpperLeg', [/l.*thigh/i, /l.*upper.*leg/i, /left.*thigh/i]);
+        patterns.set('LeftLowerLeg', [/l.*calf/i, /l.*shin/i, /l.*lower.*leg/i]);
+        patterns.set('LeftFoot', [/l.*foot/i, /left.*foot/i, /l.*ankle/i]);
+        patterns.set('LeftToes', [/l.*toe/i, /left.*toe/i]);
+        // Right Leg
+        patterns.set('RightUpperLeg', [/r.*thigh/i, /r.*upper.*leg/i, /right.*thigh/i]);
+        patterns.set('RightLowerLeg', [/r.*calf/i, /r.*shin/i, /r.*lower.*leg/i]);
+        patterns.set('RightFoot', [/r.*foot/i, /right.*foot/i, /r.*ankle/i]);
+        patterns.set('RightToes', [/r.*toe/i, /right.*toe/i]);
+        // Fingers (simplified patterns)
+        const fingers = ['Thumb', 'Index', 'Middle', 'Ring', 'Little'];
+        const segments = ['Proximal', 'Intermediate', 'Distal'];
+        for (const finger of fingers) {
+            for (let i = 0; i < segments.length; i++) {
+                const segment = segments[i];
+                const segNum = i + 1;
+                patterns.set(`Left${finger}${segment}`, [
+                    new RegExp(`l.*${finger.toLowerCase()}.*${segNum}`, 'i'),
+                    new RegExp(`left.*${finger.toLowerCase()}.*${segment.toLowerCase()}`, 'i'),
+                ]);
+                patterns.set(`Right${finger}${segment}`, [
+                    new RegExp(`r.*${finger.toLowerCase()}.*${segNum}`, 'i'),
+                    new RegExp(`right.*${finger.toLowerCase()}.*${segment.toLowerCase()}`, 'i'),
+                ]);
+            }
+        }
+        return patterns;
+    }
+    buildMirrorPairs() {
+        const pairs = new Map();
+        // Arms
+        pairs.set('LeftShoulder', 'RightShoulder');
+        pairs.set('RightShoulder', 'LeftShoulder');
+        pairs.set('LeftUpperArm', 'RightUpperArm');
+        pairs.set('RightUpperArm', 'LeftUpperArm');
+        pairs.set('LeftLowerArm', 'RightLowerArm');
+        pairs.set('RightLowerArm', 'LeftLowerArm');
+        pairs.set('LeftHand', 'RightHand');
+        pairs.set('RightHand', 'LeftHand');
+        // Legs
+        pairs.set('LeftUpperLeg', 'RightUpperLeg');
+        pairs.set('RightUpperLeg', 'LeftUpperLeg');
+        pairs.set('LeftLowerLeg', 'RightLowerLeg');
+        pairs.set('RightLowerLeg', 'LeftLowerLeg');
+        pairs.set('LeftFoot', 'RightFoot');
+        pairs.set('RightFoot', 'LeftFoot');
+        pairs.set('LeftToes', 'RightToes');
+        pairs.set('RightToes', 'LeftToes');
+        // Fingers
+        const fingers = ['Thumb', 'Index', 'Middle', 'Ring', 'Little'];
+        const segments = ['Proximal', 'Intermediate', 'Distal'];
+        for (const finger of fingers) {
+            for (const segment of segments) {
+                const left = `Left${finger}${segment}`;
+                const right = `Right${finger}${segment}`;
+                pairs.set(left, right);
+                pairs.set(right, left);
+            }
+        }
+        return pairs;
+    }
+    // ─── Skeleton Management ───────────────────────────────
+    registerSkeleton(skeleton) {
+        // Auto-detect humanoid mapping if not provided
+        if (skeleton.isHumanoid && !skeleton.humanoidMapping) {
+            skeleton.humanoidMapping = this.autoDetectHumanoidMapping(skeleton);
+        }
+        this.skeletons.set(skeleton.id, skeleton);
+    }
+    getSkeleton(id) {
+        return this.skeletons.get(id);
+    }
+    createSkeleton(name, bones) {
+        const boneMap = new Map();
+        let rootBoneId = '';
+        for (const bone of bones) {
+            boneMap.set(bone.id, bone);
+            if (!bone.parentId) {
+                rootBoneId = bone.id;
+            }
+        }
+        const skeleton = {
+            id: `skeleton_${Date.now()}`,
+            name,
+            bones: boneMap,
+            rootBoneId,
+            isHumanoid: false,
+            scale: 1,
+            upAxis: 'y',
+            forwardAxis: 'z',
+        };
+        return skeleton;
+    }
+    markAsHumanoid(skeletonId) {
+        const skeleton = this.skeletons.get(skeletonId);
+        if (!skeleton) {
+            return false;
+        }
+        skeleton.isHumanoid = true;
+        skeleton.humanoidMapping = this.autoDetectHumanoidMapping(skeleton);
+        return true;
+    }
+    autoDetectHumanoidMapping(skeleton) {
+        const mapping = new Map();
+        for (const [boneId, bone] of skeleton.bones) {
+            for (const [humanoidBone, patterns] of this.humanoidNamePatterns) {
+                if (mapping.has(humanoidBone)) {
+                    continue;
+                }
+                for (const pattern of patterns) {
+                    if (pattern.test(bone.name)) {
+                        mapping.set(humanoidBone, boneId);
+                        bone.humanoidBone = humanoidBone;
+                        break;
+                    }
+                }
+            }
+        }
+        return mapping;
+    }
+    setHumanoidBoneMapping(skeletonId, humanoidBone, boneId) {
+        const skeleton = this.skeletons.get(skeletonId);
+        if (!skeleton || !skeleton.isHumanoid) {
+            return false;
+        }
+        if (!skeleton.humanoidMapping) {
+            skeleton.humanoidMapping = new Map();
+        }
+        skeleton.humanoidMapping.set(humanoidBone, boneId);
+        const bone = skeleton.bones.get(boneId);
+        if (bone) {
+            bone.humanoidBone = humanoidBone;
+        }
+        return true;
+    }
+    // ─── Retargeting Profile Management ────────────────────
+    createRetargetingProfile(name, sourceSkeletonId, targetSkeletonId) {
+        const source = this.skeletons.get(sourceSkeletonId);
+        const target = this.skeletons.get(targetSkeletonId);
+        if (!source || !target) {
+            return null;
+        }
+        const profile = {
+            id: `profile_${Date.now()}`,
+            name,
+            description: '',
+            sourceSkeletonId,
+            targetSkeletonId,
+            boneMappings: [],
+            globalScale: target.scale / source.scale,
+            globalRotationOffset: MathUtils.quaternionIdentity(),
+            rootMotionScale: MathUtils.vector3One(),
+            preserveHipHeight: true,
+            adjustArmLength: true,
+            adjustLegLength: true,
+            useSourcePose: false,
+            mirrorMode: 'none',
+            useFootIK: false,
+            useHandIK: false,
+            footGroundOffset: 0,
+            createdAt: Date.now(),
+            modifiedAt: Date.now(),
+        };
+        // Auto-generate bone mappings
+        this.autoGenerateMappings(profile, source, target);
+        this.profiles.set(profile.id, profile);
+        return profile;
+    }
+    autoGenerateMappings(profile, source, target) {
+        // Humanoid mapping (preferred)
+        if (source.isHumanoid &&
+            target.isHumanoid &&
+            source.humanoidMapping &&
+            target.humanoidMapping) {
+            for (const [humanoidBone, sourceBoneId] of source.humanoidMapping) {
+                const targetBoneId = target.humanoidMapping.get(humanoidBone);
+                if (targetBoneId) {
+                    const mirrorHumanoidBone = this.mirrorPairs.get(humanoidBone);
+                    profile.boneMappings.push({
+                        sourceBoneId,
+                        targetBoneId,
+                        mappingType: 'direct',
+                        isMirroredPair: mirrorHumanoidBone !== undefined,
+                        mirrorBoneId: target.humanoidMapping.get(mirrorHumanoidBone),
+                    });
+                }
+            }
+            return;
+        }
+        // Fallback: name-based mapping
+        for (const [sourceBoneId, sourceBone] of source.bones) {
+            const targetBoneId = this.findMatchingBone(sourceBone.name, target);
+            if (targetBoneId) {
+                profile.boneMappings.push({
+                    sourceBoneId,
+                    targetBoneId,
+                    mappingType: 'direct',
+                });
+            }
+        }
+    }
+    findMatchingBone(name, skeleton) {
+        const nameLower = name.toLowerCase();
+        // Exact match
+        for (const [boneId, bone] of skeleton.bones) {
+            if (bone.name.toLowerCase() === nameLower) {
+                return boneId;
+            }
+        }
+        // Partial match
+        for (const [boneId, bone] of skeleton.bones) {
+            const boneName = bone.name.toLowerCase();
+            if (boneName.includes(nameLower) || nameLower.includes(boneName)) {
+                return boneId;
+            }
+        }
+        return null;
+    }
+    getProfile(id) {
+        return this.profiles.get(id);
+    }
+    updateProfile(id, updates) {
+        const profile = this.profiles.get(id);
+        if (!profile) {
+            return false;
+        }
+        Object.assign(profile, updates, { modifiedAt: Date.now() });
+        return true;
+    }
+    setBoneMapping(profileId, mapping) {
+        const profile = this.profiles.get(profileId);
+        if (!profile) {
+            return false;
+        }
+        // Replace existing or add new
+        const existingIndex = profile.boneMappings.findIndex((m) => m.sourceBoneId === mapping.sourceBoneId);
+        if (existingIndex !== -1) {
+            profile.boneMappings[existingIndex] = mapping;
+        }
+        else {
+            profile.boneMappings.push(mapping);
+        }
+        profile.modifiedAt = Date.now();
+        return true;
+    }
+    removeBoneMapping(profileId, sourceBoneId) {
+        const profile = this.profiles.get(profileId);
+        if (!profile) {
+            return false;
+        }
+        profile.boneMappings = profile.boneMappings.filter((m) => m.sourceBoneId !== sourceBoneId);
+        profile.modifiedAt = Date.now();
+        return true;
+    }
+    // ─── Animation Clip Management ─────────────────────────
+    registerClip(clip) {
+        this.clips.set(clip.id, clip);
+    }
+    getClip(id) {
+        return this.clips.get(id);
+    }
+    // ─── Retargeting ───────────────────────────────────────
+    retargetClip(clipId, profileId) {
+        const result = {
+            success: false,
+            warnings: [],
+            errors: [],
+            unmappedBones: [],
+            scaleDifferences: new Map(),
+        };
+        const clip = this.clips.get(clipId);
+        const profile = this.profiles.get(profileId);
+        if (!clip) {
+            result.errors.push(`Animation clip not found: ${clipId}`);
+            return result;
+        }
+        if (!profile) {
+            result.errors.push(`Retargeting profile not found: ${profileId}`);
+            return result;
+        }
+        if (clip.sourceSkeletonId !== profile.sourceSkeletonId) {
+            result.warnings.push('Clip source skeleton does not match profile source skeleton');
+        }
+        const sourceSkeleton = this.skeletons.get(profile.sourceSkeletonId);
+        const targetSkeleton = this.skeletons.get(profile.targetSkeletonId);
+        if (!sourceSkeleton || !targetSkeleton) {
+            result.errors.push('Source or target skeleton not found');
+            return result;
+        }
+        // Create mapping lookup
+        const boneMapping = new Map();
+        for (const mapping of profile.boneMappings) {
+            boneMapping.set(mapping.sourceBoneId, mapping);
+        }
+        // Retarget tracks
+        const retargetedTracks = [];
+        for (const track of clip.tracks) {
+            const mapping = boneMapping.get(track.boneId);
+            if (!mapping) {
+                result.unmappedBones.push(track.boneId);
+                continue;
+            }
+            if (mapping.mappingType === 'ignore') {
+                continue;
+            }
+            const retargetedTrack = this.retargetTrack(track, mapping, profile, sourceSkeleton, targetSkeleton);
+            if (retargetedTrack) {
+                retargetedTracks.push(retargetedTrack);
+                // Handle mirroring
+                if (profile.mirrorMode !== 'none' && mapping.isMirroredPair && mapping.mirrorBoneId) {
+                    const mirroredTrack = this.mirrorTrack(retargetedTrack, mapping.mirrorBoneId, profile.mirrorMode);
+                    retargetedTracks.push(mirroredTrack);
+                }
+            }
+        }
+        // Create retargeted clip
+        const retargetedClip = {
+            id: `${clip.id}_retargeted_${Date.now()}`,
+            name: `${clip.name} (Retargeted)`,
+            duration: clip.duration,
+            frameRate: clip.frameRate,
+            tracks: retargetedTracks,
+            hasRootMotion: clip.hasRootMotion,
+            isLooping: clip.isLooping,
+            loopTime: clip.loopTime,
+            events: clip.events ? [...clip.events] : undefined,
+            sourceSkeletonId: profile.targetSkeletonId,
+        };
+        // Handle root motion
+        if (clip.hasRootMotion && clip.rootMotionBoneId) {
+            const rootMapping = boneMapping.get(clip.rootMotionBoneId);
+            if (rootMapping) {
+                retargetedClip.rootMotionBoneId = rootMapping.targetBoneId;
+                this.adjustRootMotion(retargetedClip, profile);
+            }
+        }
+        result.success = true;
+        result.clip = retargetedClip;
+        // Register the new clip
+        this.clips.set(retargetedClip.id, retargetedClip);
+        return result;
+    }
+    retargetTrack(track, mapping, profile, sourceSkeleton, targetSkeleton) {
+        const retargetedTrack = {
+            boneId: mapping.targetBoneId,
+            property: track.property,
+            keyframes: [],
+            blendShapeName: track.blendShapeName,
+        };
+        const sourceBone = sourceSkeleton.bones.get(track.boneId);
+        const targetBone = targetSkeleton.bones.get(mapping.targetBoneId);
+        if (!sourceBone || !targetBone) {
+            return null;
+        }
+        for (const keyframe of track.keyframes) {
+            const retargetedKeyframe = this.retargetKeyframe(keyframe, track.property, mapping, profile, sourceBone, targetBone);
+            retargetedTrack.keyframes.push(retargetedKeyframe);
+        }
+        return retargetedTrack;
+    }
+    retargetKeyframe(keyframe, property, mapping, profile, sourceBone, targetBone) {
+        const retargeted = {
+            time: keyframe.time,
+            value: keyframe.value,
+            interpolation: keyframe.interpolation,
+            inTangent: keyframe.inTangent,
+            outTangent: keyframe.outTangent,
+        };
+        switch (property) {
+            case 'rotation':
+                retargeted.value = this.retargetRotation(keyframe.value, mapping, profile);
+                break;
+            case 'position':
+                retargeted.value = this.retargetPosition(keyframe.value, mapping, profile, sourceBone, targetBone);
+                break;
+            case 'scale':
+                retargeted.value = this.retargetScale(keyframe.value, mapping);
+                break;
+        }
+        return retargeted;
+    }
+    retargetRotation(rotation, mapping, profile) {
+        let result = rotation;
+        // Apply global rotation offset
+        result = MathUtils.multiplyQuaternion(profile.globalRotationOffset, result);
+        // Apply bone-specific rotation offset
+        if (mapping.rotationOffset) {
+            result = MathUtils.multiplyQuaternion(mapping.rotationOffset, result);
+        }
+        return MathUtils.normalizeQuaternion(result);
+    }
+    retargetPosition(position, mapping, profile, sourceBone, targetBone) {
+        let result = { ...position };
+        // Apply global scale
+        result = MathUtils.multiplyVector3(result, profile.globalScale);
+        // Apply bone length difference
+        if (profile.adjustArmLength || profile.adjustLegLength) {
+            const lengthRatio = targetBone.length / (sourceBone.length || 1);
+            result = MathUtils.multiplyVector3(result, lengthRatio);
+        }
+        // Apply bone-specific offset
+        if (mapping.positionOffset) {
+            result = MathUtils.addVector3(result, mapping.positionOffset);
+        }
+        return result;
+    }
+    retargetScale(scale, mapping) {
+        if (mapping.scaleMultiplier) {
+            return {
+                x: scale.x * mapping.scaleMultiplier.x,
+                y: scale.y * mapping.scaleMultiplier.y,
+                z: scale.z * mapping.scaleMultiplier.z,
+            };
+        }
+        return scale;
+    }
+    mirrorTrack(track, mirrorBoneId, mode) {
+        const mirroredTrack = {
+            boneId: mirrorBoneId,
+            property: track.property,
+            keyframes: [],
+            blendShapeName: track.blendShapeName,
+        };
+        for (const keyframe of track.keyframes) {
+            const mirroredKeyframe = {
+                time: keyframe.time,
+                interpolation: keyframe.interpolation,
+                inTangent: keyframe.inTangent,
+                outTangent: keyframe.outTangent,
+                value: keyframe.value,
+            };
+            if (track.property === 'rotation') {
+                mirroredKeyframe.value =
+                    mode === 'x' ? MathUtils.mirrorQuaternionX(keyframe.value) : keyframe.value; // TODO: Z mirroring
+            }
+            else if (track.property === 'position') {
+                mirroredKeyframe.value =
+                    mode === 'x' ? MathUtils.mirrorVector3X(keyframe.value) : keyframe.value; // TODO: Z mirroring
+            }
+            mirroredTrack.keyframes.push(mirroredKeyframe);
+        }
+        return mirroredTrack;
+    }
+    adjustRootMotion(clip, profile) {
+        if (!clip.rootMotionBoneId) {
+            return;
+        }
+        // Find root motion track
+        const rootTrack = clip.tracks.find((t) => t.boneId === clip.rootMotionBoneId && t.property === 'position');
+        if (!rootTrack) {
+            return;
+        }
+        // Apply root motion scale
+        for (const keyframe of rootTrack.keyframes) {
+            const pos = keyframe.value;
+            keyframe.value = {
+                x: pos.x * profile.rootMotionScale.x,
+                y: pos.y * profile.rootMotionScale.y,
+                z: pos.z * profile.rootMotionScale.z,
+            };
+        }
+    }
+    // ─── Utilities ─────────────────────────────────────────
+    getBoneHierarchy(skeletonId) {
+        const skeleton = this.skeletons.get(skeletonId);
+        if (!skeleton) {
+            return [];
+        }
+        const buildHierarchy = (boneId) => {
+            const bone = skeleton.bones.get(boneId);
+            return {
+                id: bone.id,
+                name: bone.name,
+                humanoidBone: bone.humanoidBone,
+                children: bone.children.map((childId) => buildHierarchy(childId)),
+            };
+        };
+        return [buildHierarchy(skeleton.rootBoneId)];
+    }
+    getMappingVisualization(profileId) {
+        const profile = this.profiles.get(profileId);
+        if (!profile) {
+            return [];
+        }
+        const source = this.skeletons.get(profile.sourceSkeletonId);
+        const target = this.skeletons.get(profile.targetSkeletonId);
+        if (!source || !target) {
+            return [];
+        }
+        return profile.boneMappings.map((mapping) => {
+            const sourceBone = source.bones.get(mapping.sourceBoneId);
+            const targetBone = target.bones.get(mapping.targetBoneId);
+            return {
+                sourceBoneId: mapping.sourceBoneId,
+                sourceBoneName: sourceBone?.name ?? 'Unknown',
+                targetBoneId: mapping.targetBoneId,
+                targetBoneName: targetBone?.name ?? 'Unknown',
+                mappingType: mapping.mappingType,
+                hasOffset: !!mapping.rotationOffset || !!mapping.positionOffset,
+                isMirrorPair: mapping.isMirroredPair ?? false,
+            };
+        });
+    }
+    // ─── Serialization ─────────────────────────────────────
+    serializeProfile(profileId) {
+        const profile = this.profiles.get(profileId);
+        if (!profile) {
+            return null;
+        }
+        return JSON.stringify(profile, null, 2);
+    }
+    deserializeProfile(json) {
+        try {
+            const profile = JSON.parse(json);
+            this.profiles.set(profile.id, profile);
+            return profile;
+        }
+        catch {
+            return null;
+        }
+    }
+    serializeSkeleton(skeletonId) {
+        const skeleton = this.skeletons.get(skeletonId);
+        if (!skeleton) {
+            return null;
+        }
+        const data = {
+            ...skeleton,
+            bones: Object.fromEntries(skeleton.bones),
+            humanoidMapping: skeleton.humanoidMapping
+                ? Object.fromEntries(skeleton.humanoidMapping)
+                : undefined,
+            tPose: skeleton.tPose ? Object.fromEntries(skeleton.tPose) : undefined,
+        };
+        return JSON.stringify(data, null, 2);
+    }
+    deserializeSkeleton(json) {
+        try {
+            const data = JSON.parse(json);
+            const skeleton = {
+                ...data,
+                bones: new Map(Object.entries(data.bones)),
+                humanoidMapping: data.humanoidMapping
+                    ? new Map(Object.entries(data.humanoidMapping))
+                    : undefined,
+                tPose: data.tPose ? new Map(Object.entries(data.tPose)) : undefined,
+            };
+            this.skeletons.set(skeleton.id, skeleton);
+            return skeleton;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ============================================================
+// Factory Functions
+// ============================================================
+function createAnimationRetargeting() {
+    return new AnimationRetargeting();
+}
+function createBone(name, parentId = null, transform) {
+    return {
+        id: `bone_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+        name,
+        parentId,
+        localTransform: {
+            position: transform?.position ?? MathUtils.vector3Zero(),
+            rotation: transform?.rotation ?? MathUtils.quaternionIdentity(),
+            scale: transform?.scale ?? MathUtils.vector3One(),
+        },
+        length: 1,
+        children: [],
+    };
+}
+
+exports.AnimationRetargeting = AnimationRetargeting;
+exports.createAnimationRetargeting = createAnimationRetargeting;
+exports.createBone = createBone;
+//# sourceMappingURL=AnimationRetargeting.js.map