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

package/src/engine-components/NeedleMenu.ts

@@ -4,50 +4,68 @@ import { DeviceUtilities } from '../engine/engine_utils.js';
 import { Behaviour } from './Component.js';
 
 /** 
- * Exposes options to customize the built-in Needle Menu.  
+ * Provides configuration options for the built-in Needle Menu.
+ * Needle Menu uses HTML in 2D mode, and automatically switches to a 3D menu in VR/AR mode.
+ * 
+ * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
  * @category User Interface
  * @group Components
  **/
 export class NeedleMenu extends Behaviour {
 
+    /**
+     * Determines the vertical positioning of the menu on the screen
+     */
     @serializable()
     position: "top" | "bottom" = "bottom";
 
-    /** Show the Needle logo in the menu (requires PRO license) */
+    /** 
+     * Controls the visibility of the Needle logo in the menu (requires PRO license)
+     */
     @serializable()
     showNeedleLogo: boolean = true;
 
-    /** When enabled the menu will also be visible in VR/AR when you look up 
+    /** 
+     * When enabled, displays the menu in VR/AR mode when the user looks up
      * @default undefined
-    */
+     */
     @serializable()
     showSpatialMenu?: boolean;
 
-    /** When enabled a button to enter fullscreen will be added to the menu 
+    /** 
+     * When enabled, adds a fullscreen toggle button to the menu
      * @default undefined
-    */
+     */
     @serializable()
     createFullscreenButton?: boolean;
-    /** When enabled a button to mute the application will be added to the menu 
+    
+    /** 
+     * When enabled, adds an audio mute/unmute button to the menu
      * @default undefined
-    */
+     */
     @serializable()
     createMuteButton?: boolean;
 
     /**
-     * When enabled a button to show a QR code will be added to the menu.
+     * When enabled, adds a button to display a QR code for sharing the application.
+     * The QR code is only displayed on desktop devices.
      * @default undefined
      */
     @serializable()
     createQRCodeButton?: boolean;
 
-    /** @hidden */
+    /** 
+     * Applies the configured menu options when the component is enabled
+     * @hidden
+     */
     onEnable() {
         this.applyOptions();
     }
 
-    /** applies the options to `this.context.menu` */
+    /** 
+     * Applies all configured options to the active {@link Context.menu}.
+     */
     applyOptions() {
         this.context.menu.setPosition(this.position);
         this.context.menu.showNeedleLogo(this.showNeedleLogo);

package/src/engine-components/Networking.ts

@@ -7,21 +7,33 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugnet");
 
 /**
- * The networking component is used to provide a websocket url to the networking system. It implements the {@link INetworkingWebsocketUrlProvider} interface. 
+ * Provides configuration to the built-in networking system.
+ * This component supplies websocket URLs for establishing connections.
+ * It implements the {@link INetworkingWebsocketUrlProvider} interface.
+ * 
  * @category Networking
  * @group Components
  */
 export class Networking extends Behaviour implements INetworkingWebsocketUrlProvider {
 
-    /** The url that should be used for the websocket connection */
+    /** 
+     * The websocket URL to connect to for networking functionality.
+     * Can be a complete URL or a relative path that will be resolved against the current origin.
+     */
     @serializable()
     url: string | null = null;
 
-    /** The name of the url parameter that should be used to override the url. When set the url will be overridden by the url parameter e.g. when `urlParameterName=ws` `?ws=ws://localhost:8080` */
+    /** 
+     * Name of the URL parameter that can override the websocket connection URL.
+     * When set, the URL will be overridden by the parameter value from the browser URL.
+     * For example, with `urlParameterName="ws"`, adding `?ws=ws://localhost:8080` to the browser URL will override the connection URL.
+     */
     @serializable()
     urlParameterName: string | null = null;
 
-    /** Thie localhost url that should be used when the networking is running on a local network. This is useful when the server is running on the same machine as the client.
+    /** 
+     * Alternative URL to use when running on a local network.
+     * This is particularly useful for development, when the server is running on the same machine as the client.
      */
     @serializable()
     localhost: string | null = null;
@@ -33,7 +45,13 @@ export class Networking extends Behaviour implements INetworkingWebsocketUrlProv
         this.context.connection.registerProvider(this);
     }
 
-    /** @internal */
+    /** 
+     * Determines the websocket URL to use for networking connections.
+     * Processes the configured URL, applying localhost fallbacks when appropriate and
+     * handling URL parameter overrides if specified.
+     * @returns The formatted websocket URL string or null if no valid URL could be determined
+     * @internal
+     */
     getWebsocketUrl(): string | null {
 
         let socketurl = this.url ? Networking.GetUrl(this.url, this.localhost) : null;
@@ -58,7 +76,13 @@ export class Networking extends Behaviour implements INetworkingWebsocketUrlProv
         return "wss://" + match?.groups["url"];
     }
 
-
+    /**
+     * Processes a URL string applying various transformations based on network environment.
+     * Handles relative paths and localhost fallbacks for local network environments.
+     * @param url The original URL to process
+     * @param localhostFallback Alternative URL to use when on a local network
+     * @returns The processed URL string or null/undefined if input was invalid
+     */
     public static GetUrl(url: string | null | undefined, localhostFallback?: string | null): string | null | undefined {
 
         let result = url;
@@ -78,6 +102,13 @@ export class Networking extends Behaviour implements INetworkingWebsocketUrlProv
         return result;
     }
 
+    /**
+     * Determines if the current connection is on a local network.
+     * Useful for applying different networking configurations in local development environments.
+     * This is the same as calling {@link isLocalNetwork}.
+     * @param hostname Optional hostname to check instead of the current window location
+     * @returns True if the connection is on a local network, false otherwise
+     */
     public static IsLocalNetwork(hostname = window.location.hostname) {
         return isLocalNetwork(hostname);
     }

package/src/engine-components/SceneSwitcher.ts

@@ -857,9 +857,18 @@ function sceneUriToName(uri: string): string {
 
 
 
+/**
+ * PreLoadScheduler is responsible for managing preloading of scenes.
+ * It handles scheduling and limiting concurrent downloads of scenes based on specified parameters.
+ */
 class PreLoadScheduler {
+    /** Maximum number of scenes to preload ahead of the current scene */
     maxLoadAhead: number;
+    
+    /** Maximum number of scenes to preload behind the current scene */
     maxLoadBehind: number;
+    
+    /** Maximum number of scenes that can be preloaded concurrently */
     maxConcurrent: number;
 
     private _isRunning: boolean = false;
@@ -867,6 +876,13 @@ class PreLoadScheduler {
     private _loadTasks: LoadTask[] = [];
     private _maxConcurrentLoads: number = 1;
 
+    /**
+     * Creates a new PreLoadScheduler instance
+     * @param rooms The SceneSwitcher that this scheduler belongs to
+     * @param ahead Number of scenes to preload ahead of current scene
+     * @param behind Number of scenes to preload behind current scene
+     * @param maxConcurrent Maximum number of concurrent preloads allowed
+     */
     constructor(rooms: SceneSwitcher, ahead: number = 1, behind: number = 1, maxConcurrent: number = 2) {
         this._switcher = rooms;
         this.maxLoadAhead = ahead;
@@ -874,6 +890,10 @@ class PreLoadScheduler {
         this.maxConcurrent = maxConcurrent;
     }
 
+    /**
+     * Starts the preloading process after a specified delay
+     * @param delay Time in milliseconds to wait before starting preload
+     */
     begin(delay: number) {
         if (this._isRunning) return;
         if (debug) console.log("Preload begin", { delay })
@@ -919,14 +939,25 @@ class PreLoadScheduler {
         }, 200);
     }
 
+    /**
+     * Stops the preloading process
+     */
     stop() {
         this._isRunning = false;
     }
 
+    /**
+     * Checks if a new scene can be loaded based on current load limits
+     * @returns True if a new scene can be loaded, false otherwise
+     */
     canLoadNewScene(): boolean {
         return this._loadTasks.length < this._maxConcurrentLoads;
     }
 
+    /**
+     * Checks if all scenes in the SceneSwitcher have been loaded
+     * @returns True if all scenes are loaded, false otherwise
+     */
     allLoaded(): boolean {
         if (this._switcher.scenes) {
             for (const scene of this._switcher.scenes) {
@@ -937,12 +968,25 @@ class PreLoadScheduler {
     }
 }
 
+/**
+ * Represents a single preloading task for a scene
+ */
 class LoadTask {
-
+    /** The index of the scene in the scenes array */
     index: number;
+    
+    /** The AssetReference to be loaded */
     asset: AssetReference;
+    
+    /** The collection of active load tasks this task belongs to */
     tasks: LoadTask[];
 
+    /**
+     * Creates a new LoadTask and begins loading immediately
+     * @param index The index of the scene in the scenes array
+     * @param asset The AssetReference to preload
+     * @param tasks The collection of active load tasks
+     */
     constructor(index: number, asset: AssetReference, tasks: LoadTask[]) {
         this.index = index;
         this.asset = asset;
@@ -951,6 +995,9 @@ class LoadTask {
         this.awaitLoading();
     }
 
+    /**
+     * Asynchronously loads the asset and removes this task from the active tasks list when complete
+     */
     private async awaitLoading() {
         if (this.asset && !this.asset.isLoaded()) {
             if (debug)

package/src/engine-components/SpatialTrigger.ts

@@ -8,8 +8,15 @@ import { EventList } from "./EventList.js";
 
 const debug = getParam("debugspatialtrigger");
 
+/** Layer instances used for mask comparison */
 const layer1 = new Layers();
 const layer2 = new Layers();
+/**
+ * Tests if two layer masks intersect
+ * @param mask1 First layer mask
+ * @param mask2 Second layer mask
+ * @returns True if the layers intersect
+ */
 function testMask(mask1, mask2) {
     layer1.mask = mask1;
     layer2.mask = mask2;
@@ -17,25 +24,45 @@ function testMask(mask1, mask2) {
 }
 
 /**
+ * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
+ * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
  * @category Interactivity
  * @group Components
  */
 export class SpatialTriggerReceiver extends Behaviour {
 
-    // currently Layers in unity but maybe this should be a string or plane number? Or should it be a bitmask to allow receivers use multiple triggers?
+    /**
+     * Bitmask determining which triggers this receiver responds to
+     * Only triggers with matching masks will interact with this receiver
+     */
     @serializable()
     triggerMask: number = 0;
+    
+    /** Event invoked when this object enters a trigger zone */
     @serializable(EventList)
     onEnter?: EventList<any>;
+    
+    /** Event invoked continuously while this object is inside a trigger zone */
     @serializable(EventList)
     onStay?: EventList<any>;
+    
+    /** Event invoked when this object exits a trigger zone */
     @serializable(EventList)
     onExit?: EventList<any>;
 
+    /** 
+     * Initializes the receiver and logs debug info if enabled
+     * @internal
+     */
     start() {
         if (debug) console.log(this.name, this.triggerMask, this);
     }
 
+    /**
+     * Checks for intersections with spatial triggers and fires appropriate events
+     * Handles enter, stay, and exit events for all relevant triggers
+     * @internal
+     */
     update(): void {
         this.currentIntersected.length = 0;
         for (const trigger of SpatialTrigger.triggers) {
@@ -59,23 +86,38 @@ export class SpatialTriggerReceiver extends Behaviour {
         }
         this.lastIntersected.length = 0;
         this.lastIntersected.push(...this.currentIntersected);
-
     }
 
+    /** Array of triggers currently intersecting with this receiver */
     readonly currentIntersected: SpatialTrigger[] = [];
+    
+    /** Array of triggers that intersected with this receiver in the previous frame */
     readonly lastIntersected: SpatialTrigger[] = [];
 
+    /**
+     * Handles trigger enter events.
+     * @param trigger The spatial trigger that was entered
+     */
     onEnterTrigger(trigger: SpatialTrigger): void {
         if(debug) console.log("ENTER TRIGGER", this.name, trigger.name, this, trigger);
         trigger.raiseOnEnterEvent(this);
         this.onEnter?.invoke();
     }
+    
+    /**
+     * Handles trigger exit events.
+     * @param trigger The spatial trigger that was exited
+     */
     onExitTrigger(trigger: SpatialTrigger): void {
         if(debug) console.log("EXIT TRIGGER", this.name, trigger.name, );
         trigger.raiseOnExitEvent(this);
         this.onExit?.invoke();
     }
 
+    /**
+     * Handles trigger stay events.
+     * @param trigger The spatial trigger that the receiver is staying in
+     */
     onStayTrigger(trigger: SpatialTrigger): void {
         trigger.raiseOnStayEvent(this);
         this.onStay?.invoke();
@@ -83,24 +125,38 @@ export class SpatialTriggerReceiver extends Behaviour {
 }
 
 /**
- * A trigger that can be used to detect if an object is inside a box.
+ * A spatial trigger component that detects objects within a box-shaped area.
+ * Used to trigger events when objects enter, stay in, or exit the defined area
  * @category Interactivity
  * @group Components
  */
 export class SpatialTrigger extends Behaviour {
 
+    /** Global registry of all active spatial triggers in the scene */
     static triggers: SpatialTrigger[] = [];
 
+    /** 
+     * Bitmask determining which receivers this trigger affects.
+     * Only receivers with matching masks will be triggered.
+     */
+    // currently Layers in unity but maybe this should be a string or plane number? Or should it be a bitmask to allow receivers use multiple triggers?
     @serializable()
     triggerMask?: number;
 
+    /** Box helper component used to visualize and calculate the trigger area */
     private boxHelper?: BoxHelperComponent;
 
+    /**
+     * Initializes the trigger and logs debug info if enabled
+     */
     start() {
         if (debug)
             console.log(this.name, this.triggerMask, this);
     }
 
+    /**
+     * Registers this trigger in the global registry and sets up debug visualization if enabled
+     */
     onEnable(): void {
         SpatialTrigger.triggers.push(this);
         if (!this.boxHelper) {
@@ -108,10 +164,19 @@ export class SpatialTrigger extends Behaviour {
             this.boxHelper?.showHelper(null, debug as boolean);
         }
     }
+    
+    /**
+     * Removes this trigger from the global registry when disabled
+     */
     onDisable(): void {
         SpatialTrigger.triggers.splice(SpatialTrigger.triggers.indexOf(this), 1);
     }
 
+    /**
+     * Tests if an object is inside this trigger's box
+     * @param obj The object to test against this trigger
+     * @returns True if the object is inside the trigger box
+     */
     test(obj: Object3D): boolean {
         if (!this.boxHelper) return false;
         return this.boxHelper.isInBox(obj) ?? false;
@@ -119,6 +184,10 @@ export class SpatialTrigger extends Behaviour {
 
     // private args: SpatialTriggerEventArgs = new SpatialTriggerEventArgs();
 
+    /**
+     * Raises the onEnter event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+     * @param rec The receiver that entered this trigger
+     */
     raiseOnEnterEvent(rec: SpatialTriggerReceiver) {
         // this.args.trigger = this;
         // this.args.source = rec;
@@ -130,6 +199,10 @@ export class SpatialTrigger extends Behaviour {
         }, false);
     }
 
+    /**
+     * Raises the onStay event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+     * @param rec The receiver that is staying in this trigger
+     */
     raiseOnStayEvent(rec: SpatialTriggerReceiver) {
         // this.args.trigger = this;
         // this.args.source = rec;
@@ -141,6 +214,10 @@ export class SpatialTrigger extends Behaviour {
         }, false);
     }
 
+    /**
+     * Raises the onExit event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+     * @param rec The receiver that exited this trigger
+     */
     raiseOnExitEvent(rec: SpatialTriggerReceiver) {
         GameObject.foreachComponent(this.gameObject, c => {
             if (c === rec) return;