@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/animation/spring/multi_chain_spring_system.js

@@ -1,7 +1,8 @@
 import { Vector3, Quaternion } from '@zephyr3d/base';
 import { IKUtils } from '../ik/ik_utils.js';
-import { updateColliderFromNode, resolveSphereCollision, resolveCapsuleCollision, resolvePlaneCollision } from './spring_collider.js';
+import { updateColliderFromNode, resolveSphereCollision, resolveCapsuleCollision, resolvePlaneCollision, resolveBoxCollision } from './spring_collider.js';
 import { SpringNodePoseTracker } from './spring_node_pose_tracker.js';
+import { DEFAULT_INITIAL_COLLISION_PENETRATION_RELEASE_TIME, getSpringPoseTopology, getKawaiiPoseTarget, interpolateSpringValue, solveAngleLimit, resolveInelasticCollision, solveDistanceConstraint, measureCollisionPenetration, INITIAL_COLLISION_PENETRATION_SLOP, getReleasedCollisionPenetration, getIterationStrength } from './spring_solver.js';
 
 const FIXED_SIMULATION_TIME_STEP = 1 / 60;
 const MAX_ACCUMULATED_SIMULATION_TIME = 1 / 20;
@@ -31,10 +32,19 @@ class MultiChainSpringSystem {
     _smoothedSphereCenters;
     _smoothedCapsuleEndpoints;
     _smoothedPlaneData;
+    _smoothedBoxData;
     _runtimeNodeMap;
     _runtimeAnchorOffsets;
     _runtimeRestLengths;
     _nodePoseTracker;
+    _motionModel;
+    _angleLimitRoot;
+    _angleLimitTip;
+    _constraintVelocityHistoryRetention;
+    _preserveInitialCollisionPenetration;
+    _initialCollisionPenetrationReleaseTime;
+    _initialCollisionPenetrationElapsed;
+    _initialCollisionPenetration;
     constructor(options){
         this._chains = [];
         this._interChainConstraints = [];
@@ -58,10 +68,19 @@ class MultiChainSpringSystem {
         this._smoothedSphereCenters = new WeakMap();
         this._smoothedCapsuleEndpoints = new WeakMap();
         this._smoothedPlaneData = new WeakMap();
+        this._smoothedBoxData = new WeakMap();
         this._runtimeNodeMap = null;
         this._runtimeAnchorOffsets = new WeakMap();
         this._runtimeRestLengths = new WeakMap();
         this._nodePoseTracker = new SpringNodePoseTracker();
+        this._motionModel = options?.motionModel ?? 'kawaii';
+        this._angleLimitRoot = Math.max(0, options?.angleLimitRoot ?? 0);
+        this._angleLimitTip = Math.max(0, options?.angleLimitTip ?? this._angleLimitRoot);
+        this._constraintVelocityHistoryRetention = Math.max(0, Math.min(1, options?.constraintVelocityHistoryRetention ?? 0.35));
+        this._preserveInitialCollisionPenetration = options?.preserveInitialCollisionPenetration ?? this._motionModel === 'kawaii';
+        this._initialCollisionPenetrationReleaseTime = Math.max(0, options?.initialCollisionPenetrationReleaseTime ?? DEFAULT_INITIAL_COLLISION_PENETRATION_RELEASE_TIME);
+        this._initialCollisionPenetrationElapsed = 0;
+        this._initialCollisionPenetration = new WeakMap();
     }
     addChain(chain) {
         this._chains.push(chain);
@@ -113,7 +132,7 @@ class MultiChainSpringSystem {
         }
         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);
+            this.simulateStep(FIXED_SIMULATION_TIME_STEP, i === 0 ? frameDt : 0, i, stepCount);
         }
     }
     applyToNodes(weight = 1.0) {
@@ -164,6 +183,9 @@ class MultiChainSpringSystem {
         this._smoothedSphereCenters = new WeakMap();
         this._smoothedCapsuleEndpoints = new WeakMap();
         this._smoothedPlaneData = new WeakMap();
+        this._smoothedBoxData = new WeakMap();
+        this._initialCollisionPenetrationElapsed = 0;
+        this._initialCollisionPenetration = new WeakMap();
     }
     get chains() {
         return this._chains;
@@ -218,6 +240,57 @@ class MultiChainSpringSystem {
             }
         }
     }
