@needle-tools/materialx 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.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

package/README.md

@@ -1,6 +1,6 @@
 # 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)
@@ -25,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",
+  "version": "1.5.1",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/src/materialx.material.js

@@ -122,6 +122,13 @@ export class MaterialXMaterial extends ShaderMaterial {
         fragmentShader = fragmentShader.replace(/\bu_envLightIntensity\b/g, 'envMapIntensity');
 
         // Capture some vertex shader properties
+        // 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;');
+
         // Remove `in vec3 position;` and so on since they're already declared by ShaderMaterial
         vertexShader = vertexShader.replace(/in\s+vec3\s+position;/g, '');
         vertexShader = vertexShader.replace(/in\s+vec3\s+normal;/g, '');
@@ -137,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 vec2→vec3. After removing `in vecN uv;` declarations above,
-        // Three.js always provides uv/uv1/uv2/uv3 as vec2 attributes. Any vec3
-        // assignment from these must be wrapped. This applies unconditionally —
-        // even if MaterialX originally declared them as vec2, compound displacement
-        // functions may still reference them as vec3 internally.
-        vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv;/g, 'vec3 $1 = vec3(uv, 0.0);');
-        vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv1;/g, 'vec3 $1 = vec3(uv1, 0.0);');
-        vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv2;/g, 'vec3 $1 = vec3(uv2, 0.0);');
-        vertexShader = vertexShader.replace(/\bvec3 (\w+) = uv3;/g, 'vec3 $1 = vec3(uv3, 0.0);');
-        // Also handle non-declaration assignments (e.g. `texcoord_0 = uv;`)
-        vertexShader = vertexShader.replace(/(\w+) = uv;/g, (match, name) => {
-            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;