@zephyr3d/scene 0.8.0 → 0.8.2

package/dist/animation/spring/spring_bone_constraint.js

@@ -0,0 +1,170 @@
+import { Vector3 } from '@zephyr3d/base';
+
+/**
+ * Base class for spring bone constraints.
+ *
+ * @remarks
+ * Constraints are applied after physics simulation to enforce
+ * additional rules between spring bones.
+ *
+ * @public
+ */ class SpringBoneConstraint {
+}
+/**
+ * Distance constraint between two spring bones.
+ *
+ * @remarks
+ * Maintains a distance range between two spring bones.
+ * Useful for preventing penetration and excessive stretching between
+ * adjacent chains (e.g., skirt panels).
+ *
+ * @public
+ */ class DistanceConstraint extends SpringBoneConstraint {
+    /** First spring bone */ _bone1;
+    /** Second spring bone */ _bone2;
+    /** Minimum distance (prevents penetration) */ _minDistance;
+    /** Maximum distance (prevents excessive stretching) */ _maxDistance;
+    /** Constraint stiffness (0-1, how strongly to enforce) */ _stiffness;
+    /**
+   * Create a distance constraint.
+   *
+   * @param bone1 - First spring bone
+   * @param bone2 - Second spring bone
+   * @param minDistance - Minimum distance (default: 0.01)
+   * @param maxDistance - Maximum distance (default: 0.2)
+   * @param stiffness - Constraint stiffness (0-1, default: 0.5)
+   */ constructor(bone1, bone2, minDistance = 0.01, maxDistance = 0.2, stiffness = 0.5){
+        super();
+        this._bone1 = bone1;
+        this._bone2 = bone2;
+        this._minDistance = Math.max(0, minDistance);
+        this._maxDistance = Math.max(this._minDistance, maxDistance);
+        this._stiffness = Math.max(0, Math.min(1, stiffness));
+    }
+    /**
+   * Get/set minimum distance.
+   */ get minDistance() {
+        return this._minDistance;
+    }
+    set minDistance(value) {
+        this._minDistance = Math.max(0, value);
+        this._maxDistance = Math.max(this._minDistance, this._maxDistance);
+    }
+    /**
+   * Get/set maximum distance.
+   */ get maxDistance() {
+        return this._maxDistance;
+    }
+    set maxDistance(value) {
+        this._maxDistance = Math.max(this._minDistance, value);
+    }
+    /**
+   * Get/set stiffness.
+   */ get stiffness() {
+        return this._stiffness;
+    }
+    set stiffness(value) {
+        this._stiffness = Math.max(0, Math.min(1, value));
+    }
+    /**
+   * Apply the distance constraint.
+   */ apply() {
+        const pos1 = this._bone1.currentPosition;
+        const pos2 = this._bone2.currentPosition;
+        // Calculate current distance
+        const direction = Vector3.sub(pos2, pos1, new Vector3());
+        const distance = direction.magnitude;
+        if (distance < 0.000001) {
+            return; // Bones are at same position
+        }
+        const directionNorm = Vector3.scale(direction, 1 / distance, new Vector3());
+        let correction = 0;
+        if (distance < this._minDistance) {
+            // Too close, push apart
+            correction = (this._minDistance - distance) * 0.5 * this._stiffness;
+        } else if (distance > this._maxDistance) {
+            // Too far, pull together
+            correction = (this._maxDistance - distance) * 0.5 * this._stiffness;
+        } else {
+            // Within range, no correction needed
+            return;
+        }
+        // Apply correction to both bones (equal and opposite)
+        const offset = Vector3.scale(directionNorm, correction, new Vector3());
+        pos1.addBy(Vector3.scale(offset, -1, new Vector3()));
+        pos2.addBy(offset);
+    }
+}
+/**
+ * Circular constraint for skirt-like structures.
+ *
+ * @remarks
+ * Maintains distance constraints between adjacent bones in a circular arrangement.
+ * Automatically creates distance constraints between neighboring chains.
+ *
+ * @public
+ */ class CircularConstraint extends SpringBoneConstraint {
+    /** Array of spring bone chains arranged in a circle */ _chains;
+    /** Distance constraints between adjacent chains */ _constraints;
+    /** Minimum distance between adjacent bones */ _minDistance;
+    /** Maximum distance between adjacent bones */ _maxDistance;
+    /** Constraint stiffness */ _stiffness;
+    /**
+   * Create a circular constraint.
+   *
+   * @param chains - Array of spring bone chains arranged in a circle
+   * @param minDistance - Minimum distance between adjacent bones (default: 0.05)
+   * @param maxDistance - Maximum distance between adjacent bones (default: 0.15)
+   * @param stiffness - Constraint stiffness (0-1, default: 0.5)
+   */ constructor(chains, minDistance = 0.05, maxDistance = 0.15, stiffness = 0.5){
+        super();
+        this._chains = chains;
+        this._minDistance = minDistance;
+        this._maxDistance = maxDistance;
+        this._stiffness = stiffness;
+        this._constraints = [];
+        this._buildConstraints();
+    }
+    /**
+   * Build distance constraints between adjacent chains.
+   */ _buildConstraints() {
+        this._constraints = [];
+        if (this._chains.length < 2) {
+            return; // Need at least 2 chains
+        }
+        // For each level (depth in the chain)
+        const maxDepth = Math.min(...this._chains.map((chain)=>chain.length));
+        for(let depth = 0; depth < maxDepth; depth++){
+            // Connect adjacent chains
+            for(let i = 0; i < this._chains.length; i++){
+                const nextIndex = (i + 1) % this._chains.length; // Wrap around
+                const bone1 = this._chains[i][depth];
+                const bone2 = this._chains[nextIndex][depth];
+                if (bone1 && bone2) {
+                    const constraint = new DistanceConstraint(bone1, bone2, this._minDistance, this._maxDistance, this._stiffness);
+                    this._constraints.push(constraint);
+                }
+            }
+        }
+    }
+    /**
+   * Rebuild constraints (call after modifying chains).
+   */ rebuild() {
+        this._buildConstraints();
+    }
+    /**
+   * Apply all distance constraints.
+   */ apply() {
+        for (const constraint of this._constraints){
+            constraint.apply();
+        }
+    }
+    /**
+   * Get all distance constraints.
+   */ get constraints() {
+        return this._constraints;
+    }
+}
+
+export { CircularConstraint, DistanceConstraint, SpringBoneConstraint };
+//# sourceMappingURL=spring_bone_constraint.js.map

