@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/animation/joint_dynamics/controller.js

@@ -3,7 +3,7 @@ import { buildConstraints, buildSurfaceFaces } from './constraints.js';
 import { simulate, applyAngleLimits, applyResult, extractLocalTwist } from './solver.js';
 import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@zephyr3d/base';
 
-// High-level orchestrator - SPCRJointDynamicsController API
+// High-level SPCR joint-dynamics controller.
 /**
  * High-level controller for joint dynamics simulation.
  *
@@ -80,10 +80,8 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         this._pointTransforms = pointTransforms;
         this._colliderTransforms = colliders.map((c)=>c.transform);
         this._grabberTransforms = grabbers.map((g)=>g.transform);
-        // Build constraints
         this._rebuildConstraints();
         this._baseConstraintLengths = this._constraints.map((constraint)=>constraint.length);
-        // Flatten bone hierarchy to point list, build parent map
         const allPoints = [];
         const visitedPoints = new Set();
         this._parentMap = new Map(); // child index -> parent index
@@ -104,35 +102,29 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         allPoints.sort((a, b)=>a.index - b.index);
         this._allPoints = allPoints;
         this._maxPointDepth = allPoints.length > 0 ? Math.max(...allPoints.map((p)=>p.depth)) : 0;
-        // Compute boneAxis from transforms: local-space direction to first child
-        // This is critical for correct bone rotation in skinned meshes
+        // Derive each missing bone axis in parent-local space for skinning.
         for (const p of allPoints){
             if (!p.boneAxis && p.children.length > 0) {
                 const childPos = pointTransforms[p.children[0].index].getWorldPosition();
                 const parentPos = pointTransforms[p.index].getWorldPosition();
-                // InverseTransformPoint: convert child world pos to parent local space
                 const parentRot = pointTransforms[p.index].getWorldRotation();
                 const parentScale = pointTransforms[p.index].getLocalScale();
                 const diff = Vector3.sub(childPos, parentPos);
                 const invRot = Quaternion.inverse(parentRot);
                 const localDir = invRot.transform(diff);
-                // Apply inverse scale
                 const unscaled = new Vector3(parentScale.x !== 0 ? localDir.x / parentScale.x : 0, parentScale.y !== 0 ? localDir.y / parentScale.y : 0, parentScale.z !== 0 ? localDir.z / parentScale.z : 0);
                 p.boneAxis = Vector3.normalize(unscaled);
             }
         }
-        // Build PointR/RW arrays
         this._pointsR = allPoints.map((p)=>this._createPointR(p));
         this._basePointParentLengths = this._pointsR.map((point)=>point.parentLength);
         this._pointsRW = allPoints.map(()=>this._createPointRW());
         this._positionsToTransform = new Array(allPoints.length).fill(Vector3.zero());
         this._clearOutputTransformCache();
-        // Initialize colliders
         this._collidersR = colliders.map((c)=>c.r);
         this._collidersRW = colliders.map((c)=>this._createColliderRW(c.transform));
         this._colliderHandleIds = this._collidersR.map(()=>this._nextColliderHandleId++);
         this._rebuildColliderHandleMap();
-        // Initialize grabbers
         this._grabbersR = grabbers.map((g)=>g.r);
         this._grabbersRW = grabbers.map((g)=>({
                 enabled: g.enabled ? 1 : 0,
@@ -140,7 +132,6 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
             }));
         this._grabberHandleIds = this._grabbersR.map(()=>this._nextGrabberHandleId++);
         this._rebuildGrabberHandleMap();
-        // Flat planes
         this._flatPlanes = flatPlanes.map((fp)=>({
                 normal: Vector3.normalize(fp.up),
                 distance: -Vector3.dot(Vector3.normalize(fp.up), fp.position)
@@ -151,7 +142,6 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         this._flatPlaneEnabled = this._flatPlaneAll.map(()=>true);
         this._flatPlaneHandleIds = this._flatPlaneAll.map(()=>this._nextFlatPlaneHandleId++);
         this._rebuildFlatPlaneHandleMap();
-        // Capture initial state
         this._previousRootPosition = rootTransform.getWorldPosition();
         this._previousRootRotation = rootTransform.getWorldRotation();
         for(let i = 0; i < this._pointsRW.length; i++){
@@ -178,7 +168,6 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         if (!this._initialized || !this._rootTransform) {
             return;
         }
-        // Update fade
         if (this._fadeState !== 'none') {
             this._fadeTimer += deltaTime;
             if (this._fadeTimer >= this._fadeDuration) {
@@ -189,7 +178,6 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         const blendRatio = this._computeBlendRatio();
         this._updateScaleDependentParameters();
         const rootSlideLimit = this._config.rootSlideLimit < 0 ? -1 : this._config.rootSlideLimit * this._currentSystemScale;
-        // Capture current transforms
         const rootPos = this._rootTransform.getWorldPosition();
         const rootRot = this._rootTransform.getWorldRotation();
         const inputLocalRotations = this._getInputLocalRotations();
@@ -209,7 +197,6 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         for(let i = 0; i < this._grabbersRW.length; i++){
             this._grabbersRW[i].position = this._grabberTransforms[i].getWorldPosition();
         }
-        // Run simulation
         const params = {
             isPaused: this._isPaused,
             stepTime: deltaTime,
@@ -236,11 +223,9 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
         const result = simulate(params, this._pointsR, this._pointsRW, this._constraints, this._collidersR, this._collidersRW, this._grabbersR, this._grabbersRW, this._movableLimitTargets, this._flatPlanes);
         this._positionsToTransform = result.positionsToTransform;
         this._fakeWaveCounter = result.fakeWaveCounter;
-        // Angle limits
         if (this._config.angleLimitConfig.angleLimit >= 0) {
             applyAngleLimits(this._pointsR, this._pointsRW, this._config.angleLimitConfig);
         }
-        // Apply results
         const transformRots = this._pointTransforms.map((t)=>t.getWorldRotation());
         const transformLocalRots = inputLocalRotations;
         const sceneParentRots = this._pointTransforms.map((t)=>this._getSceneParentWorldRotation(t));
@@ -963,14 +948,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01, InterpolatorScalar } from '@ze
     _createPointR(node) {
         const parentIdx = this._parentMap.get(node.index) ?? -1;
         const childIdx = node.children.length > 0 ? node.children[0].index : -1;
-        // Capture initial local transform for rotation blending
         const t = this._pointTransforms[node.index];
         const initLocalPos = t.getLocalPosition();
         const initLocalRot = t.getLocalRotation();
         const initLocalScale = t.getLocalScale();
-        // BoneAxis: local-space direction to first child (computed in initialize)
         const boneAxis = node.boneAxis ?? new Vector3(0, -1, 0);
-        // ParentLength: distance to parent
         let parentLength = 0;
         if (parentIdx !== -1) {
             const pPos = this._pointTransforms[parentIdx].getWorldPosition();