@needle-tools/materialx 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -4,11 +4,24 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.7.2] - 2026-07-06
+
+### Fixed
+- MaterialX materials now honor Three.js `InstancedMesh` per-instance transforms in generated vertex shaders, including position, normal, and tangent transforms.
+- Raw `.mtlx` material creation can now resolve relative texture filenames through the public `path` option.
+
+## [1.7.1] - 2026-07-01
+
+### Fixed
+- Normalized MaterialX texture request paths when combining loader search paths, `fileprefix`, and relative filename values, avoiding duplicate slashes in hosted asset URLs.
+- Preserved absolute texture URLs and filename substitution tokens while resolving relative MaterialX texture paths.
+- Improved texture path handling for included MaterialX libraries, file prefixes, relative paths, and texture-load diagnostics.
+
 ## [1.7.0] - 2026-06-30
 
 ### Added
 - Runtime environment radiance modes for fast Three.js PMREM sampling, MaterialX prefiltered latlong sampling, and MaterialX filtered importance sampling.
-- MaterialX viewer examples for material library inspection, PMREM comparison, shaderball previews, configurable environments, and graph-driven material loading.
+- Browser examples for material library inspection, PMREM comparison, shaderball previews, configurable environments, and graph-driven material loading.
 - Missing tangents are now automatically generated for MaterialX materials that require them. Set `generateTangents: false` to disable this.
 
 ### Changed
@@ -20,8 +33,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Added the JSON module import attribute for `package.json` so raw browser ESM imports can read the package version without MIME errors.
 - Made Node ESM imports browser-global safe and load the bundled MaterialX WASM/data files from the installed package when `ready()` runs under Node.
 - Switched bundled MaterialX Emscripten loaders to `node:module` builtin imports for Deno compatibility, and added runtime smoke scripts for Node, Deno, and Bun.
-- Corrected material parameter editing for color values, environment controls, and graph-loaded materials in the viewer examples.
-- Kept viewer debug panels and camera controls consistent across the material library, graph, shadows, and complex scenes.
+- Corrected material parameter editing for color values, environment controls, and graph-loaded materials in browser examples.
+- Improved consistency of example controls and camera behavior across the material library, graph, shadows, and complex scenes.
 
 ## [1.6.0] – 2026-04-01
 
@@ -70,7 +83,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Fix: Improved error log formatting with package version
 
 ## [1.4.4] – 2026-03-17
-- Fix: Minor type fixes and improved debug logging
+- Fix: Minor type fixes and improved logging
 
 ## [1.4.3] – 2026-02-20
 - Add: `globalThis.NEEDLE_MATERIALX_LOCATION` to override WASM location. Use `"package"` for package-local files, or a custom path for self-hosted/CDN.

package/README.md