+    get motionModel() {
+        return this._motionModel;
+    }
+    set motionModel(value) {
+        if (value !== 'legacy' && value !== 'kawaii') {
+            return;
+        }
+        if (this._motionModel !== value) {
+            this._motionModel = value;
+            this.reset();
+        }
+    }
+    get angleLimitRoot() {
+        return this._angleLimitRoot;
+    }
+    set angleLimitRoot(value) {
+        this._angleLimitRoot = Math.max(0, Number(value) || 0);
+    }
+    get angleLimitTip() {
+        return this._angleLimitTip;
+    }
+    set angleLimitTip(value) {
+        this._angleLimitTip = Math.max(0, Number(value) || 0);
+    }
+    get constraintVelocityHistoryRetention() {
+        return this._constraintVelocityHistoryRetention;
+    }
+    set constraintVelocityHistoryRetention(value) {
+        this._constraintVelocityHistoryRetention = Math.max(0, Math.min(1, Number(value) || 0));
+    }
+    get preserveInitialCollisionPenetration() {
+        return this._preserveInitialCollisionPenetration;
+    }
+    set preserveInitialCollisionPenetration(value) {
+        if (this._preserveInitialCollisionPenetration !== value) {
+            this._preserveInitialCollisionPenetration = value;
+            this._initialCollisionPenetrationElapsed = 0;
+            this._initialCollisionPenetration = new WeakMap();
+        }
+    }
+    get initialCollisionPenetrationReleaseTime() {
+        return this._initialCollisionPenetrationReleaseTime;
+    }
+    set initialCollisionPenetrationReleaseTime(value) {
+        const duration = Math.max(0, Number(value) || 0);
+        if (this._initialCollisionPenetrationReleaseTime !== duration) {
+            this._initialCollisionPenetrationReleaseTime = duration;
+            this._initialCollisionPenetrationElapsed = 0;
+            this._initialCollisionPenetration = new WeakMap();
+        }
+    }
     get poseFollow() {
         return this._poseFollow;
     }
