@onerjs/core 8.51.4 → 8.51.5

package/Animations/animatorAvatar.d.ts

@@ -173,6 +173,8 @@ export declare class AnimatorAvatar {
     private _checkParentHierarchy;
     private _getRootNodeName;
     private _findVerticalAxis;
+    private _captureAvatarSkeletonStates;
+    private _restoreAvatarSkeletonStates;
     private _resetStates;
     private _fixRootPosition;
     private _fixGroundReference;

package/Animations/animatorAvatar.js

@@ -123,115 +123,133 @@ export class AnimatorAvatar {
             fixRootPosition: true,
             ...options,
         };
-        // Make sure that all world matrices are up to date, both in the bone hierarchy and in the animation transform node hierarchy
-        this._computeBoneWorldMatrices();
-        const mapNodeNames = localOptions.mapNodeNames ?? new Map();
-        const lstSourceTransformNodes = new Set();
-        const sourceTransformNodeNameToNode = new Map();
-        for (let i = 0; i < sourceAnimationGroup.targetedAnimations.length; ++i) {
-            const ta = sourceAnimationGroup.targetedAnimations[i];
-            if (ta.target.getClassName?.() === "TransformNode" && !lstSourceTransformNodes.has(ta.target)) {
-                const tn = ta.target;
-                lstSourceTransformNodes.add(tn);
-                sourceTransformNodeNameToNode.set(mapNodeNames.get(tn.name) ?? tn.name, {
-                    node: tn,
-                    initialTransformations: {
-                        position: tn.position.clone(),
-                        scaling: tn.scaling.clone(),
-                        quaternion: tn.rotationQuaternion?.clone(),
-                        rotation: tn.rotation.clone(),
-                    },
-                });
-                if (!tn.rotationQuaternion) {
-                    tn.rotationQuaternion = Quaternion.FromEulerAngles(tn.rotation.x, tn.rotation.y, tn.rotation.z);
-                    tn.rotation.setAll(0);
-                }
-            }
-        }
-        lstSourceTransformNodes.forEach((node) => {
-            node.computeWorldMatrix(true);
-        });
-        // Clone the source animation and retarget it
-        const animationGroup = sourceAnimationGroup.clone(localOptions.animationGroupName, undefined, true, true);
-        const mapTransformNodeToRootNode = new Map();
-        const lstAnims = new Set();
-        for (let i = 0; i < animationGroup.targetedAnimations.length; ++i) {
-            const ta = animationGroup.targetedAnimations[i];
-            const animation = ta.animation;
-            if (lstAnims.has(animation)) {
-                if (this.showWarnings) {
-                    Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': animation '${animation.name}' is used multiple times in the same animation group: duplicated animations are not supported, the retargeted animation may not work as expected.`);
+        // Capture the avatar's current bone state so we can restore it before returning.
+        // _computeBoneWorldMatrices() (called next) returns the skeletons to rest, and the
+        // optional _fixRootPosition / _fixGroundReference helpers further drive the bones via
+        // an internal play / goToFrame loop. Without restoring afterwards, any animation
+        // already playing on the avatar gets clobbered (typically visible as a snap to the
+        // rest pose the moment that animation is later stopped). The restore is wrapped in
+        // a try/finally so the avatar is also reset if the body throws.
+        const avatarSkeletonStates = this._captureAvatarSkeletonStates();
+        try {
+            // Make sure that all world matrices are up to date, both in the bone hierarchy and in the animation transform node hierarchy
+            this._computeBoneWorldMatrices();
+            const mapNodeNames = localOptions.mapNodeNames ?? new Map();
+            const lstSourceTransformNodes = new Set();
+            const sourceTransformNodeNameToNode = new Map();
+            for (let i = 0; i < sourceAnimationGroup.targetedAnimations.length; ++i) {
+                const ta = sourceAnimationGroup.targetedAnimations[i];
+                if (ta.target.getClassName?.() === "TransformNode" && !lstSourceTransformNodes.has(ta.target)) {
+                    const tn = ta.target;
+                    lstSourceTransformNodes.add(tn);
+                    sourceTransformNodeNameToNode.set(mapNodeNames.get(tn.name) ?? tn.name, {
+                        node: tn,
+                        initialTransformations: {
+                            position: tn.position.clone(),
+                            scaling: tn.scaling.clone(),
+                            quaternion: tn.rotationQuaternion?.clone(),
+                            rotation: tn.rotation.clone(),
+                        },
+                    });
+                    if (!tn.rotationQuaternion) {
+                        tn.rotationQuaternion = Quaternion.FromEulerAngles(tn.rotation.x, tn.rotation.y, tn.rotation.z);
+                        tn.rotation.setAll(0);
+                    }
                 }
             }
-            lstAnims.add(animation);
-            switch (animation.targetProperty) {
-                case "influence": {
-                    if (!this._retargetMorphTarget(ta, animationGroup.name)) {
-                        animationGroup.targetedAnimations.splice(i, 1);
-                        i--;
+            lstSourceTransformNodes.forEach((node) => {
+                node.computeWorldMatrix(true);
+            });
+            // Clone the source animation and retarget it
+            const animationGroup = sourceAnimationGroup.clone(localOptions.animationGroupName, undefined, true, true);
+            const mapTransformNodeToRootNode = new Map();
+            const lstAnims = new Set();
+            for (let i = 0; i < animationGroup.targetedAnimations.length; ++i) {
+                const ta = animationGroup.targetedAnimations[i];
+                const animation = ta.animation;
+                if (lstAnims.has(animation)) {
+                    if (this.showWarnings) {
+                        Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': animation '${animation.name}' is used multiple times in the same animation group: duplicated animations are not supported, the retargeted animation may not work as expected.`);
                     }
-                    break;
                 }
-                case "position":
-                case "rotationQuaternion":
-                case "scaling": {
-                    if (ta.target.getClassName?.() !== "TransformNode") {
+                lstAnims.add(animation);
+                switch (animation.targetProperty) {
+                    case "influence": {
+                        if (!this._retargetMorphTarget(ta, animationGroup.name)) {
+                            animationGroup.targetedAnimations.splice(i, 1);
+                            i--;
+                        }
                         break;
                     }
-                    const sourceTransformNode = ta.target;
-                    const sourceTransformNodeName = mapNodeNames.get(sourceTransformNode.name) ?? sourceTransformNode.name;
-                    let targetBone = this.findBoneByTransformNode(sourceTransformNodeName);
-                    if (!targetBone) {
-                        targetBone = this.findBoneByName(sourceTransformNodeName);
-                    }
-                    if (!targetBone) {
-                        if (this.showWarnings) {
-                            Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': "${sourceTransformNodeName}" bone not found in any skeleton of avatar: animation removed.`);
+                    case "position":
+                    case "rotationQuaternion":
+                    case "scaling": {
+                        if (ta.target.getClassName?.() !== "TransformNode") {
+                            break;
+                        }
+                        const sourceTransformNode = ta.target;
+                        const sourceTransformNodeName = mapNodeNames.get(sourceTransformNode.name) ?? sourceTransformNode.name;
+                        let targetBone = this.findBoneByTransformNode(sourceTransformNodeName);
+                        if (!targetBone) {
+                            targetBone = this.findBoneByName(sourceTransformNodeName);
+                        }
+                        if (!targetBone) {
+                            if (this.showWarnings) {
+                                Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': "${sourceTransformNodeName}" bone not found in any skeleton of avatar: animation removed.`);
+                            }
+                            animationGroup.targetedAnimations.splice(i, 1);
+                            i--;
+                            break;
+                        }
+                        if (!this._retargetTransformNodeToBone(ta, sourceTransformNode, targetBone, animationGroup.name, mapTransformNodeToRootNode, mapNodeNames, !!localOptions.checkHierarchy)) {
+                            animationGroup.targetedAnimations.splice(i, 1);
+                            i--;
+                        }
+                        else if (localOptions.retargetAnimationKeys) {
+                            this._retargetAnimationKeys(ta.animation, sourceTransformNode, targetBone);
                         }
-                        animationGroup.targetedAnimations.splice(i, 1);
-                        i--;
                         break;
                     }
-                    if (!this._retargetTransformNodeToBone(ta, sourceTransformNode, targetBone, animationGroup.name, mapTransformNodeToRootNode, mapNodeNames, !!localOptions.checkHierarchy)) {
-                        animationGroup.targetedAnimations.splice(i, 1);
-                        i--;
-                    }
-                    else if (localOptions.retargetAnimationKeys) {
-                        this._retargetAnimationKeys(ta.animation, sourceTransformNode, targetBone);
-                    }
-                    break;
                 }
             }
-        }
-        if (localOptions.fixAnimations) {
-            this._fixAnimationGroup(animationGroup);
-        }
-        if (localOptions.fixGroundReference || localOptions.fixRootPosition) {
-            const msg = localOptions.fixGroundReference && localOptions.fixRootPosition
-                ? "Ground reference and root position fixing processes skipped."
-                : localOptions.fixGroundReference
-                    ? "Ground reference fixing process skipped."
-                    : "Root position fixing process skipped.";
-            const res = this._findVerticalAxis(msg, animationGroup, mapNodeNames.get(localOptions.rootNodeName) ?? localOptions.rootNodeName, sourceTransformNodeNameToNode, mapNodeNames.get(localOptions.groundReferenceNodeName) ?? localOptions.groundReferenceNodeName, localOptions.groundReferenceVerticalAxis);
-            if (res) {
-                const { verticalAxis, sourceRootTransformNode, targetRootTransformNodeOrBone, targetRootPositionAnimation, sourceGroundReferenceTransformNode, targetGroundReferenceTransformNodeOrBone, proportionRatio, } = res;
-                if (localOptions.fixRootPosition) {
-                    this._fixRootPosition(sourceAnimationGroup, animationGroup, sourceRootTransformNode, targetRootTransformNodeOrBone, targetRootPositionAnimation, proportionRatio);
-                    this._resetStates(sourceTransformNodeNameToNode);
-                }
-                const fixGroundReferenceDynamicRefNode = !!localOptions.fixGroundReferenceDynamicRefNode;
-                if (localOptions.fixGroundReference) {
-                    this._fixGroundReference(sourceAnimationGroup, animationGroup, verticalAxis, targetRootTransformNodeOrBone, targetRootPositionAnimation, sourceGroundReferenceTransformNode, targetGroundReferenceTransformNodeOrBone, lstSourceTransformNodes, mapNodeNames, fixGroundReferenceDynamicRefNode);
-                    this._resetStates(sourceTransformNodeNameToNode);
-                }
-                else if (fixGroundReferenceDynamicRefNode) {
-                    if (this.showWarnings) {
-                        Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': fixGroundReferenceDynamicRefNode option is set to true but fixGroundReference is false: dynamic ground reference node fixing process skipped.`);
+            if (localOptions.fixAnimations) {
+                this._fixAnimationGroup(animationGroup);
+            }
+            if (localOptions.fixGroundReference || localOptions.fixRootPosition) {
+                const msg = localOptions.fixGroundReference && localOptions.fixRootPosition
+                    ? "Ground reference and root position fixing processes skipped."
+                    : localOptions.fixGroundReference
+                        ? "Ground reference fixing process skipped."
+                        : "Root position fixing process skipped.";
+                const res = this._findVerticalAxis(msg, animationGroup, mapNodeNames.get(localOptions.rootNodeName) ?? localOptions.rootNodeName, sourceTransformNodeNameToNode, mapNodeNames.get(localOptions.groundReferenceNodeName) ?? localOptions.groundReferenceNodeName, localOptions.groundReferenceVerticalAxis);
+                if (res) {
+                    const { verticalAxis, sourceRootTransformNode, targetRootTransformNodeOrBone, targetRootPositionAnimation, sourceGroundReferenceTransformNode, targetGroundReferenceTransformNodeOrBone, proportionRatio, } = res;
+                    if (localOptions.fixRootPosition) {
+                        this._fixRootPosition(sourceAnimationGroup, animationGroup, sourceRootTransformNode, targetRootTransformNodeOrBone, targetRootPositionAnimation, proportionRatio);
+                        this._resetStates(sourceTransformNodeNameToNode);
+                    }
+                    const fixGroundReferenceDynamicRefNode = !!localOptions.fixGroundReferenceDynamicRefNode;
+                    if (localOptions.fixGroundReference) {
+                        this._fixGroundReference(sourceAnimationGroup, animationGroup, verticalAxis, targetRootTransformNodeOrBone, targetRootPositionAnimation, sourceGroundReferenceTransformNode, targetGroundReferenceTransformNodeOrBone, lstSourceTransformNodes, mapNodeNames, fixGroundReferenceDynamicRefNode);
+                        this._resetStates(sourceTransformNodeNameToNode);
+                    }
+                    else if (fixGroundReferenceDynamicRefNode) {
+                        if (this.showWarnings) {
+                            Logger.Warn(`RetargetAnimationGroup - Avatar '${this.name}', AnimationGroup '${animationGroup.name}': fixGroundReferenceDynamicRefNode option is set to true but fixGroundReference is false: dynamic ground reference node fixing process skipped.`);
+                        }
                     }
                 }
             }
+            return animationGroup;
+        }
+        finally {
+            // Restore the avatar's bones to their pre-call state. The internal helpers above
+            // (_computeBoneWorldMatrices and, when enabled, _fixRootPosition / _fixGroundReference)
+            // overwrite the bone transforms; without restoring, any animation already driving the
+            // avatar appears clobbered (visible as a snap to rest pose the moment that animation
+            // is later stopped). Running in finally also makes sure we restore on exception.
+            this._restoreAvatarSkeletonStates(avatarSkeletonStates);
         }
-        return animationGroup;
     }
     /**
      * Disposes of the avatar and releases all associated resources.
@@ -534,6 +552,57 @@ export class AnimatorAvatar {
             proportionRatio: sourceDiff !== 0 ? targetDiff / sourceDiff : 1.0,
         };
     }
+    _captureAvatarSkeletonStates() {
+        const transformNodeStates = new Map();
+        const boneMatrices = new Map();
+        this.skeletons.forEach((skeleton) => {
+            for (const bone of skeleton.bones) {
+                const linkedNode = bone._linkedTransformNode;
+                if (linkedNode) {
+                    transformNodeStates.set(linkedNode, {
+                        position: linkedNode.position.clone(),
+                        scaling: linkedNode.scaling.clone(),
+                        quaternion: linkedNode.rotationQuaternion?.clone(),
+                        rotation: linkedNode.rotation.clone(),
+                    });
+                }
+                else {
+                    boneMatrices.set(bone, bone.getLocalMatrix().clone());
+                }
+            }
+        });
+        return { transformNodeStates, boneMatrices };
+    }
+    _restoreAvatarSkeletonStates(states) {
+        states.transformNodeStates.forEach((data, node) => {
+            node.position.copyFrom(data.position);
+            node.scaling.copyFrom(data.scaling);
+            if (data.quaternion) {
+                // Snapshot was using a quaternion: ensure the node still has one and restore it.
+                // _computeBoneWorldMatrices() can null/replace it via Bone.returnToRest, so we can't
+                // assume node.rotationQuaternion is the same instance (or non-null) we captured.
+                if (node.rotationQuaternion) {
+                    node.rotationQuaternion.copyFrom(data.quaternion);
+                }
+                else {
+                    node.rotationQuaternion = data.quaternion.clone();
+                }
+            }
+            else {
+                // Snapshot was using Euler rotation: clear any quaternion that may have been
+                // assigned in the meantime (Babylon ignores rotation when rotationQuaternion is set).
+                node.rotationQuaternion = null;
+                node.rotation.copyFrom(data.rotation);
+            }
+            node.computeWorldMatrix(true);
+        });
+        states.boneMatrices.forEach((matrix, bone) => {
+            bone._matrix = matrix;
+        });
+        // Re-prepare each skeleton so the restored bone state takes effect immediately
+        // rather than being left as stale world/final matrices until the next frame.
+        this.skeletons.forEach((skeleton) => skeleton.prepare(true));
+    }
     _resetStates(sourceTransformNodeNameToNode) {
         this.skeletons.forEach((skeleton) => skeleton.returnToRest());
         sourceTransformNodeNameToNode.forEach((data) => {