@needle-tools/engine 4.7.1 → 4.7.2-alpha

package/src/engine-components/LookAtConstraint.ts

@@ -1,26 +1,26 @@
-import { Object3D } from "three";
-
-import { serializable } from "../engine/engine_serialization_decorator.js";
-import { Behaviour } from "./Component.js";
-
-/**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
- */
-export class LookAtConstraint extends Behaviour {
-
-    /**
-     * When true the constraint is active.
-     */
-    @serializable()
-    constraintActive: boolean = true;
-    /**
-     * When true the look at is locked to the position of the assigned sources.
-     */
-    @serializable()
-    locked: boolean = false;
-    /**
-     * The sources to look at.
-     */
-    @serializable(Object3D)
-    sources: Object3D[] = [];
+import { Object3D } from "three";
+
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { Behaviour } from "./Component.js";
+
+/**
+ * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
+ */
+export class LookAtConstraint extends Behaviour {
+
+    /**
+     * When true the constraint is active.
+     */
+    @serializable()
+    constraintActive: boolean = true;
+    /**
+     * When true the look at is locked to the position of the assigned sources.
+     */
+    @serializable()
+    locked: boolean = false;
+    /**
+     * The sources to look at.
+     */
+    @serializable(Object3D)
+    sources: Object3D[] = [];
 }

package/src/engine-components/NeedleMenu.ts

@@ -1,85 +1,85 @@
-import type { Context } from '../engine/engine_context.js';
-import { serializable } from '../engine/engine_serialization.js';
-import { DeviceUtilities } from '../engine/engine_utils.js';
-import { Behaviour } from './Component.js';
-
-/** 
- * 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";
-
-    /** 
-     * Controls the visibility of the Needle logo in the menu (requires PRO license)
-     */
-    @serializable()
-    showNeedleLogo: boolean = false;
-
-    /** 
-     * When enabled, displays the menu in VR/AR mode when the user looks up
-     * @default undefined
-     */
-    @serializable()
-    showSpatialMenu?: boolean;
-
-    /** 
-     * When enabled, adds a fullscreen toggle button to the menu
-     * @default undefined
-     */
-    @serializable()
-    createFullscreenButton?: boolean;
-    
-    /** 
-     * When enabled, adds an audio mute/unmute button to the menu
-     * @default undefined
-     */
-    @serializable()
-    createMuteButton?: boolean;
-
-    /**
-     * 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;
-
-    /** 
-     * Applies the configured menu options when the component is enabled
-     * @hidden
-     */
-    onEnable() {
-        this.applyOptions();
-    }
-
-    /** 
-     * Applies all configured options to the active {@link Context.menu}.
-     */
-    applyOptions() {
-        this.context.menu.setPosition(this.position);
-        this.context.menu.showNeedleLogo(this.showNeedleLogo);
-        if (this.createFullscreenButton === true)
-            this.context.menu.showFullscreenOption(true);
-        if (this.createMuteButton === true)
-            this.context.menu.showAudioPlaybackOption(true);
-        if (this.showSpatialMenu === true)
-            this.context.menu.showSpatialMenu(this.showSpatialMenu);
-        if (this.createQRCodeButton === true) {
-            if (!DeviceUtilities.isMobileDevice()) {
-                this.context.menu.showQRCodeButton(true);
-            }
-        }
-    }
-
+import type { Context } from '../engine/engine_context.js';
+import { serializable } from '../engine/engine_serialization.js';
+import { DeviceUtilities } from '../engine/engine_utils.js';
+import { Behaviour } from './Component.js';
+
+/** 
+ * 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";
+
+    /** 
+     * Controls the visibility of the Needle logo in the menu (requires PRO license)
+     */
+    @serializable()
+    showNeedleLogo: boolean = false;
+
+    /** 
+     * When enabled, displays the menu in VR/AR mode when the user looks up
+     * @default undefined
+     */
+    @serializable()
+    showSpatialMenu?: boolean;
+
+    /** 
+     * When enabled, adds a fullscreen toggle button to the menu
+     * @default undefined
+     */
+    @serializable()
+    createFullscreenButton?: boolean;
+    
+    /** 
+     * When enabled, adds an audio mute/unmute button to the menu
+     * @default undefined
+     */
+    @serializable()
+    createMuteButton?: boolean;
+
+    /**
+     * 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;
+
+    /** 
+     * Applies the configured menu options when the component is enabled
+     * @hidden
+     */
+    onEnable() {
+        this.applyOptions();
+    }
+
+    /** 
+     * Applies all configured options to the active {@link Context.menu}.
+     */
+    applyOptions() {
+        this.context.menu.setPosition(this.position);
+        this.context.menu.showNeedleLogo(this.showNeedleLogo);
+        if (this.createFullscreenButton === true)
+            this.context.menu.showFullscreenOption(true);
+        if (this.createMuteButton === true)
+            this.context.menu.showAudioPlaybackOption(true);
+        if (this.showSpatialMenu === true)
+            this.context.menu.showSpatialMenu(this.showSpatialMenu);
+        if (this.createQRCodeButton === true) {
+            if (!DeviceUtilities.isMobileDevice()) {
+                this.context.menu.showQRCodeButton(true);
+            }
+        }
+    }
+
 }