package/dist/animation/spring/spring_bone_constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring_bone_constraint.js","sources":["../../../src/animation/spring/spring_bone_constraint.ts"],"sourcesContent":["import { Vector3 } from '@zephyr3d/base';\r\nimport type { SpringBone } from './spring_bone';\r\n\r\n/**\r\n * Base class for spring bone constraints.\r\n *\r\n * @remarks\r\n * Constraints are applied after physics simulation to enforce\r\n * additional rules between spring bones.\r\n *\r\n * @public\r\n */\r\nexport abstract class SpringBoneConstraint {\r\n  /**\r\n   * Apply the constraint.\r\n   *\r\n   * @remarks\r\n   * This method modifies the positions of spring bones to satisfy the constraint.\r\n   */\r\n  abstract apply(): void;\r\n}\r\n\r\n/**\r\n * Distance constraint between two spring bones.\r\n *\r\n * @remarks\r\n * Maintains a distance range between two spring bones.\r\n * Useful for preventing penetration and excessive stretching between\r\n * adjacent chains (e.g., skirt panels).\r\n *\r\n * @public\r\n */\r\nexport class DistanceConstraint extends SpringBoneConstraint {\r\n  /** First spring bone */\r\n  private _bone1: SpringBone;\r\n  /** Second spring bone */\r\n  private _bone2: SpringBone;\r\n  /** Minimum distance (prevents penetration) */\r\n  private _minDistance: number;\r\n  /** Maximum distance (prevents excessive stretching) */\r\n  private _maxDistance: number;\r\n  /** Constraint stiffness (0-1, how strongly to enforce) */\r\n  private _stiffness: number;\r\n\r\n  /**\r\n   * Create a distance constraint.\r\n   *\r\n   * @param bone1 - First spring bone\r\n   * @param bone2 - Second spring bone\r\n   * @param minDistance - Minimum distance (default: 0.01)\r\n   * @param maxDistance - Maximum distance (default: 0.2)\r\n   * @param stiffness - Constraint stiffness (0-1, default: 0.5)\r\n   */\r\n  constructor(\r\n    bone1: SpringBone,\r\n    bone2: SpringBone,\r\n    minDistance = 0.01,\r\n    maxDistance = 0.2,\r\n    stiffness = 0.5\r\n  ) {\r\n    super();\r\n    this._bone1 = bone1;\r\n    this._bone2 = bone2;\r\n    this._minDistance = Math.max(0, minDistance);\r\n    this._maxDistance = Math.max(this._minDistance, maxDistance);\r\n    this._stiffness = Math.max(0, Math.min(1, stiffness));\r\n  }\r\n\r\n  /**\r\n   * Get/set minimum distance.\r\n   */\r\n  get minDistance(): number {\r\n    return this._minDistance;\r\n  }\r\n\r\n  set minDistance(value: number) {\r\n    this._minDistance = Math.max(0, value);\r\n    this._maxDistance = Math.max(this._minDistance, this._maxDistance);\r\n  }\r\n\r\n  /**\r\n   * Get/set maximum distance.\r\n   */\r\n  get maxDistance(): number {\r\n    return this._maxDistance;\r\n  }\r\n\r\n  set maxDistance(value: number) {\r\n    this._maxDistance = Math.max(this._minDistance, value);\r\n  }\r\n\r\n  /**\r\n   * Get/set stiffness.\r\n   */\r\n  get stiffness(): number {\r\n    return this._stiffness;\r\n  }\r\n\r\n  set stiffness(value: number) {\r\n    this._stiffness = Math.max(0, Math.min(1, value));\r\n  }\r\n\r\n  /**\r\n   * Apply the distance constraint.\r\n   */\r\n  apply(): void {\r\n    const pos1 = this._bone1.currentPosition;\r\n    const pos2 = this._bone2.currentPosition;\r\n\r\n    // Calculate current distance\r\n    const direction = Vector3.sub(pos2, pos1, new Vector3());\r\n    const distance = direction.magnitude;\r\n\r\n    if (distance < 0.000001) {\r\n      return; // Bones are at same position\r\n    }\r\n\r\n    const directionNorm = Vector3.scale(direction, 1 / distance, new Vector3());\r\n\r\n    let correction = 0;\r\n\r\n    if (distance < this._minDistance) {\r\n      // Too close, push apart\r\n      correction = (this._minDistance - distance) * 0.5 * this._stiffness;\r\n    } else if (distance > this._maxDistance) {\r\n      // Too far, pull together\r\n      correction = (this._maxDistance - distance) * 0.5 * this._stiffness;\r\n    } else {\r\n      // Within range, no correction needed\r\n      return;\r\n    }\r\n\r\n    // Apply correction to both bones (equal and opposite)\r\n    const offset = Vector3.scale(directionNorm, correction, new Vector3());\r\n    pos1.addBy(Vector3.scale(offset, -1, new Vector3()));\r\n    pos2.addBy(offset);\r\n  }\r\n}\r\n\r\n/**\r\n * Circular constraint for skirt-like structures.\r\n *\r\n * @remarks\r\n * Maintains distance constraints between adjacent bones in a circular arrangement.\r\n * Automatically creates distance constraints between neighboring chains.\r\n *\r\n * @public\r\n */\r\nexport class CircularConstraint extends SpringBoneConstraint {\r\n  /** Array of spring bone chains arranged in a circle */\r\n  private _chains: SpringBone[][];\r\n  /** Distance constraints between adjacent chains */\r\n  private _constraints: DistanceConstraint[];\r\n  /** Minimum distance between adjacent bones */\r\n  private _minDistance: number;\r\n  /** Maximum distance between adjacent bones */\r\n  private _maxDistance: number;\r\n  /** Constraint stiffness */\r\n  private _stiffness: number;\r\n\r\n  /**\r\n   * Create a circular constraint.\r\n   *\r\n   * @param chains - Array of spring bone chains arranged in a circle\r\n   * @param minDistance - Minimum distance between adjacent bones (default: 0.05)\r\n   * @param maxDistance - Maximum distance between adjacent bones (default: 0.15)\r\n   * @param stiffness - Constraint stiffness (0-1, default: 0.5)\r\n   */\r\n  constructor(\r\n    chains: SpringBone[][],\r\n    minDistance = 0.05,\r\n    maxDistance = 0.15,\r\n    stiffness = 0.5\r\n  ) {\r\n    super();\r\n    this._chains = chains;\r\n    this._minDistance = minDistance;\r\n    this._maxDistance = maxDistance;\r\n    this._stiffness = stiffness;\r\n    this._constraints = [];\r\n\r\n    this._buildConstraints();\r\n  }\r\n\r\n  /**\r\n   * Build distance constraints between adjacent chains.\r\n   */\r\n  private _buildConstraints(): void {\r\n    this._constraints = [];\r\n\r\n    if (this._chains.length < 2) {\r\n      return; // Need at least 2 chains\r\n    }\r\n\r\n    // For each level (depth in the chain)\r\n    const maxDepth = Math.min(...this._chains.map(chain => chain.length));\r\n\r\n    for (let depth = 0; depth < maxDepth; depth++) {\r\n      // Connect adjacent chains\r\n      for (let i = 0; i < this._chains.length; i++) {\r\n        const nextIndex = (i + 1) % this._chains.length; // Wrap around\r\n\r\n        const bone1 = this._chains[i][depth];\r\n        const bone2 = this._chains[nextIndex][depth];\r\n\r\n        if (bone1 && bone2) {\r\n          const constraint = new DistanceConstraint(\r\n            bone1,\r\n            bone2,\r\n            this._minDistance,\r\n            this._maxDistance,\r\n            this._stiffness\r\n          );\r\n          this._constraints.push(constraint);\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Rebuild constraints (call after modifying chains).\r\n   */\r\n  rebuild(): void {\r\n    this._buildConstraints();\r\n  }\r\n\r\n  /**\r\n   * Apply all distance constraints.\r\n   */\r\n  apply(): void {\r\n    for (const constraint of this._constraints) {\r\n      constraint.apply();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all distance constraints.\r\n   */\r\n  get constraints(): readonly DistanceConstraint[] {\r\n    return this._constraints;\r\n  }\r\n}\r\n"],"names":["SpringBoneConstraint","DistanceConstraint","bone1","bone2","minDistance","maxDistance","stiffness","_bone1","_bone2","_minDistance","Math","max","_maxDistance","_stiffness","min","value","apply","pos1","currentPosition","pos2","direction","Vector3","sub","distance","magnitude","directionNorm","scale","correction","offset","addBy","CircularConstraint","chains","_chains","_constraints","_buildConstraints","length","maxDepth","map","chain","depth","i","nextIndex","constraint","push","rebuild","constraints"],"mappings":"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"}

package/dist/animation/spring/spring_bone_system.js

@@ -0,0 +1,328 @@
+import { Vector3, Quaternion } from '@zephyr3d/base';
+import { SpringBone } from './spring_bone.js';
+import { CircularConstraint } from './spring_bone_constraint.js';
+
+/**
+ * Spring bone system manager.
+ *
+ * @remarks
+ * Manages multiple spring bones, colliders, and constraints.
+ * Updates physics simulation and applies results to bone nodes.
+ *
+ * @public
+ */ class SpringBoneSystem {
+    /** All spring bones in the system */ _springBones;
+    /** All colliders in the system */ _colliders;
+    /** All constraints in the system */ _constraints;
+    /** Gravity vector in world space */ _gravity;
+    /** Wind force vector in world space */ _windForce;
+    /** Enable/disable the system */ _enabled;
+    /** Number of constraint iterations per update */ _constraintIterations;
+    /** Whether deltaTime is in milliseconds (true) or seconds (false) */ _deltaTimeInMilliseconds;
+    /**
+   * Create a spring bone system.
+   *
+   * @param deltaTimeInMilliseconds - Whether deltaTime is in milliseconds (default: false)
+   */ constructor(deltaTimeInMilliseconds = false){
+        this._springBones = [];
+        this._colliders = [];
+        this._constraints = [];
+        this._gravity = new Vector3(0, -9.8, 0);
+        this._windForce = new Vector3(0, 0, 0);
+        this._enabled = true;
+        this._constraintIterations = 2;
+        this._deltaTimeInMilliseconds = deltaTimeInMilliseconds;
+    }
+    /**
+   * Get/set gravity vector.
+   */ get gravity() {
+        return this._gravity;
+    }
+    set gravity(value) {
+        this._gravity.set(value);
+    }
+    /**
+   * Get/set wind force vector.
+   */ get windForce() {
+        return this._windForce;
+    }
+    set windForce(value) {
+        this._windForce.set(value);
+    }
+    /**
+   * Get/set enabled state.
+   */ get enabled() {
+        return this._enabled;
+    }
+    set enabled(value) {
+        this._enabled = value;
+    }
+    /**
+   * Add a spring bone to the system.
+   *
+   * @param bone - The bone node to control
+   * @param stiffness - Spring stiffness (0-1, default: 0.1)
+   * @param damping - Damping factor (0-1, default: 0.5)
+   * @param mass - Mass of the bone (default: 1)
+   * @param gravityScale - Gravity scale (default: 1)
+   * @param radius - Collision radius (default: 0.05)
+   * @returns The created spring bone
+   */ addSpringBone(bone, stiffness = 0.1, damping = 0.5, mass = 1, gravityScale = 1, radius = 0.05) {
+        const springBone = new SpringBone(bone, stiffness, damping, mass, gravityScale, radius);
+        this._springBones.push(springBone);
+        return springBone;
+    }
+    /**
+   * Add a spring bone chain to the system.
+   *
+   * @remarks
+   * Adds multiple bones in a chain with the same parameters.
+   * The first bone (root) is typically fixed and not simulated.
+   *
+   * @param bones - Array of bone nodes from root to tip
+   * @param stiffness - Spring stiffness (0-1, default: 0.1)
+   * @param damping - Damping factor (0-1, default: 0.5)
+   * @param mass - Mass of each bone (default: 1)
+   * @param gravityScale - Gravity scale (default: 1)
+   * @param radius - Collision radius (default: 0.05)
+   * @param skipRoot - Skip the first bone (root) (default: true)
+   * @returns Array of created spring bones
+   */ addSpringChain(bones, stiffness = 0.1, damping = 0.5, mass = 1, gravityScale = 1, radius = 0.05, skipRoot = true) {
+        const springBones = [];
+        const startIndex = skipRoot ? 1 : 0;
+        for(let i = startIndex; i < bones.length; i++){
+            const springBone = this.addSpringBone(bones[i], stiffness, damping, mass, gravityScale, radius);
+            springBones.push(springBone);
+        }
+        return springBones;
+    }
+    /**
+   * Remove a spring bone from the system.
+   *
+   * @param springBone - The spring bone to remove
+   * @returns True if removed, false if not found
+   */ removeSpringBone(springBone) {
+        const index = this._springBones.indexOf(springBone);
+        if (index >= 0) {
+            this._springBones.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+   * Clear all spring bones.
+   */ clearSpringBones() {
+        this._springBones = [];
+    }
+    /**
+   * Add a collider to the system.
+   *
+   * @param collider - The collider to add
+   */ addCollider(collider) {
+        this._colliders.push(collider);
+    }
+    /**
+   * Remove a collider from the system.
+   *
+   * @param collider - The collider to remove
+   * @returns True if removed, false if not found
+   */ removeCollider(collider) {
+        const index = this._colliders.indexOf(collider);
+        if (index >= 0) {
+            this._colliders.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+   * Clear all colliders.
+   */ clearColliders() {
+        this._colliders = [];
+    }
+    /**
+   * Add a constraint to the system.
+   *
+   * @param constraint - The constraint to add
+   */ addConstraint(constraint) {
+        this._constraints.push(constraint);
+    }
+    /**
+   * Remove a constraint from the system.
+   *
+   * @param constraint - The constraint to remove
+   * @returns True if removed, false if not found
+   */ removeConstraint(constraint) {
+        const index = this._constraints.indexOf(constraint);
+        if (index >= 0) {
+            this._constraints.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+   * Clear all constraints.
+   */ clearConstraints() {
+        this._constraints = [];
+    }
+    /**
+   * Create circular constraints for skirt-like structures.
+   *
+   * @remarks
+   * This is a convenience method for creating distance constraints
+   * between adjacent chains arranged in a circle (e.g., skirt panels).
+   *
+   * @param chains - Array of spring bone chains arranged in a circle
+   * @param minDistance - Minimum distance between adjacent bones (default: 0.05)
+   * @param maxDistance - Maximum distance between adjacent bones (default: 0.15)
+   * @param stiffness - Constraint stiffness (0-1, default: 0.5)
+   * @returns The created circular constraint
+   */ createCircularConstraints(chains, minDistance = 0.05, maxDistance = 0.15, stiffness = 0.5) {
+        const constraint = new CircularConstraint(chains, minDistance, maxDistance, stiffness);
+        this.addConstraint(constraint);
+        return constraint;
+    }
+    /**
+   * Get/set number of constraint iterations.
+   *
+   * @remarks
+   * Higher values give more accurate constraint solving but cost more performance.
+   * Typical values: 1-5
+   */ get constraintIterations() {
+        return this._constraintIterations;
+    }
+    set constraintIterations(value) {
+        this._constraintIterations = Math.max(1, Math.floor(value));
+    }
+    /**
+   * Reset all spring bones to their initial state.
+   */ reset() {
+        for (const springBone of this._springBones){
+            springBone.reset();
+        }
+    }
+    /**
+   * Update parent bone rotation if parent is not in the spring system.
+   *
+   * @remarks
+   * When skipRoot=true, the parent bone is not in the spring system,
+   * but its rotation still needs to be updated to point toward the
+   * spring bone's simulated position.
+   *
+   * @param springBone - The spring bone whose parent should be updated
+   */ _updateParentRotation(springBone) {
+        const bone = springBone.bone;
+        const parent = bone.parent;
+        if (!parent) {
+            return; // No parent to update
+        }
+        // Check if parent is in the spring system
+        const parentIsSpringBone = this._springBones.some((sb)=>sb.bone === parent);
+        if (parentIsSpringBone) {
+            return; // Parent is already being updated by the spring system
+        }
+        // Parent is not in the spring system, so we need to update its rotation
+        // to point toward the spring bone's simulated position
+        // Get parent's world position
+        const parentWorldPos = new Vector3();
+        parent.worldMatrix.decompose(null, null, parentWorldPos);
+        // Get simulated position
+        const simulatedPos = springBone.currentPosition;
+        // Calculate direction from parent to simulated position (in world space)
+        const currentDir = Vector3.sub(simulatedPos, parentWorldPos, new Vector3());
+        const currentLength = currentDir.magnitude;
+        if (currentLength < 0.000001) {
+            return; // Too close to parent
+        }
+        currentDir.scaleBy(1 / currentLength);
+        // Get grandparent (parent's parent) if it exists
+        const grandparent = parent.parent;
+        let grandparentWorldRot = new Quaternion().identity();
+        if (grandparent) {
+            grandparent.worldMatrix.decompose(null, grandparentWorldRot, null);
+        }
+        // Transform current direction to grandparent's local space
+        const grandparentInvRot = Quaternion.conjugate(grandparentWorldRot, new Quaternion());
+        const currentDirLocal = grandparentInvRot.transform(currentDir, new Vector3());
+        // Original direction in local space (normalized)
+        const originalDirLocal = Vector3.normalize(springBone.initialLocalPosition, new Vector3());
+        // Calculate local rotation from original to current
+        const localRotation = new Quaternion();
+        this._fromToRotation(originalDirLocal, currentDirLocal, localRotation);
+        // Apply to parent bone
+        parent.rotation = localRotation;
+    }
+    /**
+   * Calculate rotation from one direction to another.
+   */ _fromToRotation(from, to, result) {
+        const dot = Vector3.dot(from, to);
+        if (dot >= 0.999999) {
+            return result.identity();
+        }
+        if (dot <= -0.999999) {
+            let axis = Vector3.cross(Vector3.axisPX(), from, new Vector3());
+            const lenSq = axis.x * axis.x + axis.y * axis.y + axis.z * axis.z;
+            if (lenSq < 0.000001) {
+                axis = Vector3.cross(Vector3.axisPY(), from, new Vector3());
+            }
+            axis.inplaceNormalize();
+            return result.fromAxisAngle(axis, Math.PI);
+        }
+        const axis = Vector3.cross(from, to).inplaceNormalize();
+        const angle = Math.acos(dot);
+        return result.fromAxisAngle(axis, angle);
+    }
+    /**
+   * Update the spring bone system.
+   *
+   * @param deltaTime - Time step (in seconds or milliseconds, depending on constructor parameter)
+   */ update(deltaTime) {
+        if (!this._enabled || deltaTime <= 0) {
+            return;
+        }
+        // Convert to seconds if needed
+        const deltaTimeSeconds = this._deltaTimeInMilliseconds ? deltaTime / 1000 : deltaTime;
+        // Clamp delta time to avoid instability
+        const clampedDeltaTime = Math.min(deltaTimeSeconds, 0.1);
+        // Update spring bones one by one (not in parallel)
+        // This ensures parent bones are updated before child bones
+        for (const springBone of this._springBones){
+            // Update physics
+            springBone.update(clampedDeltaTime, this._gravity, this._windForce);
+            // Apply collisions
+            const position = springBone.currentPosition;
+            const radius = springBone.radius;
+            for (const collider of this._colliders){
+                collider.collide(position, radius);
+            }
+            // Update parent bone rotation if parent is not in the spring system
+            this._updateParentRotation(springBone);
+            // Apply to bone node
+            springBone.applyToNode();
+            // Force update the bone's world matrix
+            // This ensures child bones see the updated parent transform
+            const bone = springBone.bone;
+            if (typeof bone.updateWorldMatrix === 'function') {
+                bone.updateWorldMatrix(true, false);
+            }
+        }
+        // Apply constraints (multiple iterations for better convergence)
+        for(let i = 0; i < this._constraintIterations; i++){
+            for (const constraint of this._constraints){
+                constraint.apply();
+            }
+        }
+    }
+    /**
+   * Get all spring bones.
+   */ get springBones() {
+        return this._springBones;
+    }
+    /**
+   * Get all colliders.
+   */ get colliders() {
+        return this._colliders;
+    }
+}
+
+export { SpringBoneSystem };
+//# sourceMappingURL=spring_bone_system.js.map

package/dist/animation/spring/spring_bone_system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring_bone_system.js","sources":["../../../src/animation/spring/spring_bone_system.ts"],"sourcesContent":["import { Vector3, Quaternion } from '@zephyr3d/base';\r\nimport { SpringBone } from './spring_bone';\r\nimport type { SpringBoneCollider } from './spring_bone_collider';\r\nimport type { SpringBoneConstraint } from './spring_bone_constraint';\r\nimport { CircularConstraint } from './spring_bone_constraint';\r\nimport type { SceneNode } from '../../scene/scene_node';\r\n\r\n/**\r\n * Spring bone system manager.\r\n *\r\n * @remarks\r\n * Manages multiple spring bones, colliders, and constraints.\r\n * Updates physics simulation and applies results to bone nodes.\r\n *\r\n * @public\r\n */\r\nexport class SpringBoneSystem {\r\n  /** All spring bones in the system */\r\n  private _springBones: SpringBone[];\r\n  /** All colliders in the system */\r\n  private _colliders: SpringBoneCollider[];\r\n  /** All constraints in the system */\r\n  private _constraints: SpringBoneConstraint[];\r\n  /** Gravity vector in world space */\r\n  private _gravity: Vector3;\r\n  /** Wind force vector in world space */\r\n  private _windForce: Vector3;\r\n  /** Enable/disable the system */\r\n  private _enabled: boolean;\r\n  /** Number of constraint iterations per update */\r\n  private _constraintIterations: number;\r\n  /** Whether deltaTime is in milliseconds (true) or seconds (false) */\r\n  private _deltaTimeInMilliseconds: boolean;\r\n\r\n  /**\r\n   * Create a spring bone system.\r\n   *\r\n   * @param deltaTimeInMilliseconds - Whether deltaTime is in milliseconds (default: false)\r\n   */\r\n  constructor(deltaTimeInMilliseconds = false) {\r\n    this._springBones = [];\r\n    this._colliders = [];\r\n    this._constraints = [];\r\n    this._gravity = new Vector3(0, -9.8, 0);\r\n    this._windForce = new Vector3(0, 0, 0);\r\n    this._enabled = true;\r\n    this._constraintIterations = 2;\r\n    this._deltaTimeInMilliseconds = deltaTimeInMilliseconds;\r\n  }\r\n\r\n  /**\r\n   * Get/set gravity vector.\r\n   */\r\n  get gravity(): Vector3 {\r\n    return this._gravity;\r\n  }\r\n\r\n  set gravity(value: Vector3) {\r\n    this._gravity.set(value);\r\n  }\r\n\r\n  /**\r\n   * Get/set wind force vector.\r\n   */\r\n  get windForce(): Vector3 {\r\n    return this._windForce;\r\n  }\r\n\r\n  set windForce(value: Vector3) {\r\n    this._windForce.set(value);\r\n  }\r\n\r\n  /**\r\n   * Get/set enabled state.\r\n   */\r\n  get enabled(): boolean {\r\n    return this._enabled;\r\n  }\r\n\r\n  set enabled(value: boolean) {\r\n    this._enabled = value;\r\n  }\r\n\r\n  /**\r\n   * Add a spring bone to the system.\r\n   *\r\n   * @param bone - The bone node to control\r\n   * @param stiffness - Spring stiffness (0-1, default: 0.1)\r\n   * @param damping - Damping factor (0-1, default: 0.5)\r\n   * @param mass - Mass of the bone (default: 1)\r\n   * @param gravityScale - Gravity scale (default: 1)\r\n   * @param radius - Collision radius (default: 0.05)\r\n   * @returns The created spring bone\r\n   */\r\n  addSpringBone(\r\n    bone: SceneNode,\r\n    stiffness = 0.1,\r\n    damping = 0.5,\r\n    mass = 1,\r\n    gravityScale = 1,\r\n    radius = 0.05\r\n  ): SpringBone {\r\n    const springBone = new SpringBone(bone, stiffness, damping, mass, gravityScale, radius);\r\n    this._springBones.push(springBone);\r\n    return springBone;\r\n  }\r\n\r\n  /**\r\n   * Add a spring bone chain to the system.\r\n   *\r\n   * @remarks\r\n   * Adds multiple bones in a chain with the same parameters.\r\n   * The first bone (root) is typically fixed and not simulated.\r\n   *\r\n   * @param bones - Array of bone nodes from root to tip\r\n   * @param stiffness - Spring stiffness (0-1, default: 0.1)\r\n   * @param damping - Damping factor (0-1, default: 0.5)\r\n   * @param mass - Mass of each bone (default: 1)\r\n   * @param gravityScale - Gravity scale (default: 1)\r\n   * @param radius - Collision radius (default: 0.05)\r\n   * @param skipRoot - Skip the first bone (root) (default: true)\r\n   * @returns Array of created spring bones\r\n   */\r\n  addSpringChain(\r\n    bones: SceneNode[],\r\n    stiffness = 0.1,\r\n    damping = 0.5,\r\n    mass = 1,\r\n    gravityScale = 1,\r\n    radius = 0.05,\r\n    skipRoot = true\r\n  ): SpringBone[] {\r\n    const springBones: SpringBone[] = [];\r\n    const startIndex = skipRoot ? 1 : 0;\r\n\r\n    for (let i = startIndex; i < bones.length; i++) {\r\n      const springBone = this.addSpringBone(bones[i], stiffness, damping, mass, gravityScale, radius);\r\n      springBones.push(springBone);\r\n    }\r\n\r\n    return springBones;\r\n  }\r\n\r\n  /**\r\n   * Remove a spring bone from the system.\r\n   *\r\n   * @param springBone - The spring bone to remove\r\n   * @returns True if removed, false if not found\r\n   */\r\n  removeSpringBone(springBone: SpringBone): boolean {\r\n    const index = this._springBones.indexOf(springBone);\r\n    if (index >= 0) {\r\n      this._springBones.splice(index, 1);\r\n      return true;\r\n    }\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * Clear all spring bones.\r\n   */\r\n  clearSpringBones(): void {\r\n    this._springBones = [];\r\n  }\r\n\r\n  /**\r\n   * Add a collider to the system.\r\n   *\r\n   * @param collider - The collider to add\r\n   */\r\n  addCollider(collider: SpringBoneCollider): void {\r\n    this._colliders.push(collider);\r\n  }\r\n\r\n  /**\r\n   * Remove a collider from the system.\r\n   *\r\n   * @param collider - The collider to remove\r\n   * @returns True if removed, false if not found\r\n   */\r\n  removeCollider(collider: SpringBoneCollider): boolean {\r\n    const index = this._colliders.indexOf(collider);\r\n    if (index >= 0) {\r\n      this._colliders.splice(index, 1);\r\n      return true;\r\n    }\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * Clear all colliders.\r\n   */\r\n  clearColliders(): void {\r\n    this._colliders = [];\r\n  }\r\n\r\n  /**\r\n   * Add a constraint to the system.\r\n   *\r\n   * @param constraint - The constraint to add\r\n   */\r\n  addConstraint(constraint: SpringBoneConstraint): void {\r\n    this._constraints.push(constraint);\r\n  }\r\n\r\n  /**\r\n   * Remove a constraint from the system.\r\n   *\r\n   * @param constraint - The constraint to remove\r\n   * @returns True if removed, false if not found\r\n   */\r\n  removeConstraint(constraint: SpringBoneConstraint): boolean {\r\n    const index = this._constraints.indexOf(constraint);\r\n    if (index >= 0) {\r\n      this._constraints.splice(index, 1);\r\n      return true;\r\n    }\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * Clear all constraints.\r\n   */\r\n  clearConstraints(): void {\r\n    this._constraints = [];\r\n  }\r\n\r\n  /**\r\n   * Create circular constraints for skirt-like structures.\r\n   *\r\n   * @remarks\r\n   * This is a convenience method for creating distance constraints\r\n   * between adjacent chains arranged in a circle (e.g., skirt panels).\r\n   *\r\n   * @param chains - Array of spring bone chains arranged in a circle\r\n   * @param minDistance - Minimum distance between adjacent bones (default: 0.05)\r\n   * @param maxDistance - Maximum distance between adjacent bones (default: 0.15)\r\n   * @param stiffness - Constraint stiffness (0-1, default: 0.5)\r\n   * @returns The created circular constraint\r\n   */\r\n  createCircularConstraints(\r\n    chains: SpringBone[][],\r\n    minDistance = 0.05,\r\n    maxDistance = 0.15,\r\n    stiffness = 0.5\r\n  ): CircularConstraint {\r\n    const constraint = new CircularConstraint(chains, minDistance, maxDistance, stiffness);\r\n    this.addConstraint(constraint);\r\n    return constraint;\r\n  }\r\n\r\n  /**\r\n   * Get/set number of constraint iterations.\r\n   *\r\n   * @remarks\r\n   * Higher values give more accurate constraint solving but cost more performance.\r\n   * Typical values: 1-5\r\n   */\r\n  get constraintIterations(): number {\r\n    return this._constraintIterations;\r\n  }\r\n\r\n  set constraintIterations(value: number) {\r\n    this._constraintIterations = Math.max(1, Math.floor(value));\r\n  }\r\n\r\n  /**\r\n   * Reset all spring bones to their initial state.\r\n   */\r\n  reset(): void {\r\n    for (const springBone of this._springBones) {\r\n      springBone.reset();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Update parent bone rotation if parent is not in the spring system.\r\n   *\r\n   * @remarks\r\n   * When skipRoot=true, the parent bone is not in the spring system,\r\n   * but its rotation still needs to be updated to point toward the\r\n   * spring bone's simulated position.\r\n   *\r\n   * @param springBone - The spring bone whose parent should be updated\r\n   */\r\n  private _updateParentRotation(springBone: SpringBone): void {\r\n    const bone = springBone.bone;\r\n    const parent = bone.parent;\r\n\r\n    if (!parent) {\r\n      return; // No parent to update\r\n    }\r\n\r\n    // Check if parent is in the spring system\r\n    const parentIsSpringBone = this._springBones.some((sb) => sb.bone === parent);\r\n    if (parentIsSpringBone) {\r\n      return; // Parent is already being updated by the spring system\r\n    }\r\n\r\n    // Parent is not in the spring system, so we need to update its rotation\r\n    // to point toward the spring bone's simulated position\r\n\r\n    // Get parent's world position\r\n    const parentWorldPos = new Vector3();\r\n    parent.worldMatrix.decompose(null, null, parentWorldPos);\r\n\r\n    // Get simulated position\r\n    const simulatedPos = springBone.currentPosition;\r\n\r\n    // Calculate direction from parent to simulated position (in world space)\r\n    const currentDir = Vector3.sub(simulatedPos, parentWorldPos, new Vector3());\r\n    const currentLength = currentDir.magnitude;\r\n\r\n    if (currentLength < 0.000001) {\r\n      return; // Too close to parent\r\n    }\r\n\r\n    currentDir.scaleBy(1 / currentLength);\r\n\r\n    // Get grandparent (parent's parent) if it exists\r\n    const grandparent = parent.parent;\r\n    let grandparentWorldRot = new Quaternion().identity();\r\n\r\n    if (grandparent) {\r\n      grandparent.worldMatrix.decompose(null, grandparentWorldRot, null);\r\n    }\r\n\r\n    // Transform current direction to grandparent's local space\r\n    const grandparentInvRot = Quaternion.conjugate(grandparentWorldRot, new Quaternion());\r\n    const currentDirLocal = grandparentInvRot.transform(currentDir, new Vector3());\r\n\r\n    // Original direction in local space (normalized)\r\n    const originalDirLocal = Vector3.normalize(springBone.initialLocalPosition, new Vector3());\r\n\r\n    // Calculate local rotation from original to current\r\n    const localRotation = new Quaternion();\r\n    this._fromToRotation(originalDirLocal, currentDirLocal, localRotation);\r\n\r\n    // Apply to parent bone\r\n    parent.rotation = localRotation;\r\n  }\r\n\r\n  /**\r\n   * Calculate rotation from one direction to another.\r\n   */\r\n  private _fromToRotation(from: Vector3, to: Vector3, result: Quaternion): Quaternion {\r\n    const dot = Vector3.dot(from, to);\r\n\r\n    if (dot >= 0.999999) {\r\n      return result.identity();\r\n    }\r\n\r\n    if (dot <= -0.999999) {\r\n      let axis = Vector3.cross(Vector3.axisPX(), from, new Vector3());\r\n      const lenSq = axis.x * axis.x + axis.y * axis.y + axis.z * axis.z;\r\n      if (lenSq < 0.000001) {\r\n        axis = Vector3.cross(Vector3.axisPY(), from, new Vector3());\r\n      }\r\n      axis.inplaceNormalize();\r\n      return result.fromAxisAngle(axis, Math.PI);\r\n    }\r\n\r\n    const axis = Vector3.cross(from, to).inplaceNormalize();\r\n    const angle = Math.acos(dot);\r\n    return result.fromAxisAngle(axis, angle);\r\n  }\r\n\r\n  /**\r\n   * Update the spring bone system.\r\n   *\r\n   * @param deltaTime - Time step (in seconds or milliseconds, depending on constructor parameter)\r\n   */\r\n  update(deltaTime: number): void {\r\n    if (!this._enabled || deltaTime <= 0) {\r\n      return;\r\n    }\r\n\r\n    // Convert to seconds if needed\r\n    const deltaTimeSeconds = this._deltaTimeInMilliseconds ? deltaTime / 1000 : deltaTime;\r\n\r\n    // Clamp delta time to avoid instability\r\n    const clampedDeltaTime = Math.min(deltaTimeSeconds, 0.1);\r\n\r\n    // Update spring bones one by one (not in parallel)\r\n    // This ensures parent bones are updated before child bones\r\n    for (const springBone of this._springBones) {\r\n      // Update physics\r\n      springBone.update(clampedDeltaTime, this._gravity, this._windForce);\r\n\r\n      // Apply collisions\r\n      const position = springBone.currentPosition;\r\n      const radius = springBone.radius;\r\n\r\n      for (const collider of this._colliders) {\r\n        collider.collide(position, radius);\r\n      }\r\n\r\n      // Update parent bone rotation if parent is not in the spring system\r\n      this._updateParentRotation(springBone);\r\n\r\n      // Apply to bone node\r\n      springBone.applyToNode();\r\n\r\n      // Force update the bone's world matrix\r\n      // This ensures child bones see the updated parent transform\r\n      const bone = springBone.bone;\r\n      if (typeof (bone as any).updateWorldMatrix === 'function') {\r\n        (bone as any).updateWorldMatrix(true, false);\r\n      }\r\n    }\r\n\r\n    // Apply constraints (multiple iterations for better convergence)\r\n    for (let i = 0; i < this._constraintIterations; i++) {\r\n      for (const constraint of this._constraints) {\r\n        constraint.apply();\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all spring bones.\r\n   */\r\n  get springBones(): readonly SpringBone[] {\r\n    return this._springBones;\r\n  }\r\n\r\n  /**\r\n   * Get all colliders.\r\n   */\r\n  get colliders(): readonly SpringBoneCollider[] {\r\n    return this._colliders;\r\n  }\r\n}\r\n"],"names":["SpringBoneSystem","deltaTimeInMilliseconds","_springBones","_colliders","_constraints","_gravity","Vector3","_windForce","_enabled","_constraintIterations","_deltaTimeInMilliseconds","gravity","value","set","windForce","enabled","addSpringBone","bone","stiffness","damping","mass","gravityScale","radius","springBone","SpringBone","push","addSpringChain","bones","skipRoot","springBones","startIndex","i","length","removeSpringBone","index","indexOf","splice","clearSpringBones","addCollider","collider","removeCollider","clearColliders","addConstraint","constraint","removeConstraint","clearConstraints","createCircularConstraints","chains","minDistance","maxDistance","CircularConstraint","constraintIterations","Math","max","floor","reset","_updateParentRotation","parent","parentIsSpringBone","some","sb","parentWorldPos","worldMatrix","decompose","simulatedPos","currentPosition","currentDir","sub","currentLength","magnitude","scaleBy","grandparent","grandparentWorldRot","Quaternion","identity","grandparentInvRot","conjugate","currentDirLocal","transform","originalDirLocal","normalize","initialLocalPosition","localRotation","_fromToRotation","rotation","from","to","result","dot","axis","cross","axisPX","lenSq","x","y","z","axisPY","inplaceNormalize","fromAxisAngle","PI","angle","acos","update","deltaTime","deltaTimeSeconds","clampedDeltaTime","min","position","collide","applyToNode","updateWorldMatrix","apply","colliders"],"mappings":"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"}

package/dist/asset/model.js

@@ -1,12 +1,12 @@
 import { Vector3, Quaternion, Matrix4x4, Disposable, DRef } from '@zephyr3d/base';
 import { Mesh } from '../scene/mesh.js';
 import { SceneNode } from '../scene/scene_node.js';
-import { NodeTranslationTrack } from '../animation/translationtrack.js';
 import { NodeRotationTrack } from '../animation/rotationtrack.js';
 import '../animation/eulerrotationtrack.js';
+import { NodeTranslationTrack } from '../animation/translationtrack.js';
 import { NodeScaleTrack } from '../animation/scaletrack.js';
-import { MorphTargetTrack } from '../animation/morphtrack.js';
 import { Skeleton } from '../animation/skeleton.js';
+import { MorphTargetTrack } from '../animation/morphtrack.js';
 import { processMorphData } from '../animation/morphtarget.js';
 import { MAX_MORPH_TARGETS } from '../values.js';
 

package/dist/index.d.ts

@@ -12210,6 +12210,7 @@ declare class Skeleton extends Disposable {
         scale: Vector3;
         position: Vector3;
     }[]);
+    get bindPoseModelSpace(): Matrix4x4[];
     set playing(b: boolean);
     set persistentId(val: string);
     /**
@@ -12262,6 +12263,7 @@ declare class Skeleton extends Disposable {
         blendIndices: TypedArray;
         weights: TypedArray;
     }): SkinnedBoundingBox;
+    private findRootJoint;
 }
 
 /**
@@ -12449,6 +12451,21 @@ declare class AnimationSet extends Disposable implements IDisposable {
      * @param options - Optional fade-out configuration.
      */
     stopAnimation(name: string, options?: StopAnimationOptions): void;
+    /**
+     * Copy an animation clip from another AnimationSet into this one.
+     *
+     * Prerequisites:
+     * - Both sets must reference skeletons with identical joint names and counts.
+     * - The source clip must exist in `sourceSet`.
+     *
+     * @param sourceSet - The AnimationSet to copy from.
+     * @param animationName - Name of the clip to copy.
+     * @param targetName - Name for the new clip in this set. Defaults to `animationName`.
+     * @param excludeJoint - Optional predicate; joints whose name returns true are excluded from
+     *   skeleton structure matching.
+     * @returns The newly created AnimationClip, or null on failure.
+     */
+    copyAnimationFrom(sourceSet: AnimationSet, animationName: string, targetName?: string, excludeJoint?: (jointName: string) => boolean): AnimationClip | null;
     /**
      * Dispose the animation set and release owned resources.
      *