@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/animation/animationset.js

@@ -7,6 +7,7 @@ import { NodeScaleTrack } from './scaletrack.js';
 import { MorphTargetGroupTrack } from './morphtargetgrouptrack.js';
 import { HumanoidBodyRig } from './skeleton.js';
 import { createSkeletalMaskedAnimationClip } from './animationmask.js';
+import { GpuAnimationDriver } from './gpu_animation_driver.js';
 
 let nextAnimationPlaybackId = 1;
 /**
@@ -236,6 +237,8 @@ function cloneInterpolator(src) {
 function createJointRetargetRemap(srcSkeleton, dstSkeleton, srcJoint, dstJoint, translationRotation, translationScale, translationCorrection, translationAxisLocks, rotationCorrection) {
     const si = srcSkeleton.joints.indexOf(srcJoint);
     const di = dstSkeleton.joints.indexOf(dstJoint);
+    const srcReferencePose = srcSkeleton.retargetPose[si];
+    const dstReferencePose = dstSkeleton.retargetPose[di];
     const srcBindPose = srcSkeleton.bindPose[si];
     const dstBindPose = dstSkeleton.bindPose[di];
     const srcLen = srcBindPose.position.magnitude;
@@ -244,10 +247,10 @@ function createJointRetargetRemap(srcSkeleton, dstSkeleton, srcJoint, dstJoint,
         dstNode: dstJoint,
         dstJointIndex: di,
         srcNode: srcJoint,
-        srcBindRotInv: Quaternion.inverse(srcBindPose.rotation),
-        dstBindRot: dstBindPose.rotation.clone(),
+        srcBindRotInv: Quaternion.inverse(srcReferencePose.rotation),
+        dstBindRot: dstReferencePose.rotation.clone(),
         rotationCorrection,
-        srcBindPos: srcBindPose.position.clone(),
+        srcBindPos: srcReferencePose.position.clone(),
         dstBindPos: dstBindPose.position.clone(),
         translationScale: translationScale ?? (srcLen > 1e-6 ? dstLen / srcLen : 1),
         translationRotation,
@@ -275,15 +278,14 @@ function getBindPosition(skeleton, joint) {
     const index = skeleton.joints.indexOf(joint);
     return index >= 0 ? skeleton.bindPose[index].position : null;
 }
-function getSkeletonLocalBindTransform(skeleton, node, jointSet, cache) {
+function getSkeletonLocalReferenceTransform(skeleton, node, jointSet, cache) {
     let transform = cache.get(node);
     if (!transform) {
-        const bindPose = getRigBindPoseForNode(skeleton, node);
-        const position = bindPose.position.clone();
-        const rotation = bindPose.rotation.clone();
+        const position = getRigBindPoseForNode(skeleton, node).position.clone();
+        const rotation = getRigReferencePoseForNode(skeleton, node).rotation.clone();
         const parent = node.parent;
         if (parent && jointSet.has(parent)) {
-            const parentTransform = getSkeletonLocalBindTransform(skeleton, parent, jointSet, cache);
+            const parentTransform = getSkeletonLocalReferenceTransform(skeleton, parent, jointSet, cache);
             parentTransform.rotation.transform(position, position);
             position.addBy(parentTransform.position);
             Quaternion.multiply(parentTransform.rotation, rotation, rotation);
@@ -345,7 +347,7 @@ function getHumanoidLateralXSign(skeleton) {
         if (!left || !right || !jointSet.has(left) || !jointSet.has(right)) {
             continue;
         }
-        const dx = getSkeletonLocalBindTransform(skeleton, left, jointSet, cache).position.x - getSkeletonLocalBindTransform(skeleton, right, jointSet, cache).position.x;
+        const dx = getSkeletonLocalReferenceTransform(skeleton, left, jointSet, cache).position.x - getSkeletonLocalReferenceTransform(skeleton, right, jointSet, cache).position.x;
         if (Math.abs(dx) > 1e-5) {
             score += dx;
             weight++;
@@ -381,7 +383,7 @@ function getHumanoidForwardZSign(skeleton) {
         if (!foot || !toes || !jointSet.has(foot) || !jointSet.has(toes)) {
             continue;
         }
-        const dz = getSkeletonLocalBindTransform(skeleton, toes, jointSet, cache).position.z - getSkeletonLocalBindTransform(skeleton, foot, jointSet, cache).position.z;
+        const dz = getSkeletonLocalReferenceTransform(skeleton, toes, jointSet, cache).position.z - getSkeletonLocalReferenceTransform(skeleton, foot, jointSet, cache).position.z;
         if (Math.abs(dz) > 1e-5) {
             score += dz;
             weight++;
@@ -420,6 +422,13 @@ function getHumanoidRotationCorrection(srcSkeleton, dstSkeleton, srcSignSkeleton
         z: determinant * axisZSign
     };
 }
+function getRigReferencePoseForNode(skeleton, node) {
+    return skeleton.getRetargetPoseForJoint(node) ?? (node === skeleton.rootJoint ? skeleton.rootBindPose : {
+        position: node.position,
+        rotation: node.rotation,
+        scale: node.scale
+    });
+}
 function getRigBindPoseForNode(skeleton, node) {
     return skeleton.getBindPoseForJoint(node) ?? (node === skeleton.rootJoint ? skeleton.rootBindPose : {
         position: node.position,
@@ -463,11 +472,36 @@ function getHumanoidRootMotionScale(srcSkeleton, dstSkeleton) {
 function findTranslationTrack(tracks) {
     return tracks?.find((track)=>track instanceof NodeTranslationTrack) ?? null;
 }
-function findAncestorTranslationTrack(clip, node, modelRoot) {
+function isTranslationTrackAnimated(track) {
+    const inputs = track.interpolator.inputs;
+    const outputs = track.interpolator.outputs;
+    const cubic = track.interpolator.mode === 'cubicspline';
+    const stride = cubic ? 9 : 3;
+    const valueOffset = cubic ? 3 : 0;
+    if (inputs.length < 2) {
+        return false;
+    }
+    const first = [
+        outputs[valueOffset],
+        outputs[valueOffset + 1],
+        outputs[valueOffset + 2]
+    ];
+    let maxValue = Math.max(1, Math.abs(first[0]), Math.abs(first[1]), Math.abs(first[2]));
+    let maxDelta = 0;
+    for(let i = 1; i < inputs.length; i++){
+        const base = i * stride + valueOffset;
+        for(let axis = 0; axis < 3; axis++){
+            maxValue = Math.max(maxValue, Math.abs(outputs[base + axis]));
+            maxDelta = Math.max(maxDelta, Math.abs(outputs[base + axis] - first[axis]));
+        }
+    }
+    return maxDelta > maxValue * 1e-5;
+}
+function findAncestorTranslationTrack(clip, node, modelRoot, animatedOnly = false) {
     let current = node.parent;
     while(current){
         const track = findTranslationTrack(clip.tracks.get(current));
-        if (track) {
+        if (track && (!animatedOnly || isTranslationTrackAnimated(track))) {
             return {
                 node: current,
                 track
@@ -667,18 +701,20 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     const remapsByDstNode = new Map();
     const srcJointSet = new Set(srcSkeleton.joints);
     const dstJointSet = new Set(dstSkeleton.joints);
-    const srcBindRotByNode = new Map();
-    const dstBindRotByNode = new Map();
+    const srcReferenceRotByNode = new Map();
+    const srcBaseRotByNode = new Map();
+    const dstReferenceRotByNode = new Map();
     const srcRotationTrackByNode = new Map();
     for(let i = 0; i < srcSkeleton.joints.length; i++){
         const joint = srcSkeleton.joints[i];
-        srcBindRotByNode.set(joint, srcSkeleton.bindPose[i].rotation);
+        srcReferenceRotByNode.set(joint, srcSkeleton.retargetPose[i].rotation);
+        srcBaseRotByNode.set(joint, srcSkeleton.bindPose[i].rotation);
         const track = findRotationTrack(sourceClip.tracks.get(joint));
         srcRotationTrackByNode.set(joint, track);
         collectTrackTimes(track, times);
     }
     for(let i = 0; i < dstSkeleton.joints.length; i++){
-        dstBindRotByNode.set(dstSkeleton.joints[i], dstSkeleton.bindPose[i].rotation);
+        dstReferenceRotByNode.set(dstSkeleton.joints[i], dstSkeleton.retargetPose[i].rotation);
     }
     for (const remap of remaps){
         const track = findRotationTrack(sourceClip.tracks.get(remap.srcNode));
@@ -705,7 +741,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     function getSrcBindWorldRot(node) {
         let rot = srcBindWorldRots.get(node);
         if (!rot) {
-            rot = (srcBindRotByNode.get(node) ?? Quaternion.identity()).clone();
+            rot = (srcReferenceRotByNode.get(node) ?? Quaternion.identity()).clone();
             const parent = node.parent;
             if (parent && srcJointSet.has(parent)) {
                 Quaternion.multiply(getSrcBindWorldRot(parent), rot, rot);
@@ -719,7 +755,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     function getDstBindWorldRot(node) {
         let rot = dstBindWorldRots.get(node);
         if (!rot) {
-            rot = (dstBindRotByNode.get(node) ?? Quaternion.identity()).clone();
+            rot = (dstReferenceRotByNode.get(node) ?? Quaternion.identity()).clone();
             const parent = node.parent;
             if (parent && dstJointSet.has(parent)) {
                 Quaternion.multiply(getDstBindWorldRot(parent), rot, rot);
@@ -738,7 +774,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
         const parent = node.parent;
         const parentWorldRot = parent && srcJointSet.has(parent) ? getSrcAnimWorldRot(parent, time) : null;
-        sampleRotationTrack(srcRotationTrackByNode.get(node) ?? null, time, srcBindRotByNode.get(node) ?? Quaternion.identity(), tmpLocalRot);
+        sampleRotationTrack(srcRotationTrackByNode.get(node) ?? null, time, srcBaseRotByNode.get(node) ?? Quaternion.identity(), tmpLocalRot);
         if (parentWorldRot) {
             Quaternion.multiply(parentWorldRot, tmpLocalRot, rot);
         } else {
@@ -776,7 +812,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
         let rot = dstAnimWorldRots.get(parent);
         if (!rot) {
-            rot = (dstBindRotByNode.get(parent) ?? Quaternion.identity()).clone();
+            rot = (dstReferenceRotByNode.get(parent) ?? Quaternion.identity()).clone();
             const parentWorldRot = getDstParentAnimWorldRot(parent, time);
             if (parentWorldRot) {
                 Quaternion.multiply(parentWorldRot, rot, rot);
@@ -802,7 +838,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
     }
     for (const remap of remaps){
-        if (!rotationTracksByRemap.get(remap)) {
+        if (!rotationTracksByRemap.get(remap) && !srcSkeleton.hasRetargetPose && !dstSkeleton.hasRetargetPose) {
             continue;
         }
         const outputs = new Float32Array(outputsByRemap.get(remap));
@@ -849,6 +885,8 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
    * game clock instead of running on real time.
    * @internal
    */ _timelineTickers;
