@needle-tools/materialx 1.4.4-next.d2335d8 → 1.4.5

package/README.md

@@ -1,10 +1,15 @@
-# Needle MaterialX
+# Needle MaterialX – MaterialX Materials for three.js & the Web
 
-Web runtime support to load and display MaterialX materials in Needle Engine and three.js via the MaterialX WebAssembly library. glTF files containing the `NEEDLE_materials_mtlx` extension can be loaded with this package. There is also experimental support for loading raw MaterialX XML files.
+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.
+
+- MaterialX to WebGL/WebGPU shader generation via WASM
+- 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
 
 [Learn more in the Needle Engine documentation](https://engine.needle.tools/docs/how-to-guides/export/materialx.html)
 
-[![](https://cloud.needle.tools/-/media/Xc99R6zbaD-kpoTw1cMRKA.gif)](https://engine.needle.tools/samples/material-x)
+[![MaterialX material rendered in the browser with Needle Engine](https://cloud.needle.tools/-/media/Xc99R6zbaD-kpoTw1cMRKA.gif)](https://engine.needle.tools/samples/material-x)
 
 
 ## Installation
@@ -15,9 +20,31 @@ Web runtime support to load and display MaterialX materials in Needle Engine and
 
 ## How to use
 
+### Use with Needle Engine
+
+```ts
+import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
+// Simply call this function in global scope as soon as possible
+useNeedleMaterialX();
+```
+
+### Use with three.js
+
+```ts
+import { useNeedleMaterialX } from "@needle-tools/materialx";
+// Call the function with your GLTFLoader instance
+useNeedleMaterialX(<yourGltfLoaderInstance>);
+```
+
+## WASM
+
+### Default (CDN)
+
+By default, MaterialX WASM files are loaded from the Needle CDN at `https://cdn.needle.tools/static/materialx/<version>/`. No configuration needed.
+
 ### Custom WASM Location
 
-By default, MaterialX WASM files are loaded from `https://cdn.needle.tools/static/materialx/<version>/`. You can override this by setting `globalThis.NEEDLE_MATERIALX_LOCATION` **before** any MaterialX code runs.
+You can override the WASM location by setting `globalThis.NEEDLE_MATERIALX_LOCATION` **before** MaterialX loads (for example in global scope in a root script).
 
 #### Package-local files
 
@@ -43,27 +70,8 @@ To use a custom base URL (for self-hosted deployments, air-gapped environments,
 globalThis.NEEDLE_MATERIALX_LOCATION = "/assets/materialx/";
 ```
 
-The value must end with a trailing slash (`/`).
-
-#### Default (CDN)
-
-By default, MaterialX WASM files are loaded from the Needle CDN. No configuration needed.
-
-### Use with Needle Engine
-
-```ts
-import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
-// Simply call this function in global scope as soon as possible
-useNeedleMaterialX();
-```
-
-### Use with three.js
+IMPORTANT: The value must end with a trailing slash (`/`).
 
-```ts
-import { useNeedleMaterialX } from "@needle-tools/materialx";
-// Call the function with your GLTFLoader instance
-useNeedleMaterialX(<yourGltfLoaderInstance>);
-```
 
 ## glTF Extension: NEEDLE_materials_mtlx
 
@@ -93,7 +101,7 @@ Materials can also contain the `NEEDLE_materials_mtlx` extension, which referenc
                             "name": "Perforated_Metal_normal"
                         }
                     ],
-                    "shaders": [ // optional ]
+                    "shaders": []  ← optional
                 }
             ]
         }
@@ -124,7 +132,7 @@ Materials can also contain the `NEEDLE_materials_mtlx` extension, which referenc
 # Contact ✒️
 <b>[🌵 Needle](https://needle.tools)</b> • 
 [Github](https://github.com/needle-tools) • 
-[Twitter](https://twitter.com/NeedleTools) • 
+[X](https://x.com/NeedleTools) • 
 [Discord](https://discord.needle.tools) • 
 [Forum](https://forum.needle.tools) • 
 [Youtube](https://www.youtube.com/@needle-tools)

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@needle-tools/materialx",
-  "version": "1.4.4-next.d2335d8",
+  "description": "MaterialX material support for three.js and Needle Engine – render physically based MaterialX shaders in the browser via WebAssembly",
+  "version": "1.4.5",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -57,7 +58,12 @@
     "threejs",
     "three.js",
     "webgl",
+    "webgpu",
     "mtlx",
-    "rendering"
+    "rendering",
+    "gltf",
+    "pbr",
+    "3d",
+    "wasm"
   ]
 }

package/src/loader/loader.three.js

@@ -338,7 +338,7 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
 
     } catch (error) {
         // This is a wasm error (an int) that we need to resolve
-        console.error(`[MaterialX v${VERSION}] Error creating MaterialX material (${materialNodeNameOrIndex}):`, error, `\n→ This may be caused by invalid MaterialX XML data or a problem in the shader generation process. Please provide the mtlx string when reporting this issue:`, mtlx);
+        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);
         // Return a fallback material with stored MaterialX data
         const fallbackMaterial = new MeshStandardMaterial();
         fallbackMaterial.color.set(0xff00ff);