@needle-tools/engine 4.11.4 → 4.11.5-next.53316bf

package/src/engine-components/RendererLightmap.ts

@@ -9,6 +9,10 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
+let cloningCounter = 0;
+
+const $lightmapVersion = Symbol("lightmap-material-version");
+
 
 /**
  * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
@@ -37,6 +41,8 @@ export class RendererLightmap {
     private lightmapScaleOffset: Vector4 = new Vector4(1, 1, 0, 0);
 
     private readonly renderer: Renderer;
+    private readonly clonedMaterials = new Array<Material>();
+
     private get context(): Context { return this.renderer.context; }
     private get gameObject() { return this.renderer.gameObject; }
     private lightmapTexture: Texture | null = null;
@@ -89,8 +95,7 @@ export class RendererLightmap {
 
             const mat = this.renderer.sharedMaterials[i];
             if (!mat) continue;
-
-            const newMat = this.ensureLightmapMaterial(mat);
+            const newMat = this.ensureLightmapMaterial(mat, i);
             if (mat !== newMat) {
                 this.renderer.sharedMaterials[i] = newMat;
             }
@@ -118,23 +123,28 @@ export class RendererLightmap {
         }
     }
 
-    private ensureLightmapMaterial(material: Material) {
+    private ensureLightmapMaterial(material: Material, index: number) {
         if (!material.userData) material.userData = {};
         // if (material instanceof MeshPhysicalMaterial) {
         //     return material;
         // }
         // check if the material version has changed and only then clone the material
-        if (material["NEEDLE:lightmap-material-version"] != material.version) {
-            if (material["NEEDLE:lightmap-material-version"] == undefined) {
-                if (debug) console.warn("Cloning material for lightmap " + material.name);
-                const mat: Material = material.clone();
-                if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
-                material = mat;
-                material.onBeforeCompile = this.onBeforeCompile;
-            }
-            else {
-                // we need to clone the material
+        if (this.clonedMaterials[index] !== material) {
+            if (debug) {
+                ++cloningCounter;
+                if (cloningCounter++ < 1000) {
+                    console.warn(`Cloning material for lightmap ${this.renderer.name}: '${material.name}'`);
+                }
+                else if (cloningCounter === 1000) {
+                    console.warn(`Further material cloning for lightmaps suppressed to avoid flooding the console.`);
+                }
             }
+            const mat: Material = material.clone();
+            if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
+            material = mat;
+            material.onBeforeCompile = this.onBeforeCompile;
+            this.clonedMaterials[index] = material;
+
         }
         return material;
     }
@@ -144,22 +154,22 @@ export class RendererLightmap {
         if (material instanceof MeshPhysicalMaterial && material.transmission > 0) {
             return;
         }
-        const hasChanged = material.lightMap !== this.lightmapTexture || material["NEEDLE:lightmap-material-version"] !== material.version;
+        const hasChanged = material.lightMap !== this.lightmapTexture || material[$lightmapVersion] !== material.version;
         if (!hasChanged) {
             return;
         }
 
-        if (debug) console.log("Assigning lightmap", material.name, material.version, material);
+        if (debug) console.log(`Assigning lightmap texture ${this.renderer.name}: '${material.name}' (${material.version} ${material[$lightmapVersion]})`);
 
         // assign the lightmap
         material.lightMap = this.lightmapTexture;
         material.needsUpdate = true;
         // store the version of the material
-        material["NEEDLE:lightmap-material-version"] = material.version;
+        material[$lightmapVersion] = material.version;
     }
 
     private onBeforeCompile = (shader: WebGLProgramParametersWithUniforms, _) => {
-        if (debug) console.log("Lightmaps, before compile\n", shader)
+        if (debug === "verbose") console.log("Lightmaps, before compile\n", shader)
         this.lightmapScaleOffsetUniform.value = this.lightmapScaleOffset;
         this.lightmapUniform.value = this.lightmapTexture;
         shader.uniforms.lightmapScaleOffset = this.lightmapScaleOffsetUniform;

package/src/engine-components/Skybox.ts

@@ -1,16 +1,14 @@
-import { CompressedCubeTexture, CubeRefractionMapping, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader } from "three"
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
-import { RGBELoader } from 'three/examples/jsm/loaders/RGBELoader.js';
+import { CompressedCubeTexture, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, Texture } from "three"
 
+import { isDevEnvironment } from "../engine/debug/debug.js";
 import { ContextEvent, ContextRegistry } from "../engine/engine_context_registry.js";
 import { syncField } from "../engine/engine_networking_auto.js";
 import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { type IContext } from "../engine/engine_types.js";
-import { addAttributeChangeCallback, getParam, PromiseAllWithErrors, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
+import { addAttributeChangeCallback, getParam, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
 import { registerObservableAttribute } from "../engine/webcomponents/needle-engine.extras.js";
-import { Camera, ClearFlags } from "./Camera.js";
+import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 const debug = getParam("debugskybox");
@@ -18,6 +16,29 @@ const debug = getParam("debugskybox");
 registerObservableAttribute("background-image");
 registerObservableAttribute("environment-image");
 
+
+type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
+const MagicSkyboxNames: Record<MagicSkyboxName, { url: string, url_low: string }> = {
+    "studio": {
+        url: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem"
+    },
+    "blurred-skybox": {
+        url: "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook-ar": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem"
+    }
+} as const;
+type AnyString = string & { _brand?: never };
+
+
 function createRemoteSkyboxComponent(context: IContext, url: string, skybox: boolean, environment: boolean, attribute: "background-image" | "environment-image") {
 
     // when the user sets the attribute to a color we can not handle it as a skybox url.
@@ -91,8 +112,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 });
 
 
+
 /**
- * RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.  
+ * RemoteSkybox is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.  
  * It supports .hdr, .exr, .jpg, .png files.
  * 
  * ### Events
@@ -127,8 +149,13 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 export class RemoteSkybox extends Behaviour {
 
     /**
-     * URL to a remote skybox. This value can also use a magic skybox name. Options are "quicklook", "quicklook-ar", "studio", "blurred-skybox".  
-     * To update the skybox/environment map use `setSkybox(url)`
+     * URL to a remote skybox.   
+     * To update the skybox/environment map use `setSkybox(url)`. 
+     * 
+     * The url can also be set to a magic skybox name.   
+     * Magic name options are: "quicklook", "quicklook-ar", "studio", "blurred-skybox".     
+     * These will resolve to built-in skyboxes hosted on the Needle CDN that are static, optimized for the web and will never change.  
+     * 
      * @example
      * ```ts
      * skybox.url = "https://example.com/skybox.hdr";
@@ -136,7 +163,7 @@ export class RemoteSkybox extends Behaviour {
      */
     @syncField(RemoteSkybox.prototype.urlChangedSyncField)
     @serializable(URL)
