@needle-tools/materialx 1.7.1 → 1.7.3

package/CHANGELOG.md

@@ -4,18 +4,29 @@ 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.3] - 2026-07-09
+
+### Fixed
+- Three PMREM environment sampling now reads the encoded CubeUV atlas from the base texture level, keeping glossy MaterialX reflections stable for prefiltered KTX2 environments that include hardware mip levels.
+
+## [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.
-- Added MaterialX path fixtures with reference renders for included libraries, file prefixes, relative paths, and texture-load diagnostics.
+- 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
@@ -27,8 +38,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
 
@@ -77,7 +88,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
@@ -138,7 +139,22 @@ 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 search 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.
+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.1",
+  "version": "1.7.3",
   "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

@@ -188,6 +188,10 @@ function resolveTexturePath(searchPath, value) {
         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}`);
 }
 

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

@@ -203,7 +203,10 @@ vec3 mx_cubeuv_bilinear(sampler2D envMap, vec3 direction, float mipInt) {
     uv.y += 4.0 * (exp2(u_envRadianceCubeUVMaxMip) - faceSize);
     uv.x *= u_envRadianceCubeUVTexelWidth;
     uv.y *= u_envRadianceCubeUVTexelHeight;
-    return texture(envMap, uv).rgb;
+    // PMREM encodes roughness in the CubeUV atlas itself. If the source KTX2
+    // carries hardware mip levels, implicit sampling may pick those mips and
+    // corrupt the atlas lookup.
+    return textureLod(envMap, uv, 0.0).rgb;
 }
 
 float mx_cubeuv_roughnessToMip(float roughness) {
@@ -354,6 +357,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 +422,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 +791,8 @@ $2`
         );
         } // end hasShadowUniforms
 
+        vertexShader = patchInstancingTransforms(vertexShader);
+
         const threeParameters = { ...init.parameters };
         materialParameters = {
             name: init.name,
@@ -754,7 +814,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 +831,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() },