@@ -271,6 +344,9 @@ class MultiChainSpringSystem {
         this._smoothedSphereCenters = new WeakMap();
         this._smoothedCapsuleEndpoints = new WeakMap();
         this._smoothedPlaneData = new WeakMap();
+        this._smoothedBoxData = new WeakMap();
+        this._initialCollisionPenetrationElapsed = 0;
+        this._initialCollisionPenetration = new WeakMap();
     }
     removeCollider(collider) {
         const index = this._colliders.indexOf(collider);
@@ -279,6 +355,9 @@ class MultiChainSpringSystem {
             this._smoothedSphereCenters = new WeakMap();
             this._smoothedCapsuleEndpoints = new WeakMap();
             this._smoothedPlaneData = new WeakMap();
+            this._smoothedBoxData = new WeakMap();
+            this._initialCollisionPenetrationElapsed = 0;
+            this._initialCollisionPenetration = new WeakMap();
             return true;
         }
         return false;
@@ -288,6 +367,9 @@ class MultiChainSpringSystem {
         this._smoothedSphereCenters = new WeakMap();
         this._smoothedCapsuleEndpoints = new WeakMap();
         this._smoothedPlaneData = new WeakMap();
+        this._smoothedBoxData = new WeakMap();
+        this._initialCollisionPenetrationElapsed = 0;
+        this._initialCollisionPenetration = new WeakMap();
     }
     get colliders() {
         return this._colliders;
@@ -357,7 +439,7 @@ class MultiChainSpringSystem {
         }
         this.clearRuntimeCaches();
     }
-    simulateStep(dt, inputDeltaTime) {
+    simulateStep(dt, inputDeltaTime, stepIndex, stepCount) {
         if (this._enableInertialForces) {
             for (const chain of this._chains){
                 for (const particle of chain.particles){
@@ -365,7 +447,8 @@ class MultiChainSpringSystem {
                 }
             }
         }
-        this.updateFixedParticles(inputDeltaTime);
+        const substepBlend = 1 / Math.max(1, stepCount - stepIndex);
+        this.updateFixedParticles(inputDeltaTime, substepBlend);
         let rotationCenter = null;
         let angularVelocity = null;
         if (this._enableInertialForces && dt > 0.0001) {
@@ -394,9 +477,14 @@ class MultiChainSpringSystem {
         if (this._solver === 'xpbd') {
             this.resetConstraintLambdas();
         }
+        if (this._motionModel === 'kawaii') {
+            this.solvePosePreservation(1, true);
+        }
         for(let iter = 0; iter < this._iterations; iter++){
             for (const chain of this._chains){
-                for (const constraint of chain.constraints){
+                const reverse = this._motionModel === 'kawaii' && !!(iter & 1);
+                for(let constraintIndex = 0; constraintIndex < chain.constraints.length; constraintIndex++){
+                    const constraint = chain.constraints[reverse ? chain.constraints.length - 1 - constraintIndex : constraintIndex];
                     if (this._solver === 'xpbd') {
                         this.solveConstraintXPBD(chain, constraint, dt);
                     } else {
@@ -404,19 +492,74 @@ class MultiChainSpringSystem {
                     }
                 }
             }
-            for (const constraint of this._interChainConstraints){
+            const reverse = this._motionModel === 'kawaii' && !!(iter & 1);
+            for(let constraintIndex = 0; constraintIndex < this._interChainConstraints.length; constraintIndex++){
+                const constraint = this._interChainConstraints[reverse ? this._interChainConstraints.length - 1 - constraintIndex : constraintIndex];
                 if (this._solver === 'xpbd') {
                     this.solveInterChainConstraintXPBD(constraint, dt);
                 } else {
                     this.solveInterChainConstraint(constraint);
                 }
             }
-            this.solvePosePreservation(this._iterations);
-            this.solveCollisions(inputDeltaTime);
+            if (this._motionModel === 'legacy') {
+                this.solvePosePreservation(this._iterations, false);
+                this.solveCollisions(inputDeltaTime);
+            }
+        }
+        if (this._motionModel === 'kawaii') {
+            this.solveCollisions(inputDeltaTime, substepBlend);
+            this.solveAngleLimits();
+            if (this._solver === 'xpbd') {
+                this.solveCollisions(0, 0);
+                this.resetConstraintLambdas();
+                const closureIterations = Math.min(16, Math.max(4, this._iterations));
+                for(let iteration = 0; iteration < closureIterations; iteration++){
+                    const reverse = !!(iteration & 1);
+                    for (const chain of this._chains){
+                        for(let constraintIndex = 0; constraintIndex < chain.constraints.length; constraintIndex++){
+                            const constraint = chain.constraints[reverse ? chain.constraints.length - 1 - constraintIndex : constraintIndex];
+                            this.solveConstraintXPBD(chain, constraint, dt);
+                        }
+                    }
+                    for(let constraintIndex = 0; constraintIndex < this._interChainConstraints.length; constraintIndex++){
+                        const constraint = this._interChainConstraints[reverse ? this._interChainConstraints.length - 1 - constraintIndex : constraintIndex];
+                        this.solveInterChainConstraintXPBD(constraint, dt);
+                    }
+                }
+                if (this._colliders.some((collider)=>collider.enabled)) {
+                    this.resetConstraintLambdas();
+                    const contactClosureIterations = Math.min(4, closureIterations);
+                    for(let iteration = 0; iteration < contactClosureIterations; iteration++){
+                        const reverse = !!(iteration & 1);
+                        for (const chain of this._chains){
+                            for(let constraintIndex = 0; constraintIndex < chain.constraints.length; constraintIndex++){
+                                const constraint = chain.constraints[reverse ? chain.constraints.length - 1 - constraintIndex : constraintIndex];
+                                this.solveConstraintXPBD(chain, constraint, dt);
+                            }
+                        }
+                        for(let constraintIndex = 0; constraintIndex < this._interChainConstraints.length; constraintIndex++){
+                            const constraint = this._interChainConstraints[reverse ? this._interChainConstraints.length - 1 - constraintIndex : constraintIndex];
+                            this.solveInterChainConstraintXPBD(constraint, dt);
+                        }
+                        this.solveCollisions(0, 0);
+                    }
+                }
+            } else {
+                for (const chain of this._chains){
+                    for (const constraint of chain.constraints){
+                        this.solveConstraint(chain, constraint);
+                    }
+                }
+                for (const constraint of this._interChainConstraints){
+                    this.solveInterChainConstraint(constraint);
+                }
+                this.solveCollisions(0, 0);
+            }
         }
+        this.advanceInitialCollisionPenetrationRelease(dt);
     }
-    updateFixedParticles(deltaTime) {
-        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_PARTICLE_TARGET_SMOOTHING_TIME);
+    updateFixedParticles(deltaTime, substepBlend) {
+        const blend = this._motionModel === 'kawaii' ? substepBlend : this.getTemporalBlendFactor(deltaTime, DEFAULT_PARTICLE_TARGET_SMOOTHING_TIME);
         for (const chain of this._chains){
             for (const particle of chain.particles){
                 const sourceNode = this.resolveRuntimeNode(particle.anchorNode ?? particle.node);
@@ -443,40 +586,54 @@ class MultiChainSpringSystem {
             }
         }
     }
-    solvePosePreservation(totalIterations) {
+    solvePosePreservation(totalIterations, parentRelative) {
         if (this._poseFollowRoot <= 0 && this._poseFollowTip <= 0) {
             return;
         }
         for (const chain of this._chains){
-            const lastIndex = Math.max(1, chain.particles.length - 1);
+            const topology = getSpringPoseTopology(chain.particles);
             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 t = Math.pow(topology[i].normalizedDistance, 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 iterationFollow = getIterationStrength(particlePoseFollow, totalIterations);
+                const poseTarget = parentRelative ? getKawaiiPoseTarget(particle, topology[i]) : particle.animPosition;
+                const toAnim = Vector3.sub(poseTarget, 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 offset = Vector3.sub(particle.position, poseTarget, new Vector3());
                     const offsetLen = offset.magnitude;
                     if (offsetLen > particleMaxPoseOffset && offsetLen > 1e-6) {
                         offset.scaleBy(particleMaxPoseOffset / offsetLen);
-                        Vector3.add(particle.animPosition, offset, particle.position);
+                        Vector3.add(poseTarget, offset, particle.position);
                     }
                 }
             }
         }
     }
-    solveCollisions(deltaTime) {
-        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_COLLIDER_SMOOTHING_TIME);
+    solveAngleLimits() {
+        if (this._angleLimitRoot <= 0 && this._angleLimitTip <= 0) {
+            return;
+        }
+        for (const chain of this._chains){
+            const particles = chain.particles;
+            for(let i = 1; i < particles.length; i++){
+                const limit = interpolateSpringValue(this._angleLimitRoot, this._angleLimitTip, this._poseFollowExponent, i, particles.length);
+                solveAngleLimit(particles[i - 1], particles[i], limit, this._solver === 'xpbd');
+            }
+        }
+    }
+    solveCollisions(deltaTime, blendOverride) {
+        const blend = blendOverride ?? this.getTemporalBlendFactor(deltaTime, DEFAULT_COLLIDER_SMOOTHING_TIME);
         const spheres = [];
         const capsules = [];
         const planes = [];
+        const boxes = [];
         for (const collider of this._colliders){
             const colliderNode = this.resolveRuntimeNode(collider.node);
             if (colliderNode) {
@@ -490,8 +647,11 @@ class MultiChainSpringSystem {
                     {
                         const source = collider;
                         spheres.push({
-                            ...source,
-                            center: this.getSmoothedSphereCenter(source, blend)
+                            source,
+                            collider: {
+                                ...source,
+                                center: this.getSmoothedSphereCenter(source, blend)
+                            }
                         });
                         break;
                     }
@@ -500,9 +660,12 @@ class MultiChainSpringSystem {
                         const source = collider;
                         const endpoints = this.getSmoothedCapsuleEndpoints(source, blend);
                         capsules.push({
-                            ...source,
-                            start: endpoints.start,
-                            end: endpoints.end
+                            source,
+                            collider: {
+                                ...source,
+                                start: endpoints.start,
+                                end: endpoints.end
+                            }
                         });
                         break;
                     }
@@ -511,9 +674,24 @@ class MultiChainSpringSystem {
                         const source = collider;
                         const plane = this.getSmoothedPlaneData(source, blend);
                         planes.push({
-                            ...source,
-                            point: plane.point,
-                            normal: plane.normal
+                            source,
+                            collider: {
+                                ...source,
+                                point: plane.point,
+                                normal: plane.normal
+                            }
+                        });
+                        break;
+                    }
+                case 'box':
+                    {
+                        const source = collider;
+                        boxes.push({
+                            source,
+                            collider: {
+                                ...source,
+                                ...this.getSmoothedBoxData(source, blend)
+                            }
                         });
                         break;
                     }
@@ -524,19 +702,33 @@ class MultiChainSpringSystem {
                 if (particle.fixed) {
                     continue;
                 }
-                const positionBeforeCollision = particle.position.clone();
-                let collided = false;
                 for (const collider of spheres){
-                    collided = resolveSphereCollision(particle.position, collider) || collided;
+                    if (this._motionModel === 'kawaii') {
+                        resolveInelasticCollision(particle, collider.collider, resolveSphereCollision, this.getInitialCollisionPenetration(particle, collider.source, collider.collider, resolveSphereCollision));
+                    } else {
+                        resolveSphereCollision(particle.position, collider.collider, particle.collisionRadius);
+                    }
                 }
                 for (const collider of capsules){
-                    collided = resolveCapsuleCollision(particle.position, collider) || collided;
+                    if (this._motionModel === 'kawaii') {
+                        resolveInelasticCollision(particle, collider.collider, resolveCapsuleCollision, this.getInitialCollisionPenetration(particle, collider.source, collider.collider, resolveCapsuleCollision));
+                    } else {
+                        resolveCapsuleCollision(particle.position, collider.collider, particle.collisionRadius);
+                    }
                 }
                 for (const collider of planes){
-                    collided = resolvePlaneCollision(particle.position, collider) || collided;
+                    if (this._motionModel === 'kawaii') {
+                        resolveInelasticCollision(particle, collider.collider, resolvePlaneCollision, this.getInitialCollisionPenetration(particle, collider.source, collider.collider, resolvePlaneCollision));
+                    } else {
+                        resolvePlaneCollision(particle.position, collider.collider, particle.collisionRadius);
+                    }
                 }
-                if (collided) {
-                    Vector3.add(particle.prevPosition, Vector3.sub(particle.position, positionBeforeCollision, new Vector3()), particle.prevPosition);
+                for (const collider of boxes){
+                    if (this._motionModel === 'kawaii') {
+                        resolveInelasticCollision(particle, collider.collider, resolveBoxCollision, this.getInitialCollisionPenetration(particle, collider.source, collider.collider, resolveBoxCollision));
+                    } else {
+                        resolveBoxCollision(particle.position, collider.collider, particle.collisionRadius);
+                    }
                 }
             }
         }
@@ -657,6 +849,10 @@ class MultiChainSpringSystem {
     solveConstraint(chain, constraint) {
         const pA = chain.particles[constraint.particleA];
         const pB = chain.particles[constraint.particleB];
+        if (this._motionModel === 'kawaii') {
+            solveDistanceConstraint(pA, pB, this.getRuntimeRestLength(constraint), constraint.stiffness);
+            return;
+        }
         const delta = Vector3.sub(pB.position, pA.position, new Vector3());
         const currentLength = delta.magnitude;
         if (currentLength < 0.0001) {
@@ -676,6 +872,10 @@ class MultiChainSpringSystem {
         const chainB = this._chains[constraint.chainBIndex];
         const pA = chainA.particles[constraint.particleAIndex];
         const pB = chainB.particles[constraint.particleBIndex];
+        if (this._motionModel === 'kawaii') {
+            solveDistanceConstraint(pA, pB, this.getRuntimeRestLength(constraint), constraint.stiffness);
+            return;
+        }
         const delta = Vector3.sub(pB.position, pA.position, new Vector3());
         const currentLength = delta.magnitude;
         if (currentLength < 0.0001) {
@@ -710,10 +910,18 @@ class MultiChainSpringSystem {
         constraint.lambda += deltaLambda;
         const n = Vector3.scale(delta, 1.0 / currentLength, new Vector3());
         if (!pA.fixed) {
-            Vector3.add(pA.position, Vector3.scale(n, -wA * deltaLambda, new Vector3()), pA.position);
+            const correction = Vector3.scale(n, -wA * deltaLambda, new Vector3());
+            Vector3.add(pA.position, correction, pA.position);
+            if (this._motionModel === 'kawaii') {
+                Vector3.add(pA.prevPosition, Vector3.scale(correction, this._constraintVelocityHistoryRetention, new Vector3()), pA.prevPosition);
+            }
         }
         if (!pB.fixed) {
-            Vector3.add(pB.position, Vector3.scale(n, wB * deltaLambda, new Vector3()), pB.position);
+            const correction = Vector3.scale(n, wB * deltaLambda, new Vector3());
+            Vector3.add(pB.position, correction, pB.position);
+            if (this._motionModel === 'kawaii') {
+                Vector3.add(pB.prevPosition, Vector3.scale(correction, this._constraintVelocityHistoryRetention, new Vector3()), pB.prevPosition);
+            }
         }
     }
     solveInterChainConstraintXPBD(constraint, dt) {
@@ -738,10 +946,18 @@ class MultiChainSpringSystem {
         constraint.lambda += deltaLambda;
         const n = Vector3.scale(delta, 1.0 / currentLength, new Vector3());
         if (!pA.fixed) {
-            Vector3.add(pA.position, Vector3.scale(n, -wA * deltaLambda, new Vector3()), pA.position);
+            const correction = Vector3.scale(n, -wA * deltaLambda, new Vector3());
+            Vector3.add(pA.position, correction, pA.position);
+            if (this._motionModel === 'kawaii') {
+                Vector3.add(pA.prevPosition, Vector3.scale(correction, this._constraintVelocityHistoryRetention, new Vector3()), pA.prevPosition);
+            }
         }
         if (!pB.fixed) {
-            Vector3.add(pB.position, Vector3.scale(n, wB * deltaLambda, new Vector3()), pB.position);
+            const correction = Vector3.scale(n, wB * deltaLambda, new Vector3());
+            Vector3.add(pB.position, correction, pB.position);
+            if (this._motionModel === 'kawaii') {
+                Vector3.add(pB.prevPosition, Vector3.scale(correction, this._constraintVelocityHistoryRetention, new Vector3()), pB.prevPosition);
+            }
         }
     }
     collectChainNodeRotations(chain, weight, baseNodeStates, desiredWorldRotations) {
@@ -830,6 +1046,31 @@ class MultiChainSpringSystem {
         this._smoothedSphereCenters = new WeakMap();
         this._smoothedCapsuleEndpoints = new WeakMap();
         this._smoothedPlaneData = new WeakMap();
+        this._smoothedBoxData = new WeakMap();
+        this._initialCollisionPenetrationElapsed = 0;
+        this._initialCollisionPenetration = new WeakMap();
+    }
+    getInitialCollisionPenetration(particle, sourceCollider, collider, resolveCollision) {
+        if (!this._preserveInitialCollisionPenetration) {
+            return 0;
+        }
+        let particlePenetrations = this._initialCollisionPenetration.get(particle);
+        if (!particlePenetrations) {
+            particlePenetrations = new WeakMap();
+            this._initialCollisionPenetration.set(particle, particlePenetrations);
+        }
+        let penetration = particlePenetrations.get(sourceCollider);
+        if (penetration === undefined) {
+            penetration = measureCollisionPenetration(particle.animPosition, collider, resolveCollision, particle.collisionRadius) + INITIAL_COLLISION_PENETRATION_SLOP;
+            particlePenetrations.set(sourceCollider, penetration);
+        }
+        return getReleasedCollisionPenetration(penetration, this._initialCollisionPenetrationElapsed, this._initialCollisionPenetrationReleaseTime);
+    }
+    advanceInitialCollisionPenetrationRelease(deltaTime) {
+        if (!this._preserveInitialCollisionPenetration) {
+            return;
+        }
+        this._initialCollisionPenetrationElapsed = Math.min(this._initialCollisionPenetrationReleaseTime, this._initialCollisionPenetrationElapsed + Math.max(0, deltaTime));
     }
     lerp(a, b, t) {
         return a + (b - a) * t;
@@ -897,6 +1138,25 @@ class MultiChainSpringSystem {
         cached.normal.inplaceNormalize();
         return cached;
     }
+    getSmoothedBoxData(collider, blend) {
+        const current = {
+            center: collider.center.clone(),
+            halfExtents: collider.halfExtents.clone(),
+            axes: collider.axes.map((axis)=>axis.clone())
+        };
+        const cached = this._smoothedBoxData.get(collider);
+        if (!cached || blend >= 1) {
+            this._smoothedBoxData.set(collider, current);
+            return current;
+        }
+        Vector3.lerp(cached.center, current.center, blend, cached.center);
+        Vector3.lerp(cached.halfExtents, current.halfExtents, blend, cached.halfExtents);
+        for(let i = 0; i < 3; i++){
+            Vector3.lerp(cached.axes[i], current.axes[i], blend, cached.axes[i]);
+            cached.axes[i].inplaceNormalize();
+        }
+        return cached;
+    }
 }
 
 export { MultiChainSpringSystem };