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

package/src/engine-components/AnimatorController.ts

@@ -15,6 +15,11 @@ import { Animator } from "./Animator.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): number {
     let hash = 0;
     for (let i = 0; i < str.length; i++) {
@@ -25,27 +30,38 @@ function stringToHash(str): number {
     return hash;
 }
 
+/**
+ * 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 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 = { looping: false, autoTransition: true, transitionDuration: 0 }): AnimatorController {
         const states: State[] = [];
         for (let i = 0; i < clips.length; i++) {
@@ -99,6 +115,14 @@ export class AnimatorController {
         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: string | number, layerIndex: number = -1, normalizedTime: number = Number.NEGATIVE_INFINITY, durationInSec: number = 0) {
         if (layerIndex < 0) layerIndex = 0;
         else if (layerIndex >= this.model.layers.length) {
@@ -118,20 +142,42 @@ 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: string | number, value: boolean) {
         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: string | number): boolean {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value as boolean ?? 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: string | number, val: number) {
         const key = typeof name === "string" ? "name" : "hash";
         const filtered = this.model?.parameters?.filter(p => p[key] === name);
@@ -139,21 +185,45 @@ export class AnimatorController {
         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: string | number): number {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value as number ?? 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: string | number, val: number) {
         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: string | number): number {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value as number ?? 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: string | number) {
         if (debug)
             console.log("SET TRIGGER", name);
@@ -161,16 +231,32 @@ export class AnimatorController {
         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: string | number) {
         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: string | number): boolean {
         const key = typeof name === "string" ? "name" : "hash";
         return this.model?.parameters?.find(p => p[key] === name)?.value as boolean ?? false;
     }
 
+    /**
+     * Checks if the controller is currently in a transition between states.
+     * 
+     * @returns True if a transition is in progress, false otherwise
+     */
     isInTransition(): boolean {
         return this._activeStates.length > 1;
     }
@@ -182,8 +268,21 @@ export class AnimatorController {
     private _speed: number = 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: string | number | undefined | null): State | null { 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: string | number | undefined | null): State | null {
         if (!name) return null;
         if (Array.isArray(this.model.layers)) {
@@ -196,9 +295,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;
         const action = this._activeState.motion.action;
@@ -208,10 +309,11 @@ export class AnimatorController {
         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(): AnimationAction | null {
         if (!this._activeState) return null;
         const action = this._activeState.motion.action;
@@ -219,24 +321,37 @@ export class AnimatorController {
         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: number = 0;
 
-    /** 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 { 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();
@@ -254,7 +369,12 @@ export class AnimatorController {
     //     // 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: Animator) {
         if (!animator) console.error("AnimatorController.bind: animator is null");
         else if (this.animator !== animator) {
@@ -269,7 +389,12 @@ export class AnimatorController {
         }
     }
 
-    /** 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);
@@ -297,7 +422,12 @@ export class AnimatorController {
         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: number) {
         if (!this.animator) return;
         this.evaluateTransitions();
@@ -318,9 +448,11 @@ export class AnimatorController {
     private _mixer!: AnimationMixer;
     private _activeState?: State;
 
-    /** 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 { return this._activeState; }
 
     constructor(model: AnimatorControllerModel) {
@@ -770,6 +902,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;
         for (const layer of this.model.layers) {
@@ -807,6 +943,10 @@ export class AnimatorController {
     // }
 }
 
+/**
+ * Wraps a KeyframeTrack to allow custom evaluation of animation values.
+ * Used internally to modify animation behavior without changing the original data.
+ */
 class TrackEvaluationWrapper {
 
     track?: KeyframeTrack;
@@ -844,6 +984,10 @@ class TrackEvaluationWrapper {
     }
 }
 
+/**
+ * Handles root motion extraction from animation tracks.
+ * Captures movement from animations and applies it to the root object.
+ */
 class RootMotionAction {
 
     private static lastObjPosition: { [key: string]: Vector3 } = {};
@@ -1043,6 +1187,10 @@ class RootMotionAction {
     }
 }
 
+/**
+ * Manages root motion for a character.
+ * Extracts motion from animation tracks and applies it to the character's transform.
+ */
 class RootMotionHandler {
 
     private controller: AnimatorController;
@@ -1129,8 +1277,10 @@ class RootMotionHandler {
     }
 }
 
-
-
+/**
+ * Serialization handler for AnimatorController instances.
+ * Handles conversion between serialized data and runtime objects.
+ */
 class AnimatorControllerSerializator extends TypeSerializer {
     onSerialize(_: any, _context: SerializationContext) {
 

package/src/engine-components/AudioListener.ts

@@ -5,15 +5,18 @@ import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * AudioListener represents a listener that can be attached to a GameObject to listen to audio sources in the scene.
+ * AudioListener represents a listener that can hear audio sources in the scene.
+ * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
+ * to the main camera or a Camera in the parent hierarchy.
  * @category Multimedia
  * @group Components
  */
 export class AudioListener extends Behaviour {
 
     /**
-     * Gets the existing or creates a new {@link ThreeAudioListener} instance 
-     * @returns The {@link ThreeAudioListener} instance
+     * Gets the existing Three.js {@link three#AudioListener} instance or creates a new one if it doesn't exist.
+     * This listener is responsible for capturing audio in the 3D scene.
+     * @returns The {@link three#AudioListener} instance
      */
     get listener(): ThreeAudioListener {
         if (this._listener == null)
@@ -23,13 +26,21 @@ export class AudioListener extends Behaviour {
 
     private _listener: ThreeAudioListener | null = null;
 
-    /** @internal */
+    /**
+     * Registers for interaction events and initializes the audio listener
+     * when this component is enabled.
+     * @internal
+     */
     onEnable(): void {
         Application.registerWaitForInteraction(this.onInteraction);
         this.addListenerIfItExists();
     }
 
-    /** @internal */
+    /**
+     * Cleans up event registrations and removes the audio listener
+     * when this component is disabled.
+     * @internal
+     */
     onDisable(): void {
         Application.unregisterWaitForInteraction(this.onInteraction);
         this.removeListenerIfItExists();