@needle-tools/engine 4.12.5 → 4.13.0-next.2d429c0

package/src/engine/engine_loaders.ts

@@ -18,6 +18,7 @@ import * as utils from "./engine_utils.js";
 import { tryDetermineMimetypeFromURL } from "./engine_utils_format.js"
 import { invokeLoadedImportPluginHooks, registerComponentExtension, registerExtensions } from "./extensions/extensions.js";
 import { NEEDLE_components } from "./extensions/NEEDLE_components.js";
+import { MaterialXLoader } from "./extensions/NEEDLE_materialx.js";
 
 /** @internal */
 export class NeedleLoader implements INeedleGltfLoader {
@@ -43,7 +44,7 @@ const debugFileTypes = utils.getParam("debugfileformat");
 
 
 
-async function onCreateLoader(url: string, context: Context, sourceId: SourceIdentifier): Promise<CustomLoader | GLTFLoader | FBXLoader | USDZLoader | OBJLoader | null> {
+async function onCreateLoader(url: string, context: Context, sourceId: SourceIdentifier): Promise<CustomLoader | GLTFLoader | FBXLoader | USDZLoader | OBJLoader | MaterialXLoader | null> {
 
     const type = await tryDetermineMimetypeFromURL(url, { useExtension: true }) || "unknown";
     if (debugFileTypes) console.debug(`Determined file type: '${type}' for url '${url}'`, { registeredModelLoaderCallbacks });
@@ -91,6 +92,12 @@ async function onCreateLoader(url: string, context: Context, sourceId: SourceIde
                 await registerExtensions(loader, context, url, sourceId);
                 return loader;
             }
+
+        case "application/materialx+xml":
+            {
+                const loader = new MaterialXLoader();
+                return loader;
+            }
     }
 }
 
@@ -133,7 +140,7 @@ export async function parseSync(context: Context, data: string | ArrayBuffer, pa
     // Handle any other loader that is not a GLTFLoader
     const isNotGLTF = !(loader instanceof GLTFLoader);
     if (isNotGLTF) {
-        if (loader.parse === undefined) {
+        if (!("parse" in loader) || typeof loader.parse !== "function") {
             console.error("Loader does not support parse");
             return undefined;
         }

package/src/engine/engine_modules.ts

@@ -8,6 +8,30 @@
  */
 export namespace MODULES {
 
+    export namespace MaterialX {
+        export type TYPE = typeof import("@needle-tools/materialx");
+        export let MODULE: TYPE;
+        export let MAYBEMODULE: TYPE | null = null;
+
+        const callbacks: Array<(module: TYPE) => void> = [];
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        export function ready(): Promise<TYPE> {
+            if (MODULE) return Promise.resolve(MODULE);
+            return new Promise((resolve) => { callbacks.push(resolve); });
+        };
+        /** Load the module */
+        export async function load(): Promise<TYPE> {
+            if (MODULE) return MODULE;
+            const module = await import("@needle-tools/materialx");
+            MODULE = module;
+            MAYBEMODULE = module;
+            callbacks.forEach((callback) => callback(module));
+            callbacks.length = 0;
+            return module;
+        }
+
+    }
+
     export namespace RAPIER_PHYSICS {
         export type TYPE = typeof import("@dimforge/rapier3d-compat");
         export let MODULE: TYPE;

package/src/engine/engine_utils_format.ts

@@ -16,7 +16,8 @@ export type NeedleMimetype = "unknown" | "unsupported" |
     "model/vnd.usdc" |
     "model/fbx" |
     "model/vnd.autodesk.fbx" |
-    "model/obj"
+    "model/obj" |
+    "application/materialx+xml"
     | (string & {})
 
 
@@ -95,6 +96,8 @@ export async function tryDetermineMimetypeFromURL(url: string, opts: { useExtens
                 return "model/vnd.usdz+zip";
             case "OBJ":
                 return "model/obj";
+            case "MTLX":
+                return "application/materialx+xml";
         }
     }
 
@@ -222,6 +225,7 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
             case "model/fbx":
             case "model/vnd.autodesk.fbx":
             case "model/obj":
+            case "application/materialx+xml":
                 return content_type;
             // case "model/stl":
             //     return "stl";
@@ -271,7 +275,7 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
 
     if (isDevEnvironment() || debug) {
         const text = new TextDecoder().decode(data.slice(0, Math.min(data.byteLength, 32)));
-        console.warn(`Could not determine file type.\n\nConsider registering a custom loader via the 'onCreateCustomModelLoader' callback: 'NeedleEngineModelLoader.onCreateCustomModelLoader(args => { })'\n\nContent-Type: \"${response.headers.get("content-type")}\n\"Text: \"${text}\"\nBinary:`, bytes);
+        console.warn(`Could not determine file type.\n\nConsider registering a custom loader via the 'onCreateCustomModelLoader' callback: 'NeedleEngineModelLoader.onCreateCustomModelLoader(args => { })'\n\nContent-Type: \"${response.headers.get("content-type")}\"\n\"Text: \"${text}\"\nBinary:`, bytes);
     }
     else {
         console.debug(`Could not determine file type from binary data`);

package/src/engine/extensions/NEEDLE_materialx.ts

@@ -0,0 +1,142 @@
+import { Loader, LoadingManager, Material, Object3D, TextureLoader } from "three";
+import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader";
+import { ObjectUtils } from "../engine_create_objects";
+import { MODULES } from "../engine_modules";
+import { IContext } from "../engine_types";
+
+
+// #region Utils
+
+export namespace MaterialX {
+
+
+    /**
+     * Utility function to load a MaterialX material from a URL. This can be used in your own code to load MaterialX materials outside of the glTF loading process. The URL should point to a MaterialX XML file.
+     */
+    export async function loadFromUrl(urlOrXML: string,
+        opts?: {
+            url?: string,
+            loadingManager?: LoadingManager,
+            materialNameOrIndex?: number | string
+        }
+    ): Promise<import("three").Material | null> {
+
+        if (!urlOrXML) throw new Error("URL or XML string is required to load a MaterialX material");
+
+        // Ensure the MaterialX module is loaded
+        const module = await MODULES.MaterialX.load();
+
+        // Check if the input is an XML string or a URL
+        // And fetch the XML content if it's a URL
+        const isXmlString = urlOrXML.trimStart().startsWith("<");
+        const xml = isXmlString ? urlOrXML : await fetch(urlOrXML).then(r => r.text()).catch(console.error);
+        if (!xml) {
+            console.warn("Failed to load MaterialX file from url", urlOrXML);
+            return null;
+        }
+
+        // For relative texture paths we might need to detect the base directory of the material file. 
+        // We can only do this if we have a URL (not an XML string) and if the URL is not a data URL. In that case we can use the URL to determine the base path for textures.
+        // This can be used by the loader callback to resolve texture paths relative to the material file.
+        let dir: string | undefined = undefined;
+        if (opts?.url || !isXmlString) {
+            const parts = (opts?.url || urlOrXML).split('/');
+            parts.pop();
+            dir = parts.join('/');
+        }
+
+        const textureLoader = new TextureLoader();
+        return module.Experimental_API.createMaterialXMaterial(xml, opts?.materialNameOrIndex ?? 0, {
+            getTexture: async url => {
+                if (!url.startsWith("http") && !url.startsWith("data:") && !url.startsWith("blob:") && !url.startsWith("file:")) {
+                    if (dir) {
+                        url = dir + "/" + url;
+                    }
+                }
+                return textureLoader.loadAsync(url).catch(e => {
+                    console.warn(`Failed to load texture for MaterialX material ${url}`, e);
+                });
+            }
+        }, {
+            cacheKey: urlOrXML,
+        })
+    }
+}
+
+
+// #region Loader
+
+export class MaterialXLoader extends Loader<Object3D | null> {
+
+    loadAsync(url: string, onProgress?: ((event: ProgressEvent<EventTarget>) => void) | undefined): Promise<Object3D> {
+        return new Promise((resolve, reject) => {
+            this.load(url, resolve, onProgress, reject);
+        });
+    }
+
+    load(url: string, onLoad: (data: Object3D) => void, onProgress?: ((event: ProgressEvent<EventTarget>) => void) | undefined, onError?: ((err: unknown) => void) | undefined): void {
+        onProgress?.({ type: "progress", loaded: 0, total: 0 } as ProgressEvent);
+
+        MaterialX.loadFromUrl(url, {
+        }).then(mat => {
+            if (mat) {
+                onLoad(this.onLoaded(mat));
+            }
+            else {
+                onError?.(new Error("Failed to load MaterialX material from url: " + url));
+            }
+        });
+    }
+
+    private onLoaded(mat: Material): Object3D {
+        const shaderball = ObjectUtils.createPrimitive("ShaderBall", { material: mat });
+        return shaderball;
+    }
+}
+
+
+
+// #region GLTF Extension
+
+export class NEEDLE_materialx implements GLTFLoaderPlugin {
+
+    get name(): string {
+        return "materialx-loading-helper";
+    }
+
+    constructor(
+        private readonly context: IContext,
+        private readonly loader: GLTFLoader,
+        private readonly url: string,
+        private readonly parser: GLTFParser,
+    ) {
+    }
+
+    private mtlxLoader?: import("@needle-tools/materialx").MaterialXLoader;
+
+    async beforeRoot() {
+        const mtlxExtension = this.parser.json.extensions?.["NEEDLE_materials_mtlx"];
+        if (mtlxExtension) {
+            const module = await MODULES.MaterialX.load();
+            try {
+                this.mtlxLoader = new module.MaterialXLoader(this.parser, {
+                    cacheKey: `${this.url}:materialx`,
+                    parameters: {
+                        precision: this.context.renderer?.capabilities.precision as any,
+                    }
+                }, {
+                    getFrame: () => this.context.time.frame,
+                    getTime: () => this.context.time.time,
+                })
+            }
+            catch (error) {
+                console.error(error);
+            }
+        }
+    }
+
+    loadMaterial(index) {
+        if (this.mtlxLoader) return this.mtlxLoader.loadMaterial(index);
+        return null;
+    }
+}

package/src/engine/extensions/extensions.ts

@@ -12,6 +12,7 @@ import { EXT_texture_exr } from "./EXT_texture_exr.js";
 import { NEEDLE_components } from "./NEEDLE_components.js";
 import { NEEDLE_gameobject_data } from "./NEEDLE_gameobject_data.js";
 import { NEEDLE_lighting_settings } from "./NEEDLE_lighting_settings.js";
+import { NEEDLE_materialx } from "./NEEDLE_materialx.js";
 import { NEEDLE_persistent_assets } from "./NEEDLE_persistent_assets.js";
 import { NEEDLE_progressive } from "./NEEDLE_progressive.js";
 import { NEEDLE_render_objects } from "./NEEDLE_render_objects.js";
@@ -136,6 +137,7 @@ export async function registerExtensions(loader: GLTFLoader, context: Context, u
     loader.register(p => new NEEDLE_render_objects(p, sourceId));
     loader.register(p => new NEEDLE_progressive(p));
     loader.register(p => new EXT_texture_exr(p));
+    loader.register(p => new NEEDLE_materialx(context, loader, url, p));
     if (isResourceTrackingEnabled()) loader.register(p => new InternalUsageTrackerPlugin(p))
 
     await KHR_ANIMATIONPOINTER_IMPORT.catch(_ => { })

package/src/engine/extensions/index.ts

@@ -3,4 +3,5 @@ export * from "./extensions.js"
 export * from "./NEEDLE_animator_controller_model.js"
 export { SceneLightSettings } from "./NEEDLE_lighting_settings.js"
 export * from "./NEEDLE_progressive.js"
-export { CustomShader } from "./NEEDLE_techniques_webgl.js"
+export { CustomShader } from "./NEEDLE_techniques_webgl.js"
+export { MaterialX } from "./NEEDLE_materialx.js"

package/src/engine-components/ContactShadows.ts

@@ -74,6 +74,7 @@ export class ContactShadows extends Behaviour {
         let instance = this._instances.get(context);
         if (!instance || instance.destroyed) {
             const obj = new Object3D();
+            obj.name = "ContactShadows";
             instance = addComponent(obj, ContactShadows, {
                 autoFit: false,
                 occludeBelowGround: false
@@ -295,7 +296,12 @@ export class ContactShadows extends Behaviour {
         this.shadowCamera = new OrthographicCamera(-1 / 2, 1 / 2, 1 / 2, -1 / 2, near, far);
         this.shadowCamera.layers.enableAll();
         this.shadowCamera.rotation.x = Math.PI / 2; // get the camera to look up
+        // Disable automatic matrix world updates because Camera.updateMatrixWorld
+        // resets scale to 1 which would break the shadow camera transform
+        this.shadowCamera.matrixWorldAutoUpdate = false;
         this.shadowGroup.add(this.shadowCamera);
+        // Update the local matrix after setting position/rotation
+        this.shadowCamera.updateMatrix();
 
         // like MeshDepthMaterial, but goes from black to transparent
         this.depthMaterial = new MeshDepthMaterial();
@@ -442,6 +448,15 @@ export class ContactShadows extends Behaviour {
             }
         }
 
+        // Manually update shadow camera's matrix world without calling Camera.updateMatrixWorld
+        // (which would reset scale to 1 for glTF conformance)
+        if (this.shadowCamera.parent) {
+            this.shadowCamera.matrixWorld.multiplyMatrices(this.shadowCamera.parent.matrixWorld, this.shadowCamera.matrix);
+        } else {
+            this.shadowCamera.matrixWorld.copy(this.shadowCamera.matrix);
+        }
+        this.shadowCamera.matrixWorldInverse.copy(this.shadowCamera.matrixWorld).invert();
+
         // render to the render target to get the depths
         renderer.setRenderTarget(this.renderTarget);
         renderer.clear();

package/src/engine-components/Skybox.ts

@@ -443,7 +443,7 @@ 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:");
+        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:") && !str.startsWith("/")
         if(noUrlOrFile) {
             console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
         }

package/plugins/vite/materialx.js

@@ -1,32 +0,0 @@
-import { existsSync } from 'fs';
-
-const materialx_packagejson_path = "node_modules/@needle-tools/materialx/package.json";
-const materialx_import_chunk = `
-import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
-useNeedleMaterialX();
-`
-
-/**
- * Vite plugin to automatically setup the MaterialX loader for Needle Engine.
- * @param {string} command 
- * @param {object} config
- * @param {import('../types/userconfig.js').userSettings} userSettings
- * @returns {import('vite').Plugin}
- */
-export const needleMaterialXLoader = (command, config, userSettings) => {
-
-    return {
-        name: 'needle-materialx-loader',
-        transform: (code, id) => {
-            if (id.endsWith("src/main.ts")) {
-                if (userSettings?.loadMaterialX !== false && existsSync(materialx_packagejson_path)) {
-                    if (!code.includes("@needle-tools/materialx")) {
-                        console.log("[needle-materialx-loader] Adding MaterialX import to main.ts");
-                        code = materialx_import_chunk + "\n" + code;
-                    }
-                }
-            }
-            return code;
-        }
-    }
-}