@needle-tools/materialx 1.5.0-next.b9d5f3f → 1.5.1

package/CHANGELOG.md

@@ -4,35 +4,70 @@ 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.5.0] – 2026-03-19
+## [1.5.1] – 2026-03-22
+
+### Fixed
+- UV patching: always wrap vec3 targets regardless of source UV declaration type
+- Vertex color: wrap vec3→vec4 for color attributes (Three.js provides vec3)
+- Shader test page uses proper environment/lighting matching other test pages
+
+### Added
+- Playwright e2e tests validating 111+ MaterialX materials for shader compilation
+
+## [1.5.0] – 2026-03-20
 
 ### Added
 - Vertex displacement support (GLSL and ESSL/WebGL 2)
-- Multioutput nodedef pattern for shared surface + displacement parameters
 - Normal recomputation via screen-space derivatives (dFdx/dFdy) for displaced surfaces
 - Procedural noise displacement (fractal3d, position, math nodes)
 - Texture-based displacement (image node sampling in vertex shader)
 - Displacement animation support via Three.js PropertyBinding
+- Three.js shadow support for lit MaterialX shaders (directional, spot, point)
+- Alpha mode detection via `getAlphaMode` for mask/blend transparency
 
 ### Fixed
-- Skip MaterialX shader closure types (surfaceshader, displacementshader, etc.) in uniform handling instead of logging warnings
-- Alpha mode detection improvements for transparent materials
+- Unlit shaders no longer emit shadow uniforms that cause compilation errors
+- UV vec2/vec3 patching for displacement vertex shaders
+- Skip MaterialX shader closure types (surfaceshader, displacementshader, etc.) in uniform handling
 
 ### Changed
 - WASM rebuilt with displacement support (MaterialX 1.39.4, Emscripten 3.1.74)
+- Environment map intensity now combines per-material and scene intensity
+
+## [1.4.6] – 2026-03-17
+- Fix: Compatibility with older Rollup/Vite 4 by replacing `import ... with` syntax
+
+## [1.4.5] – 2026-03-17
+- Fix: Improved error log formatting with package version
+
+## [1.4.4] – 2026-03-17
+- Fix: Minor type fixes and improved debug logging
 
 ## [1.4.3] – 2026-02-20
-- Feat: Add `globalThis.NEEDLE_MATERIALX_LOCATION` to override WASM location. Use `"package"` for package-local files, or a custom path for self-hosted/CDN.
+- Add: `globalThis.NEEDLE_MATERIALX_LOCATION` to override WASM location. Use `"package"` for package-local files, or a custom path for self-hosted/CDN.
 
 ## [1.4.2] – 2026-02-10
 - Fix: Improve error handling when MaterialX renderable element is not found
 
 ## [1.4.1] – 2026-02-10
-- Feat: Use MaterialX from CDN by default
+- Change: Use CDN as default WASM source
+
+## [1.4.0] – 2026-02-10
+- Change: Load WASM binaries from Needle CDN by default instead of bundling locally
+
+## [1.3.4] – 2026-02-09
+- Fix: Matrix update for AR sessions
+
+## [1.3.3] – 2026-02-09
+- Add: Support for loading `.mtlx` files by index
+- Fix: Type fixes in loader
 
 ## [1.3.2] - 2025-08-12
 - Fix: Error when MaterialX extension is not present
 
+## [1.3.1] - 2025-08-12
+- Docs: README improvements
+
 ## [1.3.0] - 2025-08-12
 - Change: Refactor extension to use a documents array instead of a single document, backwards compatibility is maintained
 
@@ -40,7 +75,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add: `preloadWasm` function with support to wait for network idle. This is automatically done for Needle Engine projects.
 
 ## [1.2.1] - 2025-07-23
-- Fix: error caused by scene.environment being null 
+- Fix: Error caused by scene.environment being null
 
 ## [1.2.0] - 2025-07-23
 - Add: Support to load raw MaterialX materials (from mtlx as XML)
@@ -52,12 +87,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add: `useNeedleMaterialX` hooks for vanilla three.js and Needle Engine
 
 ## [1.0.6] - 2025-07-15
-- Fix: texture/environment sampling on some Android devices
+- Fix: Texture/environment sampling on some Android devices
+
+## [1.0.3] - 2025-07-10
+- Fix: Version bump for npm publish
 
 ## [1.0.2] - 2025-07-10
 - Add: Material extension `doubleSided` support
-- Improved lighting support
-- Improved texture loading and fix bug where glTF texture index was not resolved properly
+- Fix: Improved lighting support
+- Fix: Texture loading and glTF texture index resolution
 
 ## [1.0.1] - 2025-07-08
 - Initial release