-    url?: string;
+    url: MagicSkyboxName | AnyString = "studio";
 
     /**
      * When enabled a user can drop a link to a skybox image on the scene to set the skybox.
@@ -208,7 +235,7 @@ export class RemoteSkybox extends Behaviour {
      * @param name Define name of the file with extension if it isn't apart of the url
      * @returns Whether the skybox was successfully set
      */
-    async setSkybox(url: string | undefined | null, name?: string) {
+    async setSkybox(url: MagicSkyboxName | AnyString | undefined | null, name?: string) {
         if (!this.activeAndEnabled) return false;
 
         url = tryParseMagicSkyboxName(url, this.environment, this.background);
@@ -404,38 +431,22 @@ export class RemoteSkybox extends Behaviour {
 
 
 
-
 function tryParseMagicSkyboxName(str: string | null | undefined, environment: boolean, background: boolean): string | null {
 
     if (str === null || str === undefined) return null;
 
     const useLowRes = environment && !background;
 
-    switch (str.toLowerCase()) {
-        case "studio":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem";
-
-        case "blurred-skybox":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem";
-        case "quicklook-ar":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem";
-        case "quicklook":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem";
+    const value = MagicSkyboxNames[str.toLowerCase() as MagicSkyboxName];
+    if (value) {
+        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:");
+        if(noUrlOrFile) {
+            console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
+        }
     }
-
-
 
     return str;
 }

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

@@ -1,5 +1,5 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
-import { Euler, EventDispatcher, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { hasProLicense } from "../../../engine/engine_license.js";
@@ -53,6 +53,23 @@ export class CustomBranding {
     callToActionURL?: string;
 }
 
+type BeforeLODExportArguments = {
+    readonly exporter: USDZExporter;
+    /** The type of LOD being exported, either a texture or a mesh */
+    readonly type: "texture" | "mesh";
+    /** The Renderer gameobject */
+    readonly object: Object3D;
+    /** The mesh being exported, if applicable */
+    readonly mesh?: Mesh;
+    /** The material being exported, if applicable */
+    readonly material?: Material;
+    /** By default LOD 0 will be exported (highest quality). 
+     * Set to a different LOD level if needed. 
+     * Set to -1 to disable LOD export and simply export the current version.
+    */
+    overrideLevel?: number;
+}
+
 /**
  * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.  
  * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.  
@@ -72,8 +89,12 @@ export class CustomBranding {
  */
 export class USDZExporter extends Behaviour {
 
-    static readonly beforeExport = new EventList<{ exporter: USDZExporter }>();
-    static readonly afterExport = new EventList<{ exporter: USDZExporter }>();
+    /** Called before the USDZ file is exported */
+    static readonly beforeExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called after the USDZ file has been exported */
+    static readonly afterExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called before LOD level are exported. Can be used to override the LOD export settings */
+    static readonly beforeLODExport = new EventList<BeforeLODExportArguments>();
 
     /**
      * Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
@@ -329,7 +350,20 @@ export class USDZExporter extends Behaviour {
         for (const rend of renderers) {
             for (const mesh of rend.sharedMeshes) {
                 if (mesh) {
-                    const task = NEEDLE_progressive.assignMeshLOD(mesh, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "mesh" as const, object: rend.gameObject, mesh: mesh, };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD export for mesh due to overrideLevel -1", rend.gameObject, mesh);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for mesh export to level " + lodLevel + " " + mesh.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignMeshLOD(mesh, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {
@@ -342,7 +376,20 @@ export class USDZExporter extends Behaviour {
             }
             for (const mat of rend.sharedMaterials) {
                 if (mat) {
-                    const task = NEEDLE_progressive.assignTextureLOD(mat, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "texture" as const, object: rend.gameObject, material: mat };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD assignment due to overrideLevel -1", rend.gameObject, mat);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for texture export to level " + lodLevel + " " + mat.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignTextureLOD(mat, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {

package/src/engine-components/timeline/PlayableDirector.ts

@@ -114,8 +114,7 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if (debug)
-            console.log(this, this.playableAsset);
+        if (debug) console.log(`[Timeline] Awake '${this.name}'`, this);
 
         this.rebuildGraph();
 
@@ -134,6 +133,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onEnable() {
+        if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
+
         for (const track of this._audioTracks) {
             track.onEnable?.();
         }
@@ -162,6 +163,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onDisable(): void {
+        if (debug) console.log("[Timeline] OnDisable", this.name);
+
         this.stop();
         for (const track of this._audioTracks) {
             track.onDisable?.();
@@ -360,14 +363,17 @@ export class PlayableDirector extends Behaviour {
     private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
     private readonly _customTracks: Array<Tracks.TrackHandler> = [];
 
-    private readonly _allTracks: Array<Array<Tracks.TrackHandler>> = [
-        this._animationTracks,
-        this._audioTracks,
-        this._signalTracks,
-        this._markerTracks,
-        this._controlTracks,
-        this._customTracks
-    ];
+    private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
+    private get _allTracks(): Array<Array<Tracks.TrackHandler>> {
+        this._tracksArray.length = 0;
+        this._tracksArray.push(this._animationTracks);
+        this._tracksArray.push(this._audioTracks);
+        this._tracksArray.push(this._signalTracks);
+        this._tracksArray.push(this._markerTracks);
+        this._tracksArray.push(this._controlTracks);
+        this._tracksArray.push(this._customTracks);
+        return this._tracksArray;
+    }
 
     /** should be called after evaluate if the director was playing */
     private invokePauseChangedMethodsOnTracks() {

package/src/engine-components/web/CursorFollow.ts

@@ -20,6 +20,9 @@ const debug = getParam("debugcursor");
  */
 export class CursorFollow extends Behaviour {
 
+    // testing this for compilation
+    static readonly NAME = "CursorFollow";
+
     /**
      * Damping for the movement, set to 0 for instant movement
      * @default 0

package/src/engine-components/webxr/WebXR.ts

@@ -331,6 +331,10 @@ export class WebXR extends Behaviour {
             console.warn(`WebXR: another WebXR component is already active (${WebXR.activeWebXRComponent?.name}). This is ignored: ${this.name}`);
             return;
         }
+        if (this.activeAndEnabled === false || this.destroyed) {
+            console.debug("[WebXR] onBeforeXR called on disabled or destroyed component");
+            return;
+        }
         WebXR.activeWebXRComponent = this;
 
         if (_mode == "immersive-ar" && this.useDepthSensing) {

package/src/engine-components/webxr/controllers/XRControllerModel.ts

@@ -284,7 +284,7 @@ export class XRControllerModel extends Behaviour {
 
         const loader = new GLTFLoader();
         addDracoAndKTX2Loaders(loader, context);
-        await registerExtensions(loader, context, this.sourceId ?? "");
+        await registerExtensions(loader, context, this.sourceId ?? "", this.sourceId ?? "");
         const componentsExtension = registerComponentExtension(loader);
 
         let filename = "";

package/src/needle-engine.ts

@@ -7,7 +7,7 @@ export * from "./engine-components-experimental/api.js";
 export * from "./engine-schemes/api.js";
 
 // make accessible for external javascript
-import { Context, loadAsset, NeedleXRSession, onAfterRender, onBeforeRender, onClear, onDestroy, onInitialized, onStart, onUpdate, VERSION } from "./engine/api.js";
+import { Context, loadAsset, NeedleXRSession, onAfterRender, onBeforeRender, onClear, onDestroy, onInitialized, onStart, onUpdate, TypeStore, VERSION } from "./engine/api.js";
 const Needle = {
     VERSION: VERSION,
     Context: Context,
@@ -15,6 +15,7 @@ const Needle = {
     assets: {
         loadFromURL: loadAsset,
     },
+    types: TypeStore,
     onStart: onStart,
     onUpdate: onUpdate,
     onBeforeRender: onBeforeRender,
@@ -22,7 +23,8 @@ const Needle = {
     onInitializedContext: onInitialized,
     onDestroyContext: onDestroy,
     onClearContext: onClear,
-};
+} as const;
+
 if (globalThis["Needle"]?.VERSION !== undefined) {
     console.warn(`Needle Engine is already imported: ${globalThis["Needle"].VERSION}`);
 }