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

package/src/engine-components/AudioSource.ts

@@ -13,84 +13,121 @@ import { Behaviour, GameObject } from "./Component.js";
 const debug = getParam("debugaudio");
 
 /**
- * The AudioRolloffMode enum describes different ways that audio can attenuate with distance.
+ * Defines how audio volume attenuates over distance from the listener.
  */
 export enum AudioRolloffMode {
-    /// <summary>
-    ///   <para>Use this mode when you want a real-world rolloff.</para>
-    /// </summary>
+    /**
+     * Logarithmic rolloff provides a natural, real-world attenuation where volume decreases
+     * exponentially with distance.
+     */
     Logarithmic = 0,
-    /// <summary>
-    ///   <para>Use this mode when you want to lower the volume of your sound over the distance.</para>
-    /// </summary>
+    
+    /**
+     * Linear rolloff provides a straightforward volume reduction that decreases at a constant
+     * rate with distance.
+     */
     Linear = 1,
-    /// <summary>
-    ///   <para>Use this when you want to use a custom rolloff.</para>
-    /// </summary>
+    
+    /**
+     * Custom rolloff allows for defining specialized distance-based attenuation curves.
+     * Note: Custom rolloff is not fully implemented in this version.
+     */
     Custom = 2,
 }
 
 
-/** The AudioSource can be used to play audio in the scene.  
- * Use `clip` to set the audio file to play.
+/** 
+ * Plays audio clips in the scene, with support for spatial positioning.
+ * 
+ * The AudioSource component can play audio files or media streams with
+ * options for spatial blending, volume control, looping, and more.
+ * 
+ * When a page loses visibility (tab becomes inactive), audio will automatically
+ * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
+ * pauses regardless of this setting. When the page becomes visible again,
+ * previously playing audio will resume.
+ * 
+ * AudioSource also responds to application mute state changes. When the application
+ * is muted, the volume is set to 0. When unmuted, the volume
+ * returns to its previous value.
+ * 
  * @category Multimedia
  * @group Components
  */
 export class AudioSource extends Behaviour {
 
-    /** Check if the user has interacted with the page to allow audio playback.
-     * Internally calling {@link Application.userInteractionRegistered}
+    /**
+     * Checks if the user has interacted with the page to allow audio playback.
+     * Audio playback often requires a user gesture first due to browser autoplay policies.
+     * This is the same as calling {@link Application.userInteractionRegistered}.
+     * 
+     * @returns Whether user interaction has been registered to allow audio playback
      */
     public static get userInteractionRegistered(): boolean {
         return Application.userInteractionRegistered;
     }
 
-    /** Register a callback that is called when the user has interacted with the page to allow audio playback.
-     * Internally calling {@link Application.registerWaitForInteraction}
+    /**
+     * Registers a callback that will be executed once the user has interacted with the page,
+     * allowing audio playback to begin.
+     * This is the same as calling {@link Application.registerWaitForInteraction}.
+     * 
+     * @param cb - The callback function to execute when user interaction is registered
      */
     public static registerWaitForAllowAudio(cb: Function) {
         Application.registerWaitForInteraction(cb);
     }
 
     /**
-     * The audio clip to play. Can be a string (URL) or a MediaStream.
+     * The audio clip to play. Can be a URL string pointing to an audio file or a {@link MediaStream} object.
      */
     @serializable(URL)
     clip: string | MediaStream = "";
 
     /**
-     * If true, the audio source will start playing as soon as the scene starts.
-     * If false, you can call play() to start the audio.
+     * When true, the audio will automatically start playing when the component is enabled.
+     * When false, you must call play() manually to start audio playback.
      * @default false
-    */
+     */
     @serializable()
     playOnAwake: boolean = false;
 
     /**
-     * If true, the audio source will start loading the audio clip as soon as the scene starts.
-     * If false, the audio clip will be loaded when play() is called.
+     * When true, the audio clip will be loaded during initialization rather than when play() is called.
+     * This can reduce playback delay but increases initial loading time.
      * @default false
      */
     @serializable()
     preload: boolean = false;
 
     /**
-     * When true, the audio will play in the background. This means it will continue playing if the browser tab is not focused/active or minimized
+     * When true, audio will continue playing when the browser tab loses focus.
+     * When false, audio will pause when the tab is minimized or not active.
      * @default true
      */
     @serializable()
     playInBackground: boolean = true;
 
     /**
-     * If true, the audio is currently playing.
+     * Indicates whether the audio is currently playing.
+     * 
+     * @returns True if the audio is playing, false otherwise
      */
     get isPlaying(): boolean { return this.sound?.isPlaying ?? false; }
 
-    /** The duration of the audio clip in seconds. */
+    /**
+     * The total duration of the current audio clip in seconds.
+     * 
+     * @returns Duration in seconds or undefined if no clip is loaded
+     */
     get duration() {
         return this.sound?.buffer?.duration;
     }
-    /** The current time of the audio clip in 0-1 range. */
+    
+    /**
+     * The current playback position as a normalized value between 0 and 1.
+     * Can be set to seek to a specific position in the audio.
+     */
     get time01() {
         const duration = this.duration;
         if (duration && this.sound) {
@@ -106,7 +143,8 @@ export class AudioSource extends Behaviour {
     }
 
     /**
-     * The current time of the audio clip in seconds.
+     * The current playback position in seconds.
+     * Can be set to seek to a specific time in the audio.
      */
     get time(): number { return this.sound?.source ? (this.sound.source?.context.currentTime - this._lastContextTime + this.sound.offset) : 0; }
     set time(val: number) {
@@ -121,8 +159,8 @@ export class AudioSource extends Behaviour {
     }
 
     /**
-     * If true, the audio source will loop the audio clip.
-     * If false, the audio clip will play once.
+     * When true, the audio will repeat after reaching the end.
+     * When false, audio will play once and stop.
      * @default false
      */
     @serializable()
@@ -134,10 +172,12 @@ export class AudioSource extends Behaviour {
         this._loop = val;
         if (this.sound) this.sound.setLoop(val);
     }
-    /** Can be used to play the audio clip in 2D or 3D space.  
-     * 2D Playback is currently not fully supported.  
-     * 0 = 2D, 1 = 3D 
-     * */
+    
+    /**
+     * Controls how the audio is positioned in space.
+     * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
+     * Note: 2D playback is not fully supported in the current implementation.
+     */
     @serializable()
     get spatialBlend(): number {
         return this._spatialBlend;
@@ -147,6 +187,11 @@ export class AudioSource extends Behaviour {
         this._spatialBlend = val;
         this._needUpdateSpatialDistanceSettings = true;
     }
+    
+    /**
+     * The minimum distance from the audio source at which the volume starts to attenuate.
+     * Within this radius, the audio plays at full volume regardless of distance.
+     */
     @serializable()
     get minDistance(): number {
         return this._minDistance;
@@ -156,6 +201,11 @@ export class AudioSource extends Behaviour {
         this._minDistance = val;
         this._needUpdateSpatialDistanceSettings = true;
     }
+    
+    /**
+     * The maximum distance from the audio source beyond which the volume no longer decreases.
+     * This defines the outer limit of the attenuation curve.
+     */
     @serializable()
     get maxDistance(): number {
         return this._maxDistance;
@@ -170,6 +220,11 @@ export class AudioSource extends Behaviour {
     private _minDistance: number = 1;
     private _maxDistance: number = 100;
 
+    /**
+     * Controls the overall volume/loudness of the audio.
+     * Values range from 0 (silent) to 1 (full volume).
+     * @default 1
+     */
     @serializable()
     get volume(): number { return this._volume; }
     set volume(val: number) {
@@ -181,6 +236,12 @@ export class AudioSource extends Behaviour {
     }
     private _volume: number = 1;
 
+    /**
+     * Controls the playback rate (speed) of the audio.
+     * Values greater than 1 increase speed, values less than 1 decrease it.
+     * This affects both speed and pitch of the audio.
+     * @default 1
+     */
     @serializable()
     set pitch(val: number) {
         if (this.sound) this.sound.setPlaybackRate(val);
@@ -189,6 +250,11 @@ export class AudioSource extends Behaviour {
         return this.sound ? this.sound.getPlaybackRate() : 1;
     }
 
+    /**
+     * Determines how audio volume decreases with distance from the listener.
+     * @default AudioRolloffMode.Logarithmic
+     * @see {@link AudioRolloffMode}
+     */
     @serializable()
     rollOffMode: AudioRolloffMode = 0;
 
@@ -204,10 +270,15 @@ export class AudioSource extends Behaviour {
     private _lastClipStartedLoading: string | MediaStream | null = null;
     private _audioElement: HTMLAudioElement | null = null;
 
+    /**
+     * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
+     * The audio source needs a user interaction to be initialized due to browser autoplay policies.
+     * 
+     * @returns The three.js PositionalAudio object or null if unavailable
+     */
     public get Sound(): PositionalAudio | null {
         if (!this.sound && AudioSource.userInteractionRegistered) {
-            let listener = GameObject.getComponent(this.context.mainCamera, AudioListener) ?? GameObject.findObjectOfType(AudioListener, this.context);
-            if (!listener && this.context.mainCamera) listener = GameObject.addComponent(this.context.mainCamera, AudioListener);
+            const listener = GameObject.getOrAddComponent(this.gameObject, AudioListener);
             if (listener?.listener) {
                 this.sound = new PositionalAudio(listener.listener);
                 this.gameObject?.add(this.sound);
@@ -250,9 +321,19 @@ export class AudioSource extends Behaviour {
     //     }
     // }
 
+    /**
+     * Indicates whether the audio source is queued to play when possible.
+     * This may be true before user interaction has been registered.
+     * 
+     * @returns Whether the audio source intends to play
+     */
     public get ShouldPlay(): boolean { return this.shouldPlay; }
 
-    /** Get the audio context from the Sound */
+    /**
+     * Returns the Web Audio API context associated with this audio source.
+     * 
+     * @returns The {@link AudioContext} or null if not available
+     */
     public get audioContext() {
         return this.sound?.context;
     }
@@ -424,7 +505,12 @@ export class AudioSource extends Behaviour {
         }
     }
 
-    /** Play a audioclip or mediastream */
+    /**
+     * Plays the audio clip or media stream.
+     * If no argument is provided, plays the currently assigned clip.
+     * 
+     * @param clip - Optional audio clip or {@link MediaStream} to play
+     */
     play(clip: string | MediaStream | undefined = undefined) {
         // use audio source's clip when no clip is passed in
         if (!clip && this.clip)
@@ -483,7 +569,8 @@ export class AudioSource extends Behaviour {
     }
 
     /**
-     * Pause the audio
+     * Pauses audio playback while maintaining the current position.
+     * Use play() to resume from the paused position.
      */
     pause() {
         if (debug) console.log("Pause", this);
@@ -497,7 +584,8 @@ export class AudioSource extends Behaviour {
     }
 
     /**
-     * Stop the audio and reset the time to 0
+     * Stops audio playback completely and resets the playback position to the beginning.
+     * Unlike pause(), calling play() after stop() will start from the beginning.
      */
     stop() {
         if (debug) console.log("Pause", this);

package/src/engine-components/AvatarLoader.ts

@@ -10,17 +10,37 @@ import { GameObject } from "./Component.js";
 
 const debug = utils.getParam("debugavatar");
 
+/**
+ * Represents an avatar model with head and hands references.
+ * Used for representing characters in 3D space.
+ */
 export class AvatarModel {
+    /** The root object of the avatar model */
     root: Object3D;
+    /** The head object of the avatar model */
     head: Object3D;
+    /** The left hand object of the avatar model, if available */
     leftHand: Object3D | null;
+    /** The right hand object of the avatar model, if available */
     rigthHand: Object3D | null;
 
 
+    /**
+     * Checks if the avatar model has a valid configuration.
+     * An avatar is considered valid if it has a head.
+     * @returns Whether the avatar has a valid setup
+     */
     get isValid(): boolean {
         return this.head !== null && this.head !== undefined;
     }
 
+    /**
+     * Creates a new avatar model.
+     * @param root The root object of the avatar
+     * @param head The head object of the avatar
+     * @param leftHand The left hand object of the avatar
+     * @param rigthHand The right hand object of the avatar
+     */
     constructor(root: Object3D, head: Object3D, leftHand: Object3D | null, rigthHand: Object3D | null) {
         this.root = root;
         this.head = head;
@@ -33,12 +53,25 @@ export class AvatarModel {
     }
 }
 
+/**
+ * Handles loading and instantiating avatar models from various sources.
+ * Provides functionality to find and extract important parts of an avatar (head, hands).
+ * 
+ * Debug mode can be enabled with the URL parameter `?debugavatar`,
+ * which will log detailed information about avatar loading and configuration.
+ */
 export class AvatarLoader {
 
     private readonly avatarRegistryUrl: string | null = null;
     // private loader: GLTFLoader | null;
     // private avatarModelCache: Map<string, AvatarModel | null> = new Map<string, AvatarModel | null>();
 
+    /**
+     * Retrieves or creates a new avatar instance from an ID or existing Object3D.
+     * @param context The application context
+     * @param avatarId Either a string ID to load an avatar or an existing Object3D to use as avatar
+     * @returns Promise resolving to an AvatarModel if successful, or null if failed
+     */
     public async getOrCreateNewAvatarInstance(context: Context, avatarId: string | Object3D): Promise<AvatarModel | null> {
 
         if (!avatarId) {
@@ -76,6 +109,12 @@ export class AvatarLoader {
     }
 
 
+    /**
+     * Loads an avatar model from a file or registry using the provided ID.
+     * @param context The engine context
+     * @param avatarId The ID of the avatar to load
+     * @returns Promise resolving to the loaded avatar's Object3D, or null if failed
+     */
     private async loadAvatar(context: Context, avatarId: string): Promise<Object3D | null> {
 
         console.assert(avatarId !== undefined && avatarId !== null && typeof avatarId === "string", "Avatar id must not be null");
@@ -140,11 +179,20 @@ export class AvatarLoader {
         });
     }
 
+    /**
+     * Caches an avatar model for reuse.
+     * @param _id The ID to associate with the model
+     * @param _model The avatar model to cache
+     */
     private cacheModel(_id: string, _model: AvatarModel) {
         // this.avatarModelCache.set(id, model);
     }
 
-    // TODO this should be burned to the ground once 🤞 we have proper extras that define object relations.
+    /**
+     * Analyzes an Object3D to find avatar parts (head, hands) based on naming conventions.
+     * @param obj The Object3D to search for avatar parts
+     * @returns A structured AvatarModel with references to found parts
+     */
     private findAvatar(obj: Object3D): AvatarModel {
 
         const root: Object3D = obj;
@@ -175,7 +223,12 @@ export class AvatarLoader {
         return model;
     }
 
-
+    /**
+     * Recursively searches for an avatar part by name within an Object3D hierarchy.
+     * @param obj The Object3D to search within
+     * @param searchString Array of strings that should all be present in the object name
+     * @returns The found Object3D part or null if not found
+     */
     private findAvatarPart(obj: Object3D, searchString: string[]): Object3D | null {
 
         const name = obj.name.toLowerCase();
@@ -196,6 +249,12 @@ export class AvatarLoader {
         return null;
     }
 
+    /**
+     * Handles HTTP response errors from avatar loading operations.
+     * @param response The fetch API response to check
+     * @returns The response if it was ok
+     * @throws Error with status text if response was not ok
+     */
     private handleCustomAvatarErrors(response) {
         if (!response.ok) {
             throw Error(response.statusText);

package/src/engine-components/AxesHelper.ts

@@ -5,20 +5,37 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * AxesHelper is a component that displays the axes of the object in the scene.
+ * Component that visualizes the axes of an object in the scene.
+ * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
  * @category Helpers
  * @group Components
  */
 export class AxesHelper extends Behaviour {
+    /**
+     * The length of each axis line in scene units.
+     */
     @serializable()
     public length: number = 1;
+    
+    /**
+     * Whether the axes should be occluded by objects in the scene.
+     * When set to false, axes will always appear on top regardless of their depth.
+     */
     @serializable()
     public depthTest: boolean = true;
+    
+    /**
+     * When true, this helper will only be visible if the debug flag `?gizmos` is enabled.
+     */
     @serializable()
     public isGizmo: boolean = false;
 
     private _axes: _AxesHelper | null = null;
 
+    /**
+     * Creates and adds the axes visualization to the scene when the component is enabled.
+     * If marked as a gizmo, it will only be shown when gizmos are enabled in the global parameters.
+     */
     onEnable(): void {
         if (this.isGizmo && !params.showGizmos) return;
         if (!this._axes)
@@ -33,6 +50,9 @@ export class AxesHelper extends Behaviour {
         }
     }
 
+    /**
+     * Removes the axes visualization from the scene when the component is disabled.
+     */
     onDisable(): void {
         if (!this._axes) return;
         this.gameObject.remove(this._axes);

package/src/engine-components/BoxHelperComponent.ts

@@ -9,11 +9,17 @@ const gizmos = getParam("gizmos");
 const debug = getParam("debugboxhelper");
 
 /**
+ * A component that creates a bounding box around an object and provides intersection testing functionality.
+ * 
+ * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
+ * Helper visualization can be enabled with the URL parameter `?gizmos`.
+ * 
  * @category Helpers
  * @group Components
  */
 export class BoxHelperComponent extends Behaviour {
 
+    /** The bounding box for this component */
     private box: Box3 | null = null;
     private static testBox: Box3 = new Box3();
     private _lastMatrixUpdateFrame: number = -1;
@@ -21,6 +27,11 @@ export class BoxHelperComponent extends Behaviour {
     private static _size: Vector3 = new Vector3(.01, .01, .01);
     private static _emptyObjectSize: Vector3 = new Vector3(.01, .01, .01);
 
+    /**
+     * Tests if an object intersects with this helper's bounding box
+     * @param obj The object to test for intersection
+     * @returns True if objects intersect, false if not, undefined if the provided object is invalid
+     */
     public isInBox(obj: Object3D): boolean | undefined {
         if (!obj) return undefined;
 
@@ -44,11 +55,21 @@ export class BoxHelperComponent extends Behaviour {
         return intersects;
     }
 
+    /**
+     * Tests if this helper's bounding box intersects with another box
+     * @param box The {@link Box3} to test for intersection
+     * @returns True if boxes intersect, false otherwise
+     */
     public intersects(box: Box3): boolean {
         if (!box) return false;
         return this.updateBox(false).intersectsBox(box);
     }
 
+    /**
+     * Updates the helper's bounding box based on the gameObject's position and scale
+     * @param force Whether to force an update regardless of frame count
+     * @returns The updated {@link Box3}
+     */
     public updateBox(force: boolean = false): Box3 {
         if (!this.box) {
             this.box = new Box3();
@@ -74,6 +95,11 @@ export class BoxHelperComponent extends Behaviour {
         this.box = null;
     }
 
+    /**
+     * Creates and displays a visual wireframe representation of this box helper
+     * @param col Optional color for the wireframe. If not provided, uses default color
+     * @param force If true, shows the helper even if gizmos are disabled
+     */
     public showHelper(col: ColorRepresentation | null = null, force: boolean = false) {
         if (!gizmos && !force) return;
         if (this._helper) {