@needle-tools/engine 4.15.0-next.cecd8e7 → 4.15.0-next.f391a30

package/src/engine/engine_utils.ts

@@ -607,7 +607,7 @@ export namespace DeviceUtilities {
     /** @returns `true` if it's a phone or tablet */
     export function isMobileDevice() {
         if (_ismobile !== undefined) return _ismobile;
-        // eslint-disable-next-line deprecation/deprecation
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         if ((typeof window.orientation !== "undefined") || (navigator.userAgent.indexOf('IEMobile') !== -1)) {
             return _ismobile = true;
         }
@@ -677,7 +677,7 @@ export namespace DeviceUtilities {
     /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
     export function isiOS() {
         if (__isiOS !== undefined) return __isiOS;
-        // eslint-disable-next-line deprecation/deprecation
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         return __isiOS = iosDevices.includes(navigator.platform)
             // iPad on iOS 13 detection
             || (navigator.userAgent.includes("Mac") && "ontouchend" in document)

package/src/engine/export/gltf/index.ts

@@ -1,12 +1,12 @@
 import { AnimationClip, Object3D } from "three";
 import { GLTFExporter, GLTFExporterOptions } from "three/examples/jsm/exporters/GLTFExporter.js";
 
-import GLTFMeshGPUInstancingExtension from "../../../include/three/EXT_mesh_gpu_instancing_exporter.js";
 import { AnimationUtils } from "../../engine_animation.js";
 import type { Context } from "../../engine_setup.js";
 import { registerExportExtensions } from "../../extensions/index.js";
 import { __isExporting } from "../state.js";
 import { shouldExport_HideFlags } from "../utils.js";
+import GLTFMeshGPUInstancingExtension from "./EXT_mesh_gpu_instancing_exporter.js";
 import { GizmoWriter as GLTFGizmoWriter, RenderTextureWriter as GLTFRenderTextureWriter } from "./Writers.js";
 
 declare type ExportOptions = {

package/src/engine/webcomponents/logo-element.ts

@@ -20,8 +20,13 @@ export class NeedleLogoElement extends HTMLElement {
         return document.createElement(elementName) as NeedleLogoElement;
     }
 
+    private _didInitialize = false;
+
     constructor() {
         super();
+    }
+
+    private initializeDom() {
         this._root = this.attachShadow({ mode: 'closed' });
         const template = document.createElement('template');
         template.innerHTML = `<style>
@@ -83,25 +88,37 @@ export class NeedleLogoElement extends HTMLElement {
         this.addEventListener("click", () => {
             globalThis.open("https://needle.tools", "_blank");
         });
+    }
 
+    ensureInitialized() {
+        if (!this._didInitialize) {
+            this._didInitialize = true;
+            this.initializeDom();
+        }
     }
 
     connectedCallback() {
+        this.ensureInitialized();
+        if (!this.wrapper) return;
         this.wrapper.setAttribute("title", "Made with Needle Engine");
         this.setAttribute("aria-label", "Needle Engine logo. Click to open the Needle Engine website.");
     }
 
-    private readonly _root: ShadowRoot;
-    private readonly wrapper: HTMLDivElement;
-    private readonly logoElement: HTMLImageElement;
+    private _root!: ShadowRoot;
+    private wrapper!: HTMLDivElement;
+    private logoElement!: HTMLImageElement;
 
     /** Show or hide the logo element (used by the menu) */
     setLogoVisible(val: boolean) {
+        this.ensureInitialized();
+        if (!this.logoElement) return;
         this.logoElement.style.display = val ? "block" : "none";
     }
 
     /** Switch the logo between full and compact versions */
     setType(type: "full" | "compact") {
+        this.ensureInitialized();
+        if (!this.logoElement) return;
         if (type === "full") {
             this.logoElement.src = needleLogoSVG;
             this.logoElement.classList.remove("with-text");

package/src/engine/webcomponents/needle menu/needle-menu-spatial.ts

@@ -302,7 +302,7 @@ export class NeedleSpatialMenu {
             // logoObject.position.y = 1;
             // this._context.scene.add(logoObject);
             const textureLoader = new TextureLoader();
-            textureLoader.load("./include/needle/poweredbyneedle.webp", (texture) => {
+            textureLoader.load("https://cdn.needle.tools/static/branding/poweredbyneedle.webp", (texture) => {
                 if (texture) {
                     onClick.allowModifyUI = false;
                     firstLabel.removeFromParent();
@@ -343,7 +343,11 @@ export class NeedleSpatialMenu {
 
         if (!fontFamily) {
             fontFamily = ThreeMeshUI.FontLibrary.addFontFamily(this.familyName);
-            const normal = fontFamily.addVariant("normal", "normal", "./include/needle/arial-msdf.json", "./include/needle/arial.png") as any as ThreeMeshUI.FontVariant;
+            const normal = fontFamily.addVariant(
+                "normal", 
+                "normal", 
+                "https://cdn.needle.tools/static/fonts/msdf/arial/arial-msdf.json", 
+                "https://cdn.needle.tools/static/fonts/msdf/arial/arial.png") as any as ThreeMeshUI.FontVariant;
             /** @ts-ignore */
             normal?.addEventListener('ready', () => {
                 this.markDirty();

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -129,6 +129,7 @@ export class NeedleMenu {
 
     constructor(context: Context) {
         this._menu = NeedleMenuElement.getOrCreate(context.domElement, context);
+        this._menu.ensureInitialized();
         this._context = context;
         this._spatialMenu = new NeedleSpatialMenu(context, this._menu);
         window.addEventListener("message", this.onPostMessage);
@@ -309,8 +310,7 @@ export class NeedleMenu {
 export class NeedleMenuElement extends HTMLElement {
 
     static create() {
-        // https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#is
-        return document.createElement(elementName, { is: elementName });
+        return document.createElement(elementName);
     }
 
     static getOrCreate(domElement: HTMLElement, context: Context) {
@@ -337,9 +337,13 @@ export class NeedleMenuElement extends HTMLElement {
 
     private _domElement: HTMLElement | null = null;
     private _context: Context | null = null;
+    private _didInitialize = false;
 
     constructor() {
         super();
+    }
+
+    private initializeDom() {
 
         const template = document.createElement('template');
         // TODO: make host full size again and move the buttons to a wrapper so that we can later easily open e.g. foldouts/dropdowns / use the whole canvas space
@@ -795,7 +799,7 @@ export class NeedleMenuElement extends HTMLElement {
 
 
         let context = this._context;
-        // we need to assign it in the timeout because the reference is set *after* the constructor did run
+        // we need to assign it in the timeout because the reference is set *after* the element is initialized
         setTimeout(() => context = this._context);
 
         // watch changes
@@ -864,13 +868,21 @@ export class NeedleMenuElement extends HTMLElement {
         }
     }
 
+    ensureInitialized() {
+        if (!this._didInitialize) {
+            this._didInitialize = true;
+            this.initializeDom();
+        }
+    }
+
     private _sizeChangeInterval;
 
     connectedCallback() {
+        this.ensureInitialized();
         window.addEventListener("resize", this.handleSizeChange);
         this.handleMenuVisible();
         this._sizeChangeInterval = setInterval(() => this.handleSizeChange(undefined, false), 5000);
-        // the dom element is set after the constructor runs
+        // the dom element is set after initialization runs
         setTimeout(() => {
             this._domElement?.addEventListener("resize", this.handleSizeChange);
             this._domElement?.addEventListener("click", this.#onClick);
@@ -958,19 +970,19 @@ export class NeedleMenuElement extends HTMLElement {
 
     // private _root: ShadowRoot | null = null;
     /** @private root container element inside shadow DOM */
-    private readonly root: HTMLDivElement;
+    private root!: HTMLDivElement;
     /** @private wraps the whole content (internal layout) */
-    private readonly wrapper: HTMLDivElement;
+    private wrapper!: HTMLDivElement;
     /** @private contains the buttons and dynamic elements */
-    private readonly options: HTMLDivElement;
+    private options!: HTMLDivElement;
     /** @private contains options visible when in compact mode */
-    private readonly optionsCompactMode: HTMLDivElement;
+    private optionsCompactMode!: HTMLDivElement;
     /** @private contains the needle-logo html element */
-    private readonly logoContainer: HTMLDivElement;
+    private logoContainer!: HTMLDivElement;
     /** @private compact menu button element */
-    private readonly compactMenuButton: HTMLButtonElement;
+    private compactMenuButton!: HTMLButtonElement;
     /** @private foldout container used in compact mode */
-    private readonly foldout: HTMLDivElement;
+    private foldout!: HTMLDivElement;
 
 
     private readonly trackedElements: WeakSet<Node> = new WeakSet();

package/src/engine/webcomponents/needle-engine.ar-overlay.ts

@@ -121,7 +121,7 @@ export class AROverlayHandler {
 
         const quitARSlot = document.createElement("slot");
         quitARSlot.style.display = "contents";
-        quitARSlot.style.padding = "10px"; 
+        quitARSlot.style.padding = "10px";
         quitARSlot.setAttribute("name", "quit-ar");
         this.appendElement(quitARSlot, element);
         this._createdAROnlyElements.push(quitARSlot);
@@ -131,7 +131,16 @@ export class AROverlayHandler {
         // No default quit button in the top right corner in app clips
         // we provide one via the native UI
         if (DeviceUtilities.isNeedleAppClip()) {
-            quitARSlot.style.display = "none";
+
+            // quitARSlot.style.display = "none";
+            globalThis["NEEDLE_ENGINE_APPCLIP_DISABLE_MENU"] = true;
+
+            // respect the UI bar at the top of the screen and add some padding to the quit button container
+            // @TODO: this should be done in CSS in one place and not here and in debug overlay
+            const meta = document.querySelector('meta[name="viewport"]');
+            if (meta && !meta.getAttribute("content")?.includes("viewport-fit=")) {
+                meta.setAttribute("content", meta.getAttribute("content") + ",viewport-fit=cover");
+            }
         }
 
         // We want to search the document if there's a quit-ar button
@@ -155,6 +164,8 @@ export class AROverlayHandler {
             right: 0;
             z-index: 600;
             pointer-events: all;
+            padding-top: env(safe-area-inset-top, 0px);
+            padding-right: calc(env(safe-area-inset-right, 0px) + 10px);
         `;
         this.appendElement(fixedButtonContainer, quitARSlot);
 

package/src/engine/webcomponents/needle-engine.ts

@@ -168,19 +168,30 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      */
     public get context() { return this._context; }
 
-    private _context: Context;
+    private _context!: Context;
     private _overlay_ar: AROverlayHandler;
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
     private _previousSrc: string | null | string[] = null;
     /** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
     private _didFullyLoad: boolean = false;
+    private _didInitialize = false;
 
     constructor() {
         super();
         this._overlay_ar = new AROverlayHandler();
         // TODO: do we want to rename this event?
         this.addEventListener("ready", this.onReady);
+    }
+
+    private ensureInitialized() {
+        if (!this._didInitialize) {
+            this._didInitialize = true;
+            this.initializeDom();
+        }
+    }
+
+    private initializeDom() {
 
         ensureFonts();
 
@@ -281,6 +292,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * @internal
      */
     async connectedCallback() {
+        this.ensureInitialized();
         if (debug) {
             console.log("<needle-engine> connected");
         }

package/src/engine-components/Component.ts

@@ -49,7 +49,7 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     abstract activeSelf: boolean;
 
     /** @deprecated Use {@link addComponent} instead */
-    // eslint-disable-next-line deprecation/deprecation
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     abstract addNewComponent<T extends IComponent>(type: ConstructorConcrete<T>, init?: ComponentInit<T>): T;
 
     /** 
@@ -364,7 +364,6 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 
     /** @deprecated use `addComponent` */
-    // eslint-disable-next-line deprecation/deprecation
     public static addNewComponent<T extends IComponent>(go: IGameObject | Object3D, type: T | ConstructorConcrete<T>, init?: ComponentInit<T>, callAwake: boolean = true): T {
         return addComponent(go, type, init, { callAwake });
     }

package/src/engine-components/ReflectionProbe.ts

@@ -1,11 +1,9 @@
-import { Color, CubeReflectionMapping, CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, MeshBasicMaterial, MeshStandardMaterial, Object3D, SRGBColorSpace, Texture, Vector3 } from "three";
+import { CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, Object3D, Texture, Vector3 } from "three";
 
-import { isDevEnvironment, showBalloonWarning } from "../engine/debug/index.js";
 import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
-import type { IRenderer } from "../engine/engine_types.js";
 import { getParam, resolveUrl } from "../engine/engine_utils.js";
 import { BoxHelperComponent } from "./BoxHelperComponent.js";
 import { Behaviour } from "./Component.js";
@@ -42,7 +40,11 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 export class ReflectionProbe extends Behaviour {
 
     private static _probes: Map<Context, ReflectionProbe[]> = new Map();
-
+    
+    
+    /**
+     * Checks if the given material is currently using a reflection probe. This is determined by checking for an override on the material's "envMap" property, which is set by the Renderer component when applying a reflection probe.
+     */
     static isUsingReflectionProbe(material: Material) {
         return !!(material as any)[$reflectionProbeKey];
     }
@@ -50,8 +52,13 @@ export class ReflectionProbe extends Behaviour {
 
     /**
      * Event invoked when a reflection probe is enabled. Used internally by Renderer components to update probes when they become active. Not recommended to call this directly in most cases.
+     * @see {@link onDisabled} for the corresponding disable event.
      */
     static readonly onEnabled: EventList<ReflectionProbe> = new EventList();
+    /**
+     * Event invoked when a reflection probe is disabled. Used internally by Renderer components to update probes when they become inactive. Not recommended to call this directly in most cases.
+     * @see {@link onEnabled} for the corresponding enable event.
+     */
     static readonly onDisabled: EventList<ReflectionProbe> = new EventList();
 
     /**
@@ -90,11 +97,14 @@ export class ReflectionProbe extends Behaviour {
         return null;
     }
 
-    private _texture!: Texture;
+    private _texture!: Texture | null;
     private _textureUrlInFlight?: string;
 
+    /**
+     * The cubemap or HDR texture used for reflections. Can be assigned directly or via a URL string. When assigning via URL, the texture will be loaded asynchronously and applied once ready.
+     */
     @serializable([Texture, String])
-    set texture(tex: Texture) {
+    set texture(tex: Texture | null) {
         if (this._texture === tex) return;
 
         if (typeof tex === "string") {
@@ -111,7 +121,10 @@ export class ReflectionProbe extends Behaviour {
             return;
         }
 
-        this._textureUrlInFlight = undefined;
+        // During deserialization / loading of the GLB the deserializer sets an empty DataTexture 
+        // But if the texture is serialized as a string (via Blender Reflection Probes) then the async loading above
+        // Will abort IF textureInFlight is reset (here). That's why we do NOT reset textureInFlight during initialization (when __didAwake is false). Only after awake, when we are sure that the async loading is done, we reset the in-flight URL to allow new assignments.
+        if(this.__didAwake) this._textureUrlInFlight = undefined;
 
         this._texture = tex;
 
@@ -127,7 +140,7 @@ export class ReflectionProbe extends Behaviour {
             tex.needsUpdate = true;
         }
     }
-    get texture(): Texture {
+    get texture(): Texture | null {
         return this._texture;
     }
 
@@ -165,6 +178,7 @@ export class ReflectionProbe extends Behaviour {
         ReflectionProbe._probes.get(this.context)?.push(this);
     }
 
+    /** @internal */
     awake() {
         this._boxHelper = this.gameObject.addComponent(BoxHelperComponent) as BoxHelperComponent;
         this._boxHelper.updateBox(true);
@@ -178,20 +192,24 @@ export class ReflectionProbe extends Behaviour {
         }
     }
 
+    /** @internal */
     onEnable(): void {
         ReflectionProbe.onEnabled?.invoke(this);
     }
 
+    /** @internal */
     onDisable(): void {
         ReflectionProbe.onDisabled?.invoke(this);
     }
 
+    /** @internal */
     start(): void {
         if (!this._texture) {
             console.warn(`[ReflectionProbe] Missing texture. Please assign a custom cubemap texture. To use reflection probes assign them to your renderer's "anchor" property.`);
         }
     }
 
+    /** @internal */
     onDestroy() {
         const probes = ReflectionProbe._probes.get(this.context);
         if (probes) {
@@ -202,6 +220,9 @@ export class ReflectionProbe extends Behaviour {
         }
     }
 
+    /**
+     * Applies this reflection probe to the given object by setting material property overrides for "envMap", "envMapRotation", and "envMapIntensity". This is typically called by the Renderer component when determining which reflection probe to use for a given object.
+     */
     apply(object: Object3D) {
         if (disable) return;
         if (!this.enabled) return;
@@ -218,6 +239,9 @@ export class ReflectionProbe extends Behaviour {
         propertyBlock.setOverride("envMapIntensity", intensity);
     }
 
+    /**
+     * Removes the reflection probe overrides from the given object. This is typically called by the Renderer component when an object is no longer influenced by this probe or when the probe is disabled.
+     */
     unapply(obj: Object3D) {
         const block = MaterialPropertyBlock.get(obj);
         if (block) {

package/src/engine-components/Skybox.ts

@@ -479,8 +479,10 @@ function tryParseMagicSkyboxName(str: string | null | undefined, environment: bo
         return useLowRes ? value.url_low : value.url;
     }
     else if (typeof str === "string" && str?.length && (isDevEnvironment() || debug)) {
-        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:") && !str.startsWith("/")
-        if(noUrlOrFile) {
+        // Only warn if the string looks like it was meant to be a magic skybox name.
+        // Strings that contain "/" or "." are paths or URLs, not magic names.
+        const looksLikePath = str.includes("/") || str.includes(".");
+        if(!looksLikePath) {
             console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
         }
     }

package/src/engine-components/export/gltf/GltfExport.ts

@@ -6,11 +6,11 @@ import { SerializationContext } from "../../../engine/engine_serialization_core.
 import { serializable } from "../../../engine/engine_serialization_decorator.js";
 import { getWorldPosition } from "../../../engine/engine_three_utils.js";
 import { getParam } from "../../../engine/engine_utils.js";
+import GLTFMeshGPUInstancingExtension from '../../../engine/export/gltf/EXT_mesh_gpu_instancing_exporter.js';
 import { RenderTextureWriter } from "../../../engine/export/gltf/Writers.js";
 import { shouldExport_HideFlags } from "../../../engine/export/utils.js";
 import { registerExportExtensions } from "../../../engine/extensions/index.js";
 import { NEEDLE_components } from "../../../engine/extensions/NEEDLE_components.js";
-import GLTFMeshGPUInstancingExtension from '../../../include/three/EXT_mesh_gpu_instancing_exporter.js';
 import { BoxHelperComponent } from "../../BoxHelperComponent.js";
 import { Behaviour, GameObject } from "../../Component.js";
 import { Renderer } from "../../Renderer.js";

package/src/engine-components/export/usdz/ThreeUSDZExporter.ts

@@ -2457,7 +2457,7 @@ ${usedUVChannels.has(0) ? `
 			def Shader "uvReader_st"
 			{
 				uniform token info:id = "UsdPrimvarReader_float2"
-				token inputs:varname = "st"
+				string inputs:varname = "st"
 				float2 inputs:fallback = (0.0, 0.0)
 				float2 outputs:result
 			}
@@ -2466,7 +2466,7 @@ ${usedUVChannels.has(1) ? `
 			def Shader "uvReader_st1"
 			{
 				uniform token info:id = "UsdPrimvarReader_float2"
-				token inputs:varname = "st1"
+				string inputs:varname = "st1"
 				float2 inputs:fallback = (0.0, 0.0)
 				float2 outputs:result
 			}

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -740,7 +740,7 @@ export class USDZExporter extends Behaviour {
         }
         else if (sessionRoot) {
             arScale = sessionRoot.arScale;
-            // eslint-disable-next-line deprecation/deprecation
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             _invertForward = sessionRoot.invertForward;
         }
 

package/src/engine-components/export/usdz/extensions/behavior/PhysicsExtension.ts

@@ -62,9 +62,9 @@ export class PhysicsExtension implements IUSDExporterExtension {
                         writer.appendLine(`double dynamicFriction = ${colliderSource.sharedMaterial?.dynamicFriction}`);
                     if (mat && mat.bounciness !== undefined)
                         writer.appendLine(`double restitution = ${colliderSource.sharedMaterial?.bounciness}`);
-                    // eslint-disable-next-line deprecation/deprecation
+                    // eslint-disable-next-line @typescript-eslint/no-deprecated
                     if (mat && mat.staticFriction !== undefined)
-                        // eslint-disable-next-line deprecation/deprecation
+                        // eslint-disable-next-line @typescript-eslint/no-deprecated
                         writer.appendLine(`double staticFriction = ${colliderSource.sharedMaterial?.staticFriction}`);
                     writer.closeBlock( "}" );
                 }