package/src/engine-components/NestedGltf.ts

@@ -1,87 +1,87 @@
-import { AssetReference, type ProgressCallback } from "../engine/engine_addressables.js";
-import { InstantiateOptions } from "../engine/engine_gameobject.js";
-import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
-import { serializable } from "../engine/engine_serialization_decorator.js";
-import { getParam } from "../engine/engine_utils.js";
-import { Behaviour } from "../engine-components/Component.js";
-
-const debug = getParam("debugnestedgltf");
-
-/** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
- * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
- */
-export class NestedGltf extends Behaviour {
-    /**
-     * A reference to the gltf file that should be loaded
-     */
-    @serializable(AssetReference)
-    filePath?: AssetReference;
-
-    /**
-     * EXPERIMENTAL for cloud asset loading
-     */
-    loadAssetInParent = true;
-
-    private _isLoadingOrDoneLoading: boolean = false;
-
-    /** Register a callback that will be called when the progress of the loading changes */
-    listenToProgress(evt: ProgressCallback) {
-        this.filePath?.beginListenDownload(evt)
-    }
-
-    /** Begin loading the referenced gltf file in filePath */
-    preload() {
-        this.filePath?.preload();
-    }
-
-    /** @internal */
-    async start() {
-        if (this._isLoadingOrDoneLoading) return;
-        if (debug) console.log(this, this.guid);
-
-        const parent = this.gameObject.parent;
-        if (parent) {
-            this._isLoadingOrDoneLoading = true;
-            const opts = new InstantiateOptions();
-            // we need to provide stable guids for creating nested gltfs
-            opts.idProvider = new InstantiateIdProvider(this.hash(this.guid));
-            opts.parent = this.loadAssetInParent !== false ? parent : this.gameObject;
-            this.gameObject.updateMatrix();
-            const matrix = this.gameObject.matrix;
-            if (debug) console.log("Load nested:", this.filePath?.url ?? this.filePath, this.gameObject.position);
-            const res = await this.filePath?.instantiate?.call(this.filePath, opts);
-            if (debug) console.log("Nested loaded:", this.filePath?.url ?? this.filePath, res);
-            if (res && this.loadAssetInParent !== false) {
-                res.matrixAutoUpdate = false;
-                res.matrix.identity();
-                res.applyMatrix4(matrix);
-                res.matrixAutoUpdate = true;
-                res.layers.disableAll();
-                res.layers.set(this.layer);
-
-                this.dispatchEvent(new CustomEvent("loaded", { detail: { instance: res, assetReference: this.filePath } }));
-            }
-            if (debug) console.log("Nested loading done:", this.filePath?.url ?? this.filePath, res);
-        }
-    }
-
-    /** @internal */
-    onDestroy(): void {
-        // When the NestedGLTF gets destroyed we assume the loaded glTF is also destroyed
-        // meaning the resources, textures etc are disposed
-        // When this NestedGLTF would now be loaded again the AssetReference would still be in the loaded state
-        // so it would instantiate without textures etc...
-        // Perhaps we want to add a dispose callback or event method too?
-        // Somehow we have to clean the AssetReference state
-        this.filePath?.unload();
-    }
-
-
-    private hash(str: string): number {
-        let hash = 0;
-        for (let i = 0; i < str.length; i++) {
-            hash = str.charCodeAt(i) + ((hash << 5) - hash);
-        }
-        return hash;
-    }
+import { AssetReference, type ProgressCallback } from "../engine/engine_addressables.js";
+import { InstantiateOptions } from "../engine/engine_gameobject.js";
+import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { getParam } from "../engine/engine_utils.js";
+import { Behaviour } from "../engine-components/Component.js";
+
+const debug = getParam("debugnestedgltf");
+
+/** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
+ * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+ */
+export class NestedGltf extends Behaviour {
+    /**
+     * A reference to the gltf file that should be loaded
+     */
+    @serializable(AssetReference)
+    filePath?: AssetReference;
+
+    /**
+     * EXPERIMENTAL for cloud asset loading
+     */
+    loadAssetInParent = true;
+
+    private _isLoadingOrDoneLoading: boolean = false;
+
+    /** Register a callback that will be called when the progress of the loading changes */
+    listenToProgress(evt: ProgressCallback) {
+        this.filePath?.beginListenDownload(evt)
+    }
+
+    /** Begin loading the referenced gltf file in filePath */
+    preload() {
+        this.filePath?.preload();
+    }
+
+    /** @internal */
+    async start() {
+        if (this._isLoadingOrDoneLoading) return;
+        if (debug) console.log(this, this.guid);
+
+        const parent = this.gameObject.parent;
+        if (parent) {
+            this._isLoadingOrDoneLoading = true;
+            const opts = new InstantiateOptions();
+            // we need to provide stable guids for creating nested gltfs
+            opts.idProvider = new InstantiateIdProvider(this.hash(this.guid));
+            opts.parent = this.loadAssetInParent !== false ? parent : this.gameObject;
+            this.gameObject.updateMatrix();
+            const matrix = this.gameObject.matrix;
+            if (debug) console.log("Load nested:", this.filePath?.url ?? this.filePath, this.gameObject.position);
+            const res = await this.filePath?.instantiate?.call(this.filePath, opts);
+            if (debug) console.log("Nested loaded:", this.filePath?.url ?? this.filePath, res);
+            if (res && this.loadAssetInParent !== false) {
+                res.matrixAutoUpdate = false;
+                res.matrix.identity();
+                res.applyMatrix4(matrix);
+                res.matrixAutoUpdate = true;
+                res.layers.disableAll();
+                res.layers.set(this.layer);
+
+                this.dispatchEvent(new CustomEvent("loaded", { detail: { instance: res, assetReference: this.filePath } }));
+            }
+            if (debug) console.log("Nested loading done:", this.filePath?.url ?? this.filePath, res);
+        }
+    }
+
+    /** @internal */
+    onDestroy(): void {
+        // When the NestedGLTF gets destroyed we assume the loaded glTF is also destroyed
+        // meaning the resources, textures etc are disposed
+        // When this NestedGLTF would now be loaded again the AssetReference would still be in the loaded state
+        // so it would instantiate without textures etc...
+        // Perhaps we want to add a dispose callback or event method too?
+        // Somehow we have to clean the AssetReference state
+        this.filePath?.unload();
+    }
+
+
+    private hash(str: string): number {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            hash = str.charCodeAt(i) + ((hash << 5) - hash);
+        }
+        return hash;
+    }
 }

