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

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-next.b9d5f3f",
   "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

@@ -143,12 +143,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 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 units – seems MaterialX uses different units and we end up with wrong light values?
         // result.direction = light.position - position;

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[];
     }