@zephyr3d/scene 0.8.2 → 0.9.0

package/dist/animation/spring/spring_system.js

@@ -1,7 +1,12 @@
 import { Vector3, Quaternion } from '@zephyr3d/base';
 import { IKUtils } from '../ik/ik_utils.js';
-import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision, resolveSphereCollision } from './spring_collider.js';
+import { updateColliderFromNode, resolveSphereCollision, resolveCapsuleCollision, resolvePlaneCollision } from './spring_collider.js';
 
+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;
 /**
  * Physics engine for spring-based particle simulation
  * Uses Verlet integration and iterative constraint solving
@@ -17,6 +22,18 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
     _coriolisScale;
     _colliders;
     _solver;
+    _poseFollow;
+    _maxPoseOffset;
+    _poseFollowRoot;
+    _poseFollowTip;
+    _poseFollowExponent;
+    _maxPoseOffsetRoot;
+    _maxPoseOffsetTip;
+    _timeAccumulator;
+    _smoothedParticleTargets;
+    _smoothedSphereCenters;
+    _smoothedCapsuleEndpoints;
+    _smoothedPlaneData;
     constructor(chain, options){
         this._chain = chain;
         this._iterations = options?.iterations ?? 5;
@@ -27,13 +44,38 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
         this._coriolisScale = options?.coriolisScale ?? 1.0;
         this._colliders = [];
         this._solver = options?.solver ?? 'verlet';
+        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._timeAccumulator = 0;
+        this._smoothedParticleTargets = new WeakMap();
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
     }
     /**
    * Updates the physics simulation
    * @param deltaTime - Time step in seconds
    */ update(deltaTime) {
-        // Clamp deltaTime to prevent instability
-        const dt = Math.min(deltaTime, 0.033); // Max 30 FPS
+        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);
+        }
+    }
+    simulateStep(dt, inputDeltaTime) {
         // Step 1: Save all particle positions before updating
         if (this._enableInertialForces) {
             for (const p of this._chain.particles){
@@ -41,7 +83,7 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
             }
         }
         // Step 2: Update fixed particles from their scene nodes
-        this.updateFixedParticles();
+        this.updateFixedParticles(inputDeltaTime);
         // Step 3: Calculate global rotation parameters
         let rotationCenter = null;
         let angularVelocity = null;
@@ -87,25 +129,34 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
                     this.solveConstraint(constraint);
                 }
             }
+            // Pull particles back toward the animated pose to preserve hair silhouette.
+            // Normalize follow strength across solver iterations so tuning stays intuitive.
+            this.solvePosePreservation(this._iterations);
             // Apply collision constraints
