@zephyr3d/editor 0.3.0 → 0.3.1

package/dist/vendor/zephyr3d/scene/dist/animation/joint_dynamics/controller.js

@@ -4,16 +4,16 @@ import { simulate, applyAngleLimits, applyResult } from './solver.js';
 import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
 
 // 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
+/**
+ * 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 = [];
@@ -53,14 +53,14 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
     constructor(config){
         this._config = config;
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -150,11 +150,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         this._initialized = true;
     }
-    /**
-   * 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`.
+    /**
+   * 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;
@@ -229,10 +229,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._previousRootPosition = rootPos;
         this._previousRootRotation = rootRot;
     }
-    /**
-   * 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.
+    /**
+   * 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());
@@ -242,10 +242,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
                 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.
+    /**
+   * 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;
@@ -253,10 +253,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._previousRootPosition = this._rootTransform.getWorldPosition();
         this._previousRootRotation = this._rootTransform.getWorldRotation();
     }
-    /**
-   * Resets all physics state.
-   * Each simulated point is snapped back to the current transform position and grab state
-   * is cleared.
+    /**
+   * 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();
@@ -266,10 +266,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         this._fakeWaveCounter = 0;
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -280,10 +280,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._pointsRW[index].positionPrevious = pos.clone();
         this._pointsRW[index].grabberIndex = -1;
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -291,9 +291,9 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._pointsR[index].weight = 0;
         this._pointsRW[index].grabberIndex = -1;
     }
-    /**
-   * Returns whether a point is fixed to animation (`weight = 0`).
-   * @param index - Point 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;
@@ -303,34 +303,34 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
     /** Gets the total number of physics points. */ get pointCount() {
         return this._pointsR.length;
     }
-    /**
-   * 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.
+    /**
+   * 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;
     }
-    /**
-   * 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.
+    /**
+   * 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;
     }
-    /**
-   * 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.
+    /**
+   * 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
-   * @param enabled - `true` to enable broad-phase, `false` to disable.
+    /**
+   * 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;
     }
@@ -340,23 +340,23 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
     set blendRatio(value) {
         this._config.blendRatio = clamp01(value);
     }
-    /**
-   * 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.
+    /**
+   * 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.
-   *
-   * @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.
+    /**
+   * 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;
@@ -364,12 +364,12 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return false;
     }
-    /**
-   * 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.
+    /**
+   * 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) {
@@ -377,11 +377,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.setColliderEnabledAt(index, enabled);
     }
-    /**
-   * 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.
+    /**
+   * 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);
@@ -394,10 +394,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
             id
         };
     }
-    /**
-   * Remove a collider by stable handle.
-   * @param handle - Stable handle for the collider to remove.
-   * @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) {
@@ -405,10 +405,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.removeColliderAt(index);
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -420,11 +420,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._rebuildColliderHandleMap();
         return true;
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -433,11 +433,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         this._rebuildActiveFlatPlanes();
         return true;
     }
-    /**
-   * 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.
+    /**
+   * 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) {
@@ -445,11 +445,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.setFlatPlaneEnabledAt(index, enabled);
     }
-    /**
-   * 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.
+    /**
+   * 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);
@@ -466,10 +466,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
             id
         };
     }
-    /**
-   * 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.
+    /**
+   * 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) {
@@ -477,10 +477,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.removeFlatPlaneAt(index);
     }
-    /**
-   * 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.
+    /**
+   * 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;
@@ -492,14 +492,14 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         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.
-   *
-   * @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.
+    /**
+   * 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;
@@ -510,11 +510,11 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return false;
     }
-    /**
-   * 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.
+    /**
+   * 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) {
@@ -522,12 +522,12 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.setGrabberEnabledAt(index, enabled);
     }
-    /**
-   * 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.
+    /**
+   * 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);
@@ -543,10 +543,10 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
             id
         };
     }
-    /**
-   * Remove a grabber by stable handle.
-   * @param handle - Stable handle for the grabber to remove.
-   * @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) {
@@ -554,12 +554,12 @@ import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
         }
         return this.removeGrabberAt(index);
     }
-    /**
-   * 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.
+    /**
+   * 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;