package/src/engine-components/Networking.ts

@@ -1,115 +1,115 @@
-import type { INetworkingWebsocketUrlProvider } from "../engine/engine_networking.js";
-import { isLocalNetwork } from "../engine/engine_networking_utils.js";
-import { serializable } from "../engine/engine_serialization.js";
-import { getParam } from "../engine/engine_utils.js";
-import { Behaviour } from "./Component.js";
-
-const debug = getParam("debugnet");
-
-/**
- * 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 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;
-
-    /** 
-     * 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;
-
-    /** 
-     * 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;
-
-    /** @internal */
-    awake() {
-        if (debug)
-            console.log(this);
-        this.context.connection.registerProvider(this);
-    }
-
-    /** 
-     * 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;
-
-        if (this.urlParameterName) {
-            const res = getParam(this.urlParameterName);
-            if (res && typeof res === "string") {
-                socketurl = res;
-            }
-        }
-
-        if (!socketurl) return null;
-
-        // regex https://regex101.com/r/JQ5WqB/1
-        const regex = new RegExp("(((https?)|(?<socket_prefix>wss?)):\/\/)?(www\.)?(?<url>.+)", "gm");
-        const match = regex.exec(socketurl);
-        if (!match?.groups) return null;
-        // if the url has a ws or wss prefix already assume the whole url is in the correct format
-        const socketPrefix = match?.groups["socket_prefix"];
-        if (socketPrefix) return socketurl;
-        // otherwise add the ws prefix
-        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;
-
-        const useLocalHostUrl = Networking.IsLocalNetwork() && localhostFallback;
-        if (useLocalHostUrl) {
-            result = localhostFallback;
-        }
-
-        if (url?.startsWith("/")) {
-            const base = useLocalHostUrl ? result : window.location.origin;
-            if(base?.endsWith("/") && url.startsWith("/"))
-                url = url.substring(1);
-            result = base + url;
-        }
-
-        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);
-    }
+import type { INetworkingWebsocketUrlProvider } from "../engine/engine_networking.js";
+import { isLocalNetwork } from "../engine/engine_networking_utils.js";
+import { serializable } from "../engine/engine_serialization.js";
+import { getParam } from "../engine/engine_utils.js";
+import { Behaviour } from "./Component.js";
+
+const debug = getParam("debugnet");
+
+/**
+ * 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 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;
+
+    /** 
+     * 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;
+
+    /** 
+     * 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;
+
+    /** @internal */
+    awake() {
+        if (debug)
+            console.log(this);
+        this.context.connection.registerProvider(this);
+    }
+
+    /** 
+     * 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;
+
+        if (this.urlParameterName) {
+            const res = getParam(this.urlParameterName);
+            if (res && typeof res === "string") {
+                socketurl = res;
+            }
+        }
+
+        if (!socketurl) return null;
+
+        // regex https://regex101.com/r/JQ5WqB/1
+        const regex = new RegExp("(((https?)|(?<socket_prefix>wss?)):\/\/)?(www\.)?(?<url>.+)", "gm");
+        const match = regex.exec(socketurl);
+        if (!match?.groups) return null;
+        // if the url has a ws or wss prefix already assume the whole url is in the correct format
+        const socketPrefix = match?.groups["socket_prefix"];
+        if (socketPrefix) return socketurl;
+        // otherwise add the ws prefix
+        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;
+
+        const useLocalHostUrl = Networking.IsLocalNetwork() && localhostFallback;
+        if (useLocalHostUrl) {
+            result = localhostFallback;
+        }
+
+        if (url?.startsWith("/")) {
+            const base = useLocalHostUrl ? result : window.location.origin;
+            if(base?.endsWith("/") && url.startsWith("/"))
+                url = url.substring(1);
+            result = base + url;
+        }
+
+        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);
+    }
 }