@needle-tools/engine 4.2.5 → 4.3.0-alpha.1

package/lib/engine-components/AnimatorController.d.ts

@@ -3,78 +3,203 @@ import { Context } from "../engine/engine_setup.js";
 import type { AnimatorControllerModel, State } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import { AnimatorStateInfo } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import { Animator } from "./Animator.js";
+/**
+ * Configuration options for creating an AnimatorController
+ */
 declare type CreateAnimatorControllerOptions = {
-    /** Should each animationstate loop */
+    /** Should each animation state loop */
     looping?: boolean;
-    /** Set to false to disable generating transitions between animationclips */
+    /** Set to false to disable generating transitions between animation clips */
     autoTransition?: boolean;
-    /** Set to a positive value in seconds for transition duration between states */
+    /** Duration in seconds for transitions between states */
     transitionDuration?: number;
 };
 /**
- * The AnimatorController is used to control the playback of animations. It is used by the {@link Animator} component.
- * It is using a state machine to control the playback of animations.
- * To create an animator controller use the static method `AnimatorController.createFromClips(clips: AnimationClip[], options: CreateAnimatorControllerOptions)`
-*/
+ * Controls the playback of animations using a state machine architecture.
+ *
+ * The AnimatorController manages animation states, transitions between states,
+ * and parameters that affect those transitions. It is used by the {@link Animator}
+ * component to control animation behavior on 3D models.
+ *
+ * Use the static method {@link AnimatorController.createFromClips} to create
+ * an animator controller from a set of animation clips.
+ */
 export declare class AnimatorController {
-    /** Create an animatorcontroller. States are created from the clips array.
-     * @param clips the clips to assign to the controller
-     * @param options options to control the creation of the controller.
-     * @returns the created animator controller
-    */
+    /**
+     * Creates an AnimatorController from a set of animation clips.
+     * Each clip becomes a state in the controller's state machine.
+     *
+     * @param clips - The animation clips to use for creating states
+     * @param options - Configuration options for the controller including looping behavior and transitions
+     * @returns A new AnimatorController instance
+     */
     static createFromClips(clips: AnimationClip[], options?: CreateAnimatorControllerOptions): AnimatorController;
+    /**
+     * Plays an animation state by name or hash.
+     *
+     * @param name - The name or hash identifier of the state to play
+     * @param layerIndex - The layer index (defaults to 0)
+     * @param normalizedTime - The normalized time to start the animation from (0-1)
+     * @param durationInSec - Transition duration in seconds
+     */
     play(name: string | number, layerIndex?: number, normalizedTime?: number, durationInSec?: number): void;
+    /**
+     * Resets the controller to its initial state.
+     */
     reset(): void;
+    /**
+     * Sets a boolean parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param value - The boolean value to set
+     */
     setBool(name: string | number, value: boolean): void;
+    /**
+     * Gets a boolean parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The boolean value of the parameter, or false if not found
+     */
     getBool(name: string | number): boolean;
+    /**
+     * Sets a float parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param val - The float value to set
+     * @returns True if the parameter was found and set, false otherwise
+     */
     setFloat(name: string | number, val: number): boolean;
+    /**
+     * Gets a float parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The float value of the parameter, or 0 if not found
+     */
     getFloat(name: string | number): number;
+    /**
+     * Sets an integer parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param val - The integer value to set
+     */
     setInteger(name: string | number, val: number): void;
+    /**
+     * Gets an integer parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The integer value of the parameter, or 0 if not found
+     */
     getInteger(name: string | number): number;
+    /**
+     * Sets a trigger parameter to active (true).
+     * Trigger parameters are automatically reset after they are consumed by a transition.
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     */
     setTrigger(name: string | number): void;
+    /**
+     * Resets a trigger parameter to inactive (false).
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     */
     resetTrigger(name: string | number): void;
+    /**
+     * Gets the current state of a trigger parameter.
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     * @returns The boolean state of the trigger, or false if not found
+     */
     getTrigger(name: string | number): boolean;
+    /**
+     * Checks if the controller is currently in a transition between states.
+     *
+     * @returns True if a transition is in progress, false otherwise
+     */
     isInTransition(): boolean;
     /** Set the speed of the animator controller. Larger values will make the animation play faster. */
     setSpeed(speed: number): void;
     private _speed;
-    /**@deprecated use findState */
+    /**
+     * Finds an animation state by name or hash.
+     * @deprecated Use findState instead
+     *
+     * @param name - The name or hash identifier of the state to find
+     * @returns The found state or null if not found
+     */
     FindState(name: string | number | undefined | null): State | null;
+    /**
+     * Finds an animation state by name or hash.
+     *
+     * @param name - The name or hash identifier of the state to find
+     * @returns The found state or null if not found
+     */
     findState(name: string | number | undefined | null): State | null;
-    /** Get the current state info
-     * @returns the current state info or null if no state is active
-    */
+    /**
+     * Gets information about the current playing animation state.
+     *
+     * @returns An AnimatorStateInfo object with data about the current state, or null if no state is active
+     */
     getCurrentStateInfo(): AnimatorStateInfo | null;
-    /** Get the current action (shorthand for activeState.motion.action)
-     * @returns the current action that is playing. This is the action that is currently transitioning to or playing.
-     * If no action is playing null is returned.
-     **/
+    /**
+     * Gets the animation action currently playing.
+     *
+     * @returns The current animation action, or null if no action is playing
+     */
     get currentAction(): AnimationAction | null;
-    /** The normalized time of the start state. This is used to determine the start time of the first state. */
+    /**
+     * The normalized time (0-1) to start playing the first state at.
+     * This affects the initial state when the animator is first enabled.
+     */
     normalizedStartOffset: number;
-    /** the animator that this controller is bound to */
+    /**
+     * The Animator component this controller is bound to.
+     */
     animator?: Animator;
-    /** the model that this controller is based on */
+    /**
+     * The data model describing the animation states and transitions.
+     */
     model: AnimatorControllerModel;
-    /** Get the context of the animator */
+    /**
+     * Gets the engine context from the bound animator.
+     */
     get context(): Context | undefined | null;
-    /** Get the animation mixer that is used to play the animations */
+    /**
+     * Gets the animation mixer used by this controller.
+     */
     get mixer(): AnimationMixer;
     /**
-     * Clears the animation mixer and unregisters it from the context.
+     * Cleans up resources used by this controller.
+     * Stops all animations and unregisters the mixer from the animation system.
      */
     dispose(): void;
-    /** Bind the animator to the controller. Only one animator can be bound to a controller at a time. */
+    /**
+     * Binds this controller to an animator component.
+     * Creates a new animation mixer and sets up animation actions.
+     *
+     * @param animator - The animator to bind this controller to
+     */
     bind(animator: Animator): void;
-    /** Create a clone of the controller. This will clone the model but not the runtime state. */
+    /**
+     * Creates a deep copy of this controller.
+     * Clones the model data but does not copy runtime state.
+     *
+     * @returns A new AnimatorController instance with the same configuration
+     */
     clone(): AnimatorController | null;
-    /** Called by the animator. This will update the active states and transitions as well as the animation mixer. */
+    /**
+     * Updates the controller's state machine and animations.
+     * Called each frame by the animator component.
+     *
+     * @param weight - The weight to apply to the animations (for blending)
+     */
     update(weight: number): void;
     private _mixer;
     private _activeState?;
-    /** Get the currently active state playing
-     * @returns the currently active state or undefined if no state is active
-     **/
+    /**
+     * Gets the currently active animation state.
+     *
+     * @returns The active state or undefined if no state is active
+     */
     get activeState(): State | undefined;
     constructor(model: AnimatorControllerModel);
     private _activeStates;
@@ -92,6 +217,10 @@ export declare class AnimatorController {
     private createAction;
     private evaluateCondition;
     private createActions;
+    /**
+     * Yields all animation actions managed by this controller.
+     * Iterates through all states in all layers and returns their actions.
+     */
     enumerateActions(): Generator<AnimationAction, void, unknown>;
     private rootMotionHandler?;
 }

package/lib/engine-components/AnimatorController.js

@@ -9,6 +9,11 @@ import { deepClone, getParam } from "../engine/engine_utils.js";
 import { AnimatorConditionMode, AnimatorControllerParameterType, AnimatorStateInfo, createMotion } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 const debug = getParam("debuganimatorcontroller");
 const debugRootMotion = getParam("debugrootmotion");
+/**
+ * Generates a hash code for a string
+ * @param str - The string to hash
+ * @returns A numeric hash value
+ */
 function stringToHash(str) {
     let hash = 0;
     for (let i = 0; i < str.length; i++) {
@@ -19,16 +24,24 @@ function stringToHash(str) {
     return hash;
 }
 /**
- * The AnimatorController is used to control the playback of animations. It is used by the {@link Animator} component.
- * It is using a state machine to control the playback of animations.
- * To create an animator controller use the static method `AnimatorController.createFromClips(clips: AnimationClip[], options: CreateAnimatorControllerOptions)`
-*/
+ * Controls the playback of animations using a state machine architecture.
+ *
+ * The AnimatorController manages animation states, transitions between states,
+ * and parameters that affect those transitions. It is used by the {@link Animator}
+ * component to control animation behavior on 3D models.
+ *
+ * Use the static method {@link AnimatorController.createFromClips} to create
+ * an animator controller from a set of animation clips.
+ */
 export class AnimatorController {
-    /** Create an animatorcontroller. States are created from the clips array.
-     * @param clips the clips to assign to the controller
-     * @param options options to control the creation of the controller.
-     * @returns the created animator controller
-    */
+    /**
+     * Creates an AnimatorController from a set of animation clips.
+     * Each clip becomes a state in the controller's state machine.
+     *
+     * @param clips - The animation clips to use for creating states
+     * @param options - Configuration options for the controller including looping behavior and transitions
+     * @returns A new AnimatorController instance
+     */
     static createFromClips(clips, options = { looping: false, autoTransition: true, transitionDuration: 0 }) {
         const states = [];
         for (let i = 0; i < clips.length; i++) {
@@ -79,6 +92,14 @@ export class AnimatorController {
         const controller = new AnimatorController(model);
         return controller;
     }
+    /**
+     * Plays an animation state by name or hash.
+     *
+     * @param name - The name or hash identifier of the state to play
+     * @param layerIndex - The layer index (defaults to 0)
+     * @param normalizedTime - The normalized time to start the animation from (0-1)
+     * @param durationInSec - Transition duration in seconds
+     */
     play(name, layerIndex = -1, normalizedTime = Number.NEGATIVE_INFINITY, durationInSec = 0) {
         if (layerIndex < 0)
             layerIndex = 0;
@@ -98,49 +119,111 @@ export class AnimatorController {
         }
         console.warn("Could not find " + name + " to play");
     }
+    /**
+     * Resets the controller to its initial state.
+     */
     reset() {
         this.setStartTransition();
     }
+    /**
+     * Sets a boolean parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param value - The boolean value to set
+     */
     setBool(name, value) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.filter(p => p[key] === name).forEach(p => p.value = value);
     }
+    /**
+     * Gets a boolean parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The boolean value of the parameter, or false if not found
+     */
     getBool(name) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value ?? false;
     }
+    /**
+     * Sets a float parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param val - The float value to set
+     * @returns True if the parameter was found and set, false otherwise
+     */
     setFloat(name, val) {
         const key = typeof name === "string" ? "name" : "hash";
         const filtered = this.model?.parameters?.filter(p => p[key] === name);
         filtered.forEach(p => p.value = val);
         return filtered?.length > 0;
     }
+    /**
+     * Gets a float parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The float value of the parameter, or 0 if not found
+     */
     getFloat(name) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value ?? 0;
     }
+    /**
+     * Sets an integer parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @param val - The integer value to set
+     */
     setInteger(name, val) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.filter(p => p[key] === name).forEach(p => p.value = val);
     }
+    /**
+     * Gets an integer parameter value by name or hash.
+     *
+     * @param name - The name or hash identifier of the parameter
+     * @returns The integer value of the parameter, or 0 if not found
+     */
     getInteger(name) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value ?? 0;
     }
+    /**
+     * Sets a trigger parameter to active (true).
+     * Trigger parameters are automatically reset after they are consumed by a transition.
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     */
     setTrigger(name) {
         if (debug)
             console.log("SET TRIGGER", name);
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.filter(p => p[key] === name).forEach(p => p.value = true);
     }
+    /**
+     * Resets a trigger parameter to inactive (false).
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     */
     resetTrigger(name) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.filter(p => p[key] === name).forEach(p => p.value = false);
     }
