@needle-tools/materialx 1.4.6 → 1.5.0

package/bin/revision.json

@@ -1,5 +1,5 @@
 {
-  "commit": "309ccca5d7788f90d773248c88498ddc203dc260",
+  "commit": "6d829c8998eac38f6a1bcc2adf7c4851a62e69c4",
   "version": "1.39.4",
-  "buildDate": "2026-02-27 14:35:28"
+  "buildDate": "2026-03-19 09:55:05"
 }

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.4.6",
+  "version": "1.5.0",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/src/loader/loader.three.js

@@ -310,9 +310,21 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
 
         if (debug) console.log("[MaterialX] Using renderable element for shader generation");
 
-        // Check transparency and set context options like the reference
-        const isTransparent = state.materialXModule.isTransparentSurface(renderableElement, state.materialXGenerator.getTarget());
-        state.materialXGenContext.getOptions().hwTransparency = isTransparent;
+        // Check transparency and alpha mode.
+        // getAlphaMode() is the source of truth: it checks both direct gltf_pbr nodes
+        // and inner gltf_pbr nodes inside custom shader graph nodegraphs.
+        // isTransparentSurface() is a fallback for non-gltf_pbr shaders.
+        const target = state.materialXGenerator.getTarget();
+        const alphaMode = typeof state.materialXModule.getAlphaMode === "function"
+            ? state.materialXModule.getAlphaMode(renderableElement, target)
+            : (state.materialXModule.isTransparentSurface(renderableElement, target) ? "blend" : "opaque");
+        const isMask = alphaMode === "mask";
+        const isBlend = alphaMode === "blend";
+        // Both MASK and BLEND need alpha handling in the generated shader.
+        const needsAlpha = isMask || isBlend;
+
+        // hwTransparency must be true for both MASK and BLEND so the shader includes alpha handling code.
+        state.materialXGenContext.getOptions().hwTransparency = needsAlpha;
 
         // Generate shaders using the element's name path
         if (debug) console.log("[MaterialX] Generating MaterialX shaders...");
@@ -326,7 +338,10 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
             shader,
             context: context || {},
             parameters: {
-                transparent: isTransparent,
+                // MASK mode: no GL blending (discard handles cutout), BLEND mode: GL blending
+                transparent: isBlend,
+                // For MASK mode, set alphaTest so Three.js enables alpha testing
+                alphaTest: isMask ? 0.0001 : 0,
                 ...options?.parameters,
             },
             loaders: loaders,