package/README.md

@@ -1,9 +1,11 @@
 # Needle MaterialX – MaterialX Materials for three.js & the Web
 
-Web runtime for [MaterialX](https://materialx.org/) materials in [Needle Engine](https://needle.tools) and [three.js](https://threejs.org/). Renders physically based MaterialX shaders in the browser using WebAssembly — load `.mtlx` files or glTF assets with the `NEEDLE_materials_mtlx` extension.
+Web runtime for [MaterialX](https://materialx.org/) materials in [Needle Engine](https://needle.tools) and [three.js](https://threejs.org/). Renders physically based MaterialX shaders in the browser using WebAssembly — load `.mtlx` files or glTF assets with the `NEEDLE_materials_mtlx` extension (created with Needle Engine's Unity integration and ShaderGraph).
 
 - MaterialX to WebGL/WebGPU shader generation via WASM
 - Vertex displacement support (procedural noise, texture-based, animatable)
+- Three.js shadow support (directional, spot, point lights)
+- Alpha mask and blend transparency modes
 - glTF extension for embedding MaterialX materials in `.glb`/`.gltf` files
 - Experimental support for loading raw MaterialX XML (`.mtlx`) files
 - Works standalone with three.js or as a Needle Engine module
@@ -23,16 +25,22 @@ Web runtime for [MaterialX](https://materialx.org/) materials in [Needle Engine]
 
 ### Use with Needle Engine
 
-**Needle Engine has built in support for MaterialX shaders.** No changes to your code are necessary. The MaterialX module will import lazily when needed.
+**Needle Engine has built in support for MaterialX shaders.**   
+No changes to your code are necessary. The MaterialX module will import lazily when needed.
 
 ### Use with three.js
 
 ```ts
 import { useNeedleMaterialX } from "@needle-tools/materialx";
-// Call the function with your GLTFLoader instance
+// Call the function with your GLTFLoader instance to add the GLTFLoader plugin
 useNeedleMaterialX(<yourGltfLoaderInstance>);
 ```
 
+### Accessing Materials
+MaterialX shaders will create `MaterialXMaterial` materials at runtime. These are custom three.js ShaderMaterials and assigned to objects like any other three.js material.  
+
+[Learn more in the Needle Engine documentation](https://engine.needle.tools/docs/how-to-guides/export/materialx.html)
+
 ## WASM
 
 ### Default (CDN)

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.5.0-next.b9d5f3f",
+  "version": "1.5.1",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/src/materialx.material.js

@@ -122,7 +122,9 @@ export class MaterialXMaterial extends ShaderMaterial {
         fragmentShader = fragmentShader.replace(/\bu_envLightIntensity\b/g, 'envMapIntensity');
 
         // Capture some vertex shader properties
-        const uv_is_vec2 = vertexShader.includes('in vec2 uv;'); // check if uv is vec2; e.g. https://matlib.gpuopen.com/main/materials/all?material=da6ec531-f5c1-4790-ac14-8a5c51d0314e
+        // Detect whether each UV was originally vec2 or vec3 before removing declarations.
+        // Three.js always provides vec2 attributes, so vec3 assignments need wrapping.
+        const uv_is_vec2 = vertexShader.includes('in vec2 uv;');
         const uv1_is_vec2 = vertexShader.includes('in vec2 uv1;');
         const uv2_is_vec2 = vertexShader.includes('in vec2 uv2;');
         const uv3_is_vec2 = vertexShader.includes('in vec2 uv3;');
@@ -142,20 +144,41 @@ export class MaterialXMaterial extends ShaderMaterial {
         vertexShader = vertexShader.replace(/in\s+vec4\s+tangent;/g, '');
         var hasColor = vertexShader.includes('in vec4 color;');
         vertexShader = vertexShader.replace(/in\s+vec4\s+color;/g, '');
+        // Three.js provides `color` as vec3 but MaterialX declares it as vec4.
+        // Wrap assignments to vec4 targets: `color_0 = color;` → `color_0 = vec4(color, 1.0);`
+        if (hasColor) {
+            vertexShader = vertexShader.replace(/\bvec4 (\w+) = color;/g, 'vec4 $1 = vec4(color, 1.0);');
+            vertexShader = vertexShader.replace(/(\w+) = color;/g, (match, name) => {
+                if (match.includes('vec4')) return match;
+                const isVec4 = new RegExp(`\\bvec4\\s+${name}\\b`).test(vertexShader);
+                return isVec4 ? `${name} = vec4(color, 1.0);` : match;
+            });
+        }
 
-        // Patch uv 2-component to 3-component. Three.js UVs are vec2 but MaterialX
-        // texcoords may be vec3. Replace all `= uv;` assignments where the type is vec3.
-        // This covers both vertex data connectors (texcoord_0 = uv) and displacement
-        // dependency outputs (uv_0_out = uv).
-        if (!uv_is_vec2) vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv;/g, 'vec3 $1 = vec3(uv, 0.0);');
-        if (!uv1_is_vec2) vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv1;/g, 'vec3 $1 = vec3(uv1, 0.0);');
-        if (!uv2_is_vec2) vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv2;/g, 'vec3 $1 = vec3(uv2, 0.0);');
-        if (!uv3_is_vec2) vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv3;/g, 'vec3 $1 = vec3(uv3, 0.0);');
-        // Also handle non-declaration assignments (e.g. `texcoord_0 = uv;`)
-        if (!uv_is_vec2) vertexShader = vertexShader.replace(/(\w+) = uv;/g, (match, name) => {
-            // Only replace if not already a vec3() call
-            return match.includes('vec3') ? match : `${name} = vec3(uv, 0.0);`;
-        });
+        // Patch uv vec2→vec3. Three.js always provides uv/uv1/uv2/uv3 as vec2
+        // attributes. When MaterialX originally declared them as vec3, any
+        // assignment from these attributes to a vec3 variable needs wrapping.
+        // When the UV was originally vec2, all assignments are already compatible.
+        // Three.js always provides uv/uv1/uv2/uv3 as vec2 attributes.
+        // When the generated shader assigns them to vec3 variables, we need to wrap.
+        // This applies regardless of the original declaration type, because Three.js
+        // always delivers vec2.
+        /** @param {string} shader @param {string} uvName */
+        function patchUvAssignments(shader, uvName) {
+            // 1. Declaration assignments: `vec3 x = <uv>;` → `vec3 x = vec3(<uv>, 0.0);`
+            shader = shader.replace(new RegExp(`\\bvec3 (\\w+) = ${uvName};`, 'g'), `vec3 $1 = vec3(${uvName}, 0.0);`);
+            // 2. Non-declaration assignments: `x = <uv>;` → wrap only when target is vec3
+            shader = shader.replace(new RegExp(`(\\w+) = ${uvName};`, 'g'), (match, name) => {
+                if (match.includes('vec3')) return match; // already handled
+                const isVec3 = new RegExp(`\\bvec3\\s+${name}\\b`).test(shader);
+                return isVec3 ? `${name} = vec3(${uvName}, 0.0);` : match;
+            });
+            return shader;
+        }
+        vertexShader = patchUvAssignments(vertexShader, 'uv');
+        vertexShader = patchUvAssignments(vertexShader, 'uv1');
+        vertexShader = patchUvAssignments(vertexShader, 'uv2');
+        vertexShader = patchUvAssignments(vertexShader, 'uv3');
 
         // Patch units – seems MaterialX uses different units and we end up with wrong light values?
         // result.direction = light.position - position;
@@ -182,7 +205,12 @@ export class MaterialXMaterial extends ShaderMaterial {
         if (hasTangent) defines['USE_TANGENT'] = '';
         if (hasColor) defines['USE_COLOR'] = '';
 
-        // Add Three.js shadow support
+        // Detect whether the vertex shader declares the inverse-transpose matrix uniform.
+        // Unlit shaders omit this uniform, so shadow code that references it would fail.
+        const hasShadowUniforms = vertexShader.includes('u_worldInverseTransposeMatrix');
+
+        // Add Three.js shadow support (only when the vertex shader has the required uniforms)
+        if (hasShadowUniforms) {
         // Insert shadow pars before main() in vertex shader
         vertexShader = vertexShader.replace(
             /void\s+main\s*\(\s*\)\s*\{/,
@@ -199,7 +227,7 @@ void main() {`
             /(\n\s*)\}(\s*)$/,
             `$1    // Three.js shadow support
 $1    vec4 worldPosition = u_worldMatrix * vec4(position, 1.0);
-$1    vec3 transformedNormal = mat3(viewMatrix) * normalWorld;
+$1    vec3 transformedNormal = normalize(mat3(viewMatrix) * mat3(u_worldInverseTransposeMatrix) * normal);
 $1    #include <shadowmap_vertex>
 $1}$2`
         );
@@ -320,6 +348,7 @@ void sampleLightSource(LightData light, vec3 position, out lightshader result)`
     }
 $2`
         );
+        } // end hasShadowUniforms
 
         const isTransparent = init.parameters?.transparent ?? false;
         materialParameters = {