+    /**
+     * Gets the current state of a trigger parameter.
+     *
+     * @param name - The name or hash identifier of the trigger parameter
+     * @returns The boolean state of the trigger, or false if not found
+     */
     getTrigger(name) {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value ?? false;
     }
+    /**
+     * Checks if the controller is currently in a transition between states.
+     *
+     * @returns True if a transition is in progress, false otherwise
+     */
     isInTransition() {
         return this._activeStates.length > 1;
     }
@@ -149,8 +232,20 @@ export class AnimatorController {
         this._speed = speed;
     }
     _speed = 1;
-    /**@deprecated use findState */
+    /**
+     * Finds an animation state by name or hash.
+     * @deprecated Use findState instead
+     *
+     * @param name - The name or hash identifier of the state to find
+     * @returns The found state or null if not found
+     */
     FindState(name) { return this.findState(name); }
+    /**
+     * Finds an animation state by name or hash.
+     *
+     * @param name - The name or hash identifier of the state to find
+     * @returns The found state or null if not found
+     */
     findState(name) {
         if (!name)
             return null;
@@ -164,9 +259,11 @@ export class AnimatorController {
         }
         return null;
     }
-    /** Get the current state info
-     * @returns the current state info or null if no state is active
-    */
+    /**
+     * Gets information about the current playing animation state.
+     *
+     * @returns An AnimatorStateInfo object with data about the current state, or null if no state is active
+     */
     getCurrentStateInfo() {
         if (!this._activeState)
             return null;
@@ -177,10 +274,11 @@ export class AnimatorController {
         const normalizedTime = dur <= 0 ? 0 : Math.abs(action.time / dur);
         return new AnimatorStateInfo(this._activeState, normalizedTime, dur, this._speed);
     }
-    /** Get the current action (shorthand for activeState.motion.action)
-     * @returns the current action that is playing. This is the action that is currently transitioning to or playing.
-     * If no action is playing null is returned.
-     **/
+    /**
+     * Gets the animation action currently playing.
+     *
+     * @returns The current animation action, or null if no action is playing
+     */
     get currentAction() {
         if (!this._activeState)
             return null;
@@ -189,20 +287,32 @@ export class AnimatorController {
             return null;
         return action;
     }
-    /** The normalized time of the start state. This is used to determine the start time of the first state. */
+    /**
+     * The normalized time (0-1) to start playing the first state at.
+     * This affects the initial state when the animator is first enabled.
+     */
     normalizedStartOffset = 0;
-    /** the animator that this controller is bound to */
+    /**
+     * The Animator component this controller is bound to.
+     */
     animator;
-    /** the model that this controller is based on */
+    /**
+     * The data model describing the animation states and transitions.
+     */
     model;
-    /** Get the context of the animator */
+    /**
+     * Gets the engine context from the bound animator.
+     */
     get context() { return this.animator?.context; }
-    /** Get the animation mixer that is used to play the animations */
+    /**
+     * Gets the animation mixer used by this controller.
+     */
     get mixer() {
         return this._mixer;
     }
     /**
-     * Clears the animation mixer and unregisters it from the context.
+     * Cleans up resources used by this controller.
+     * Stops all animations and unregisters the mixer from the animation system.
      */
     dispose() {
         this._mixer.stopAllAction();
@@ -218,7 +328,12 @@ export class AnimatorController {
     // applyRootMotion(obj: Object3D) {
     //     // this.internalApplyRootMotion(obj);
     // }
-    /** Bind the animator to the controller. Only one animator can be bound to a controller at a time. */
+    /**
+     * Binds this controller to an animator component.
+     * Creates a new animation mixer and sets up animation actions.
+     *
+     * @param animator - The animator to bind this controller to
+     */
     bind(animator) {
         if (!animator)
             console.error("AnimatorController.bind: animator is null");
@@ -233,7 +348,12 @@ export class AnimatorController {
             this.createActions(this.animator);
         }
     }
-    /** Create a clone of the controller. This will clone the model but not the runtime state. */
+    /**
+     * Creates a deep copy of this controller.
+     * Clones the model data but does not copy runtime state.
+     *
+     * @returns A new AnimatorController instance with the same configuration
+     */
     clone() {
         if (typeof this.model === "string") {
             console.warn("AnimatorController has not been resolved, can not create model from string", this.model);
@@ -265,7 +385,12 @@ export class AnimatorController {
         const controller = new AnimatorController(clonedModel);
         return controller;
     }
-    /** Called by the animator. This will update the active states and transitions as well as the animation mixer. */
+    /**
+     * Updates the controller's state machine and animations.
+     * Called each frame by the animator component.
+     *
+     * @param weight - The weight to apply to the animations (for blending)
+     */
     update(weight) {
         if (!this.animator)
             return;
@@ -284,9 +409,11 @@ export class AnimatorController {
     }
     _mixer;
     _activeState;
-    /** Get the currently active state playing
-     * @returns the currently active state or undefined if no state is active
-     **/
+    /**
+     * Gets the currently active animation state.
+     *
+     * @returns The active state or undefined if no state is active
+     */
     get activeState() { return this._activeState; }
     constructor(model) {
         this.model = model;
@@ -706,6 +833,10 @@ export class AnimatorController {
             }
         }
     }
+    /**
+     * Yields all animation actions managed by this controller.
+     * Iterates through all states in all layers and returns their actions.
+     */
     *enumerateActions() {
         if (!this.model.layers)
             return;
@@ -725,6 +856,10 @@ export class AnimatorController {
     // https://docs.unity3d.com/Manual/RootMotion.html
     rootMotionHandler;
 }
+/**
+ * Wraps a KeyframeTrack to allow custom evaluation of animation values.
+ * Used internally to modify animation behavior without changing the original data.
+ */
 class TrackEvaluationWrapper {
     track;
     createdInterpolant;
@@ -759,6 +894,10 @@ class TrackEvaluationWrapper {
         this.customEvaluate = undefined;
     }
 }
+/**
+ * Handles root motion extraction from animation tracks.
+ * Captures movement from animations and applies it to the root object.
+ */
 class RootMotionAction {
     static lastObjPosition = {};
     static lastObjRotation = {};
@@ -922,6 +1061,10 @@ class RootMotionAction {
         return true;
     }
 }
+/**
+ * Manages root motion for a character.
+ * Extracts motion from animation tracks and applies it to the character's transform.
+ */
 class RootMotionHandler {
     controller;
     handler = [];
@@ -993,6 +1136,10 @@ class RootMotionHandler {
         return null;
     }
 }
+/**
+ * Serialization handler for AnimatorController instances.
+ * Handles conversion between serialized data and runtime objects.
+ */
 class AnimatorControllerSerializator extends TypeSerializer {
     onSerialize(_, _context) {
     }