@needle-tools/engine 4.2.5 → 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

@@ -46,6 +46,10 @@ export type LoadSceneEvent = {
     index: number;
 }
 
+export type LoadSceneProgressEvent = LoadSceneEvent & {
+    progress: number,
+}
+
 /** 
  * The ISceneEventListener is called by the {@link SceneSwitcher} when a scene is loaded or unloaded.   
  * It must be added to the root object of your scene (that is being loaded) or on the same object as the SceneSwitcher  
@@ -225,6 +229,15 @@ export class SceneSwitcher extends Behaviour {
      */
     get currentlyLoadedScene() { return this._currentScene; }
 
+    /**
+     * Called when a scene starts loading
+     */
+    @serializable(EventList)
+    sceneLoadingStart: EventList<LoadSceneEvent> = new EventList();
+
+    @serializable(EventList)
+    sceneLoadingProgress: EventList<ProgressEvent> = new EventList();
+
     /**
      * The sceneLoaded event is called when a scene/glTF is loaded and added to the scene
      */
@@ -281,7 +294,7 @@ export class SceneSwitcher extends Behaviour {
         this._preloadScheduler.maxLoadAhead = this.preloadNext;
         this._preloadScheduler.maxLoadBehind = this.preloadPrevious;
         this._preloadScheduler.maxConcurrent = this.preloadConcurrent;
-        this._preloadScheduler.begin();
+        this._preloadScheduler.begin(2000);
 
         // Begin loading the loading scene
         if (this.autoLoadFirstScene && this._currentIndex === -1 && !await this.tryLoadFromQueryParam()) {
@@ -602,11 +615,13 @@ export class SceneSwitcher extends Behaviour {
 
             const loadStartEvt = new CustomEvent<LoadSceneEvent>("loadscene-start", { detail: { scene: scene, switcher: this, index: index } })
             this.dispatchEvent(loadStartEvt);
+            this.sceneLoadingStart?.invoke(loadStartEvt.detail);
             await this.onStartLoading();
             // start loading and wait for the scene to be loaded
             await scene.loadAssetAsync((_, prog) => {
                 this._currentLoadingProgress = prog;
                 this.dispatchEvent(prog);
+                this.sceneLoadingProgress?.invoke(prog);
             }).catch(console.error);
             await this.onEndLoading();
             const finishedEvt = new CustomEvent<LoadSceneEvent>("loadscene-finished", { detail: { scene: scene, switcher: this, index: index } });
@@ -842,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;
@@ -852,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;
@@ -859,26 +890,34 @@ class PreLoadScheduler {
         this.maxConcurrent = maxConcurrent;
     }
 
-    begin() {
+    /**
+     * 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")
+        if (debug) console.log("Preload begin", { delay })
         this._isRunning = true;
-        let lastRoom: number = -1;
+        let lastRoom: number = -10;
         let searchDistance: number;
         let searchCall: number;
         const array = this._switcher.scenes;
+        const startTime = Date.now() + delay;
         const interval = setInterval(() => {
             if (this.allLoaded()) {
                 if (debug)
-                    console.log("All scenes loaded");
+                    console.log("All scenes (pre-)loaded");
                 this.stop();
             }
             if (!this._isRunning) {
                 clearInterval(interval);
                 return;
             }
+
+            if (Date.now() < startTime) return;
+
             if (this.canLoadNewScene() === false) return;
-            if (lastRoom !== this._switcher.currentIndex) {
+            if (lastRoom === -10 || lastRoom !== this._switcher.currentIndex) {
                 lastRoom = this._switcher.currentIndex;
                 searchCall = 0;
                 searchDistance = 0;
@@ -892,19 +931,33 @@ class PreLoadScheduler {
             if (roomIndex < 0) return;
             // if (roomIndex < 0) roomIndex = array.length + roomIndex;
             if (roomIndex < 0 || roomIndex >= array.length) return;
-            const scene = array[roomIndex];
-            new LoadTask(roomIndex, scene, this._loadTasks);
+            if (!this._loadTasks.some(t => t.index === roomIndex)) {
+                const scene = array[roomIndex];
+                if (debug) console.log("Preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
+                new LoadTask(roomIndex, scene, this._loadTasks);
+            }
         }, 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) {
@@ -915,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;
@@ -929,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;