@zephyr3d/scene 0.9.4 → 0.9.6

package/dist/animation/skeleton.js

@@ -1,4 +1,4 @@
-import { Vector3, Disposable, randomUUID, DRef, Quaternion, DWeakRef, Matrix4x4, nextPowerOf2 } from '@zephyr3d/base';
+import { Vector3, Disposable, randomUUID, Quaternion, DWeakRef, DRef, Matrix4x4, nextPowerOf2 } from '@zephyr3d/base';
 import { BoundingBox } from '../utility/bounding_volume.js';
 import { getDevice } from '../app/api.js';
 
@@ -61,6 +61,183 @@ const tmpV0 = new Vector3();
 const tmpV1 = new Vector3();
 const tmpV2 = new Vector3();
 const tmpV3 = new Vector3();
+/**
+ * Shared joint rig for skeletal animation.
+ *
+ * A rig owns the animated joint nodes, bind pose, humanoid mapping and procedural
+ * modifiers. Multiple skin bindings may reference the same rig with different
+ * inverse bind matrices.
+ *
+ * @public
+ */ class SkeletonRig extends Disposable {
+    static _registry = new Map();
+    _id;
+    _joints;
+    _bindPoseByJoint;
+    _bindPose;
+    _rootJoint;
+    _rootBindPose;
+    _playing;
+    _modifiers;
+    _humanoidJointMapping;
+    _humanoidRootRotation;
+    constructor(joints, bindPose, options){
+        super();
+        this._id = randomUUID();
+        this._joints = joints;
+        this._bindPose = bindPose;
+        this._bindPoseByJoint = new Map();
+        for(let i = 0; i < joints.length; i++){
+            this._bindPoseByJoint.set(joints[i], bindPose[i]);
+        }
+        const skeletonRoot = this.findRootJoint(this._joints);
+        this._rootJoint = options?.rootJoint ?? skeletonRoot;
+        this._rootBindPose = options?.rootBindPose ?? this.getNodeBindPose(this._rootJoint);
+        this._playing = false;
+        this._modifiers = [];
+        this.computeBindPose();
+        if (skeletonRoot) {
+            this._humanoidJointMapping = Skeleton.tryExtractHumanoidJoints(skeletonRoot);
+            this._humanoidRootRotation = Quaternion.identity();
+        } else {
+            this._humanoidJointMapping = null;
+            this._humanoidRootRotation = Quaternion.identity();
+        }
+        if (this._humanoidJointMapping) {
+            let p = this._humanoidJointMapping.body["Hips"];
+            while(this._joints.includes(p.parent)){
+                Quaternion.multiply(p.parent.rotation, this._humanoidRootRotation, this._humanoidRootRotation);
+                p = p.parent;
+            }
+        }
+        SkeletonRig._registry.set(this._id, new DWeakRef(this));
+    }
+    static getRigKey(joints, rootJoint) {
+        return [
+            rootJoint?.persistentId ?? '',
+            ...joints.map((joint)=>joint.persistentId).sort()
+        ].join('|');
+    }
+    static findRigById(id) {
+        const m = this._registry.get(id);
+        if (m && !m.get()) {
+            this._registry.delete(id);
+            return null;
+        }
+        return m ? m.get() : null;
+    }
+    get persistentId() {
+        return this._id;
+    }
+    set persistentId(val) {
+        if (val !== this._id) {
+            const m = SkeletonRig._registry.get(this._id);
+            if (!m || m.get() !== this) {
+                throw new Error('Registry skeleton rig mismatch');
+            }
+            SkeletonRig._registry.delete(this._id);
+            this._id = val;
+            SkeletonRig._registry.set(this._id, m);
+        }
+    }
+    get joints() {
+        return this._joints;
+    }
+    get bindPose() {
+        return this._bindPose;
+    }
+    get rootJoint() {
+        return this._rootJoint;
+    }
+    set rootJoint(joint) {
+        this._rootJoint = joint;
+        this._rootBindPose = this.getNodeBindPose(joint);
+    }
+    get rootBindPose() {
+        return this._rootBindPose;
+    }
+    getBindPoseForJoint(joint) {
+        return this._bindPoseByJoint.get(joint) ?? null;
+    }
+    get humanoidJointMapping() {
+        return this._humanoidJointMapping;
+    }
+    get humanoidRootRotation() {
+        return this._humanoidRootRotation;
+    }
+    get modifiers() {
+        return this._modifiers;
+    }
+    get playing() {
+        return this._playing;
+    }
+    set playing(b) {
+        this._playing = b;
+    }
+    getJointIndex(joint) {
+        return this._joints.indexOf(joint);
+    }
+    getJointIndexByName(jointName) {
+        return this._joints.findIndex((joint)=>joint.name === jointName);
+    }
+    computeBindPose() {
+        for(let i = 0; i < this._joints.length; i++){
+            const joint = this._joints[i];
+            const bindpose = this._bindPose[i];
+            joint.position.set(bindpose.position);
+            joint.rotation.set(bindpose.rotation);
+            joint.scale.set(bindpose.scale);
+        }
+        if (this._rootJoint && !this._bindPoseByJoint.has(this._rootJoint)) {
+            this._rootJoint.position.set(this._rootBindPose.position);
+            this._rootJoint.rotation.set(this._rootBindPose.rotation);
+            this._rootJoint.scale.set(this._rootBindPose.scale);
+        }
+    }
+    apply(deltaTime) {
+        for (const modifier of this._modifiers){
+            modifier.apply(this, deltaTime);
+        }
+    }
+    reset() {
+        this._playing = false;
+    }
+    onDispose() {
+        super.onDispose();
+        const m = SkeletonRig._registry.get(this._id);
+        if (m?.get() === this) {
+            SkeletonRig._registry.delete(this._id);
+            m.dispose();
+        }
+    }
+    findRootJoint(joints) {
+        let root = null;
+        for (const joint of joints){
+            if (!root) {
+                root = joint;
+            }
+            while(!root.isParentOf(joint)){
+                root = root.parent;
+            }
+            if (!root) {
+                break;
+            }
+        }
+        return root;
+    }
+    getNodeBindPose(node) {
+        const bindPose = node ? this._bindPoseByJoint.get(node) : null;
+        return bindPose ? {
+            position: bindPose.position.clone(),
+            rotation: bindPose.rotation.clone(),
+            scale: bindPose.scale.clone()
+        } : {
+            position: node?.position.clone() ?? Vector3.zero(),
+            rotation: node?.rotation.clone() ?? Quaternion.identity(),
+            scale: node?.scale.clone() ?? Vector3.one()
+        };
+    }
+}
 function jointPattern(all, none, any) {
     return {
         all,
@@ -90,10 +267,11 @@ function sideJointPatterns(side, patterns) {
             })));
 }
 /**
- * Skeleton for skinned animation.
+ * Skin binding for skinned animation.
  *
  * Responsibilities:
- * - Maintains joint transforms: inverse bind, bind pose, and current skinning matrices.
+ * - References a shared SkeletonRig.
+ * - Maintains inverse bind and current skinning matrices for one skin.
  * - Provides a texture containing joint matrices for GPU skinning.
  * - Applies skinning state to associated meshes each frame.
  * - Computes animated axis-aligned bounding boxes using representative skinned vertices.
@@ -105,58 +283,49 @@ function sideJointPatterns(side, patterns) {
  *   and `_jointOffsets[1]` (previous).
  *
  * Usage:
- * - Construct with joints, bind data, meshes and submesh bounding info.
+ * - Construct with a rig, bind data, meshes and submesh bounding info.
  * - Call `apply()` each frame to update joint texture, bind to meshes, and update bounds.
  * - Call `reset()` to clear skinning on meshes.
  *
  * @public
- */ class Skeleton extends Disposable {
+ */ class SkinBinding extends Disposable {
     /** @internal Global weak registry keyed by persistentId for serialization/lookup. */ static _registry = new Map();
     /** @internal */ _id;
+    /** @internal */ _rig;
     /** @internal */ _joints;
     /** @internal */ _inverseBindMatrices;
-    /** @internal */ _bindPose;
     /** @internal */ _jointMatrices;
     /** @internal */ _jointOffsets;
     /** @internal */ _jointMatrixArray;
     /** @internal */ _jointTexture;
     /** @internal */ _playing;
-    /** @internal */ _modifiers;
     /** @internal */ _lastUpdateTime;
-    /** @internal */ _humanoidJointMapping;
-    /** @internal */ _humanoidRootRotation;
     /**
-   * Create a skeleton instance.
+   * Create a skin binding instance.
    *
+   * @param rig - Shared skeleton rig that owns animated joint transforms.
    * @param joints - Joint scene nodes (one per joint), ordered to match skin data.
    * @param inverseBindMatrices - Inverse bind matrices for each joint.
    * @param bindPoseMatrices - Bind pose matrices for each joint (model-space).
-   */ constructor(joints, inverseBindMatrices, bindPose){
+   */ constructor(rig, inverseBindMatrices, joints, bindPose){
         super();
         this._id = randomUUID();
-        this._joints = joints;
+        this._rig = rig;
+        this._joints = joints ?? rig.joints;
         this._inverseBindMatrices = inverseBindMatrices;
-        this._bindPose = bindPose;
         this._jointTexture = new DRef();
         this._playing = false;
-        this._modifiers = [];
         this._lastUpdateTime = 0;
-        this.computeBindPose();
-        this.updateJointMatrices(0);
-        let skeletonRoot = this.findRootJoint(this._joints);
-        if (!skeletonRoot || !this._joints.includes(skeletonRoot)) {
-            throw new Error('Skeleton root must be included in the joint list');
-        }
-        this._humanoidJointMapping = Skeleton.tryExtractHumanoidJoints(skeletonRoot);
-        this._humanoidRootRotation = Quaternion.identity();
-        if (this._humanoidJointMapping) {
-            let p = this._humanoidJointMapping.body["Hips"];
-            while(this._joints.includes(p.parent)){
-                Quaternion.multiply(p.parent.rotation, this._humanoidRootRotation, this._humanoidRootRotation);
-                p = p.parent;
-            }
+        if (bindPose && bindPose !== rig.bindPose) {
+            // Legacy callers used Skeleton as both rig and binding. Keep the old bind
+            // pose visible by replacing the rig pose only when explicitly supplied.
+            this._rig = new SkeletonRig(rig.joints, bindPose, {
+                rootJoint: rig.rootJoint,
+                rootBindPose: rig.rootBindPose
+            });
         }
-        Skeleton._registry.set(this._id, new DWeakRef(this));
+        this.updateJointMatrices();
+        SkinBinding._registry.set(this._id, new DWeakRef(this));
     }
     /**
    * Lookup a skeleton from the global registry by persistent id.
@@ -164,7 +333,7 @@ function sideJointPatterns(side, patterns) {
    * @param id - The persistent UUID to search for.
    * @returns The skeleton if alive, otherwise `null`.
    * @internal
-   */ static findSkeletonById(id) {
+   */ static findSkinBindingById(id) {
         const m = this._registry.get(id);
         if (m && !m.get()) {
             this._registry.delete(id);
@@ -172,20 +341,26 @@ function sideJointPatterns(side, patterns) {
         }
         return m ? m.get() : null;
     }
+    static findSkeletonById(id) {
+        return this.findSkinBindingById(id);
+    }
+    get rig() {
+        return this._rig;
+    }
     /** Gets joint nodes */ get joints() {
         return this._joints;
     }
     /** Gets the humanoid joint mapping */ get humanoidJointMapping() {
-        return this._humanoidJointMapping;
+        return this._rig.humanoidJointMapping;
     }
     /** Root rotation of humanoid hips bone */ get humanoidRootRotation() {
-        return this._humanoidRootRotation;
+        return this._rig.humanoidRootRotation;
     }
     /** @internal */ get inverseBindMatrices() {
         return this._inverseBindMatrices;
     }
     /** @internal */ get bindPose() {
-        return this._bindPose;
+        return this._joints.map((joint)=>this._rig.getBindPoseForJoint(joint));
     }
     get playing() {
         return this._playing;
@@ -198,13 +373,13 @@ function sideJointPatterns(side, patterns) {
     }
     set persistentId(val) {
         if (val !== this._id) {
-            const m = Skeleton._registry.get(this._id);
+            const m = SkinBinding._registry.get(this._id);
             if (!m || m.get() !== this) {
-                throw new Error('Registry skeleton mismatch');
+                throw new Error('Registry skin binding mismatch');
             }
-            Skeleton._registry.delete(this._id);
+            SkinBinding._registry.delete(this._id);
             this._id = val;
-            Skeleton._registry.set(this._id, m);
+            SkinBinding._registry.set(this._id, m);
         }
     }
     /**
@@ -243,8 +418,7 @@ function sideJointPatterns(side, patterns) {
    * @param jointTransforms - Optional per-joint transforms to use instead of node world matrices.
    * @param worldMatrix - Optional world-to-model transform applied before inverse bind.
    * @internal
-   */ updateJointMatrices(deltaTime) {
-        this.applyModifiers(deltaTime);
+   */ updateJointMatrices() {
         if (!this._jointTexture.get()) {
             this._createJointTexture();
         }
@@ -253,10 +427,10 @@ function sideJointPatterns(side, patterns) {
             this._jointOffsets[1] = 1;
         } else {
             this._jointOffsets[1] = this._jointOffsets[0];
-            this._jointOffsets[0] = this._joints.length - this._jointOffsets[0] + 2;
+            this._jointOffsets[0] = this.joints.length - this._jointOffsets[0] + 2;
         }
-        for(let i = 0; i < this._joints.length; i++){
-            Matrix4x4.multiply(this._joints[i].worldMatrix, this._inverseBindMatrices[i], this._jointMatrices[i + this._jointOffsets[0] - 1]);
+        for(let i = 0; i < this.joints.length; i++){
+            Matrix4x4.multiply(this.joints[i].worldMatrix, this._inverseBindMatrices[i], this._jointMatrices[i + this._jointOffsets[0] - 1]);
         }
     }
     /**
@@ -264,22 +438,16 @@ function sideJointPatterns(side, patterns) {
    *
    * @internal
    */ computeBindPose() {
-        for(let i = 0; i < this._joints.length; i++){
-            const joint = this._joints[i];
-            const bindpose = this._bindPose[i];
-            joint.position.set(bindpose.position);
-            joint.rotation.set(bindpose.rotation);
-            //joint.rotation.identity();
-            joint.scale.set(bindpose.scale);
-        }
+        this._rig.computeBindPose();
     }
     /**
    * Compute current joint matrices from the nodes and upload them to the joint texture.
    *
    * @internal
-   */ apply(deltaTime) {
-        this.updateJointMatrices(deltaTime);
+   */ apply() {
+        this.updateJointMatrices();
         const tex = this.jointTexture;
+        this._syncJointMatrixArray();
         tex.update(this._jointMatrixArray, 0, 0, tex.width, tex.height);
     }
     /**
@@ -291,16 +459,14 @@ function sideJointPatterns(side, patterns) {
    * @param deltaTime - Time elapsed since last frame (in seconds)
    * @internal
    */ applyModifiers(deltaTime) {
-        for (const modifier of this._modifiers){
-            modifier.apply(this, deltaTime);
-        }
+        this._rig.apply(deltaTime);
     }
     /**
    * Get all modifiers attached to this skeleton.
    *
    * @public
    */ get modifiers() {
-        return this._modifiers;
+        return this._rig.modifiers;
     }
     /**
    * Reset all meshes to an unskinned state and clear animated bounds.
@@ -341,9 +507,9 @@ function sideJointPatterns(side, patterns) {
    */ onDispose() {
         super.onDispose();
         this._jointTexture.dispose();
-        const m = Skeleton._registry.get(this._id);
+        const m = SkinBinding._registry.get(this._id);
         if (m?.get() === this) {
-            Skeleton._registry.delete(this._id);
+            SkinBinding._registry.delete(this._id);
             m.dispose();
         }
     }
@@ -359,7 +525,7 @@ function sideJointPatterns(side, patterns) {
    *
    * @internal
    */ _createJointTexture() {
-        const textureWidth = nextPowerOf2(Math.max(4, Math.ceil(Math.sqrt((this._joints.length * 2 + 1) * 4))));
+        const textureWidth = nextPowerOf2(Math.max(4, Math.ceil(Math.sqrt((this.joints.length * 2 + 1) * 4))));
         const device = getDevice();
         this._jointTexture.set(device.createTexture2D('rgba32f', textureWidth, textureWidth, {
             mipmapping: false,
@@ -369,13 +535,17 @@ function sideJointPatterns(side, patterns) {
             }
         }));
         this._jointMatrixArray = new Float32Array(textureWidth * textureWidth * 4);
-        const buffer = this._jointMatrixArray.buffer;
-        this._jointOffsets = new Float32Array(buffer);
+        this._jointOffsets = this._jointMatrixArray.subarray(0, 2);
         this._jointOffsets[0] = 0;
         this._jointOffsets[1] = 0;
         this._jointMatrices = Array.from({
-            length: this._joints.length * 2
-        }).map((val, index)=>new Matrix4x4(buffer, (index + 1) * 16 * Float32Array.BYTES_PER_ELEMENT));
+            length: this.joints.length * 2
+        }).map(()=>new Matrix4x4());
+    }
+    _syncJointMatrixArray() {
+        for(let i = 0; i < this._jointMatrices.length; i++){
+            this._jointMatrixArray.set(this._jointMatrices[i], (i + 1) * 16);
+        }
     }
     /**
    * Build representative skinned bounding data for a submesh.
@@ -509,21 +679,6 @@ function sideJointPatterns(side, patterns) {
         }
         return result;
     }
-    findRootJoint(joints) {
-        let root = null;
-        for (const joint of joints){
-            if (!root) {
-                root = joint;
-            }
-            while(!root.isParentOf(joint)){
-                root = root.parent;
-            }
-            if (!root) {
-                break;
-            }
-        }
-        return root;
-    }
     static normalizeHumanoidJointName(name) {
         return name.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([a-zA-Z])(\d+)/g, '$1 $2').replace(/(\d+)([a-zA-Z])/g, '$1 $2').replace(/[_:\/\\.-]+/g, ' ').replace(/[^a-zA-Z0-9]+/g, ' ').toLowerCase().replace(/\bforearm\b/g, 'fore arm').replace(/\bupperarm\b/g, 'upper arm').replace(/\blowerarm\b/g, 'lower arm').replace(/\bupleg\b/g, 'up leg').replace(/\bupperleg\b/g, 'upper leg').replace(/\blowerleg\b/g, 'lower leg').replace(/\btoebase\b/g, 'toe base').replace(/\bupperchest\b/g, 'upper chest').replace(/\btoes\b/g, 'toe').replace(/\blittle\b/g, 'pinky').replace(/\bcollar\b/g, 'clavicle').replace(/\s+/g, ' ').trim();
     }
@@ -2258,6 +2413,26 @@ function sideJointPatterns(side, patterns) {
         return this.tryExtractHumanoidJointsByBodyProfile(root, this.createBipedHumanoidBodyProfile());
     }
 }
+/**
+ * Legacy compatibility name for a skin binding.
+ *
+ * New code should use {@link SkeletonRig} for the shared animated rig and
+ * {@link SkinBinding} for per-skin inverse bind matrices.
+ *
+ * @public
+ */ class Skeleton extends SkinBinding {
+    constructor(joints, inverseBindMatrices, bindPose){
+        super(new SkeletonRig(joints, bindPose), inverseBindMatrices, joints);
+    }
+    static tryExtractHumanoidJoints = SkinBinding.tryExtractHumanoidJoints;
+    static tryExtractHumanoidJointsMixamo = SkinBinding.tryExtractHumanoidJointsMixamo;
+    static tryExtractHumanoidJointsVRM = SkinBinding.tryExtractHumanoidJointsVRM;
+    static tryExtractHumanoidJointsUnityHumanoid = SkinBinding.tryExtractHumanoidJointsUnityHumanoid;
+    static tryExtractHumanoidJointsBiped = SkinBinding.tryExtractHumanoidJointsBiped;
+    static findSkeletonById(id) {
+        return SkinBinding.findSkinBindingById(id);
+    }
+}
 
-export { HumanoidBodyRig, HumanoidHandRig, Skeleton };
+export { HumanoidBodyRig, HumanoidHandRig, Skeleton, SkeletonRig, SkinBinding };
 //# sourceMappingURL=skeleton.js.map