@@ -6,6 +6,7 @@ Web runtime for [MaterialX](https://materialx.org/) materials in [Needle Engine]
 - Vertex displacement support (procedural noise, texture-based, animatable)
 - Material-level ambient occlusion (per glTF specification)
 - UV coordinate convention handling (glTF ↔ OpenGL)
+- Three.js `InstancedMesh` support for generated MaterialX shaders
 - Automatic MikkTSpace tangent generation when MaterialX shaders need tangents
 - Three.js shadow support (directional, spot, point lights)
 - Alpha mask and blend transparency modes
@@ -136,6 +137,25 @@ globalThis.NEEDLE_MATERIALX_LOCATION = "/assets/materialx/";
 
 IMPORTANT: The value must end with a trailing slash (`/`).
 
+### Texture Path Resolution
+
+MaterialX texture filenames are resolved from the MaterialX-authored filename value, any active `fileprefix`, and the loader path. Relative paths are normalized for web requests so hosted asset URLs do not gain duplicate slashes, while absolute URLs such as `https://`, `file://`, root-relative paths, data URIs, blob URLs, and MaterialX filename tokens such as `<UDIM>` are preserved.
+
+For raw `.mtlx` XML loaded from a URL, pass the containing directory as `path`, matching the `parse(data, path, ...)` convention used by Three.js loaders:
+
+```ts
+const material = await Experimental_API.createMaterialXMaterial(
+    mtlxSource,
+    0,
+    {
+        getTexture: async (url) => textureLoader.loadAsync(url),
+    },
+    {
+        path: "https://example.com/materials/",
+    },
+);
+```
+
 
 ## glTF Extension: NEEDLE_materials_mtlx
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@needle-tools/materialx",
   "description": "MaterialX material support for three.js and Needle Engine – render physically based MaterialX shaders in the browser via WebAssembly",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "type": "module",
   "license": "PolyForm-Noncommercial-1.0.0",
   "main": "index.js",

package/src/loader/loader.three.d.ts

@@ -46,6 +46,8 @@ export interface MaterialXLoaderOptions {
     specularAntialiasing?: boolean;
     /** Generate missing MikkTSpace tangents for tangent-dependent shaders. Defaults to true. */
     generateTangents?: boolean;
+    /** Base path used to resolve relative MaterialX texture filenames for raw .mtlx material creation. */
+    path?: string;
     /** Flip texcoord V at the MaterialX texcoord node output. Defaults to false for standalone .mtlx creation and true for GLTFLoader integration. */
     hwTexcoordVerticalFlip?: boolean;
     /** Flip texcoord V inside MaterialX file texture sampling. Defaults to false for standalone .mtlx creation and true for GLTFLoader integration. */

package/src/loader/loader.three.js

@@ -359,6 +359,7 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
             environmentRadianceMode: options?.environmentRadianceMode,
             specularAntialiasing: options?.specularAntialiasing,
             generateTangents: options?.generateTangents,
+            path: options?.path,
             parameters: {
                 // MASK uses discard; BLEND uses Three.js transparent sorting and blending.
                 transparent: renderAsTransparent,

package/src/materialx.helper.js

@@ -122,6 +122,79 @@ function addToCache(key, value) {
     if (debug) console.log('[MaterialX] Added to cache:', key, value);
 }
 
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteTexturePath(value) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//") || value.startsWith("/");
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteUrl(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function withTrailingSlash(value) {
+    return value.endsWith(IMAGE_PATH_SEPARATOR) ? value : `${value}${IMAGE_PATH_SEPARATOR}`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeRelativeTexturePath(value) {
+    const suffixStart = value.search(/[?#]/);
+    const path = suffixStart >= 0 ? value.slice(0, suffixStart) : value;
+    const suffix = suffixStart >= 0 ? value.slice(suffixStart) : "";
+    const hasLeadingSlash = path.startsWith(IMAGE_PATH_SEPARATOR);
+    const parts = [];
+
+    for (const part of path.split(IMAGE_PATH_SEPARATOR)) {
+        if (!part || part === ".") continue;
+        if (part === "..") {
+            const previous = parts[parts.length - 1];
+            if (previous && previous !== "..") parts.pop();
+            else if (!hasLeadingSlash) parts.push(part);
+            continue;
+        }
+        parts.push(part);
+    }
+
+    const normalizedPath = `${hasLeadingSlash ? IMAGE_PATH_SEPARATOR : ""}${parts.join(IMAGE_PATH_SEPARATOR)}`;
+    return `${normalizedPath}${suffix}`;
+}
+
+/**
+ * @param {string} searchPath
+ * @param {string} value
+ * @returns {string}
+ */
+function resolveTexturePath(searchPath, value) {
+    if (isAbsoluteTexturePath(value)) return value;
+    if (!searchPath) return value;
+
+    const normalizedSearchPath = searchPath.replace(/\/+$/, "");
+    if (!normalizedSearchPath) return value;
+
+    if (isAbsoluteUrl(normalizedSearchPath)) {
+        return new URL(value, withTrailingSlash(normalizedSearchPath)).href;
+    }
+
+    if (THREE.LoaderUtils?.resolveURL) {
+        return normalizeRelativeTexturePath(THREE.LoaderUtils.resolveURL(value, withTrailingSlash(normalizedSearchPath)));
+    }
+
+    return normalizeRelativeTexturePath(`${normalizedSearchPath}${IMAGE_PATH_SEPARATOR}${value}`);
+}
+
 /**
  * Get Three uniform from MaterialX value
  * @param {any} uniforms
@@ -165,19 +238,19 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
                 // Cache / reuse texture to avoid reload overhead.
                 // Note: that data blobs and embedded data textures are not cached as they are transient data.
                 let checkCache = true;
-                let texturePath = searchPath + IMAGE_PATH_SEPARATOR + value;
+                let texturePath = value;
                 if (value.startsWith('blob:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('data:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('http')) {
-                    texturePath = value;
                     checkCache = true;
                 }
+                else {
+                    texturePath = resolveTexturePath(searchPath, value);
+                }
 
                 const cacheKey = loaders.cacheKey?.length ? `${loaders.cacheKey}-${texturePath}` : texturePath;
                 const cacheValue = checkCache ? tryGetFromCache(cacheKey) : null;
@@ -247,7 +320,7 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
         case 'displacementshader':
         case 'volumeshader':
         case 'lightshader':
-            // MaterialX closure/shader types — not real uniforms, skip silently
+            // MaterialX closure/shader types — not emitted uniforms, skip silently
             break;
         default:
             const key = type + ':' + name;

package/src/materialx.material.d.ts

@@ -13,6 +13,7 @@ declare type MaterialXMaterialInitParameters = {
     environmentRadianceMode?: MaterialXEnvironmentRadianceMode;
     specularAntialiasing?: boolean;
     generateTangents?: boolean;
+    path?: string;
     debug?: boolean;
 }
 

package/src/materialx.material.js

@@ -354,6 +354,60 @@ function patchImageAddressModes(fragmentShader) {
     );
 }
 
+function patchInstancingTransforms(vertexShader) {
+    if (!vertexShader.includes('u_worldMatrix') || vertexShader.includes('mtlxWorldMatrix')) return vertexShader;
+
+    let helper = `
+mat4 mtlxWorldMatrix()
+{
+#ifdef USE_INSTANCING
+    return u_worldMatrix * instanceMatrix;
+#else
+    return u_worldMatrix;
+#endif
+}
+`;
+
+    if (vertexShader.includes('u_worldInverseTransposeMatrix')) {
+        helper += `
+vec3 mtlxWorldNormal(vec3 objectNormal)
+{
+    vec3 transformedNormal = objectNormal;
+#ifdef USE_INSTANCING
+    mat3 instanceNormalMatrix = mat3(instanceMatrix);
+    transformedNormal /= vec3(
+        dot(instanceNormalMatrix[0], instanceNormalMatrix[0]),
+        dot(instanceNormalMatrix[1], instanceNormalMatrix[1]),
+        dot(instanceNormalMatrix[2], instanceNormalMatrix[2])
+    );
+    transformedNormal = instanceNormalMatrix * transformedNormal;
+#endif
+    return normalize(mat3(u_worldInverseTransposeMatrix) * transformedNormal);
+}
+`;
+    }
+
+    vertexShader = vertexShader.replace(/void\s+main\s*\(\s*\)\s*\{/, `${helper}\nvoid main() {`);
+    vertexShader = vertexShader.replaceAll(
+        'u_worldMatrix * vec4(position, 1.0)',
+        'mtlxWorldMatrix() * vec4(position, 1.0)',
+    );
+    vertexShader = vertexShader.replaceAll(
+        'mx_matrix_mul(u_worldMatrix, vec4(tangent, 0.0)).xyz',
+        '(mtlxWorldMatrix() * vec4(tangent, 0.0)).xyz',
+    );
+    vertexShader = vertexShader.replaceAll(
+        'normalize(mx_matrix_mul(u_worldInverseTransposeMatrix, vec4(normal, 0.0)).xyz)',
+        'mtlxWorldNormal(normal)',
+    );
+    vertexShader = vertexShader.replaceAll(
+        'normalize(mat3(viewMatrix) * mat3(u_worldInverseTransposeMatrix) * normal)',
+        'normalize(mat3(viewMatrix) * mtlxWorldNormal(normal))',
+    );
+
+    return vertexShader;
+}
+
 /**
  * @typedef {Object} MaterialXMaterialInitParameters
  * @property {string} name
@@ -365,6 +419,7 @@ function patchImageAddressModes(fragmentShader) {
  * @property {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} [environmentRadianceMode]
  * @property {boolean} [specularAntialiasing] - Match Three.js glossy specular antialiasing. Defaults to true.
  * @property {boolean} [generateTangents] - Generate missing MikkTSpace tangents for tangent-dependent shaders. Defaults to true.
+ * @property {string} [path] - Base path used to resolve relative MaterialX texture filenames.
  * @property {boolean} [debug] - Debug flag
  */
 
@@ -733,6 +788,8 @@ $2`
         );
         } // end hasShadowUniforms
 
+        vertexShader = patchInstancingTransforms(vertexShader);
+
         const threeParameters = { ...init.parameters };
         materialParameters = {
             name: init.name,
@@ -754,7 +811,7 @@ $2`
             return;
         }
 
-        const searchPath = ""; // Could be derived from the asset path if needed
+        const path = init.path || "";
         /** @type {Array<Promise<unknown>>} */
         const pendingTextureLoads = [];
         this.shaderName = init.shaderName || null;
@@ -771,8 +828,8 @@ $2`
             // uniforms below must keep their original object identity so async
             // texture resolution updates the same uniform object.
             mergeUniforms([createThreeLightUniforms()]),
-            getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath, pendingTextureLoads),
-            getUniformValues(init.shader.getStage('pixel'), init.loaders, searchPath, pendingTextureLoads),
+            getUniformValues(init.shader.getStage('vertex'), init.loaders, path, pendingTextureLoads),
+            getUniformValues(init.shader.getStage('pixel'), init.loaders, path, pendingTextureLoads),
             {
                 u_worldMatrix: { value: new Matrix4() },
                 u_worldInverseMatrix: { value: new Matrix4() },