@needle-tools/engine 4.5.0-alpha.2 → 4.5.0-alpha.4

package/src/engine/engine_loaders.callbacks.ts

@@ -1,11 +1,12 @@
 import { BufferGeometry, Object3D } from "three";
 import { Context } from "./engine_setup.js";
 import { CustomModel } from "./engine_types.js";
-import { type FileType } from "./engine_utils_format.js";
+import { type NeedleMimetype } from "./engine_utils_format.js";
 
 export type ValidLoaderReturnType = CustomModel | Object3D | BufferGeometry;
 
 
+
 /** @internal */
 export type CustomLoader = {
     /** The name of the loader. This is used for debugging purposes. */
@@ -16,12 +17,12 @@ export type CustomLoader = {
     parse: (buffer: ArrayBuffer | string, path: string) => ValidLoaderReturnType,
 };
 
-type CustomLoaderCallback = (args: { context: Context, url: string, filetype: FileType }) => CustomLoader | null | undefined | void;
+type CustomLoaderCallback = (args: { context: Context, url: string, mimetype: NeedleMimetype }) => CustomLoader | Promise<CustomLoader> | null | undefined | void;
 /** @internal */
-export const registeredModelLoaderCallbacks: Array<CustomLoaderCallback> = [];
+export const registeredModelLoaderCallbacks: Array<{ name?: string, priority: number, callback: CustomLoaderCallback }> = [];
 
 
-type FileTypeCallback = (args: {
+type MimetypeCallback = (args: {
     /** The URL of the file to load */
     url: string,
     /** The response of the range request with the first few bytes of the file (bytes are available in the 'args.bytes' property of this callback) */
@@ -30,22 +31,58 @@ type FileTypeCallback = (args: {
     contentType: string | null,
     /** The first few bytes of the file as a Uint8Array */
     bytes: Uint8Array
-}) => FileType | null;
+}) => NeedleMimetype | null;
 /** @internal */
-export const registeredFileTypeCallbacks: Array<FileTypeCallback> = [];
+export const registeredMimetypeCallbacks: Array<MimetypeCallback> = [];
 
 
 /**
  * NeedleEngineModelLoader is a namespace that provides functions to register custom model loaders and mimetype callbacks.
  * It allows you to create custom loaders for specific file types and determine the mimetype of files based on their content.
+ * @example
+ * ```ts
+ * import { NeedleEngineModelLoader } from "@needle-tools/engine";
+ * import { STLLoader } from "three/examples/jsm/loaders/STLLoader";
+ * 
+ * NeedleEngineModelLoader.onCreateCustomModelLoader(args => {
+ *    if (args.mimetype === "model/stl") {
+ *       return new STLLoader(); 
+ *  }  
+ * });
+ * 
+ * NeedleEngineModelLoader.onDetermineModelMimetype((args) => {
+ *   // detect stl mimetype
+ *   const bytes = args.bytes;
+ *   if (bytes[0] === 0x73 && bytes[1] === 0x74 && bytes[2] === 0x6c) {
+ *      return "model/stl";
+ *   }
+ *   return null;
+ * });
+ * ```
  */
 export namespace NeedleEngineModelLoader {
 
-    // export type ModelLoaderPlugin = {
-    //     name: string,
-    //     canLoad: (url: string, mimetype: string) => boolean,
+    // export type Plugin = {
+    //     readonly name: string;
+    //     canLoad: (mimetype: string, url: string) => boolean,
+    //     createLoader: (url: string, mimetype: string) => Promise<CustomLoader>,
+    // }
+
+    // export function registerLoaderPlugin(plugin: Plugin) {
     // }
-    
+
+
+
+    type CustomLoaderOptions = {
+        /** The name of the loader. This is used for debugging purposes. */
+        name?: string,
+        /** 
+         * The priority of the loader. Higher priority loaders will be called first.
+         * @default 0
+         */
+        priority?: number,
+    }
+
     /**
      * Register a custom loader callback. For every file that is requested this callback is called with the url and mimetype. It should return a custom loader or null if it does not want to handle the file.
      * @param callback The callback to register
@@ -60,10 +97,19 @@ export namespace NeedleEngineModelLoader {
      *     return null;
      * });
      */
-    export function onCreateCustomModelLoader(callback: CustomLoaderCallback) {
-        registeredModelLoaderCallbacks.push(callback);
+    export function onCreateCustomModelLoader(callback: CustomLoaderCallback, opts?: CustomLoaderOptions) {
+        const entry = { name: opts?.name, priority: opts?.priority ?? 0, callback };
+        registeredModelLoaderCallbacks.push(entry);
+
+        // sort plugins by priority. Higher priority first
+        registeredModelLoaderCallbacks.sort((a, b) => {
+            if (a.priority === b.priority) return 0;
+            if (a.priority > b.priority) return -1;
+            return 1;
+        });
+
         return () => {
-            const index = registeredModelLoaderCallbacks.indexOf(callback);
+            const index = registeredModelLoaderCallbacks.indexOf(entry);
             if (index >= 0) {
                 registeredModelLoaderCallbacks.splice(index, 1);
             }
@@ -76,12 +122,12 @@ export namespace NeedleEngineModelLoader {
      * @returns A function to unregister the callback
      * 
      */
-    export function onDetermineModelFiletype(callback: FileTypeCallback): (() => void) {
-        registeredFileTypeCallbacks.push(callback);
+    export function onDetermineModelMimetype(callback: MimetypeCallback): (() => void) {
+        registeredMimetypeCallbacks.push(callback);
         return () => {
-            const index = registeredFileTypeCallbacks.indexOf(callback);
+            const index = registeredMimetypeCallbacks.indexOf(callback);
             if (index >= 0) {
-                registeredFileTypeCallbacks.splice(index, 1);
+                registeredMimetypeCallbacks.splice(index, 1);
             }
         }
     }

package/src/engine/engine_loaders.ts

@@ -15,7 +15,7 @@ import { Context } from "./engine_setup.js"
 import { postprocessFBXMaterials } from "./engine_three_utils.js";
 import { CustomModel, isGLTFModel, Model, type UIDProvider } from "./engine_types.js";
 import * as utils from "./engine_utils.js";
-import { tryDetermineFileTypeFromURL } from "./engine_utils_format.js"
+import { tryDetermineMimetypeFromURL } from "./engine_utils_format.js"
 import { invokeLoadedImportPluginHooks, registerComponentExtension, registerExtensions } from "./extensions/extensions.js";
 import { NEEDLE_components } from "./extensions/NEEDLE_components.js";
 
@@ -45,42 +45,44 @@ const debugFileTypes = utils.getParam("debugfileformat");
 
 export async function onCreateLoader(url: string, context: Context): Promise<CustomLoader | GLTFLoader | FBXLoader | USDZLoader | OBJLoader | null> {
 
-    const type = await tryDetermineFileTypeFromURL(url, { useExtension: true }) || "unknown";
+    const type = await tryDetermineMimetypeFromURL(url, { useExtension: true }) || "unknown";
     if (debugFileTypes) console.debug(`Determined file type: '${type}' for url '${url}'`);
 
-    for (const callback of registeredModelLoaderCallbacks) {
-        const loader = callback({ context, url, filetype: type });
+    for (const entry of registeredModelLoaderCallbacks) {
+        const { callback } = entry;
+        let loader = callback({ context, url, mimetype: type });
+        if (loader instanceof Promise) await loader;
         if (loader) {
-            console.debug("Using custom loader");
+            console.debug(`Using custom loader (${entry.name}) for url '${url}'`);
             return loader;
         }
     }
 
     switch (type) {
         default:
-            console.warn(`Unknown file type: ${type}`);
         case "unknown":
             {
-                console.warn("Unknown file type. Assuming glTF:", url);
+                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);
                 return loader;
             }
-        case "fbx":
+        case "model/fbx":
+        case "model/vnd.autodesk.fbx":
             return new FBXLoader();
-        case "obj":
+        case "model/obj":
             return new OBJLoader();
-        case "usd":
-        case "usda":
-        case "usdz":
+        case "model/vnd.usdz+zip":
+        case "model/vnd.usd+zip":
+        case "model/vnd.usda+zip":
             {
                 console.warn(type.toUpperCase() + " files are not supported.");
                 // return new USDZLoader();
                 return null;
             }
-        case "gltf":
-        case "glb":
-        case "vrm":
+        case "model/gltf+json":
+        case "model/gltf-binary":
+        case "model/vrm":
             {
                 const loader = new GLTFLoader();
                 await registerExtensions(loader, context, url);

package/src/engine/engine_utils_format.ts

@@ -1,13 +1,24 @@
 import { isDevEnvironment } from "./debug/index.js";
-import { NeedleEngineModelLoader, registeredFileTypeCallbacks } from "./engine_loaders.callbacks.js";
+import { registeredMimetypeCallbacks } from "./engine_loaders.callbacks.js";
 import { getParam } from "./engine_utils.js";
 
 const debug = getParam("debugfileformat");
-
 /**
- * The supported file types that can be determined by the engine. Used in {@link tryDetermineFileTypeFromURL} and {@link tryDetermineFileTypeFromBinary}
+ * The supported file types that can be determined by the engine. Used in {@link tryDetermineMimetypeFromURL} and {@link tryDetermineMimetypeFromBinary}
  */
-export declare type FileType = "gltf" | "glb" | "vrm" | "fbx" | "obj" | "usdz" | "usd" | "usda" | "unknown" | ({} & string);
+export type NeedleMimetype = "unknown" |
+    "model/gltf+json" |
+    "model/gltf-binary" |
+    "model/vrm" |
+    "model/vnd.usdz+zip" |
+    "model/vnd.usd+zip" |
+    "model/vnd.usda+zip" |
+    "model/fbx" |
+    "model/vnd.autodesk.fbx" |
+    "model/obj" |
+    `model/${string}`
+    | (string & {})
+
 
 /**
  * Tries to determine the file type of a file from its URL  
@@ -21,7 +32,7 @@ export declare type FileType = "gltf" | "glb" | "vrm" | "fbx" | "obj" | "usdz" |
  * const fileType = await tryDetermineFileTypeFromURL(url);
  * console.log(fileType); // "glb"
  */
-export async function tryDetermineFileTypeFromURL(url: string, opts: { useExtension: boolean }): Promise<FileType> {
+export async function tryDetermineMimetypeFromURL(url: string, opts: { useExtension: boolean }): Promise<NeedleMimetype> {
 
     const { useExtension = true } = opts;
 
@@ -44,21 +55,21 @@ export async function tryDetermineFileTypeFromURL(url: string, opts: { useExtens
         if (debug) console.debug("Use file extension to determine type: " + ext);
         switch (ext) {
             case "GLTF":
-                return "gltf";
+                return "model/gltf+json"
             case "VRM":
-                return "vrm";
+                return "model/vrm";
             case "GLB":
-                return "glb";
+                return "model/gltf-binary";
             case "FBX":
-                return "fbx";
+                return "model/fbx";
             case "USD":
-                return "usd";
+                return "model/vnd.usd+zip";
             case "USDA":
-                return "usda";
+                return "model/vnd.usda+zip";
             case "USDZ":
-                return "usdz";
+                return "model/vnd.usdz+zip";
             case "OBJ":
-                return "obj";
+                return "model/obj";
         }
     }
 
@@ -88,7 +99,7 @@ export async function tryDetermineFileTypeFromURL(url: string, opts: { useExtens
 
     if (header?.ok) {
         const data = await header.arrayBuffer();
-        const res = tryDetermineFileTypeFromBinary(originalUrl, data, header);
+        const res = tryDetermineMimetypeFromBinary(originalUrl, data, header);
         if (debug) console.log("Determined file type from header: " + res);
         return res;
     }
@@ -100,7 +111,7 @@ export async function tryDetermineFileTypeFromURL(url: string, opts: { useExtens
 /** Attempts to determine the file type of a binary file by looking at the first few bytes of the file. 
  * @hidden 
  */
-export function tryDetermineFileTypeFromBinary(url: string, data: ArrayBuffer, response: Response): FileType {
+export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, response: Response): NeedleMimetype {
 
     if (data.byteLength < 4) {
         return "unknown";
@@ -112,67 +123,67 @@ export function tryDetermineFileTypeFromBinary(url: string, data: ArrayBuffer, r
         console.warn("Trying to determine file type from binary data\n", "\"" + new TextDecoder().decode(data) + "\"\n", bytes);
     }
 
-    // GLTF or GLB
-    if (bytes[0] == 103 && bytes[1] == 108 && bytes[2] == 84 && bytes[3] == 70) {
+    // GLTF
+    if (bytes[0] == 103 && bytes[1] == 108 && bytes[2] == 84 && bytes[3] == 70 && bytes[4] == 10) {
+        // GLTF
         console.debug("GLTF detected");
-        return "glb";
+        return "model/gltf+json";
+    }
+    // GLB
+    else if (bytes[0] == 103 && bytes[1] == 108 && bytes[2] == 84 && bytes[3] == 70 && bytes[4] == 98) {
+        // GLB
+        console.debug("GLB detected");
+        return "model/gltf-binary";
     }
     // USDZ
     if (bytes[0] == 80 && bytes[1] == 75 && bytes[2] == 3 && bytes[3] == 4) {
         console.debug("USDZ detected");
-        return "usdz";
+        return "model/vnd.usdz+zip";
     }
     // USD
     if (bytes[0] == 80 && bytes[1] == 88 && bytes[2] == 82 && bytes[3] == 45 && bytes[4] == 85 && bytes[5] == 83 && bytes[6] == 68 && bytes[7] == 67) {
         console.debug("Binary USD detected");
-        return "usd";
+        return "model/vnd.usd+zip";
     }
     // USDA: check if the file starts with #usda
     else if (bytes[0] == 35 && bytes[1] == 117 && bytes[2] == 115 && bytes[3] == 100 && bytes[4] == 97) {
         console.debug("ASCII USD detected");
-        return "usda";
+        return "model/vnd.usda+zip";
     }
     // FBX
     if (bytes[0] == 75 && bytes[1] == 97 && bytes[2] == 121 && bytes[3] == 100 && bytes[4] == 97 && bytes[5] == 114 && bytes[6] == 97 && bytes[7] == 32) {
         console.debug("Binary FBX detected");
-        return "fbx";
+        return "model/fbx";
     }
     // ASCII FBX
     else if (bytes[0] == 59 && bytes[1] == 32 && bytes[2] == 70 && bytes[3] == 66 && bytes[4] == 88 && bytes[5] == 32) {
         console.debug("ASCII FBX detected");
-        return "fbx";
+        return "model/fbx";
     }
     // OBJ - in this case exported from blender it starts with "# Blender" - we only check the first 10 bytes, technically it could still be a different file so we should do this check at the end
     else if (bytes[0] == 35 && bytes[1] == 32 && bytes[2] == 66 && bytes[3] == 108 && bytes[4] == 101 && bytes[5] == 110 && bytes[6] == 100 && bytes[7] == 101 && bytes[8] == 114 && bytes[9] == 32) {
         console.debug("OBJ detected");
-        return "obj";
+        return "model/obj";
     }
     // Check if it starts "# Alias OBJ"
     else if (bytes[0] == 35 && bytes[1] == 32 && bytes[2] == 65 && bytes[3] == 108 && bytes[4] == 105 && bytes[5] == 97 && bytes[6] == 115 && bytes[7] == 32 && bytes[8] == 79 && bytes[9] == 66 && bytes[10] == 74) {
         console.debug("OBJ detected");
-        return "obj";
+        return "model/obj";
     }
     else if (response.headers.has("content-type")) {
         const content_type = response.headers.get("content-type");
         console.debug("Content-Type: " + content_type);
         switch (content_type) {
             case "model/gltf+json":
-                return "gltf";
             case "model/gltf-binary":
-                return "glb";
             case "model/vrm":
-                return "vrm";
             case "model/vnd.usdz+zip":
-                return "usdz";
             case "model/vnd.usd+zip":
-                return "usd";
             case "model/vnd.usda+zip":
-                return "usda";
             case "model/fbx":
             case "model/vnd.autodesk.fbx":
-                return "fbx";
             case "model/obj":
-                return "obj";
+                return content_type;
             // case "model/stl":
             //     return "stl";
             case "text/plain":
@@ -205,7 +216,7 @@ export function tryDetermineFileTypeFromBinary(url: string, data: ArrayBuffer, r
     //     return "gltf";
     // }
 
-    for (const callback of registeredFileTypeCallbacks) {
+    for (const callback of registeredMimetypeCallbacks) {
         const mimetype = callback({
             url: url,
             response: response,

package/src/engine-components/ContactShadows.ts

@@ -110,6 +110,21 @@ export class ContactShadows extends Behaviour {
      */
     minSize?: Partial<Vec3>;
 
+    /**
+     * When enabled the shadows will not be updated automatically. Use `needsUpdate()` to update the shadows manually.
+     * This is useful when you want to update the shadows only when the scene changes.
+     */
+    manualUpdate: boolean = false;
+    /**
+     * Call this method to update the shadows manually. The update will be done in the next frame.
+     */
+    set needsUpdate(val: boolean) {
+        this._needsUpdate = val;
+    }
+    get needsUpdate(): boolean {
+        return this._needsUpdate;
+    }
+    private _needsUpdate: boolean = false;
 
     /** All shadow objects are parented to this object. 
      * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
@@ -288,6 +303,10 @@ export class ContactShadows extends Behaviour {
         else this.applyMinSize();
     }
 
+    onEnable(): void {
+        this._needsUpdate = true;
+    }
+
     /** @internal */
     onDestroy(): void {
         const instance = ContactShadows._instances.get(this.context);
@@ -313,6 +332,11 @@ export class ContactShadows extends Behaviour {
     /** @internal */
     onBeforeRender(_frame: XRFrame | null): void {
 
+        if (this.manualUpdate) {
+            if (!this._needsUpdate) return;
+        }
+        this._needsUpdate = false;
+
         if (!this.renderTarget || !this.renderTargetBlur ||
             !this.depthMaterial || !this.shadowCamera ||
             !this.blurPlane || !this.shadowGroup || !this.plane ||

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

@@ -3,12 +3,10 @@ import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { XRControllerModelFactory } from "three/examples/jsm/webxr/XRControllerModelFactory.js";
 import { XRHandMeshModel } from "three/examples/jsm/webxr/XRHandMeshModel.js";
 
-import { showBalloonWarning } from "../../../engine/debug/index.js";
 import { AssetReference } from "../../../engine/engine_addressables.js";
 import { setDontDestroy } from "../../../engine/engine_gameobject.js";
 import { Gizmos } from "../../../engine/engine_gizmos.js";
 import { getLoader } from "../../../engine/engine_gltf.js";
-import { createBuiltinComponents } from "../../../engine/engine_gltf_builtin_components.js";
 import { addDracoAndKTX2Loaders } from "../../../engine/engine_loaders.gltf.js";
 import { serializable } from "../../../engine/engine_serialization_decorator.js";
 import type { IGameObject, SourceIdentifier } from "../../../engine/engine_types.js";