@needle-tools/engine 4.11.4 → 4.11.5-next.4201116

package/package.json

@@ -1,27 +1,35 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.11.4",
+  "version": "4.11.5-next.4201116",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {
     ".": {
+      "types": "./dist/needle-engine.d.ts",
       "import": "./lib/needle-engine.js",
       "require": "./dist/needle-engine.umd.cjs"
     },
     "./package.json": "./package.json",
+    "./components.json": "./components.needle.json",
     "./asap": "./lib/asap/needle-asap.js",
     "./vite": {
-      "types": "./plugins/types/vite.d.js",
+      "types": "./plugins/types/vite.d.ts",
       "import": "./plugins/vite/index.js",
       "require": "./plugins/vite/index.js"
     },
     "./next": {
-      "types": "./plugins/types/next.d.js",
+      "types": "./plugins/types/next.d.ts",
       "import": "./plugins/next/index.js",
       "require": "./plugins/next/index.js"
     },
-    "./plugins/vite/index.js": "./plugins/vite/index.js",
-    "./plugins/next/index.js": "./plugins/next/index.js"
+    "./plugins/vite/index.js": {
+      "types": "./plugins/types/vite.d.ts",
+      "default": "./plugins/vite/index.js"
+    },
+    "./plugins/next/index.js": {
+      "types": "./plugins/types/next.d.ts",
+      "default": "./plugins/next/index.js"
+    }
   },
   "type": "module",
   "repository": {
@@ -48,6 +56,8 @@
     "test": "node plugins/test/test.mjs",
     "test:circular-imports": "node plugins/test/check-circular-imports.mjs",
     "test:tsc": "tsc --strict false && tsc --strict true",
+    "test:attw": "npx --yes @arethetypeswrong/cli --pack dist",
+    "generate:custom-elements": "npx web-component-analyzer src --format vscode --outFile custom-elements.json && node scripts/clean-wca-json.mjs",
     "lint": "eslint --ext .ts src",
     "lint:fix": "eslint --ext .ts src --fix",
     "stats": "howfat ."
@@ -60,11 +70,6 @@
     "src",
     "lib",
     "dist",
-    "dist/needle-engine.js",
-    "dist/needle-engine.d.ts",
-    "dist/needle-engine.umd.cjs",
-    "dist/needle-engine.min.js",
-    "dist/needle-engine.light.min.js",
     "plugins",
     "components.needle.json"
   ],
@@ -141,7 +146,7 @@
     "npm-watch": "^0.11.0",
     "typescript": "^4.5.5",
     "vite": "7",
-    "vite-plugin-dts": "^4.5.0"
+    "vite-plugin-dts": "^4.5.4"
   },
   "peerDependencies": {
     "open": "^10.1.0"
@@ -166,7 +171,8 @@
       "quiet": false
     }
   },
+  "customElements": "./custom-elements.json",
   "module": "lib/needle-engine.js",
   "typings": "lib/needle-engine.d.ts",
   "types": "lib/needle-engine.d.ts"
-}
+}

package/plugins/types/needleConfig.d.ts

