@zephyr3d/scene 0.9.25 → 0.9.26

package/dist/animation/spring/multi_chain_spring_system.js

@@ -1,14 +1,14 @@
 import { Vector3, Quaternion } from '@zephyr3d/base';
 import { IKUtils } from '../ik/ik_utils.js';
+import { updateColliderFromNode, resolveSphereCollision, resolveCapsuleCollision, resolvePlaneCollision } from './spring_collider.js';
+import { SpringNodePoseTracker } from './spring_node_pose_tracker.js';
 
-/**
- * Physics engine for multiple spring chains with inter-chain constraints
- * Suitable for cloth, skirts, capes, and other multi-chain simulations
- *
- * @deprecated Use the new {@link JointDynamicsSystem} class instead.
- *
- * @public
- */ class MultiChainSpringSystem {
+const FIXED_SIMULATION_TIME_STEP = 1 / 60;
+const MAX_ACCUMULATED_SIMULATION_TIME = 1 / 20;
+const MAX_SIMULATION_STEPS_PER_UPDATE = Math.max(1, Math.ceil(MAX_ACCUMULATED_SIMULATION_TIME / FIXED_SIMULATION_TIME_STEP));
+const DEFAULT_PARTICLE_TARGET_SMOOTHING_TIME = 1 / 30;
+const DEFAULT_COLLIDER_SMOOTHING_TIME = 1 / 30;
+class MultiChainSpringSystem {
     _chains;
     _interChainConstraints;
     _iterations;
@@ -18,6 +18,23 @@ import { IKUtils } from '../ik/ik_utils.js';
     _centrifugalScale;
     _coriolisScale;
     _solver;
+    _poseFollow;
+    _maxPoseOffset;
+    _poseFollowRoot;
+    _poseFollowTip;
+    _poseFollowExponent;
+    _maxPoseOffsetRoot;
+    _maxPoseOffsetTip;
+    _colliders;
+    _timeAccumulator;
+    _smoothedParticleTargets;
+    _smoothedSphereCenters;
+    _smoothedCapsuleEndpoints;
+    _smoothedPlaneData;
+    _runtimeNodeMap;
+    _runtimeAnchorOffsets;
+    _runtimeRestLengths;
+    _nodePoseTracker;
     constructor(options){
         this._chains = [];
         this._interChainConstraints = [];
@@ -28,26 +45,32 @@ import { IKUtils } from '../ik/ik_utils.js';
         this._centrifugalScale = options?.centrifugalScale ?? 1.0;
         this._coriolisScale = options?.coriolisScale ?? 1.0;
         this._solver = options?.solver ?? 'verlet';
-    }
-    /**
-   * Adds a spring chain to the system
-   * @param chain - The chain to add
-   * @returns The index of the added chain
-   */ addChain(chain) {
+        this._poseFollow = Math.max(0, Math.min(1, options?.poseFollow ?? 0.35));
+        this._maxPoseOffset = Math.max(0, options?.maxPoseOffset ?? 0);
+        this._poseFollowRoot = Math.max(0, Math.min(1, options?.poseFollowRoot ?? this._poseFollow));
+        this._poseFollowTip = Math.max(0, Math.min(1, options?.poseFollowTip ?? this._poseFollow));
+        this._poseFollowExponent = Math.max(0.1, options?.poseFollowExponent ?? 1.6);
+        this._maxPoseOffsetRoot = Math.max(0, options?.maxPoseOffsetRoot ?? this._maxPoseOffset);
+        this._maxPoseOffsetTip = Math.max(0, options?.maxPoseOffsetTip ?? this._maxPoseOffset);
+        this._colliders = [];
+        this._timeAccumulator = 0;
+        this._smoothedParticleTargets = new WeakMap();
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
+        this._runtimeNodeMap = null;
+        this._runtimeAnchorOffsets = new WeakMap();
+        this._runtimeRestLengths = new WeakMap();
+        this._nodePoseTracker = new SpringNodePoseTracker();
+    }
+    addChain(chain) {
         this._chains.push(chain);
         return this._chains.length - 1;
     }
-    /**
-   * Adds an inter-chain constraint
-   * @param constraint - The constraint to add
-   */ addInterChainConstraint(constraint) {
+    addInterChainConstraint(constraint) {
         this._interChainConstraints.push(constraint);
     }
-    /**
-   * Creates radial constraints between adjacent chains
-   * Useful for skirts, capes, and other radial multi-chain structures
-   * @param options - Configuration options
-   */ createRadialConstraints(options) {
+    createRadialConstraints(options) {
         const skipRows = options.skipRows ?? 0;
         const connectDistance = options.connectDistance ?? 1;
         const compliance = options.compliance ?? 0;
@@ -77,21 +100,272 @@ import { IKUtils } from '../ik/ik_utils.js';
             }
         }
     }
+    update(deltaTime) {
+        this._nodePoseTracker.restoreInputPose();
+        const frameDt = Math.min(Math.max(Number(deltaTime) || 0, 0), MAX_ACCUMULATED_SIMULATION_TIME);
+        if (frameDt <= 0) {
+            return;
+        }
+        this._timeAccumulator = Math.min(this._timeAccumulator + frameDt, MAX_ACCUMULATED_SIMULATION_TIME);
+        const stepCount = Math.min(MAX_SIMULATION_STEPS_PER_UPDATE, Math.floor((this._timeAccumulator + 1e-8) / FIXED_SIMULATION_TIME_STEP));
+        if (stepCount <= 0) {
+            return;
+        }
+        this._timeAccumulator = Math.max(0, this._timeAccumulator - stepCount * FIXED_SIMULATION_TIME_STEP);
+        for(let i = 0; i < stepCount; i++){
+            this.simulateStep(FIXED_SIMULATION_TIME_STEP, i === 0 ? frameDt : 0);
+        }
+    }
+    applyToNodes(weight = 1.0) {
+        const baseNodeStates = new Map();
+        const desiredWorldRotations = new Map();
+        for (const chain of this._chains){
+            this.collectChainNodeRotations(chain, weight, baseNodeStates, desiredWorldRotations);
+        }
+        const nodes = Array.from(desiredWorldRotations.keys());
+        nodes.sort((a, b)=>this.getNodeDepth(a) - this.getNodeDepth(b));
+        for (const node of nodes){
+            const worldRotation = desiredWorldRotations.get(node);
+            if (!worldRotation) {
+                continue;
+            }
+            const parent = node.parent;
+            const inputRotation = node.rotation.clone();
+            if (parent) {
+                const parentWorldRotation = new Quaternion();
+                parent.worldMatrix.decompose(null, parentWorldRotation, null);
+                const parentInvRotation = Quaternion.conjugate(parentWorldRotation, new Quaternion());
+                const localRotation = Quaternion.multiply(parentInvRotation, worldRotation, new Quaternion());
+                node.rotation = localRotation;
+                this._nodePoseTracker.recordAppliedRotation(node, inputRotation, localRotation);
+            } else {
+                node.rotation = worldRotation;
+                this._nodePoseTracker.recordAppliedRotation(node, inputRotation, worldRotation);
+            }
+        }
+    }
+    reset() {
+        this._nodePoseTracker.clear(true);
+        for (const chain of this._chains){
+            chain.reset();
+            for (const particle of chain.particles){
+                particle.animPosition.set(particle.originalPosition);
+                particle.lastFramePosition.set(particle.originalPosition);
+                if (particle.positionHistory) {
+                    particle.positionHistory.length = 0;
+                }
+            }
+        }
+        for (const constraint of this._interChainConstraints){
+            constraint.lambda = 0;
+        }
+        this._timeAccumulator = 0;
+        this._smoothedParticleTargets = new WeakMap();
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
+    }
+    get chains() {
+        return this._chains;
+    }
+    get interChainConstraints() {
+        return this._interChainConstraints;
+    }
+    get gravity() {
+        return this._gravity;
+    }
+    set gravity(gravity) {
+        this._gravity.set(gravity);
+    }
+    get wind() {
+        return this._wind;
+    }
+    set wind(wind) {
+        this._wind.set(wind);
+    }
+    get iterations() {
+        return this._iterations;
+    }
+    set iterations(count) {
+        this._iterations = Math.max(1, count);
+    }
+    get enableInertialForces() {
+        return this._enableInertialForces;
+    }
+    set enableInertialForces(enabled) {
+        this._enableInertialForces = enabled;
+    }
+    get centrifugalScale() {
+        return this._centrifugalScale;
+    }
+    set centrifugalScale(scale) {
+        this._centrifugalScale = Math.max(0, scale);
+    }
+    get coriolisScale() {
+        return this._coriolisScale;
+    }
+    set coriolisScale(scale) {
+        this._coriolisScale = Math.max(0, scale);
+    }
+    get solver() {
+        return this._solver;
+    }
+    set solver(type) {
+        if (this._solver !== type) {
+            this._solver = type;
+            if (type === 'xpbd') {
+                this.resetConstraintLambdas();
+            }
+        }
+    }
+    get poseFollow() {
+        return this._poseFollow;
+    }
+    set poseFollow(value) {
+        const v = Math.max(0, Math.min(1, value));
+        this._poseFollow = v;
+        this._poseFollowRoot = v;
+        this._poseFollowTip = v;
+    }
+    get poseFollowRoot() {
+        return this._poseFollowRoot;
+    }
+    set poseFollowRoot(value) {
+        this._poseFollowRoot = Math.max(0, Math.min(1, value));
+    }
+    get poseFollowTip() {
+        return this._poseFollowTip;
+    }
+    set poseFollowTip(value) {
+        this._poseFollowTip = Math.max(0, Math.min(1, value));
+    }
+    get poseFollowExponent() {
+        return this._poseFollowExponent;
+    }
+    set poseFollowExponent(value) {
+        this._poseFollowExponent = Math.max(0.1, value);
+    }
+    get maxPoseOffset() {
+        return this._maxPoseOffset;
+    }
+    set maxPoseOffset(value) {
+        const v = Math.max(0, value);
+        this._maxPoseOffset = v;
+        this._maxPoseOffsetRoot = v;
+        this._maxPoseOffsetTip = v;
+    }
+    get maxPoseOffsetRoot() {
+        return this._maxPoseOffsetRoot;
+    }
+    set maxPoseOffsetRoot(value) {
+        this._maxPoseOffsetRoot = Math.max(0, value);
+    }
+    get maxPoseOffsetTip() {
+        return this._maxPoseOffsetTip;
+    }
+    set maxPoseOffsetTip(value) {
+        this._maxPoseOffsetTip = Math.max(0, value);
+    }
+    addCollider(collider) {
+        this._colliders.push(collider);
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
+    }
+    removeCollider(collider) {
+        const index = this._colliders.indexOf(collider);
+        if (index >= 0) {
+            this._colliders.splice(index, 1);
+            this._smoothedSphereCenters = new WeakMap();
+            this._smoothedCapsuleEndpoints = new WeakMap();
+            this._smoothedPlaneData = new WeakMap();
+            return true;
+        }
+        return false;
+    }
+    clearColliders() {
+        this._colliders = [];
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
+    }
+    get colliders() {
+        return this._colliders;
+    }
     /**
-   * Updates the physics simulation for all chains
-   * @param deltaTime - Time step in seconds
-   */ update(deltaTime) {
-        const dt = Math.min(deltaTime, 0.033);
-        // Save all particle positions before updating
+   * Sets a runtime-only node remapping used by particles, anchors and colliders.
+   * The authored node references remain unchanged and therefore serialize normally.
+   */ setRuntimeNodeMap(nodeMap) {
+        this._nodePoseTracker.clear(false);
+        this._runtimeNodeMap = nodeMap;
+        this._runtimeAnchorOffsets = new WeakMap();
+        this._runtimeRestLengths = new WeakMap();
+        this.clearRuntimeCaches();
+    }
+    /**
+   * Rebuilds particle history from the current runtime-remapped node pose.
+   * This must be called after a hierarchy graft or skeleton rebind.
+   */ reinitializeFromCurrentPose(options) {
+        this._nodePoseTracker.clear(false);
+        const recomputeAnchorOffsets = options?.recomputeAnchorOffsets ?? true;
+        const recalculateRestLengths = options?.recalculateRestLengths ?? true;
+        this._runtimeAnchorOffsets = new WeakMap();
+        this._runtimeRestLengths = new WeakMap();
+        for (const chain of this._chains){
+            for (const particle of chain.particles){
+                const particleNode = this.resolveRuntimeNode(particle.node);
+                let position = particleNode ? new Vector3(particleNode.worldMatrix.m03, particleNode.worldMatrix.m13, particleNode.worldMatrix.m23) : particle.position.clone();
+                const anchorNode = this.resolveRuntimeNode(particle.anchorNode);
+                if (particle.fixed && anchorNode) {
+                    let anchorOffset = particle.anchorOffset;
+                    if (recomputeAnchorOffsets && anchorOffset && particleNode) {
+                        anchorOffset = anchorNode.worldToThis(position, new Vector3());
+                        this._runtimeAnchorOffsets.set(particle, anchorOffset);
+                    }
+                    position = anchorOffset ? anchorNode.worldMatrix.transformPointAffine(anchorOffset, new Vector3()) : new Vector3(anchorNode.worldMatrix.m03, anchorNode.worldMatrix.m13, anchorNode.worldMatrix.m23);
+                }
+                particle.position.set(position);
+                particle.prevPosition.set(position);
+                particle.animPosition.set(position);
+                particle.lastFramePosition.set(position);
+                if (particle.positionHistory) {
+                    particle.positionHistory.length = 0;
+                }
+            }
+            for (const constraint of chain.constraints){
+                constraint.lambda = 0;
+                if (recalculateRestLengths) {
+                    this._runtimeRestLengths.set(constraint, Vector3.distance(chain.particles[constraint.particleA].position, chain.particles[constraint.particleB].position));
+                }
+            }
+        }
+        for (const constraint of this._interChainConstraints){
+            constraint.lambda = 0;
+            if (recalculateRestLengths) {
+                const particleA = this._chains[constraint.chainAIndex]?.particles[constraint.particleAIndex];
+                const particleB = this._chains[constraint.chainBIndex]?.particles[constraint.particleBIndex];
+                if (particleA && particleB) {
+                    this._runtimeRestLengths.set(constraint, Vector3.distance(particleA.position, particleB.position));
+                }
+            }
+        }
+        for (const collider of this._colliders){
+            const colliderNode = this.resolveRuntimeNode(collider.node);
+            if (colliderNode) {
+                updateColliderFromNode(collider, colliderNode);
+            }
+        }
+        this.clearRuntimeCaches();
+    }
+    simulateStep(dt, inputDeltaTime) {
         if (this._enableInertialForces) {
             for (const chain of this._chains){
-                for (const p of chain.particles){
-                    p.lastFramePosition.set(p.position);
+                for (const particle of chain.particles){
+                    particle.lastFramePosition.set(particle.position);
                 }
             }
         }
-        this.updateFixedParticles();
-        // Calculate global rotation parameters
+        this.updateFixedParticles(inputDeltaTime);
         let rotationCenter = null;
         let angularVelocity = null;
         if (this._enableInertialForces && dt > 0.0001) {
@@ -107,7 +381,6 @@ import { IKUtils } from '../ik/ik_utils.js';
                 const velocity = Vector3.sub(particle.position, particle.prevPosition, new Vector3());
                 velocity.scaleBy(particle.damping);
                 const acceleration = Vector3.add(this._gravity, this._wind, new Vector3());
-                // Apply inertial forces
                 if (this._enableInertialForces && rotationCenter && angularVelocity) {
                     const inertialAccel = this.calculateInertialAcceleration(particle, rotationCenter, angularVelocity, velocity, this._centrifugalScale, this._coriolisScale);
                     Vector3.add(acceleration, inertialAccel, acceleration);
@@ -119,14 +392,7 @@ import { IKUtils } from '../ik/ik_utils.js';
             }
         }
         if (this._solver === 'xpbd') {
-            for (const chain of this._chains){
-                for (const c of chain.constraints){
-                    c.lambda = 0;
-                }
-            }
-            for (const c of this._interChainConstraints){
-                c.lambda = 0;
-            }
+            this.resetConstraintLambdas();
         }
         for(let iter = 0; iter < this._iterations; iter++){
             for (const chain of this._chains){
@@ -145,21 +411,30 @@ import { IKUtils } from '../ik/ik_utils.js';
                     this.solveInterChainConstraint(constraint);
                 }
             }
+            this.solvePosePreservation(this._iterations);
+            this.solveCollisions(inputDeltaTime);
         }
     }
-    updateFixedParticles() {
+    updateFixedParticles(deltaTime) {
+        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_PARTICLE_TARGET_SMOOTHING_TIME);
         for (const chain of this._chains){
             for (const particle of chain.particles){
-                if (particle.fixed && particle.node) {
-                    const worldPos = new Vector3(particle.node.worldMatrix.m03, particle.node.worldMatrix.m13, particle.node.worldMatrix.m23);
-                    particle.position.set(worldPos);
-                    particle.prevPosition.set(worldPos);
-                    // Maintain position history
+                const sourceNode = this.resolveRuntimeNode(particle.anchorNode ?? particle.node);
+                if (!sourceNode) {
+                    continue;
+                }
+                const anchorOffset = this._runtimeAnchorOffsets.get(particle) ?? particle.anchorOffset;
+                const worldPos = anchorOffset ? sourceNode.worldMatrix.transformPointAffine(anchorOffset) : new Vector3(sourceNode.worldMatrix.m03, sourceNode.worldMatrix.m13, sourceNode.worldMatrix.m23);
+                const smoothedTarget = this.getSmoothedParticleTarget(particle, worldPos, blend);
+                particle.animPosition.set(smoothedTarget);
+                if (particle.fixed) {
+                    particle.position.set(smoothedTarget);
+                    particle.prevPosition.set(smoothedTarget);
                     if (this._enableInertialForces) {
                         if (!particle.positionHistory) {
                             particle.positionHistory = [];
                         }
-                        particle.positionHistory.push(worldPos.clone());
+                        particle.positionHistory.push(smoothedTarget.clone());
                         if (particle.positionHistory.length > 5) {
                             particle.positionHistory.shift();
                         }
@@ -168,18 +443,125 @@ import { IKUtils } from '../ik/ik_utils.js';
             }
         }
     }
+    solvePosePreservation(totalIterations) {
+        if (this._poseFollowRoot <= 0 && this._poseFollowTip <= 0) {
+            return;
+        }
+        for (const chain of this._chains){
+            const lastIndex = Math.max(1, chain.particles.length - 1);
+            for(let i = 0; i < chain.particles.length; i++){
+                const particle = chain.particles[i];
+                if (particle.fixed) {
+                    continue;
+                }
+                const t = Math.pow(i / lastIndex, this._poseFollowExponent);
+                const particlePoseFollow = this.lerp(this._poseFollowRoot, this._poseFollowTip, t);
+                const iterationFollow = totalIterations > 1 ? 1 - Math.pow(Math.max(0, 1 - particlePoseFollow), 1 / totalIterations) : particlePoseFollow;
+                const toAnim = Vector3.sub(particle.animPosition, particle.position, new Vector3());
+                const correction = Vector3.scale(toAnim, iterationFollow, new Vector3());
+                Vector3.add(particle.position, correction, particle.position);
+                const particleMaxPoseOffset = this.lerp(this._maxPoseOffsetRoot, this._maxPoseOffsetTip, t);
+                if (particleMaxPoseOffset > 0) {
+                    const offset = Vector3.sub(particle.position, particle.animPosition, new Vector3());
+                    const offsetLen = offset.magnitude;
+                    if (offsetLen > particleMaxPoseOffset && offsetLen > 1e-6) {
+                        offset.scaleBy(particleMaxPoseOffset / offsetLen);
+                        Vector3.add(particle.animPosition, offset, particle.position);
+                    }
+                }
+            }
+        }
+    }
+    solveCollisions(deltaTime) {
+        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_COLLIDER_SMOOTHING_TIME);
+        const spheres = [];
+        const capsules = [];
+        const planes = [];
+        for (const collider of this._colliders){
+            const colliderNode = this.resolveRuntimeNode(collider.node);
+            if (colliderNode) {
+                updateColliderFromNode(collider, colliderNode);
+            }
+            if (!collider.enabled) {
+                continue;
+            }
+            switch(collider.type){
+                case 'sphere':
+                    {
+                        const source = collider;
+                        spheres.push({
+                            ...source,
+                            center: this.getSmoothedSphereCenter(source, blend)
+                        });
+                        break;
+                    }
+                case 'capsule':
+                    {
+                        const source = collider;
+                        const endpoints = this.getSmoothedCapsuleEndpoints(source, blend);
+                        capsules.push({
+                            ...source,
+                            start: endpoints.start,
+                            end: endpoints.end
+                        });
+                        break;
+                    }
+                case 'plane':
+                    {
+                        const source = collider;
+                        const plane = this.getSmoothedPlaneData(source, blend);
+                        planes.push({
+                            ...source,
+                            point: plane.point,
+                            normal: plane.normal
+                        });
+                        break;
+                    }
+            }
+        }
+        for (const chain of this._chains){
+            for (const particle of chain.particles){
+                if (particle.fixed) {
+                    continue;
+                }
+                const positionBeforeCollision = particle.position.clone();
+                let collided = false;
+                for (const collider of spheres){
+                    collided = resolveSphereCollision(particle.position, collider) || collided;
+                }
+                for (const collider of capsules){
+                    collided = resolveCapsuleCollision(particle.position, collider) || collided;
+                }
+                for (const collider of planes){
+                    collided = resolvePlaneCollision(particle.position, collider) || collided;
+                }
+                if (collided) {
+                    Vector3.add(particle.prevPosition, Vector3.sub(particle.position, positionBeforeCollision, new Vector3()), particle.prevPosition);
+                }
+            }
+        }
+    }
     calculateGlobalRotation(dt) {
         const fixedParticles = [];
         const velocities = [];
+        const drivenNodes = new Set();
         for (const chain of this._chains){
-            for (const p of chain.particles){
-                if (!p.fixed) {
+            for (const particle of chain.particles){
+                const node = this.resolveRuntimeNode(particle.node);
+                if (node) {
+                    drivenNodes.add(node);
+                }
+            }
+        }
+        for (const chain of this._chains){
+            for (const particle of chain.particles){
+                if (!particle.fixed || !this.isExternalInertialAnchor(particle, drivenNodes)) {
                     continue;
                 }
-                const velocity = Vector3.sub(p.position, p.lastFramePosition, new Vector3());
+                const velocity = Vector3.sub(particle.position, particle.lastFramePosition, new Vector3());
                 velocity.scaleBy(1.0 / dt);
                 if (velocity.magnitudeSq > 0.001) {
-                    fixedParticles.push(p);
+                    fixedParticles.push(particle);
                     velocities.push(velocity);
                 }
             }
@@ -190,18 +572,16 @@ import { IKUtils } from '../ik/ik_utils.js';
                 omega: new Vector3(0, 0, 0)
             };
         }
-        // Estimate rotation center
         let center;
         if (fixedParticles.length === 1) {
             center = this.estimateRotationCenterFromHistory(fixedParticles[0], velocities[0]);
         } else {
             center = new Vector3(0, 0, 0);
-            for (const p of fixedParticles){
-                Vector3.add(center, p.position, center);
+            for (const particle of fixedParticles){
+                Vector3.add(center, particle.position, center);
             }
             center.scaleBy(1.0 / fixedParticles.length);
         }
-        // Estimate angular velocity
         let sumOmega = new Vector3(0, 0, 0);
         let count = 0;
         for(let i = 0; i < fixedParticles.length; i++){
@@ -236,16 +616,14 @@ import { IKUtils } from '../ik/ik_utils.js';
             if (perpDir.magnitudeSq < 0.0001) {
                 perpDir.set(new Vector3(1, 0, 0));
             } else {
-                Vector3.normalize(perpDir, perpDir);
+                perpDir.inplaceNormalize();
             }
-            const center = Vector3.add(particle.position, Vector3.scale(perpDir, estimatedRadius, new Vector3()), new Vector3());
-            return center;
+            return Vector3.add(particle.position, Vector3.scale(perpDir, estimatedRadius, new Vector3()), new Vector3());
         }
         const p1 = history[0];
         const p2 = history[Math.floor(history.length / 2)];
         const p3 = history[history.length - 1];
-        const center = this.calculateCircleCenter(p1, p2, p3);
-        return center;
+        return this.calculateCircleCenter(p1, p2, p3);
     }
     calculateCircleCenter(p1, p2, p3) {
         const mid12 = Vector3.scale(Vector3.add(p1, p2, new Vector3()), 0.5, new Vector3());
@@ -256,17 +634,14 @@ import { IKUtils } from '../ik/ik_utils.js';
         if (normal.magnitudeSq < 0.0001) {
             return Vector3.scale(Vector3.add(Vector3.add(p1, p2, new Vector3()), p3, new Vector3()), 1.0 / 3.0, new Vector3());
         }
-        Vector3.normalize(normal, normal);
-        const perp12 = Vector3.cross(dir12, normal, new Vector3());
-        Vector3.normalize(perp12, perp12);
-        const perp23 = Vector3.cross(dir23, normal, new Vector3());
-        Vector3.normalize(perp23, perp23);
+        normal.inplaceNormalize();
+        const perp12 = Vector3.cross(dir12, normal, new Vector3()).inplaceNormalize();
+        const perp23 = Vector3.cross(dir23, normal, new Vector3()).inplaceNormalize();
         const diff = Vector3.sub(mid23, mid12, new Vector3());
         const det = perp12.x * perp23.y - perp12.y * perp23.x;
         if (Math.abs(det) > 0.0001) {
             const t = (diff.x * perp23.y - diff.y * perp23.x) / det;
-            const center = Vector3.add(mid12, Vector3.scale(perp12, t, new Vector3()), new Vector3());
-            return center;
+            return Vector3.add(mid12, Vector3.scale(perp12, t, new Vector3()), new Vector3());
         }
         return Vector3.scale(Vector3.add(Vector3.add(p1, p2, new Vector3()), p3, new Vector3()), 1.0 / 3.0, new Vector3());
     }
@@ -277,8 +652,7 @@ import { IKUtils } from '../ik/ik_utils.js';
         centrifugalAccel.scaleBy(centrifugalScale);
         const coriolisAccel = Vector3.cross(angularVelocity, particleVelocity, new Vector3());
         coriolisAccel.scaleBy(-2 * coriolisScale);
-        const totalAccel = Vector3.add(centrifugalAccel, coriolisAccel, new Vector3());
-        return totalAccel;
+        return Vector3.add(centrifugalAccel, coriolisAccel, new Vector3());
     }
     solveConstraint(chain, constraint) {
         const pA = chain.particles[constraint.particleA];
@@ -288,7 +662,7 @@ import { IKUtils } from '../ik/ik_utils.js';
         if (currentLength < 0.0001) {
             return;
         }
-        const diff = (currentLength - constraint.restLength) / currentLength;
+        const diff = (currentLength - this.getRuntimeRestLength(constraint)) / currentLength;
         const correction = Vector3.scale(delta, diff * constraint.stiffness * 0.5, new Vector3());
         if (!pA.fixed) {
             Vector3.add(pA.position, correction, pA.position);
@@ -307,7 +681,7 @@ import { IKUtils } from '../ik/ik_utils.js';
         if (currentLength < 0.0001) {
             return;
         }
-        const diff = (currentLength - constraint.restLength) / currentLength;
+        const diff = (currentLength - this.getRuntimeRestLength(constraint)) / currentLength;
         const correction = Vector3.scale(delta, diff * constraint.stiffness * 0.5, new Vector3());
         if (!pA.fixed) {
             Vector3.add(pA.position, correction, pA.position);
@@ -330,7 +704,7 @@ import { IKUtils } from '../ik/ik_utils.js';
         if (currentLength < 0.0001) {
             return;
         }
-        const C = currentLength - constraint.restLength;
+        const C = currentLength - this.getRuntimeRestLength(constraint);
         const alphaTilde = constraint.compliance / (dt * dt);
         const deltaLambda = (-C - alphaTilde * constraint.lambda) / (wSum + alphaTilde);
         constraint.lambda += deltaLambda;
@@ -358,7 +732,7 @@ import { IKUtils } from '../ik/ik_utils.js';
         if (currentLength < 0.0001) {
             return;
         }
-        const C = currentLength - constraint.restLength;
+        const C = currentLength - this.getRuntimeRestLength(constraint);
         const alphaTilde = constraint.compliance / (dt * dt);
         const deltaLambda = (-C - alphaTilde * constraint.lambda) / (wSum + alphaTilde);
         constraint.lambda += deltaLambda;
@@ -370,33 +744,40 @@ import { IKUtils } from '../ik/ik_utils.js';
             Vector3.add(pB.position, Vector3.scale(n, wB * deltaLambda, new Vector3()), pB.position);
         }
     }
-    /**
-   * Applies simulation results to scene nodes
-   * @param weight - Blend weight [0-1] (default: 1.0)
-   */ applyToNodes(weight = 1.0) {
-        for (const chain of this._chains){
-            this.applyChainToNodes(chain, weight);
-        }
-    }
-    applyChainToNodes(chain, weight) {
+    collectChainNodeRotations(chain, weight, baseNodeStates, desiredWorldRotations) {
         for(let i = 0; i < chain.particles.length - 1; i++){
             const particle = chain.particles[i];
             const nextParticle = chain.particles[i + 1];
-            if (!particle.node) {
+            const node = this.resolveRuntimeNode(particle.node);
+            if (!node) {
                 continue;
             }
-            // Get current bone direction from node's world matrix (before physics)
-            const currentBonePos = new Vector3(particle.node.worldMatrix.m03, particle.node.worldMatrix.m13, particle.node.worldMatrix.m23);
-            const nextNode = nextParticle.node;
+            const nextNode = this.resolveRuntimeNode(nextParticle.node);
             if (!nextNode) {
                 continue;
             }
-            const nextBonePos = new Vector3(nextNode.worldMatrix.m03, nextNode.worldMatrix.m13, nextNode.worldMatrix.m23);
-            const originalDir = Vector3.sub(nextBonePos, currentBonePos, new Vector3());
-            // Get current bone rotation from node's world matrix
-            const currentBoneRotation = new Quaternion();
-            particle.node.worldMatrix.decompose(null, currentBoneRotation, null);
-            // Calculate new direction from physics simulation
+            let nodeState = baseNodeStates.get(node);
+            if (!nodeState) {
+                const currentBoneRotation = new Quaternion();
+                node.worldMatrix.decompose(null, currentBoneRotation, null);
+                nodeState = {
+                    position: new Vector3(node.worldMatrix.m03, node.worldMatrix.m13, node.worldMatrix.m23),
+                    rotation: currentBoneRotation
+                };
+                baseNodeStates.set(node, nodeState);
+            }
+            let nextNodeState = baseNodeStates.get(nextNode);
+            if (!nextNodeState) {
+                const nextBoneRotation = new Quaternion();
+                nextNode.worldMatrix.decompose(null, nextBoneRotation, null);
+                nextNodeState = {
+                    position: new Vector3(nextNode.worldMatrix.m03, nextNode.worldMatrix.m13, nextNode.worldMatrix.m23),
+                    rotation: nextBoneRotation
+                };
+                baseNodeStates.set(nextNode, nextNodeState);
+            }
+            const originalDir = Vector3.sub(nextNodeState.position, nodeState.position, new Vector3());
+            const currentBoneRotation = nodeState.rotation;
             const newDir = Vector3.sub(nextParticle.position, particle.position, new Vector3());
             const deltaRotation = new Quaternion();
             IKUtils.fromToRotation(originalDir, newDir, deltaRotation);
@@ -404,100 +785,117 @@ import { IKUtils } from '../ik/ik_utils.js';
             if (weight < 1) {
                 Quaternion.slerp(currentBoneRotation, worldRotation, weight, worldRotation);
             }
-            const parent = particle.node.parent;
-            if (parent) {
-                const parentWorldRotation = new Quaternion();
-                parent.worldMatrix.decompose(null, parentWorldRotation, null);
-                const parentInvRotation = Quaternion.conjugate(parentWorldRotation, new Quaternion());
-                const localRotation = Quaternion.multiply(parentInvRotation, worldRotation, new Quaternion());
-                particle.node.rotation = localRotation;
-            } else {
-                particle.node.rotation = worldRotation;
-            }
+            desiredWorldRotations.set(node, worldRotation);
         }
     }
-    /**
-   * Resets the simulation to initial state
-   */ reset() {
-        for (const chain of this._chains){
-            chain.reset();
+    getNodeDepth(node) {
+        let depth = 0;
+        let current = node?.parent;
+        while(current){
+            depth++;
+            current = current.parent;
         }
+        return depth;
     }
-    /**
-   * Gets the spring chains
-   */ get chains() {
-        return this._chains;
-    }
-    /**
-   * Gets the inter-chain constraints
-   */ get interChainConstraints() {
-        return this._interChainConstraints;
-    }
-    /**
-   * Gets the current gravity
-   */ get gravity() {
-        return this._gravity;
-    }
-    set gravity(gravity) {
-        this._gravity.set(gravity);
-    }
-    /**
-   * Gets the current wind
-   */ get wind() {
-        return this._wind;
-    }
-    set wind(wind) {
-        this._wind.set(wind);
-    }
-    /**
-   * Gets the number of iterations
-   */ get iterations() {
-        return this._iterations;
-    }
-    set iterations(count) {
-        this._iterations = Math.max(1, count);
-    }
-    /**
-   * Gets whether inertial forces are enabled
-   */ get enableInertialForces() {
-        return this._enableInertialForces;
-    }
-    set enableInertialForces(enabled) {
-        this._enableInertialForces = enabled;
-    }
-    /**
-   * Gets the centrifugal force scale
-   */ get centrifugalScale() {
-        return this._centrifugalScale;
-    }
-    set centrifugalScale(scale) {
-        this._centrifugalScale = Math.max(0, scale);
-    }
-    /**
-   * Gets the Coriolis force scale
-   */ get coriolisScale() {
-        return this._coriolisScale;
-    }
-    set coriolisScale(scale) {
-        this._coriolisScale = Math.max(0, scale);
+    resetConstraintLambdas() {
+        for (const chain of this._chains){
+            for (const constraint of chain.constraints){
+                constraint.lambda = 0;
+            }
+        }
+        for (const constraint of this._interChainConstraints){
+            constraint.lambda = 0;
+        }
     }
-    get solver() {
-        return this._solver;
+    resolveRuntimeNode(node) {
+        return node ? this._runtimeNodeMap?.get(node) ?? node : null;
     }
-    set solver(type) {
-        if (this._solver !== type) {
-            this._solver = type;
-            if (type === 'xpbd') {
-                for (const chain of this._chains){
-                    for (const c of chain.constraints){
-                        c.lambda = 0;
-                    }
-                }
-                for (const c of this._interChainConstraints){
-                    c.lambda = 0;
-                }
+    isExternalInertialAnchor(particle, drivenNodes) {
+        const particleNode = this.resolveRuntimeNode(particle.node);
+        let current = this.resolveRuntimeNode(particle.anchorNode ?? particle.node);
+        while(current){
+            if (current !== particleNode && drivenNodes.has(current)) {
+                return false;
             }
+            current = current.parent;
+        }
+        return true;
+    }
+    getRuntimeRestLength(constraint) {
+        return this._runtimeRestLengths.get(constraint) ?? constraint.restLength;
+    }
+    clearRuntimeCaches() {
+        this._timeAccumulator = 0;
+        this._smoothedParticleTargets = new WeakMap();
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
+    }
+    lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+    getTemporalBlendFactor(deltaTime, smoothingTime) {
+        const dt = Math.min(Math.max(Number(deltaTime) || 0, 0), MAX_ACCUMULATED_SIMULATION_TIME);
+        if (smoothingTime <= 0) {
+            return 1;
+        }
+        if (dt <= 0) {
+            return 0;
+        }
+        return 1 - Math.exp(-dt / smoothingTime);
+    }
+    getSmoothedParticleTarget(target, current, blend) {
+        const cached = this._smoothedParticleTargets.get(target);
+        if (!cached || blend >= 1) {
+            const next = current.clone();
+            this._smoothedParticleTargets.set(target, next);
+            return next;
+        }
+        cached.setXYZ(cached.x + (current.x - cached.x) * blend, cached.y + (current.y - cached.y) * blend, cached.z + (current.z - cached.z) * blend);
+        return cached;
+    }
+    getSmoothedSphereCenter(collider, blend) {
+        const current = collider.center?.clone() ?? new Vector3();
+        const cached = this._smoothedSphereCenters.get(collider);
+        if (!cached || blend >= 1) {
+            this._smoothedSphereCenters.set(collider, current);
+            return current;
+        }
+        cached.setXYZ(cached.x + (current.x - cached.x) * blend, cached.y + (current.y - cached.y) * blend, cached.z + (current.z - cached.z) * blend);
+        return cached;
+    }
+    getSmoothedCapsuleEndpoints(collider, blend) {
+        const currentStart = collider.start?.clone() ?? new Vector3();
+        const currentEnd = collider.end?.clone() ?? new Vector3();
+        const cached = this._smoothedCapsuleEndpoints.get(collider);
+        if (!cached || blend >= 1) {
+            const next = {
+                start: currentStart,
+                end: currentEnd
+            };
+            this._smoothedCapsuleEndpoints.set(collider, next);
+            return next;
+        }
+        cached.start.setXYZ(cached.start.x + (currentStart.x - cached.start.x) * blend, cached.start.y + (currentStart.y - cached.start.y) * blend, cached.start.z + (currentStart.z - cached.start.z) * blend);
+        cached.end.setXYZ(cached.end.x + (currentEnd.x - cached.end.x) * blend, cached.end.y + (currentEnd.y - cached.end.y) * blend, cached.end.z + (currentEnd.z - cached.end.z) * blend);
+        return cached;
+    }
+    getSmoothedPlaneData(collider, blend) {
+        const currentPoint = collider.point?.clone() ?? new Vector3();
+        const currentNormal = collider.normal?.clone() ?? new Vector3(0, 1, 0);
+        const cached = this._smoothedPlaneData.get(collider);
+        if (!cached || blend >= 1) {
+            const next = {
+                point: currentPoint,
+                normal: currentNormal
+            };
+            this._smoothedPlaneData.set(collider, next);
+            return next;
         }
+        cached.point.setXYZ(cached.point.x + (currentPoint.x - cached.point.x) * blend, cached.point.y + (currentPoint.y - cached.point.y) * blend, cached.point.z + (currentPoint.z - cached.point.z) * blend);
+        cached.normal.setXYZ(cached.normal.x + (currentNormal.x - cached.normal.x) * blend, cached.normal.y + (currentNormal.y - cached.normal.y) * blend, cached.normal.z + (currentNormal.z - cached.normal.z) * blend);
+        cached.normal.inplaceNormalize();
+        return cached;
     }
 }