@zephyr3d/scene 0.9.0 → 0.9.2

package/dist/animation/joint_dynamics/controller.js

@@ -3,8 +3,18 @@ import { buildConstraints, buildSurfaceFaces } from './constraints.js';
 import { simulate, applyAngleLimits, applyResult } from './solver.js';
 import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
 
-// High-level orchestrator — SPCRJointDynamicsController API
-class JointDynamicsSystemController {
+// High-level orchestrator - SPCRJointDynamicsController API
+/**
+ * High-level controller for joint dynamics simulation.
+ *
+ * This class manages the physics simulation for a hierarchy of bones, including constraints,
+ * colliders, and grabbers. It provides an API for initializing the system with bone data and
+ * transforms, stepping the simulation each frame, and modifying colliders and grabbers at runtime.
+ * The controller handles the internal state and logic for blending between animation and physics,
+ * applying forces, and enforcing constraints.
+ *
+ * @public
+ */ class JointDynamicsSystemController {
     _config;
     _pointsR = [];
     _pointsRW = [];
@@ -43,14 +53,14 @@ class JointDynamicsSystemController {
     constructor(config){
         this._config = config;
     }
-    /**
-   * 初始化物理系统
-   * @param rootTransform 根骨骼的 transform（用于检测根运动）
-   * @param rootPoints 骨骼层级的根节点数组（可以有多个根，如裙子的多条链）
-   * @param pointTransforms 所有物理点的 transform 数组（顺序必须与 BoneNode.index 对应）
-   * @param colliders 碰撞器数组（球体/胶囊体）
-   * @param grabbers 抓取器数组（用于鼠标交互等）
-   * @param flatPlanes 平面限制器数组（如地板，防止穿透）
+    /**
+   * Initializes the physics system.
+   * @param rootTransform - Root bone transform used to detect root motion.
+   * @param rootPoints - Root nodes of the bone hierarchy. Multiple roots are allowed.
+   * @param pointTransforms - Transform array for all physics points. Order must match `BoneNode.index`.
+   * @param colliders - Collider array (spheres/capsules).
+   * @param grabbers - Grabber array used for interactions such as mouse dragging.
+   * @param flatPlanes - Plane limiters such as the floor to prevent penetration.
    */ initialize(rootTransform, rootPoints, pointTransforms, colliders, grabbers, flatPlanes) {
         this._rootTransform = rootTransform;
         this._pointTransforms = pointTransforms;
@@ -61,7 +71,7 @@ class JointDynamicsSystemController {
         this._surfaceConstraints = buildSurfaceFaces(rootPoints, this._config.constraintOptions.isLoop);
         // Flatten bone hierarchy to point list, build parent map
         const allPoints = [];
-        const parentMap = new Map(); // child index → parent index
+        const parentMap = new Map(); // child index -> parent index
         function walk(node) {
             allPoints.push(node);
             for (const c of node.children){
@@ -140,10 +150,11 @@ class JointDynamicsSystemController {
         }
         this._initialized = true;
     }
-    /**
-   * 执行一帧物理模拟
-   * 内部流程：读取当前 transform → 运行 Verlet 积分和约束求解 → 写回 transform
-   * @param deltaTime 帧间隔时间（秒）。内部会被 subSteps 细分
+    /**
+   * Advances the simulation by one frame.
+   * Internal flow: read current transforms, run Verlet integration and constraint solving,
+   * then write the result back to the transforms.
+   * @param deltaTime - Frame delta time in seconds. Internally subdivided by `subSteps`.
    */ step(deltaTime) {
         if (!this._initialized || !this._rootTransform) {
             return;
@@ -218,10 +229,10 @@ class JointDynamicsSystemController {
         this._previousRootPosition = rootPos;
         this._previousRootRotation = rootRot;
     }
-    /**
-   * 获取所有点的模拟结果（世界坐标位置和旋转）
-   * 通常不需要手动调用——step() 已经自动写回 transform。
-   * 适用于需要在不写回 transform 的情况下读取物理结果的场景。
+    /**
+   * Returns the simulated results for all points as world-space positions and rotations.
+   * Usually this does not need to be called manually because `step()` already writes the
+   * output back to the transforms.
    */ getResults() {
         const transformRots = this._pointTransforms.map((t)=>t.getWorldRotation());
         const transformLocalRots = this._pointTransforms.map((t)=>t.getLocalRotation());
@@ -231,10 +242,10 @@ class JointDynamicsSystemController {
                 rotation: o.rotation
             }));
     }
-    /**
-   * 瞬移补偿——在角色传送/瞬移后调用
-   * 将上一帧的根骨骼位置和旋转设为当前值，
-   * 使下一帧的根运动增量为零，避免物理点因巨大位移而弹射。
+    /**
+   * Compensates for teleportation by resetting the previous root transform to the current one.
+   * Call this after a character warp or teleport to avoid a large root-motion impulse on the
+   * next simulation step.
    */ warp() {
         if (!this._rootTransform) {
             return;
@@ -242,10 +253,10 @@ class JointDynamicsSystemController {
         this._previousRootPosition = this._rootTransform.getWorldPosition();
         this._previousRootRotation = this._rootTransform.getWorldRotation();
     }
-    /**
-   * 重置所有物理状态
-   * 将所有点的模拟位置重置为当前 transform 位置，清除速度和抓取状态。
-   * 适用于场景切换或需要消除所有物理运动的场景。
+    /**
+   * Resets all physics state.
+   * Each simulated point is snapped back to the current transform position and grab state
+   * is cleared.
    */ reset() {
         for(let i = 0; i < this._pointsRW.length; i++){
             const pos = this._pointTransforms[i].getWorldPosition();
@@ -255,10 +266,10 @@ class JointDynamicsSystemController {
         }
         this._fakeWaveCounter = 0;
     }
-    /**
-   * 释放固定点为动态点（如脱衣、布料脱落）
-   * 将 weight 从 0 改为 1，同时重置该点的模拟状态避免瞬间弹射。
-   * @param index 点的索引
+    /**
+   * Releases a fixed point so it becomes dynamic, for example when cloth is detached.
+   * The point state is reset to avoid a sudden impulse.
+   * @param index - Point index.
    */ releasePoint(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return;
@@ -269,10 +280,10 @@ class JointDynamicsSystemController {
         this._pointsRW[index].positionPrevious = pos.clone();
         this._pointsRW[index].grabberIndex = -1;
     }
-    /**
-   * 将动态点重新固定为跟随动画（如重新穿戴）
-   * 将 weight 从 1 改为 0，清除抓取状态。
-   * @param index 点的索引
+    /**
+   * Fixes a dynamic point back to the animation pose, for example when an item is reattached.
+   * The point grab state is cleared.
+   * @param index - Point index.
    */ fixPoint(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return;
@@ -280,44 +291,47 @@ class JointDynamicsSystemController {
         this._pointsR[index].weight = 0;
         this._pointsRW[index].grabberIndex = -1;
     }
-    /**
-   * 查询某个点是否为固定状态（weight=0，跟随动画）
-   * @param index 点的索引
+    /**
+   * Returns whether a point is fixed to animation (`weight = 0`).
+   * @param index - Point index.
    */ isPointFixed(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return false;
         }
         return this._pointsR[index].weight <= EPSILON;
     }
-    /** 获取物理点总数 */ get pointCount() {
+    /** Gets the total number of physics points. */ get pointCount() {
         return this._pointsR.length;
     }
-    /**
-   * 渐入物理——从动画姿态平滑过渡到物理模拟
-   * blendRatio 从 1（纯动画）渐变到 0（纯物理）
-   * @param seconds 过渡时长（秒）
+    /**
+   * Fades physics in by blending from animation pose to simulation.
+   * `blendRatio` moves from `1` (animation only) to `0` (physics only).
+   * @param seconds - Transition duration in seconds.
    */ fadeIn(seconds) {
         this._fadeState = 'in';
         this._fadeTimer = 0;
         this._fadeDuration = seconds;
     }
-    /**
-   * 渐出物理——从物理模拟平滑过渡回动画姿态
-   * blendRatio 从 0（纯物理）渐变到 1（纯动画）
-   * @param seconds 过渡时长（秒）
+    /**
+   * Fades physics out by blending from simulation back to animation pose.
+   * `blendRatio` moves from `0` (physics only) to `1` (animation only).
+   * @param seconds - Transition duration in seconds.
    */ fadeOut(seconds) {
         this._fadeState = 'out';
         this._fadeTimer = 0;
         this._fadeDuration = seconds;
     }
-    /**
-   * 设置全局风力向量
-   * 风力会按每个点的 windForceScale 和质量进行缩放
-   * @param wind 风力向量（世界坐标）
+    /**
+   * Sets the global wind force vector.
+   * The final wind contribution is still scaled per point by `windForceScale` and mass.
+   * @param wind - Wind vector in world space.
    */ setWindForce(wind) {
         this._config.windForce = wind;
     }
-    /** Enable/disable broad-phase pruning for runtime performance comparison */ setBroadPhaseEnabled(enabled) {
+    /**
+   * Enable/disable broad-phase pruning for runtime performance comparison
+   * @param enabled - `true` to enable broad-phase, `false` to disable.
+   */ setBroadPhaseEnabled(enabled) {
         this._config.enableBroadPhase = enabled;
     }
     /** The blend ratio for the physics simulation */ get blendRatio() {
@@ -326,17 +340,23 @@ class JointDynamicsSystemController {
     set blendRatio(value) {
         this._config.blendRatio = clamp01(value);
     }
-    /**
-   * 暂停/恢复物理模拟
-   * 暂停时仍会跟随根骨骼运动，但不进行力学积分和约束求解
-   * @param paused true=暂停, false=恢复
+    /**
+   * Pauses or resumes the physics simulation.
+   * While paused, the system still follows root motion but skips force integration and
+   * constraint solving.
+   * @param paused - `true` to pause, `false` to resume.
    */ setPaused(paused) {
         this._isPaused = paused;
     }
-    /**
-   * Enable or disable a collider by current array index.
-   * Transform state is still read from the collider's TransformAccess each frame.
-   * Prefer setColliderEnabled(handle, enabled) for runtime-owned colliders.
+    /**
+   * Enable or disable a collider by current array index.
+   * Transform state is still read from the collider's TransformAccess each frame.
+   * Prefer setColliderEnabled(handle, enabled) for runtime-owned colliders.
+   *
+   * @param index - Collider index in the current array. Note that this may change when colliders are added or removed.
+   * @param enabled - `true` to enable the collider, `false` to disable it.
+   *
+   * @returns `true` if the index is valid and the collider was updated, `false` if the index is out of range.
    */ setColliderEnabledAt(index, enabled) {
         if (index >= 0 && index < this._collidersRW.length) {
             this._collidersRW[index].enabled = enabled ? 1 : 0;
@@ -344,9 +364,12 @@ class JointDynamicsSystemController {
         }
         return false;
     }
-    /**
-   * Enable or disable a runtime collider by stable handle.
-   * @returns true if the handle is still valid.
+    /**
+   * Enable or disable a runtime collider by stable handle.
+   *
+   * @param handle - Stable handle for the collider to enable or disable.
+   * @param enabled - `true` to enable the collider, `false` to disable it.
+   * @returns true if the handle is still valid.
    */ setColliderEnabled(handle, enabled) {
         const index = this._getColliderIndex(handle);
         if (index === -1) {
@@ -354,9 +377,11 @@ class JointDynamicsSystemController {
         }
         return this.setColliderEnabledAt(index, enabled);
     }
-    /**
-   * Add a collider at runtime.
-   * @returns A stable handle that remains valid until this collider is removed.
+    /**
+   * Add a collider at runtime.
+   * @param r - Read-only collider data such as shape and size.
+   * @param transform - TransformAccess that provides the collider's position and rotation each frame.
+   * @returns A stable handle that remains valid until this collider is removed.
    */ addCollider(r, transform) {
         const id = this._nextColliderHandleId++;
         this._collidersR.push(r);
@@ -369,9 +394,10 @@ class JointDynamicsSystemController {
             id
         };
     }
-    /**
-   * Remove a collider by stable handle.
-   * @returns true if the collider existed and was removed.
+    /**
+   * Remove a collider by stable handle.
+   * @param handle - Stable handle for the collider to remove.
+   * @returns true if the collider existed and was removed.
    */ removeCollider(handle) {
         const index = this._getColliderIndex(handle);
         if (index === -1) {
@@ -379,9 +405,10 @@ class JointDynamicsSystemController {
         }
         return this.removeColliderAt(index);
     }
-    /**
-   * Remove a collider by current array index.
-   * Prefer removeCollider(handle) for runtime-owned colliders.
+    /**
+   * Remove a collider by current array index.
+   * @param index - Collider index in the current array. Note that this may change when colliders are added or removed.
+   * Prefer removeCollider(handle) for runtime-owned colliders.
    */ removeColliderAt(index) {
         if (index < 0 || index >= this._collidersR.length) {
             return false;
@@ -393,9 +420,11 @@ class JointDynamicsSystemController {
         this._rebuildColliderHandleMap();
         return true;
     }
-    /**
-   * Enable or disable a flat plane by current array index.
-   * Prefer setFlatPlaneEnabled(handle, enabled) for runtime-owned flat planes.
+    /**
+   * Enable or disable a flat plane by current array index.
+   * @param index - Flat plane index in the current array. Note that this may change when flat planes are added or removed.
+   * @param enabled - `true` to enable the flat plane, `false` to disable it.
+   * @returns `true` if the index is valid and the flat plane was updated, `false` if the index is out of range.
    */ setFlatPlaneEnabledAt(index, enabled) {
         if (index < 0 || index >= this._flatPlaneAll.length) {
             return false;
@@ -404,9 +433,11 @@ class JointDynamicsSystemController {
         this._rebuildActiveFlatPlanes();
         return true;
     }
-    /**
-   * Enable or disable a runtime flat plane by stable handle.
-   * @returns true if the handle is still valid.
+    /**
+   * Enable or disable a runtime flat plane by stable handle.
+   * @param handle - Stable handle for the flat plane to enable or disable.
+   * @param enabled - `true` to enable the flat plane, `false` to disable it.
+   * @returns true if the handle is still valid.
    */ setFlatPlaneEnabled(handle, enabled) {
         const index = this._getFlatPlaneIndex(handle);
         if (index === -1) {
@@ -414,9 +445,11 @@ class JointDynamicsSystemController {
         }
         return this.setFlatPlaneEnabledAt(index, enabled);
     }
-    /**
-   * Add a flat plane at runtime.
-   * @returns A stable handle that remains valid until this flat plane is removed.
+    /**
+   * Add a flat plane at runtime.
+   * @param up - Up direction of the plane. The normal is computed as `Vector3.normalize(up)`.
+   * @param position - A point on the plane. The distance is computed as `-Vector3.dot(normal, position)`.
+   * @returns A stable handle that remains valid until this flat plane is removed.
    */ addFlatPlane(up, position) {
         const id = this._nextFlatPlaneHandleId++;
         const normal = Vector3.normalize(up);
@@ -433,9 +466,10 @@ class JointDynamicsSystemController {
             id
         };
     }
-    /**
-   * Remove a flat plane by stable handle.
-   * @returns true if the flat plane existed and was removed.
+    /**
+   * Remove a flat plane by stable handle.
+   * @param handle - Stable handle for the flat plane to remove.
+   * @returns true if the flat plane existed and was removed.
    */ removeFlatPlane(handle) {
         const index = this._getFlatPlaneIndex(handle);
         if (index === -1) {
@@ -443,9 +477,10 @@ class JointDynamicsSystemController {
         }
         return this.removeFlatPlaneAt(index);
     }
-    /**
-   * Remove a flat plane by current array index.
-   * Prefer removeFlatPlane(handle) for runtime-owned flat planes.
+    /**
+   * Remove a flat plane by current array index.
+   * @param index - Flat plane index in the current array. Note that this may change when flat planes are added or removed.
+   * @returns true if the index was valid and the flat plane was removed, false if the index was out of range.
    */ removeFlatPlaneAt(index) {
         if (index < 0 || index >= this._flatPlaneAll.length) {
             return false;
@@ -457,10 +492,14 @@ class JointDynamicsSystemController {
         this._rebuildActiveFlatPlanes();
         return true;
     }
-    /**
-   * Enable or disable a grabber by current array index.
-   * Transform state is still read from the grabber's TransformAccess each frame.
-   * Prefer setGrabberEnabled(handle, enabled) for runtime-owned grabbers.
+    /**
+   * Enable or disable a grabber by current array index.
+   * Transform state is still read from the grabber's TransformAccess each frame.
+   * Prefer setGrabberEnabled(handle, enabled) for runtime-owned grabbers.
+   *
+   * @param index - Grabber index in the current array. Note that this may change when grabbers are added or removed.
+   * @param enabled - `true` to enable the grabber, `false` to disable it.
+   * @returns `true` if the index is valid and the grabber was updated, `false` if the index is out of range.
    */ setGrabberEnabledAt(index, enabled) {
         if (index >= 0 && index < this._grabbersRW.length) {
             this._grabbersRW[index].enabled = enabled ? 1 : 0;
@@ -471,9 +510,11 @@ class JointDynamicsSystemController {
         }
         return false;
     }
-    /**
-   * Enable or disable a runtime grabber by stable handle.
-   * @returns true if the handle is still valid.
+    /**
+   * Enable or disable a runtime grabber by stable handle.
+   * @param handle - Stable handle for the grabber to enable or disable.
+   * @param enabled - `true` to enable the grabber, `false` to disable it.
+   * @returns true if the handle is still valid.
    */ setGrabberEnabled(handle, enabled) {
         const index = this._getGrabberIndex(handle);
         if (index === -1) {
@@ -481,9 +522,12 @@ class JointDynamicsSystemController {
         }
         return this.setGrabberEnabledAt(index, enabled);
     }
-    /**
-   * Add a grabber at runtime.
-   * @returns A stable handle that remains valid until this grabber is removed.
+    /**
+   * Add a grabber at runtime.
+   * @param r - Read-only grabber data such as interaction radius.
+   * @param transform - TransformAccess that provides the grabber's position each frame.
+   * @param enabled - Whether the grabber starts enabled. The grabber can still be moved by its transform while disabled, but it won't affect any points until enabled.
+   * @returns A stable handle that remains valid until this grabber is removed.
    */ addGrabber(r, transform, enabled = false) {
         const id = this._nextGrabberHandleId++;
         this._grabbersR.push(r);
@@ -499,9 +543,10 @@ class JointDynamicsSystemController {
             id
         };
     }
-    /**
-   * Remove a grabber by stable handle.
-   * @returns true if the grabber existed and was removed.
+    /**
+   * Remove a grabber by stable handle.
+   * @param handle - Stable handle for the grabber to remove.
+   * @returns true if the grabber existed and was removed.
    */ removeGrabber(handle) {
         const index = this._getGrabberIndex(handle);
         if (index === -1) {
@@ -509,9 +554,12 @@ class JointDynamicsSystemController {
         }
         return this.removeGrabberAt(index);
     }
-    /**
-   * Remove a grabber by current array index.
-   * Prefer removeGrabber(handle) for runtime-owned grabbers.
+    /**
+   * Remove a grabber by current array index.
+   * Prefer removeGrabber(handle) for runtime-owned grabbers.
+   *
+   * @param index - Grabber index in the current array. Note that this may change when grabbers are added or removed.
+   * @returns true if the index was valid and the grabber was removed, false if the index was out of range.
    */ removeGrabberAt(index) {
         if (index < 0 || index >= this._grabbersR.length) {
             return false;