@needle-tools/engine 4.3.0-alpha → 4.3.0-alpha.3

package/src/engine-components/Animator.ts

@@ -11,38 +11,73 @@ import { Behaviour } from "./Component.js";
 
 const debug = getParam("debuganimator");
 
-
+/** 
+ * Represents an event emitted by an animation mixer
+ * @category Animation and Sequencing
+ */
 export declare class MixerEvent {
+    /** The type of event that occurred */
     type: string;
+    /** The animation action that triggered this event */
     action: AnimationAction;
+    /** Number of loops completed in this cycle */
     loopDelta: number;
+    /** The animation mixer that emitted this event */
     target: AnimationMixer;
 }
 
+/**
+ * Configuration options for playing animations
+ * @category Animation and Sequencing
+ */
 export declare class PlayOptions {
+    /** Whether the animation should loop, and if so, which loop style to use */
     loop?: boolean | AnimationActionLoopStyles;
+    /** Whether the final animation state should be maintained after playback completes */
     clampWhenFinished?: boolean;
 }
 
-/** The Animator component is used to play animations on a GameObject. It is used in combination with an AnimatorController (which is a state machine for animations)   
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`
+/** 
+ * The Animator component plays and manages animations on a GameObject. 
+ * It works with an AnimatorController to handle state transitions and animation blending.
+ * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
  * @category Animation and Sequencing
  * @group Components
 */
 export class Animator extends Behaviour implements IAnimationComponent {
 
+    /** 
+     * Identifies this component as an animation component in the engine
+     */
     get isAnimationComponent() {
         return true;
     }
 
+    /**
+     * When enabled, animation will affect the root transform position and rotation
+     */
     @serializable()
     applyRootMotion: boolean = false;
+    
+    /**
+     * Indicates whether this animator contains root motion data
+     */
     @serializable()
     hasRootMotion: boolean = false;
+    
+    /**
+     * When enabled, the animator will maintain its state when the component is disabled
+     */
     @serializable()
     keepAnimatorControllerStateOnDisable: boolean = false;
 
     // set from needle animator extension
+    /**
+     * Sets or replaces the animator controller for this component.
+     * Handles binding the controller to this animator instance and ensures
+     * proper initialization when the controller changes.
+     * @param val The animator controller model or instance to use
+     */
     @serializable()
     set runtimeAnimatorController(val: AnimatorControllerModel | AnimatorController | undefined | null) {
         if (this._animatorController && this._animatorController.model === val) {
@@ -69,41 +104,53 @@ export class Animator extends Behaviour implements IAnimationComponent {
         }
         else this._animatorController = null;
     }
+
+    /**
+     * Gets the current animator controller instance
+     * @returns The current animator controller or null if none is assigned
+     */
     get runtimeAnimatorController(): AnimatorController | undefined | null {
         return this._animatorController;
     }
 
-    /** The current state info of the animator.   
-     * If you just want to access the currently playing animation action you can use currentAction
-     * @returns {AnimatorStateInfo} The current state info of the animator or null if no state is playing
-    */
+    /** 
+     * Retrieves information about the current animation state
+     * @returns The current state information, or undefined if no state is playing
+     */
     getCurrentStateInfo() {
         return this.runtimeAnimatorController?.getCurrentStateInfo();
     }
-    /** The current action playing. It can be used to modify the action   
-     * @returns {AnimationAction | null} The current action playing or null if no state is playing
-    */
+    /** 
+     * The currently playing animation action that can be used to modify animation properties
+     * @returns The current animation action, or null if no animation is playing
+     */
     get currentAction() {
         return this.runtimeAnimatorController?.currentAction || null;
     }
 
-    /** @returns {boolean} True if parameters have been changed */
+    /** 
+     * Indicates whether animation parameters have been modified since the last update
+     * @returns True if parameters have been changed
+     */
     get parametersAreDirty() { return this._parametersAreDirty; }
     private _parametersAreDirty: boolean = false;
 
-    /** @returns {boolean} True if the animator has been changed */
+    /** 
+     * Indicates whether the animator state has changed since the last update
+     * @returns True if the animator has been changed
+     */
     get isDirty() { return this._isDirty; }
     private _isDirty: boolean = false;
 
     /**@deprecated use play() */
     Play(name: string | number, layer: number = -1, normalizedTime: number = Number.NEGATIVE_INFINITY, transitionDurationInSec: number = 0) { this.play(name, layer, normalizedTime, transitionDurationInSec); }
-    /** Plays an animation on the animator
-     * @param {string | number} name The name of the animation to play. Can also be the hash of the animation
-     * @param {number} layer The layer to play the animation on. Default is -1
-     * @param {number} normalizedTime The normalized time to start the animation at. Default is Number.NEGATIVE_INFINITY
-     * @param {number} transitionDurationInSec The duration of the transition to the new animation. Default is 0
-     * @returns {void}
-     * */
+    /** 
+     * Plays an animation on the animator
+     * @param name The name or hash of the animation to play
+     * @param layer The layer to play the animation on (-1 for default layer)
+     * @param normalizedTime The time position to start playing (0-1 range, NEGATIVE_INFINITY for current position)
+     * @param transitionDurationInSec The duration of the blend transition in seconds
+     */
     play(name: string | number, layer: number = -1, normalizedTime: number = Number.NEGATIVE_INFINITY, transitionDurationInSec: number = 0) {
         this.runtimeAnimatorController?.play(name, layer, normalizedTime, transitionDurationInSec);
         this._isDirty = true;
@@ -111,7 +158,9 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use reset */
     Reset() { this.reset(); }
-    /** Resets the animatorcontroller */
+    /** 
+     * Resets the animator controller to its initial state
+     */
     reset() {
         this._animatorController?.reset();
         this._isDirty = true;
@@ -119,6 +168,12 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use setBool */
     SetBool(name: string | number, val: boolean) { this.setBool(name, val); }
+
+    /**
+     * Sets a boolean parameter in the animator
+     * @param name The name or hash of the parameter
+     * @param value The boolean value to set
+     */
     setBool(name: string | number, value: boolean) {
         if (debug) console.log("setBool", name, value);
         if (this.runtimeAnimatorController?.getBool(name) !== value)
@@ -128,18 +183,34 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use getBool */
     GetBool(name: string | number) { return this.getBool(name); }
+
+    /**
+     * Gets a boolean parameter from the animator
+     * @param name The name or hash of the parameter
+     * @returns The value of the boolean parameter, or false if not found
+     */
     getBool(name: string | number): boolean {
         const res = this.runtimeAnimatorController?.getBool(name) ?? false;
         if (debug) console.log("getBool", name, res);
         return res;
     }
 
+    /**
+     * Toggles a boolean parameter between true and false
+     * @param name The name or hash of the parameter
+     */
     toggleBool(name: string | number) {
         this.setBool(name, !this.getBool(name));
     }
 
     /**@deprecated use setFloat */
     SetFloat(name: string | number, val: number) { this.setFloat(name, val); }
+
+    /**
+     * Sets a float parameter in the animator
+     * @param name The name or hash of the parameter
+     * @param val The float value to set
+     */
     setFloat(name: string | number, val: number) {
         if (this.runtimeAnimatorController?.getFloat(name) !== val)
             this._parametersAreDirty = true;
@@ -149,6 +220,12 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use getFloat */
     GetFloat(name: string | number) { return this.getFloat(name); }
+
+    /**
+     * Gets a float parameter from the animator
+     * @param name The name or hash of the parameter
+     * @returns The value of the float parameter, or -1 if not found
+     */
     getFloat(name: string | number): number {
         const res = this.runtimeAnimatorController?.getFloat(name) ?? -1;
         if (debug) console.log("getFloat", name, res);
@@ -157,6 +234,12 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use setInteger */
     SetInteger(name: string | number, val: number) { this.setInteger(name, val); }
+
+    /**
+     * Sets an integer parameter in the animator
+     * @param name The name or hash of the parameter
+     * @param val The integer value to set
+     */
     setInteger(name: string | number, val: number) {
         if (this.runtimeAnimatorController?.getInteger(name) !== val)
             this._parametersAreDirty = true;
@@ -166,6 +249,12 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use getInteger */
     GetInteger(name: string | number) { return this.getInteger(name); }
+
+    /**
+     * Gets an integer parameter from the animator
+     * @param name The name or hash of the parameter
+     * @returns The value of the integer parameter, or -1 if not found
+     */
     getInteger(name: string | number): number {
         const res = this.runtimeAnimatorController?.getInteger(name) ?? -1;
         if (debug) console.log("getInteger", name, res);
@@ -174,6 +263,11 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use setTrigger */
     SetTrigger(name: string | number) { this.setTrigger(name); }
+
+    /**
+     * Activates a trigger parameter in the animator
+     * @param name The name or hash of the trigger parameter
+     */
     setTrigger(name: string | number) {
         this._parametersAreDirty = true;
         if (debug) console.log("setTrigger", name);
@@ -182,6 +276,11 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use resetTrigger */
     ResetTrigger(name: string | number) { this.resetTrigger(name); }
+
+    /**
+     * Resets a trigger parameter in the animator
+     * @param name The name or hash of the trigger parameter
+     */
     resetTrigger(name: string | number) {
         this._parametersAreDirty = true;
         if (debug) console.log("resetTrigger", name);
@@ -190,6 +289,12 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use getTrigger */
     GetTrigger(name: string | number) { this.getTrigger(name); }
+
+    /**
+     * Gets the state of a trigger parameter from the animator
+     * @param name The name or hash of the trigger parameter
+     * @returns The state of the trigger parameter
+     */
     getTrigger(name: string | number) {
         const res = this.runtimeAnimatorController?.getTrigger(name);
         if (debug) console.log("getTrigger", name, res);
@@ -198,13 +303,21 @@ export class Animator extends Behaviour implements IAnimationComponent {
 
     /**@deprecated use isInTransition */
     IsInTransition() { return this.isInTransition(); }
-    /** @returns `true` if the animator is currently in a transition */
+    /** 
+     * Checks if the animator is currently in a transition between states
+     * @returns True if the animator is currently blending between animations
+     */
     isInTransition(): boolean {
         return this.runtimeAnimatorController?.isInTransition() ?? false;
     }
 
     /**@deprecated use setSpeed */
     SetSpeed(speed: number) { return this.setSpeed(speed); }
+
+    /**
+     * Sets the playback speed of the animator
+     * @param speed The new playback speed multiplier
+     */
     setSpeed(speed: number) {
         if (speed === this._speed) return;
         if (debug) console.log("setSpeed", speed);
@@ -213,13 +326,20 @@ export class Animator extends Behaviour implements IAnimationComponent {
             this._animatorController.setSpeed(speed);
     }
 
-    /** Will generate a random speed between the min and max values and set it to the animatorcontroller */
+    /** 
+     * Sets a random playback speed between the min and max values
+     * @param minMax Object with x (minimum) and y (maximum) speed values
+     */
     set minMaxSpeed(minMax: { x: number, y: number }) {
         this._speed = Mathf.lerp(minMax.x, minMax.y, Math.random());
         if (this._animatorController?.animator == this)
             this._animatorController.setSpeed(this._speed);
     }
 
+    /**
+     * Sets a random normalized time offset for animations between min (x) and max (y) values
+     * @param minMax Object with x (min) and y (max) values for the offset range
+     */
     set minMaxOffsetNormalized(minMax: { x: number, y: number }) {
         this._normalizedStartOffset = Mathf.lerp(minMax.x, minMax.y, Math.random());
         if (this.runtimeAnimatorController?.animator == this)