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

package/src/engine/engine_types.ts

@@ -1,4 +1,4 @@
-import type { QueryFilterFlags } from "@dimforge/rapier3d-compat";
+import type { QueryFilterFlags, World } from "@dimforge/rapier3d-compat";
 import { AnimationClip, Color, Material, Mesh, Object3D, Quaternion } from "three";
 import { Vector3 } from "three";
 import { type GLTF as THREE_GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
@@ -442,80 +442,241 @@ export class SphereOverlapResult {
 
 
 export interface IPhysicsEngine {
+    /** Initializes the physics engine */
     initialize(): Promise<boolean>;
+    /** Indicates whether the physics engine has been initialized */
     get isInitialized(): boolean;
+    /** Advances physics simulation by the given time step */
     step(dt: number): void;
     postStep();
+    /** Indicates whether the physics engine is currently updating */
     get isUpdating(): boolean;
-    /** clear all possibly cached data (e.g. mesh data when creating scaled mesh colliders) */
+    /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
     clearCaches();
 
+    /** Enables or disables the physics engine */
     enabled: boolean;
-    get world(): any;
+    /** Returns the underlying physics world object */
+    get world(): World | undefined;
 
+    /** Sets the gravity vector for the physics simulation */
     set gravity(vec3: Vec3);
+    /** Gets the current gravity vector */
     get gravity(): Vec3;
 
-    /** Get the rapier body for a Needle component */
+    /** 
+     * Gets the rapier physics body for a Needle component 
+     * @param obj The collider or rigidbody component
+     * @returns The underlying physics body or null if not found
+     */
     getBody(obj: ICollider | IRigidbody): null | any;
-    /** Get the Needle Engine component for a rapier object */
+    /** 
+     * Gets the Needle Engine component for a rapier physics object 
+     * @param rapierObject The rapier physics object
+     * @returns The associated component or null if not found
+     */
     getComponent(rapierObject: object): IComponent | null;
 
-    // raycasting
-    /** Fast raycast against physics colliders
-     * @param origin ray origin in screen or worldspace
-     * @param direction ray direction in worldspace
-     * @param options additional options
+    /**
+     * Performs a fast raycast against physics colliders
+     * @param origin Ray origin in screen or worldspace
+     * @param direction Ray direction in worldspace
+     * @param options Additional raycast configuration options
+     * @returns Raycast result containing hit point and collider, or null if no hit
      */
     raycast(origin?: Vec2 | Vec3, direction?: Vec3, options?: {
         maxDistance?: number,
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** Raycast filter groups.  Groups are used to apply the collision group rules for the scene query. The scene query will only consider hits with colliders with collision groups compatible with this collision group (using the bitwise test described in the collision groups section). See https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups    
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 */
+        /** 
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
+         * The scene query will only consider hits with colliders with collision groups compatible with 
+         * this collision group (using the bitwise test described in the collision groups section).
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
+         */
         filterGroups?: number,
-        /** Return false to ignore this collider */
+        /** 
+         * Predicate to filter colliders in raycast results
+         * @param collider The collider being tested
+         * @returns False to ignore this collider, true to include it
+         */
         filterPredicate?: (collider: ICollider) => boolean
     }): RaycastResult;
-    /** raycast that also gets the normal vector. If you don't need it use raycast() */
+
+    /**
+     * Performs a raycast that also returns the normal vector at the hit point
+     * @param origin Ray origin in screen or worldspace
+     * @param direction Ray direction in worldspace
+     * @param options Additional raycast configuration options
+     * @returns Raycast result containing hit point, normal, and collider, or null if no hit
+     */
     raycastAndGetNormal(origin?: Vec2 | Vec3, direction?: Vec3, options?: {
         maxDistance?: number,
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** Raycast filter groups.  Groups are used to apply the collision group rules for the scene query. The scene query will only consider hits with colliders with collision groups compatible with this collision group (using the bitwise test described in the collision groups section). See https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups    
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 */
+        /** 
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
+         * The scene query will only consider hits with colliders with collision groups compatible with 
+         * this collision group (using the bitwise test described in the collision groups section).
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
+         */
         filterGroups?: number,
-        /** Return false to ignore this collider */
+        /** 
+         * Predicate to filter colliders in raycast results
+         * @param collider The collider being tested
+         * @returns False to ignore this collider, true to include it
+         */
         filterPredicate?: (collider: ICollider) => boolean
     }): RaycastResult;
+
+    /**
+     * Finds all colliders within a sphere
+     * @param point The center point of the sphere
+     * @param radius The radius of the sphere
+     * @returns Array of objects that overlap with the sphere
+     */
     sphereOverlap(point: Vector3, radius: number): Array<SphereOverlapResult>;
 
     // Collider methods
+    /**
+     * Adds a sphere collider to the physics world
+     * @param collider The collider component to add
+     */
     addSphereCollider(collider: ICollider);
+    
+    /**
+     * Adds a box collider to the physics world
+     * @param collider The collider component to add
+     * @param size The size of the box
+     */
     addBoxCollider(collider: ICollider, size: Vector3);
+    
+    /**
+     * Adds a capsule collider to the physics world
+     * @param collider The collider component to add
+     * @param radius The radius of the capsule
+     * @param height The height of the capsule
+     */
     addCapsuleCollider(collider: ICollider, radius: number, height: number);
+    
+    /**
+     * Adds a mesh collider to the physics world
+     * @param collider The collider component to add
+     * @param mesh The mesh to use for collision
+     * @param convex Whether the collision mesh should be treated as convex
+     * @param scale Optional scale to apply to the mesh
+     */
     addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale?: Vector3 | undefined);
 
+    /**
+     * Updates the physics material properties of a collider
+     * @param collider The collider to update
+     */
     updatePhysicsMaterial(collider: ICollider);
 
     // Rigidbody methods
+    /**
+     * Wakes up a sleeping rigidbody
+     * @param rb The rigidbody to wake up
+     */
     wakeup(rb: IRigidbody);
+    
+    /**
+     * Checks if a rigidbody is currently sleeping
+     * @param rb The rigidbody to check
+     * @returns Whether the rigidbody is sleeping or undefined if cannot be determined
+     */
     isSleeping(rb: IRigidbody): boolean | undefined;
+    
+    /**
+     * Updates the physical properties of a rigidbody or collider
+     * @param rb The rigidbody or collider to update
+     */
     updateProperties(rb: IRigidbody | ICollider);
+    
+    /**
+     * Resets all forces acting on a rigidbody
+     * @param rb The rigidbody to reset forces on
+     * @param wakeup Whether to wake up the rigidbody
+     */
     resetForces(rb: IRigidbody, wakeup: boolean);
+    
+    /**
+     * Resets all torques acting on a rigidbody
+     * @param rb The rigidbody to reset torques on
+     * @param wakeup Whether to wake up the rigidbody
+     */
     resetTorques(rb: IRigidbody, wakeup: boolean);
+    
+    /**
+     * Adds a continuous force to a rigidbody
+     * @param rb The rigidbody to add force to
+     * @param vec The force vector to add
+     * @param wakeup Whether to wake up the rigidbody
+     */
     addForce(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+    
+    /**
+     * Applies an instantaneous impulse to a rigidbody
+     * @param rb The rigidbody to apply impulse to
+     * @param vec The impulse vector to apply
+     * @param wakeup Whether to wake up the rigidbody
+     */
     applyImpulse(rb: IRigidbody, vec: Vec3, wakeup: boolean);
-    /** Returns the linear velocity of a rigidbody or the rigidbody of a collider */
+    
+    /**
+     * Gets the linear velocity of a rigidbody or the rigidbody attached to a collider
+     * @param rb The rigidbody or collider to get velocity from
+     * @returns The linear velocity vector or null if not available
+     */
     getLinearVelocity(rb: IRigidbody | ICollider): Vec3 | null;
+    
+    /**
+     * Gets the angular velocity of a rigidbody
+     * @param rb The rigidbody to get angular velocity from
+     * @returns The angular velocity vector or null if not available
+     */
     getAngularVelocity(rb: IRigidbody): Vec3 | null;
+    
+    /**
+     * Sets the angular velocity of a rigidbody
+     * @param rb The rigidbody to set angular velocity for
+     * @param vec The angular velocity vector to set
+     * @param wakeup Whether to wake up the rigidbody
+     */
     setAngularVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+    
+    /**
+     * Sets the linear velocity of a rigidbody
+     * @param rb The rigidbody to set linear velocity for
+     * @param vec The linear velocity vector to set
+     * @param wakeup Whether to wake up the rigidbody
+     */
     setLinearVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
 
+    /**
+     * Updates the position and/or rotation of a physics body
+     * @param comp The collider or rigidbody component to update
+     * @param translation Whether to update the position
+     * @param rotation Whether to update the rotation
+     */
     updateBody(comp: ICollider | IRigidbody, translation: boolean, rotation: boolean);
+    
+    /**
+     * Removes a physics body from the simulation
+     * @param body The component whose physics body should be removed
+     */
     removeBody(body: IComponent);
+    
+    /**
+     * Gets the physics body for a component
+     * @param obj The collider or rigidbody component
+     * @returns The underlying physics body or null if not found
+     */
     getBody(obj: ICollider | IRigidbody): null | any;
 
     // Joints

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)