+    _gpuAnimation;
+    _gpuDriver;
     /**
    * Create an AnimationSet controlling the provided model.
    *
@@ -864,6 +902,40 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         this._skeletons = [];
         this._rigs = [];
         this._timelineTickers = new Set();
+        this._gpuAnimation = false;
+        this._gpuDriver = null;
+    }
+    /**
+   * Whether skeletal animation may be played from baked poses, evaluated on the GPU where
+   * supported. Default false.
+   *
+   * @remarks
+   * Playback, events and the playback API stay the same. While exactly one clip is active, animating
+   * only the joints of the model, the joint nodes are left alone and the skinned meshes are posed by
+   * {@link AnimationBankTrack}s instead: clips are baked once per model and shared by all its
+   * instances, the poses are evaluated in a compute pass on WebGPU, and the meshes stay batchable.
+   *
+   * Frames that do not meet those conditions are posed on the regular path, without a visible jump:
+   * cross fades and other blends of clips, skeleton modifiers such as IK and joint dynamics, GPU
+   * cloth, and nodes attached below joints (which follow the joint nodes). In the editor, outside
+   * of play mode, animation always takes the regular path.
+   *
+   * Since joint nodes are not moved while baked poses are played, code reading joint transforms sees
+   * them as they were when the baked poses took over.
+   */ get gpuAnimation() {
+        return this._gpuAnimation;
+    }
+    set gpuAnimation(val) {
+        if (val !== this._gpuAnimation) {
+            this._gpuAnimation = val;
+            if (!val) {
+                this._gpuDriver?.dispose();
+                this._gpuDriver = null;
+            }
+        }
+    }
+    /** Whether the skinned meshes are currently posed from baked poses, see {@link gpuAnimation} */ get isPlayingOnGpu() {
+        return !!this._gpuDriver?.active;
     }
     /**
    * Register a callback advanced by {@link update} using the same delta time as the animations.
@@ -1076,6 +1148,21 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
                 }
             }
         });
+        if (this._gpuAnimation) {
+            let clip = null;
+            let time = 0;
+            if (this._activeAnimations.size === 1) {
+                const [[k, v]] = this._activeAnimations;
+                clip = k;
+                time = v.currentTime;
+            }
+            this._gpuDriver ??= new GpuAnimationDriver(this);
+            if (this._gpuDriver.update(clip, time)) {
+                // Bank tracks pose the skinned meshes: no joint node to pose, no palette to write
+                this._timelineTickers.forEach((ticker)=>ticker(deltaInSeconds));
+                return;
+            }
+        }
         // Update tracks
         this._activeTracks.forEach((v, k)=>{
             v.forEach((alltracks)=>{
@@ -1632,6 +1719,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         const options = typeof targetNameOrOptions === 'string' ? copyOptions ?? {} : targetNameOrOptions ?? {};
         const destName = typeof targetNameOrOptions === 'string' ? targetNameOrOptions : options.targetName ?? animationName;
         const rootMotion = options.rootMotion ?? 'scaled';
+        const hipsTranslation = options.hipsTranslation ?? 'scaled';
         const jointTranslations = options.jointTranslations ?? 'skip';
         const sourceClip = sourceSet.get(animationName);
         if (!sourceClip) {
@@ -1731,16 +1819,19 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         const dstHipsNode = dstSkeleton.humanoidJointMapping.body[HumanoidBodyRig.Hips];
         const srcRootNode = srcSkeleton.rootJoint ?? srcHipsNode;
         const dstRootNode = dstSkeleton.rootJoint ?? dstHipsNode;
+        const hasSeparateHips = srcRootNode !== srcHipsNode && dstRootNode !== dstHipsNode;
         const srcRootRot = computeParentChainRotation(srcRootNode, sourceSet.model, srcSkeleton);
         const dstRootRot = computeParentChainRotation(dstRootNode, this._model, dstSkeleton);
-        const srcRootTranslationTrack = findTranslationTrack(sourceClip.tracks.get(srcRootNode));
-        const srcAncestorTranslationTrackInfo = !srcRootTranslationTrack ? findAncestorTranslationTrack(sourceClip, srcRootNode, sourceSet.model) : null;
-        const srcFallbackHipsTranslationTrack = !srcRootTranslationTrack && !srcAncestorTranslationTrackInfo && srcRootNode !== srcHipsNode ? findTranslationTrack(sourceClip.tracks.get(srcHipsNode)) : null;
-        const srcMotionTrack = srcRootTranslationTrack ?? srcAncestorTranslationTrackInfo?.track ?? srcFallbackHipsTranslationTrack;
-        const srcMotionNode = srcRootTranslationTrack ? srcRootNode : srcAncestorTranslationTrackInfo ? srcAncestorTranslationTrackInfo.node : srcFallbackHipsTranslationTrack ? srcHipsNode : null;
+        const rootTrackCandidate = findTranslationTrack(sourceClip.tracks.get(srcRootNode));
+        const srcRootTranslationTrack = rootTrackCandidate && (!hasSeparateHips || isTranslationTrackAnimated(rootTrackCandidate)) ? rootTrackCandidate : null;
+        const srcAncestorTranslationTrackInfo = !srcRootTranslationTrack ? findAncestorTranslationTrack(sourceClip, srcRootNode, sourceSet.model, hasSeparateHips) : null;
+        const srcMotionTrack = srcRootTranslationTrack ?? srcAncestorTranslationTrackInfo?.track ?? null;
+        const srcMotionNode = srcRootTranslationTrack ? srcRootNode : srcAncestorTranslationTrackInfo ? srcAncestorTranslationTrackInfo.node : null;
         const srcMotionParentRot = srcMotionNode ? computeParentChainRotation(srcMotionNode, sourceSet.model, srcSkeleton) : srcRootRot;
         const rootTranslationRotation = Quaternion.multiply(Quaternion.inverse(dstRootRot), srcMotionParentRot);
-        const rootTranslationScale = rootMotion === 'scaled' ? typeof options.rootMotionScale === 'number' ? options.rootMotionScale : options.rootMotionScale === 'none' ? 1 : getHumanoidRootMotionScale(srcSkeleton, dstSkeleton) : 1;
+        const resolveTranslationScale = (mode)=>typeof mode === 'number' ? mode : mode === 'none' ? 1 : getHumanoidRootMotionScale(srcSkeleton, dstSkeleton);
+        const rootTranslationScale = rootMotion === 'scaled' ? resolveTranslationScale(options.rootMotionScale) : 1;
+        const hipsTranslationScale = hipsTranslation === 'scaled' ? resolveTranslationScale(options.hipsTranslationScale) : 1;
         const jointRemaps = [];
         const jointRemapsByDstSkeleton = new Map([
             [
@@ -1842,9 +1933,14 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             if (rootMotion === 'locked') {
                 dstRootTrack = createConstantTranslationTrack(dstRootBindPose.position);
             } else if (srcMotionTrack && srcMotionNode) {
-                const srcMotionBindPose = getRigBindPoseForNode(srcSkeleton, srcMotionNode);
-                const rootRemap = createTranslationRetargetRemap(srcMotionNode, dstRootNode, srcMotionBindPose.position, dstRootBindPose.position, dstSkeleton.joints.indexOf(dstRootNode), rootTranslationScale, rootTranslationRotation, humanoidRotationCorrection ?? undefined, options.lockRootMotionAxes, humanoidRotationCorrection ?? undefined);
+                const srcMotionBindPose = getRigReferencePoseForNode(srcSkeleton, srcMotionNode);
+                const rootMotionAxisLocks = options.lockRootMotionAxes ?? (hasSeparateHips ? {
+                    y: true
+                } : undefined);
+                const rootRemap = createTranslationRetargetRemap(srcMotionNode, dstRootNode, srcMotionBindPose.position, dstRootBindPose.position, dstSkeleton.joints.indexOf(dstRootNode), rootTranslationScale, rootTranslationRotation, humanoidRotationCorrection ?? undefined, rootMotionAxisLocks, humanoidRotationCorrection ?? undefined);
                 dstRootTrack = retargetTranslationTrack(srcMotionTrack, rootRemap);
+            } else {
+                dstRootTrack = createConstantTranslationTrack(dstRootBindPose.position);
             }
             if (dstRootTrack) {
                 dstRootTrack.name = srcMotionTrack?.name ?? 'translation';
@@ -1853,6 +1949,24 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
                 dstClip.addTrack(dstRootNode, dstRootTrack);
             }
         }
+        if (hasSeparateHips && hipsTranslation !== 'none') {
+            const srcHipsTrack = findTranslationTrack(sourceClip.tracks.get(srcHipsNode)) ?? (srcSkeleton.hasRetargetPose ? createConstantTranslationTrack(getRigBindPoseForNode(srcSkeleton, srcHipsNode).position) : null);
+            const dstHipsBindPose = getRigBindPoseForNode(dstSkeleton, dstHipsNode);
+            let dstHipsTrack = null;
+            if (hipsTranslation === 'locked') {
+                dstHipsTrack = createConstantTranslationTrack(dstHipsBindPose.position);
+            } else if (srcHipsTrack) {
+                const srcHipsReferencePose = getRigReferencePoseForNode(srcSkeleton, srcHipsNode);
+                const hipsRemap = createTranslationRetargetRemap(srcHipsNode, dstHipsNode, srcHipsReferencePose.position, dstHipsBindPose.position, dstSkeleton.joints.indexOf(dstHipsNode), hipsTranslationScale, undefined, humanoidRotationCorrection ?? undefined, undefined, humanoidRotationCorrection ?? undefined);
+                dstHipsTrack = retargetTranslationTrack(srcHipsTrack, hipsRemap);
+            }
+            if (dstHipsTrack) {
+                dstHipsTrack.name = srcHipsTrack?.name ?? 'translation';
+                dstHipsTrack.target = dstHipsNode.persistentId;
+                dstHipsTrack.jointIndex = dstSkeleton.joints.indexOf(dstHipsNode);
+                dstClip.addTrack(dstHipsNode, dstHipsTrack);
+            }
+        }
         for (const [srcNode, srcRemaps] of jointRemapsBySrcNode){
             const srcTracks = sourceClip.tracks.get(srcNode);
             if (!srcTracks) {
@@ -1865,7 +1979,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
                     if (srcTrack instanceof NodeRotationTrack || srcTrack instanceof NodeEulerRotationTrack) {
                         continue;
                     } else if (srcTrack instanceof NodeTranslationTrack) {
-                        if (srcNode === srcRootNode || srcTrack === srcMotionTrack || jointTranslations !== 'preserve') {
+                        if (srcNode === srcRootNode || hasSeparateHips && srcNode === srcHipsNode || srcTrack === srcMotionTrack || jointTranslations !== 'preserve') {
                             continue;
                         }
                         dstTrack = retargetTranslationTrack(srcTrack, remap);
@@ -2062,6 +2176,8 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
    * - Clears active animations, tracks, and skeleton references.
    */ onDispose() {
         super.onDispose();
+        this._gpuDriver?.dispose();
+        this._gpuDriver = null;
         for(const k in this._animations){
             this._animations[k].dispose();
         }