-            this.solveCollisions();
+            this.solveCollisions(inputDeltaTime);
         }
     }
     /**
    * Updates fixed particles to match their scene node positions
-   */ updateFixedParticles() {
+   */ updateFixedParticles(deltaTime) {
+        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_PARTICLE_TARGET_SMOOTHING_TIME);
         for (const particle of this._chain.particles){
-            if (particle.node && particle.fixed) {
-                const worldMatrix = particle.node.worldMatrix;
-                const worldPos = new Vector3(worldMatrix.m03, worldMatrix.m13, worldMatrix.m23);
-                particle.position.set(worldPos);
-                particle.prevPosition.set(worldPos);
+            if (!particle.node) {
+                continue;
+            }
+            const worldMatrix = particle.node.worldMatrix;
+            const worldPos = new Vector3(worldMatrix.m03, worldMatrix.m13, worldMatrix.m23);
+            const smoothedTarget = this.getSmoothedParticleTarget(particle, worldPos, blend);
+            particle.animPosition.set(smoothedTarget);
+            if (particle.fixed) {
+                particle.position.set(smoothedTarget);
+                particle.prevPosition.set(smoothedTarget);
                 // Maintain position history for rotation center estimation
                 if (this._enableInertialForces) {
                     if (!particle.positionHistory) {
                         particle.positionHistory = [];
                     }
-                    particle.positionHistory.push(worldPos.clone());
+                    particle.positionHistory.push(smoothedTarget.clone());
                     // Keep only last 5 frames
                     if (particle.positionHistory.length > 5) {
                         particle.positionHistory.shift();
@@ -115,6 +166,41 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
         }
     }
     /**
+   * Solves pose preservation (long-range attachment to animated pose).
+   * This keeps strands close to authored shape while preserving dynamic movement.
+   */ solvePosePreservation(totalIterations) {
+        if (this._poseFollowRoot <= 0 && this._poseFollowTip <= 0) {
+            return;
+        }
+        const lastIndex = Math.max(1, this._chain.particles.length - 1);
+        for(let i = 0; i < this._chain.particles.length; i++){
+            const particle = this._chain.particles[i];
+            if (particle.fixed) {
+                continue;
+            }
+            const t = Math.pow(i / lastIndex, this._poseFollowExponent);
+            const particlePoseFollow = this.lerp(this._poseFollowRoot, this._poseFollowTip, t);
+            // Convert user-facing per-frame follow into per-iteration follow:
+            // effective = 1 - (1 - follow)^iterations
+            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);
+                }
+            }
+        }
+    }
+    lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+    /**
    * Calculates global rotation parameters from fixed particle movements
    * Uses position history to estimate rotation center
    */ calculateGlobalRotation(dt) {
@@ -337,33 +423,75 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
     }
     /**
    * Solves collisions for all particles
-   */ solveCollisions() {
+   */ solveCollisions(deltaTime) {
         // Update dynamic colliders from their nodes
+        const blend = this.getTemporalBlendFactor(deltaTime, DEFAULT_COLLIDER_SMOOTHING_TIME);
+        const spheres = [];
+        const capsules = [];
+        const planes = [];
         for (const collider of this._colliders){
             if (collider.node) {
                 updateColliderFromNode(collider);
             }
+            if (!collider.enabled) {
+                continue;
+            }
+            switch(collider.type){
+                case 'sphere':
+                    {
+                        const source = collider;
+                        spheres.push({
+                            particleCollider: source,
+                            collider: {
+                                ...source,
+                                center: this.getSmoothedSphereCenter(source, blend)
+                            }
+                        });
+                        break;
+                    }
+                case 'capsule':
+                    {
+                        const source = collider;
+                        const endpoints = this.getSmoothedCapsuleEndpoints(source, blend);
+                        capsules.push({
+                            particleCollider: source,
+                            collider: {
+                                ...source,
+                                start: endpoints.start,
+                                end: endpoints.end
+                            }
+                        });
+                        break;
+                    }
+                case 'plane':
+                    {
+                        const source = collider;
+                        const plane = this.getSmoothedPlaneData(source, blend);
+                        planes.push({
+                            particleCollider: source,
+                            collider: {
+                                ...source,
+                                point: plane.point,
+                                normal: plane.normal
+                            }
+                        });
+                        break;
+                    }
+            }
         }
         // Check each particle against all colliders
         for (const particle of this._chain.particles){
             if (particle.fixed) {
                 continue; // Skip fixed particles
             }
-            for (const collider of this._colliders){
-                if (!collider.enabled) {
-                    continue;
-                }
-                switch(collider.type){
-                    case 'sphere':
-                        resolveSphereCollision(particle.position, collider);
-                        break;
-                    case 'capsule':
-                        resolveCapsuleCollision(particle.position, collider);
-                        break;
-                    case 'plane':
-                        resolvePlaneCollision(particle.position, collider);
-                        break;
-                }
+            for (const collider of spheres){
+                resolveSphereCollision(particle.position, collider.collider);
+            }
+            for (const collider of capsules){
+                resolveCapsuleCollision(particle.position, collider.collider);
+            }
+            for (const collider of planes){
+                resolvePlaneCollision(particle.position, collider.collider);
             }
         }
     }
@@ -421,6 +549,18 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
    * Resets the simulation to initial state
    */ reset() {
         this._chain.reset();
+        for (const particle of this._chain.particles){
+            particle.animPosition.set(particle.originalPosition);
+            particle.lastFramePosition.set(particle.originalPosition);
+            if (particle.positionHistory) {
+                particle.positionHistory.length = 0;
+            }
+        }
+        this._timeAccumulator = 0;
+        this._smoothedParticleTargets = new WeakMap();
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
     }
     /**
    * Gets the spring chain
@@ -496,9 +636,88 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
         }
     }
     /**
+   * Gets pose preservation strength [0-1]
+   */ get poseFollow() {
+        return this._poseFollow;
+    }
+    /**
+   * Sets pose preservation strength [0-1]
+   */ set poseFollow(value) {
+        const v = Math.max(0, Math.min(1, value));
+        this._poseFollow = v;
+        this._poseFollowRoot = v;
+        this._poseFollowTip = v;
+    }
+    /**
+   * Gets max allowed deviation from animated pose
+   */ get maxPoseOffset() {
+        return this._maxPoseOffset;
+    }
+    /**
+   * Sets max allowed deviation from animated pose. 0 disables clamping.
+   */ set maxPoseOffset(value) {
+        const v = Math.max(0, value);
+        this._maxPoseOffset = v;
+        this._maxPoseOffsetRoot = v;
+        this._maxPoseOffsetTip = v;
+    }
+    /**
+   * Gets root pose follow strength [0-1]
+   */ get poseFollowRoot() {
+        return this._poseFollowRoot;
+    }
+    /**
+   * Sets root pose follow strength [0-1]
+   */ set poseFollowRoot(value) {
+        this._poseFollowRoot = Math.max(0, Math.min(1, value));
+    }
+    /**
+   * Gets tip pose follow strength [0-1]
+   */ get poseFollowTip() {
+        return this._poseFollowTip;
+    }
+    /**
+   * Sets tip pose follow strength [0-1]
+   */ set poseFollowTip(value) {
+        this._poseFollowTip = Math.max(0, Math.min(1, value));
+    }
+    /**
+   * Gets exponent for root->tip interpolation
+   */ get poseFollowExponent() {
+        return this._poseFollowExponent;
+    }
+    /**
+   * Sets exponent for root->tip interpolation
+   */ set poseFollowExponent(value) {
+        this._poseFollowExponent = Math.max(0.1, value);
+    }
+    /**
+   * Gets root max allowed deviation from animated pose
+   */ get maxPoseOffsetRoot() {
+        return this._maxPoseOffsetRoot;
+    }
+    /**
+   * Sets root max allowed deviation from animated pose
+   */ set maxPoseOffsetRoot(value) {
+        this._maxPoseOffsetRoot = Math.max(0, value);
+    }
+    /**
+   * Gets tip max allowed deviation from animated pose
+   */ get maxPoseOffsetTip() {
+        return this._maxPoseOffsetTip;
+    }
+    /**
+   * Sets tip max allowed deviation from animated pose
+   */ set maxPoseOffsetTip(value) {
+        this._maxPoseOffsetTip = Math.max(0, value);
+    }
+    /**
    * Adds a collider to the system
    */ addCollider(collider) {
         this._colliders.push(collider);
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
     }
     /**
    * Removes a collider from the system
@@ -506,6 +725,9 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
         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;
@@ -514,12 +736,87 @@ import { updateColliderFromNode, resolvePlaneCollision, resolveCapsuleCollision,
    * Clears all colliders
    */ clearColliders() {
         this._colliders = [];
+        this._smoothedSphereCenters = new WeakMap();
+        this._smoothedCapsuleEndpoints = new WeakMap();
+        this._smoothedPlaneData = new WeakMap();
     }
     /**
    * Gets all colliders
    */ get colliders() {
         return this._colliders;
     }
+    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() ?? Vector3.axisPY();
+        if (currentNormal.magnitudeSq > 1e-8) {
+            currentNormal.inplaceNormalize();
+        } else {
+            currentNormal.setXYZ(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);
+        if (cached.normal.magnitudeSq > 1e-8) {
+            cached.normal.inplaceNormalize();
+        } else {
+            cached.normal.setXYZ(0, 1, 0);
+        }
+        return cached;
+    }
 }
 
 export { SpringSystem };