@@ -1,4 +1,4 @@
-import { License } from "./license";
+import { License } from "./license.js";
 
 export type needleMeta = {
     needleEditor: string | null,

package/plugins/types/next.d.ts

@@ -1,3 +1,3 @@
-import { userSettings } from './userconfig';
+import { userSettings } from './userconfig.js';
 
 export declare function needleNext(nextConfig?: import('next').NextConfig, userSettings?: userSettings): Promise<import('next').NextConfig>;

package/plugins/types/userconfig.d.ts

@@ -1,4 +1,4 @@
-import { License } from "./license";
+import { License } from "./license.js";
 
 export type needleModules = {
     webpack: object | undefined

package/src/engine/api.ts

@@ -75,8 +75,8 @@ export { registerType, TypeStore } from "./engine_typestore.js";
 export { prefix, validate } from "./engine_util_decorator.js";
 export * from "./engine_utils.js";
 export * from "./engine_utils_format.js";
-export * from "./engine_utils_screenshot.js";
 export { generateQRCode } from "./engine_utils_qrcode.js";
+export * from "./engine_utils_screenshot.js";
 export * from "./export/index.js";
 export * from "./extensions/index.js";
 export * from "./js-extensions/index.js";

package/src/engine/debug/debug_spector.ts

@@ -0,0 +1,43 @@
+import type { Context } from "../engine_setup.js";
+import { isDevEnvironment } from "./debug.js";
+
+declare global {
+    interface Window {
+        SPECTOR?: {
+            Spector: new () => Spector;
+        }
+    }
+    interface Spector {
+        displayUI: () => void;
+        setCanvas: (canvas: HTMLCanvasElement) => void;
+        spyCanvases: boolean;
+        startCaptureOnNextFrame: () => void;
+        captureCanvas: (canvas: HTMLCanvasElement) => any;
+    }
+}
+
+
+export function initSpectorIfAvailable(_context: Context, canvas: HTMLCanvasElement): void {
+    if (typeof window !== undefined && window.SPECTOR) {
+        console.log(window.SPECTOR);
+        const params = new URLSearchParams(window.location.search);
+        if (params.has("spector")) {
+            const frame = Number.parseInt(params.get("spector") || "0") || 0;
+            console.log("Scheduled Spector capture at frame #" + frame);
+            const spector = new window.SPECTOR.Spector();
+            spector.spyCanvases = true;
+            waitForFrameAndCapture();
+            return;
+
+            function waitForFrameAndCapture() {
+                if (frame > _context.time.frame) return window.requestAnimationFrame(() => waitForFrameAndCapture());
+                const res = spector.captureCanvas(canvas);
+                if (res && res instanceof Promise) res.then(() => spector.displayUI());
+                else spector.displayUI();
+            }
+        }
+        else if (isDevEnvironment()) {
+            console.debug("Spector available: Add '?spector=<frame>' to the URL to enable it and capture a frame.");
+        }
+    }
+}

package/src/engine/engine_addressables.ts

@@ -3,6 +3,7 @@ import { Group, Object3D, Texture, TextureLoader } from "three";
 import { getParam, resolveUrl } from "../engine/engine_utils.js";
 import { destroy, type IInstantiateOptions, instantiate, InstantiateOptions, isDestroyed } from "./engine_gameobject.js";
 import { getLoader } from "./engine_gltf.js";
+import type { loadAsset } from "./engine_loaders.js";
 import { processNewScripts } from "./engine_mainloop_utils.js";
 import { BlobStorage } from "./engine_networking_blob.js";
 import { registerPrefabProvider, syncInstantiate, SyncInstantiateOptions } from "./engine_networking_instantiate.js";
@@ -79,13 +80,50 @@ export type ProgressCallback = (asset: AssetReference, prog: ProgressEvent) => v
 
 const $assetReference = Symbol("assetReference");
 
-/** ### AssetReferences can be used to easily load glTF or GLB assets  
- * You can use `AssetReference.getOrCreate` to get an AssetReference for a URL to be easily loaded.  
- * When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.  
- * - `myAssetReference.preload()` to load the asset binary without creating an instance yet.
- * - `myAssetReference.loadAssetAsync()` to load the asset and create an instance.  
- * - `myAssetReference.instantiate()` to load the asset and create a new instance.  
- * - `myAssetReference.unload()` to dispose allocated memory and destroy the asset instance.  
+/** ### AssetReferences can be used to load glTF or GLB assets  
+ * Use {@link AssetReference.getOrCreateFromUrl} to get an AssetReference for a URL to be easily loaded. When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.   
+ * 
+ * **Important methods:**
+ * - {@link preload} to load the asset binary without creating an instance yet.
+ * - {@link loadAssetAsync} to load the asset and create an instance.  
+ * - {@link instantiate} to load the asset and create another instance.  
+ * - {@link unload} to dispose allocated memory and destroy the asset instance.  
+ * 
+ * @example Loading an asset from a URL
+ * ```ts
+ * import { AssetReference } from '@needle-tools/engine';
+ * const assetRef = AssetReference.getOrCreateFromUrl("https://example.com/myModel.glb");
+ * const instance = await assetRef.loadAssetAsync();
+ * scene.add(instance);
+ * ```
+ * 
+ * @example Referencing an asset in a component and loading it on start
+ * ```ts
+ * import { Behaviour, serializable, AssetReference } from '@needle-tools/engine';
+ * 
+ * export class MyComponent extends Behaviour {
+ * 
+ *   @serializable(AssetReference)
+ *   myModel?: AssetReference;
+ *   
+ *   // Load the model on start. Start is called after awake and onEnable
+ *   start() { 
+ *     if (this.myModel) {
+ *       this.myModel.loadAssetAsync().then(instance => {
+ *         if (instance) {
+ *           // add the loaded model to this component's game object
+ *           this.gameObject.add(instance); 
+ *         }
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ * 
+ * ### Related:
+ * - {@link ImageReference} to load external image URLs
+ * - {@link FileReference} to load external file URLs
+ * - {@link loadAsset} to load assets directly without using AssetReferences
  */
 export class AssetReference {
 
@@ -524,12 +562,33 @@ new AddressableSerializer();
 
 const failedTexturePromise = Promise.resolve(null);
 
-/** Use this if a file is a external image URL
+/**  
+ * Load images or textures from external URLs.
+ * 
+ * **Important methods:**
+ * - {@link createHTMLImage} to create an HTMLImageElement from the URL
+ * - {@link createTexture} to create a Three.js Texture from the URL
+ * 
  * @example
  * ```ts
- * @serializable(ImageReference)  
- * myImage?:ImageReference;
+ * import { ImageReference, serializable } from '@needle-tools/engine';
+ * 
+ * export class MyComponent extends Behaviour {
+ *   @serializable(ImageReference)  
+ *   myImage?:ImageReference;
+ *   async start() {
+ *     if(this.myImage) {
+ *       const texture = await this.myImage.createTexture();
+ *       if(texture) {
+ *         // use the texture
+ *       }
+ *     }
+ *   }
  * ```
+ * 
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link FileReference} to load external file URLs
  */
 export class ImageReference {
 
@@ -637,7 +696,12 @@ new ImageReferenceSerializer();
 
 
 
-/** Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset
+/** 
+ * Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset.  
+ * 
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link ImageReference} to load external image URLs
  */
 export class FileReference {
 

package/src/engine/engine_application.ts

@@ -15,7 +15,7 @@ const userInteractionCallbacks: Function[] = [];
  */
 export function internalOnUserInputRegistered() {
     if (userInteractionRegistered) return;
-    if (isDevEnvironment()) console.debug("User interaction registered: audio can now be played");
+    if (isDevEnvironment()) console.debug("[Needle Engine] User input registered: Media playback is now allowed.");
     userInteractionRegistered = true;
     const copy = [...userInteractionCallbacks];
     userInteractionCallbacks.length = 0;
@@ -28,6 +28,21 @@ document.addEventListener('dragstart', internalOnUserInputRegistered);
 document.addEventListener('touchend', internalOnUserInputRegistered);
 document.addEventListener('keydown', internalOnUserInputRegistered);
 
+
+declare global {
+    interface Navigator {
+        userActivation?: {
+            isActive: boolean;
+        };
+    }
+}
+// User Activation should be available across browsers since November 2023 https://developer.mozilla.org/en-US/docs/Web/API/UserActivation
+if (typeof window !== "undefined" && "userActivation" in navigator && navigator.userActivation?.isActive) {
+    if (isDevEnvironment()) console.debug("[Needle Engine] User input already active: Media playback is now allowed.");
+    userInteractionCallbacks.length = 0;
+    userInteractionRegistered = true;
+}
+
 /** 
  * The Application class can be used to mute audio globally, and to check if the application (canvas) is currently visible (it's tab is active and not minimized). 
  */

package/src/engine/engine_camera.fit.ts

@@ -1,6 +1,7 @@
 import { Camera, Object3D, PerspectiveCamera, Vector3, Vector3Like } from "three";
 
 import { GroundProjectedEnv } from "../engine-components/GroundProjection.js";
+import type { OrbitControls } from "../engine-components/OrbitControls.js";
 import { findObjectOfType } from "./engine_components.js";
 import { Context } from "./engine_context.js";
 import { Gizmos } from "./engine_gizmos.js";
@@ -9,7 +10,10 @@ import { NeedleXRSession } from "./xr/NeedleXRSession.js";
 
 
 /**
- * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
+ * Options for fitting a camera to the scene or specific objects.
+ * 
+ * Used by {@link OrbitControls.fitCamera} and the {@link fitCamera}.
+ * 
  */
 export type FitCameraOptions = {
     /** When enabled debug rendering will be shown */
@@ -31,8 +35,17 @@ export type FitCameraOptions = {
      */
     camera?: Camera,
 
+    /**
+     * The current zoom level of the camera (used to avoid clipping when fitting)
+     */
     currentZoom?: number,
+    /**
+     * Minimum and maximum zoom levels for the camera (e.g. if zoom is constrained by OrbitControls)
+     */
     minZoom?: number,
+    /**
+     * Maximum zoom level for the camera (e.g. if zoom is constrained by OrbitControls)
+     */
     maxZoom?: number,
 
     /**
@@ -40,7 +53,11 @@ export type FitCameraOptions = {
      */
     objects?: Object3D[] | Object3D;
 
-    /** Fit offset: A factor to multiply the distance to the objects by
+    /**
+     * A factor to control padding around the fitted objects.  
+     * 
+     * Values > 1 will add more space around the fitted objects, values < 1 will zoom in closer.
+     * 
      * @default 1.1
      */
     fitOffset?: number,
@@ -74,7 +91,7 @@ export type FitCameraOptions = {
     relativeTargetOffset?: Partial<Vector3Like>,
 
     /**
-     * Field of view (FOV) for the camera
+     * Target field of view (FOV) for the camera
      */
     fov?: number,
 }
@@ -86,7 +103,35 @@ export type FitCameraReturnType = {
     fov: number | undefined
 }
 
-
+/**
+ * Fit the camera to the specified objects or the whole scene.    
+ * Adjusts the camera position and optionally the FOV to ensure all objects are visible.
+ * 
+ * @example Fit the main camera to the entire scene:
+ * ```ts
+ * import { fitCamera } from '@needle-tools/engine';
+ * 
+ * // Fit the main camera to the entire scene
+ * fitCamera();
+ * ```
+ * @example Fit a specific camera to specific objects with custom options:
+ * ```ts
+ * import { fitCamera } from '@needle-tools/engine';
+ * 
+ * // Fit a specific camera to specific objects with custom options
+ * const myCamera = ...; // your camera
+ * const objectsToFit = [...]; // array of objects to fit
+ * fitCamera({
+ *    camera: myCamera,
+ *    objects: objectsToFit,
+ *    fitOffset: 1,
+ *    fov: 20,
+ * });
+ * ```
+ * 
+ * @param options Options for fitting the camera
+ * @returns 
+ */
 export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnType {
 
     if (NeedleXRSession.active) {

package/src/engine/engine_context.ts

@@ -13,6 +13,7 @@ import * as Stats from 'three/examples/jsm/libs/stats.module.js';
 import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
 import { nodeFrame } from "three/examples/jsm/renderers/webgl-legacy/nodes/WebGLNodeBuilder.js";
 
+import { initSpectorIfAvailable } from './debug/debug_spector.js';
 import { isDevEnvironment, LogType, showBalloonError, showBalloonMessage } from './debug/index.js';
 import { Addressables } from './engine_addressables.js';
 import { AnimationsRegistry } from './engine_animation.js';
@@ -37,7 +38,7 @@ import { RendererData as SceneLighting } from './engine_scenelighting.js';
 import { getTempColor, logHierarchy } from './engine_three_utils.js';
 import { Time } from './engine_time.js';
 import { patchTonemapping } from './engine_tonemapping.js';
-import type { CoroutineData, ICamera, IComponent, IContext, ILight, LoadedModel, Model, Vec2 } from "./engine_types.js";
+import type { CoroutineData, ICamera, IComponent, IContext, ILight, LoadedModel, Model, SourceIdentifier, Vec2 } from "./engine_types.js";
 import { deepClone, delay, DeviceUtilities, getParam } from './engine_utils.js';
 import type { INeedleXRSessionEventReceiver, NeedleXRSession } from './engine_xr.js';
 import { NeedleMenu } from './webcomponents/needle menu/needle-menu.js';
@@ -129,9 +130,12 @@ export function registerComponent(script: IComponent, context?: Context) {
 }
 
 /**
- * The context is the main object that holds all the data and state of the Needle Engine.  
- * It can be used to access the scene, renderer, camera, input, physics, networking, and more.
- * @example
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. 
+ * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
+ * 
+ * The context is automatically created when using the `<needle-engine>` web component.  
+ * 
+ * @example Accessing the context from a [component](https://engine.needle.tools/docs/api/Behaviour):
  * ```typescript
  * import { Behaviour } from "@needle-tools/engine";
  * import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
@@ -142,6 +146,18 @@ export function registerComponent(script: IComponent, context?: Context) {
  *   }
  * }
  * ```
+ * 
+ * @example Accessing the context from a [hook](https://engine.needle.tools/docs/scripting.html#hooks) without a component e.g. from a javascript module or svelte or react component.
+ * 
+ * ```typescript
+ * import { onStart } from "@needle-tools/engine";
+ * 
+ * onStart((context) => {
+ *   console.log("Hello from onStart hook");
+ *   context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
+ * });
+ * ```
+ * 
  */
 export class Context implements IContext {
 
@@ -357,6 +373,7 @@ export class Context implements IContext {
 	 */
 	composer: EffectComposer | ThreeEffectComposer | null = null;
 
+	// #region internal script lists
 	/**
 	 * @internal All known components. Don't use directly
 	 */
@@ -424,6 +441,9 @@ export class Context implements IContext {
 	/** @internal */
 	readonly new_scripts_xr: INeedleXRSessionEventReceiver[] = [];
 
+	// #endregion
+	// #region Properties
+
 	/** 
 	 * The **main camera component** of the scene - this camera is used for rendering.  
 	 * Use `setCurrentCamera` for updating the main camera.
@@ -468,25 +488,36 @@ export class Context implements IContext {
 	physics: Physics;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
 	connection: NetworkConnection;
-	/** 
-	 * @deprecated AssetDataBase is deprecated
-	 */
+	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
 	/** The main light in the scene */
 	mainLight: ILight | null = null;
 	/** @deprecated Use sceneLighting */
 	get rendererData() { return this.sceneLighting }
+	/** Access the scene lighting manager to control lighting settings in the context */
 	sceneLighting: SceneLighting;
 	addressables: Addressables;
 	lightmaps: ILightDataRegistry;
 	players: PlayerViewManager;
+
+	/** Access the LODs manager to control LOD behavior in the context */
 	readonly lodsManager: LODsManager;
 	/** Access the needle menu to add or remove buttons to the menu element */
 	readonly menu: NeedleMenu;
 
-	/** @returns true if the context is fully created and ready */
+	/** 
+	 * Checks if the context is fully created and ready
+	 * @returns true if the context is fully created and ready 
+	 */
 	get isCreated() { return this._isCreated; }
 
+	/** 
+	 * The source identifier(s) of the root scene(s) loaded into this context.
+	 * When using `<needle-engine>` web component this will be the `src` attribute(s).
+	 * @returns The source identifier for of the root scene
+	*/
+	get rootSourceId(): SourceIdentifier | undefined { return this.rootSceneSourceIdentifiers[0] || undefined; }
+
 	private _needsUpdateSize: boolean = false;
 	private _isCreated: boolean = false;
 	private _isCreating: boolean = false;
@@ -541,6 +572,7 @@ export class Context implements IContext {
 		ContextRegistry.register(this);
 	}
 
+	// #region Renderer
 	/** 
 	 * Calling this function will dispose the current renderer and create a new one which will then be assigned to the context. It can be used to create a new renderer with custom WebGLRendererParameters.   
 	 * **Note**: Instead you can also modify the static `Context.DefaultWebGlRendererParameters` before the context is created.  
@@ -591,6 +623,8 @@ export class Context implements IContext {
 
 		this.input.bindEvents();
 
+		initSpectorIfAvailable(this, this.renderer.domElement);
+
 		return this.renderer;
 	}
 
@@ -894,6 +928,7 @@ export class Context implements IContext {
 		}
 	}
 
+	// #region onBeforeRender / onAfterRender listeners
 	private readonly _onBeforeRenderListeners = new Map<string, OnRenderCallback[]>();
 	private readonly _onAfterRenderListeners = new Map<string, OnRenderCallback[]>();
 
@@ -991,6 +1026,8 @@ export class Context implements IContext {
 	private _lastStyleComputedResult: boolean | undefined = undefined;
 
 	private _createId: number = 0;
+
+	// #region internal create
 	private async internalOnCreate(opts?: ContextCreateArgs): Promise<boolean> {
 		const createId = ++this._createId;
 
@@ -1200,6 +1237,11 @@ export class Context implements IContext {
 		if (opts?.abortSignal?.aborted) {
 			return false;
 		}
+
+
+		const mainIdentifier = this.rootSourceId;
+		if (mainIdentifier) this.sceneLighting.enable(mainIdentifier);
+
 		invokeLifecycleFunctions(this, ContextEvent.ContextCreated);
 		if (debug) console.log("Context Created...", this.renderer, this.renderer.domElement)
 
@@ -1209,13 +1251,18 @@ export class Context implements IContext {
 		return true;
 	}
 
+
+	private readonly rootSceneSourceIdentifiers: SourceIdentifier[] = [];
 	private async internalLoadInitialContent(createId: number, args: ContextCreateArgs): Promise<Array<LoadedModel>> {
+		this.rootSceneSourceIdentifiers.length = 0;
+
 		const results = new Array<LoadedModel>();
 		// early out if we dont have any files to load
 		if (args.files.length === 0) return results;
 
-
 		const files = [...args.files];
+		this.rootSceneSourceIdentifiers.push(...files);
+
 		const progressArg: LoadingProgressArgs = {
 			name: "",
 			progress: null!,
@@ -1223,6 +1270,7 @@ export class Context implements IContext {
 			count: files.length
 		}
 
+
 		const loader = getLoader();
 		// this hash should be constant since it is used to initialize the UIDProvider per initially loaded scene
 		const loadingHash = 0;
@@ -1661,7 +1709,8 @@ export class Context implements IContext {
 
 		if (this._stats) {
 			this._stats.end();
-			if (this.time.frameCount % 150 === 0)
+			const dt = this.time.fps < 20 ? 50 : 150;
+			if (this.time.frameCount % dt === 0)
 				console.log(this.renderer.info.render.calls + " DrawCalls", "\nRender:", { ...this.renderer.info.render }, "\nMemory:", { ...this.renderer.info.memory }, "\nTarget Framerate: " + this.targetFrameRate);
 		}
 

package/src/engine/engine_loaders.ts

@@ -13,7 +13,7 @@ import { registerPrewarmObject } from "./engine_mainloop_utils.js";
 import { SerializationContext } from "./engine_serialization_core.js";
 import { Context } from "./engine_setup.js"
 import { postprocessFBXMaterials } from "./engine_three_utils.js";
-import { CustomModel, isGLTFModel, Model, type UIDProvider } from "./engine_types.js";
+import { CustomModel, isGLTFModel, Model, SourceIdentifier, type UIDProvider } from "./engine_types.js";
 import * as utils from "./engine_utils.js";
 import { tryDetermineMimetypeFromURL } from "./engine_utils_format.js"
 import { invokeLoadedImportPluginHooks, registerComponentExtension, registerExtensions } from "./extensions/extensions.js";
@@ -43,7 +43,7 @@ const debugFileTypes = utils.getParam("debugfileformat");
 
 
 
-export async function onCreateLoader(url: string, context: Context): Promise<CustomLoader | GLTFLoader | FBXLoader | USDZLoader | OBJLoader | null> {
+async function onCreateLoader(url: string, context: Context, sourceId: SourceIdentifier): Promise<CustomLoader | GLTFLoader | FBXLoader | USDZLoader | OBJLoader | null> {
 
     const type = await tryDetermineMimetypeFromURL(url, { useExtension: true }) || "unknown";
     if (debugFileTypes) console.debug(`Determined file type: '${type}' for url '${url}'`, { registeredModelLoaderCallbacks });
@@ -67,7 +67,7 @@ export async function onCreateLoader(url: string, context: Context): Promise<Cus
             {
                 console.warn(`Unknown file type (${type}). Needle Engine will fallback to the GLTFLoader - To support more model formats please create a Needle loader plugin.\nUse import { NeedleEngineModelLoader } from \"@needle-tools/engine\" namespace to register your loader.`, url);
                 const loader = new GLTFLoader();
-                await registerExtensions(loader, context, url);
+                await registerExtensions(loader, context, url, sourceId);
                 return loader;
             }
         case "model/fbx":
@@ -88,7 +88,7 @@ export async function onCreateLoader(url: string, context: Context): Promise<Cus
         case "model/vrm":
             {
                 const loader = new GLTFLoader();
-                await registerExtensions(loader, context, url);
+                await registerExtensions(loader, context, url, sourceId);
                 return loader;
             }
     }
@@ -117,7 +117,7 @@ export async function parseSync(context: Context, data: string | ArrayBuffer, pa
         path = "";
     }
     if (printGltf) console.log("Parse glTF", path)
-    const loader = await onCreateLoader(path, context);
+    const loader = await onCreateLoader(path, context, path);
     if (!loader) {
         return undefined;
     }
@@ -193,7 +193,7 @@ export async function loadSync(context: Context, url: string, sourceId: string,
     // but due to the async nature and potentially triggering multiple loads at the same time
     // we need to make sure the extensions dont override each other
     // creating new loaders should not be expensive as well
-    const loader = await onCreateLoader(url, context);
+    const loader = await onCreateLoader(url, context, sourceId);
     if (!loader) {
         return undefined;
     }

package/src/engine/engine_physics.ts

@@ -13,6 +13,7 @@ import type { IPhysicsEngine } from './engine_types.js';
 import { getParam } from "./engine_utils.js"
 
 const debugPhysics = getParam("debugphysics");
+const debugWorker = getParam("debugworker");
 const layerMaskHelper: Layers = new Layers();
 
 
@@ -654,6 +655,9 @@ namespace NEMeshBVH {
                     // if there are no workers available, create a new one
                     if (!workerInstance && workerInstances.length < 3) {
                         try {
+                            if (debugWorker) {
+                                console.warn("[GenerateMeshBVHWorker] Creating worker with import.meta.url:", import.meta.url);
+                            }
                             workerInstance = new _GenerateMeshBVHWorker();
                             workerInstances.push(workerInstance);
                         }
@@ -665,8 +669,8 @@ namespace NEMeshBVH {
                                 failedToCreateMeshBVHWorker += 10;
                             }
                             else {
-                                console.error("Failed to create MeshBVH worker");
-                                console.debug(err);
+                                console.error("Failed to create MeshBVH worker. Please see below for more details:");
+                                console.log(err);
                             }
                             failedToCreateMeshBVHWorker++;
                         }