@@ -337,8 +352,21 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
         return shaderMaterial;
 
     } catch (error) {
-        // This is a wasm error (an int) that we need to resolve
-        console.error(`[MaterialX v${VERSION}] Error creating MaterialX material (${materialNodeNameOrIndex}):`, typeof error === "number" ? `CODE ${error}` : error, `\n→ This may be caused by invalid MaterialX XML data or a problem in the shader generation process. Please provide the MaterialX code below when reporting an issue:\n`, mtlx);
+        // WASM exceptions arrive as integer pointers. Extract the detailed error message
+        // which includes shader compilation errors, line numbers, and error logs.
+        let errorMessage = error;
+        if (typeof error === "number" && state?.materialXModule) {
+            try {
+                const getDetailed = state.materialXModule.getExceptionDetailedMessage;
+                const getBasic = state.materialXModule.getExceptionMessage;
+                errorMessage = (typeof getDetailed === "function" ? getDetailed(error) : null)
+                    || (typeof getBasic === "function" ? getBasic(error) : null)
+                    || `WASM exception code ${error}`;
+            } catch (_) {
+                errorMessage = `WASM exception code ${error}`;
+            }
+        }
+        console.error(`[MaterialX v${VERSION}] Error creating MaterialX material (${materialNodeNameOrIndex}):\n${errorMessage}\n→ MaterialX source:\n`, mtlx);
         // Return a fallback material with stored MaterialX data
         const fallbackMaterial = new MeshStandardMaterial();
         fallbackMaterial.color.set(0xff00ff);

package/src/materialx.helper.js

@@ -222,6 +222,11 @@ function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
             break;
         case 'samplerCube':
         case 'string':
+        case 'surfaceshader':
+        case 'displacementshader':
+        case 'volumeshader':
+        case 'lightshader':
+            // MaterialX closure/shader types — not real uniforms, skip silently
             break;
         default:
             const key = type + ':' + name;

package/src/materialx.js

@@ -51,7 +51,7 @@ export async function ready() {
 
             // NOTE: This must be a plain string literal (not a template) so that the
             // makeFilesLocal Vite plugin can statically detect and localize this URL.
-            const defaultBaseUrl = "https://cdn.needle.tools/static/materialx/1.4.3/";
+            const defaultBaseUrl = "https://cdn.needle.tools/static/materialx/1.5.0/";
 
             /** @type {Array<string>} */
             let urls;

package/src/materialx.material.js

@@ -122,11 +122,6 @@ 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
-        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, '');
@@ -143,12 +138,19 @@ export class MaterialXMaterial extends ShaderMaterial {
         var hasColor = vertexShader.includes('in vec4 color;');
         vertexShader = vertexShader.replace(/in\s+vec4\s+color;/g, '');
 
-        // Patch uv 2-component to 3-component (`texcoord_0 = uv;` needs to be replaced with `texcoord_0 = vec3(uv, 0.0);`)
-        // TODO what if we actually have a 3-component UV? Not sure what three.js does then
-        if (!uv_is_vec2) vertexShader = vertexShader.replace(/texcoord_0 = uv;/g, 'texcoord_0 = vec3(uv, 0.0);');
-        if (!uv1_is_vec2) vertexShader = vertexShader.replace(/texcoord_1 = uv1;/g, 'texcoord_1 = vec3(uv1, 0.0);');
-        if (!uv2_is_vec2) vertexShader = vertexShader.replace(/texcoord_2 = uv2;/g, 'texcoord_2 = vec3(uv2, 0.0);');
-        if (!uv3_is_vec2) vertexShader = vertexShader.replace(/texcoord_3 = uv3;/g, 'texcoord_3 = vec3(uv3, 0.0);');
+        // 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 units – seems MaterialX uses different units and we end up with wrong light values?
         // result.direction = light.position - position;
@@ -175,7 +177,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*\{/,
@@ -192,7 +199,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`
         );
@@ -313,6 +320,7 @@ void sampleLightSource(LightData light, vec3 position, out lightshader result)`
     }
 $2`
         );
+        } // end hasShadowUniforms
 
         const isTransparent = init.parameters?.transparent ?? false;
         materialParameters = {

package/src/materialx.types.d.ts

@@ -14,6 +14,13 @@ export namespace MaterialX {
         readFromXmlString(doc: Document, xml: string, searchPath?: string): void;
         loadStandardLibraries(genContext: GenContext): StandardLibrary;
         isTransparentSurface(renderableElement: any, target: string): boolean;
+        /** Returns the alpha mode for a renderable element: "opaque", "mask", or "blend".
+         * Inspects the shader node (and its nodegraph implementation) for alpha_mode inputs. */
+        getAlphaMode?(renderableElement: any, target: string): string;
+        /** Extracts a detailed error message from a WASM exception pointer, including error logs. */
+        getExceptionDetailedMessage?(exceptionPtr: number): string;
+        /** Extracts a basic error message from a WASM exception pointer. */
+        getExceptionMessage?(exceptionPtr: number): string;
     }
 
 
@@ -32,6 +39,8 @@ export namespace MaterialX {
     export type Document = {
         setDataLibrary(lib: StandardLibrary): void;
         importLibrary(lib: Document): void;
+        /** Validates the document and returns validation result with error messages. */
+        validate?(): { valid: boolean; message: string };
 
         getNodes(): Node[];
     }