@needle-tools/materialx 1.7.0-next.0d06218 → 1.7.0-next.57183d6

package/package.json

@@ -1,8 +1,9 @@
 {
   "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.7.0-next.0d06218",
+  "version": "1.7.0-next.57183d6",
   "type": "module",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
@@ -26,7 +27,10 @@
     "three": ">=0.160.0"
   },
   "scripts": {
-    "test": "node --import=./tests/unit/register-json-loader.js --test tests/unit/**/*.test.js"
+    "test": "node --import=./tests/unit/register-json-loader.js --test tests/unit/**/*.test.js",
+    "test:runtime:node": "node tests/runtime/materialx-runtime-smoke.mjs",
+    "test:runtime:deno": "deno run --allow-read --no-lock --node-modules-dir=auto tests/runtime/materialx-runtime-smoke.mjs",
+    "test:runtime:bun": "bun tests/runtime/materialx-runtime-smoke.mjs"
   },
   "devDependencies": {
     "@needle-tools/engine": "4.x",
@@ -35,6 +39,9 @@
     "jsdom": "^29.0.1",
     "three": "npm:@needle-tools/three@^0.169.5"
   },
+  "overrides": {
+    "@needle-tools/gltf-progressive": "3.6.0-beta.2"
+  },
   "files": [
     "index.js",
     "index.d.ts",

package/src/constants.js

@@ -1,6 +1,5 @@
-// Bare JSON import works in all bundlers (Vite, Webpack, Rollup).
-// Node.js 22+ requires --experimental-json-modules or import attributes,
-// but this file is only loaded in bundler context at runtime.
-// Unit tests that run under Node.js use the --import flag in package.json.
-import pkg from '../package.json';
+// Keep the runtime version tied to package.json. The import attribute is
+// required by browsers and Node.js for JSON modules; bundlers also understand
+// this shape.
+import pkg from '../package.json' with { type: 'json' };
 export const VERSION = pkg.version;

package/src/materialx.helper.d.ts

@@ -16,7 +16,7 @@ export interface LightData {
     outer_angle: number;
 }
 
-export function prepareEnvTexture(texture: THREE.Texture, capabilities: any): THREE.Texture;
+export function prepareEnvTexture(texture: THREE.Texture, capabilities?: any): THREE.Texture;
 
 export function getLightRotation(): THREE.Matrix4;
 

package/src/materialx.helper.js

@@ -21,7 +21,7 @@ const IMAGE_PATH_SEPARATOR = "/";
 export function prepareEnvTexture(texture, capabilities) {
     const newTexture = new THREE.DataTexture(texture.image.data, texture.image.width, texture.image.height, /** @type {any} */(texture.format), texture.type);
     newTexture.wrapS = THREE.RepeatWrapping;
-    newTexture.anisotropy = capabilities.getMaxAnisotropy();
+    newTexture.anisotropy = capabilities?.getMaxAnisotropy?.() ?? 1;
     newTexture.minFilter = THREE.LinearMipmapLinearFilter;
     newTexture.magFilter = THREE.LinearFilter;
     newTexture.generateMipmaps = true;
@@ -71,10 +71,22 @@ function fromMatrix(matrix, dimension) {
  * @property {(path: string) => Promise<THREE.Texture | null | void>} getTexture - Get a texture by path
  */
 
+/**
+ * @param {string} src
+ * @returns {HTMLImageElement | { src: string }}
+ */
+function createPortableImage(src) {
+    if (typeof Image !== 'undefined') {
+        const image = new Image();
+        image.src = src;
+        return image;
+    }
+    return { src };
+}
+
 const defaultTexture = new THREE.Texture();
 defaultTexture.needsUpdate = true;
-defaultTexture.image = new Image();
-defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAANQTFRFr6+vGqg52AAAAAxJREFUeJxjZGBEgQAAWAAJLpjsTQAAAABJRU5ErkJggg=="
+defaultTexture.image = createPortableImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAANQTFRFr6+vGqg52AAAAAxJREFUeJxjZGBEgQAAWAAJLpjsTQAAAABJRU5ErkJggg==");
 // defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAB5QTFRFAAAABAQEw8PD////v7+/vb29Xl5eQEBA+/v7PDw8GPBYkgAAAB1JREFUeJxjZGBgYFQSABIUMlxgDGMGBtaIAnIZAKwQCSDYUEZEAAAAAElFTkSuQmCC";
 // defaultTexture.wrapS = THREE.RepeatWrapping;
 // defaultTexture.wrapT = THREE.RepeatWrapping;
@@ -84,8 +96,7 @@ defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAA
 
 const defaultNormalTexture = new THREE.Texture();
 defaultNormalTexture.needsUpdate = true;
-defaultNormalTexture.image = new Image();
-defaultNormalTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIBAMAAAA2IaO4AAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAABJQTFRFgYH4gIH4gYH3gIH3gIH5gID4m94ORAAAADFJREFUeJxjZBBkfMdo9P/BB0aBj/8FGB0ufghgFGT4r8wo+P8rD2Pgo3sMjIz8jAwAMLoN0ZjS5hgAAAAASUVORK5CYII=";
+defaultNormalTexture.image = createPortableImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIBAMAAAA2IaO4AAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAABJQTFRFgYH4gIH4gYH3gIH3gIH5gID4m94ORAAAADFJREFUeJxjZBBkfMdo9P/BB0aBj/8FGB0ufghgFGT4r8wo+P8rD2Pgo3sMjIz8jAwAMLoN0ZjS5hgAAAAASUVORK5CYII=");
 
 /**
  * @param {string} key

package/src/materialx.js

@@ -1,7 +1,7 @@
 import MaterialX from "../bin/JsMaterialXGenShader.js";
 import { debug, waitForNetworkIdle } from "./utils.js";
 import { renderPMREMToEquirect, renderPMREMToPrefilteredEquirect } from "./utils.texture.js";
-import { CubeUVReflectionMapping, Light, Mesh, MeshBasicMaterial, Object3D, PlaneGeometry, PMREMGenerator, Scene, Texture, WebGLRenderer } from "three";
+import { CubeUVReflectionMapping, Light, Mesh, MeshBasicMaterial, Object3D, PlaneGeometry, PMREMGenerator, Scene, Texture } from "three";
 import { registerLights, getLightData } from "./materialx.helper.js";
 import { whiteTexture } from "./utils.texture.js";
 import { VERSION } from "./constants.js";
@@ -17,6 +17,19 @@ function isTextureLike(value) {
     return !!value && typeof value === "object" && /** @type {{ isTexture?: unknown }} */(value).isTexture === true;
 }
 
+function isNodeRuntime() {
+    return !!globalThis.process?.versions?.node && globalThis.process?.type !== "renderer";
+}
+
+async function getNodePackageAssetPaths() {
+    const { fileURLToPath } = await import(/* @vite-ignore */ "node:url");
+    return [
+        fileURLToPath(new URL("../bin/JsMaterialXCore.wasm", import.meta.url)),
+        fileURLToPath(new URL("../bin/JsMaterialXGenShader.wasm", import.meta.url)),
+        fileURLToPath(new URL("../bin/JsMaterialXGenShader.data.txt", import.meta.url)),
+    ];
+}
+
 
 /**
  * Preloads the MaterialX WebAssembly module.
@@ -69,7 +82,10 @@ export async function ready() {
 
             const location = globalThis.NEEDLE_MATERIALX_LOCATION;
 
-            if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
+            if (isNodeRuntime()) {
+                urls = await getNodePackageAssetPaths();
+            }
+            else if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
                 // Use local files from the @needle-tools/materialx npm package.
                 // Vite's ?url suffix copies these files to the output directory
                 // and returns their URL automatically — no CDN download needed.
@@ -229,7 +245,7 @@ export class MaterialXEnvironment {
 
     /**
      * Initialize with Needle Engine context
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @returns {Promise<boolean>}
      */
     async initialize(renderer) {
@@ -243,7 +259,7 @@ export class MaterialXEnvironment {
     /**
      * @param {number} frame
      * @param {Scene} scene
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      */
     update(frame, scene, renderer) {
         if (!this._initializePromise) {
@@ -334,13 +350,13 @@ export class MaterialXEnvironment {
 
     /** @type {PMREMGenerator | null} */
     _pmremGenerator = null;
-    /** @type {WebGLRenderer | null} */
+    /** @type {import("three").WebGLRenderer | null} */
     _renderer = null;
     /** @type {Map<Texture | null, Map<string, EnvironmentTextureSet>>} */
     _texturesCache = new Map();
 
     /**
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @returns {Promise<boolean>}
      */
     async _initialize(renderer) {

package/src/materialx.material.js

@@ -1,8 +1,7 @@
-import { BufferGeometry, Camera, Euler, FrontSide, GLSL3, Group, Matrix4, Object3D, Scene, ShaderMaterial, Texture, UniformsLib, Vector3, WebGLRenderer } from "three";
+import { BufferGeometry, Camera, Euler, FrontSide, GLSL3, Group, Matrix4, Object3D, Scene, ShaderMaterial, Texture, Vector3 } from "three";
 import { debug, getFrame, getTime } from "./utils.js";
 import { MaterialXEnvironment } from "./materialx.js";
 import { generateMaterialPropertiesForUniforms, getUniformValues, getLightTypeIds } from "./materialx.helper.js";
-import { cloneUniforms, cloneUniformsGroups, mergeUniforms } from "three/src/renderers/shaders/UniformsUtils.js";
 
 export const DEFAULT_ENVIRONMENT_RADIANCE_MODE = "three-pmrem";
 
@@ -15,6 +14,83 @@ const worldViewProjectionMat = new Matrix4();
 const envMat = new Matrix4();
 const envRotation = new Euler();
 
+// Local copy of Three.js UniformsUtils.cloneUniforms from
+// three/src/renderers/shaders/UniformsUtils.js. Keep this in sync with the
+// minimum supported Three.js version when Three changes uniform cloning.
+function cloneUniforms(src) {
+    const dst = {};
+    for (const uniformName in src) {
+        dst[uniformName] = {};
+        for (const propertyName in src[uniformName]) {
+            const property = src[uniformName][propertyName];
+            if (property && (
+                property.isColor ||
+                property.isMatrix3 || property.isMatrix4 ||
+                property.isVector2 || property.isVector3 || property.isVector4 ||
+                property.isTexture || property.isQuaternion
+            )) {
+                dst[uniformName][propertyName] = property.isRenderTargetTexture ? null : property.clone();
+            }
+            else if (Array.isArray(property)) {
+                dst[uniformName][propertyName] = property.slice();
+            }
+            else {
+                dst[uniformName][propertyName] = property;
+            }
+        }
+    }
+    return dst;
+}
+
+// Local copy of Three.js UniformsUtils.mergeUniforms from
+// three/src/renderers/shaders/UniformsUtils.js. Copied to avoid importing from
+// three/src, which breaks package consumers using Three's public ESM surface.
+function mergeUniforms(uniforms) {
+    const merged = {};
+    for (const uniformSet of uniforms) {
+        const tmp = cloneUniforms(uniformSet);
+        for (const propertyName in tmp) {
+            merged[propertyName] = tmp[propertyName];
+        }
+    }
+    return merged;
+}
+
+// Local copy of Three.js UniformsUtils.cloneUniformsGroups from
+// three/src/renderers/shaders/UniformsUtils.js. Keep alongside cloneUniforms
+// and mergeUniforms so ShaderMaterial.clone() stays behavior-compatible.
+function cloneUniformsGroups(src) {
+    return src.map(group => group.clone());
+}
+
+function createThreeLightUniforms() {
+    return {
+        ambientLightColor: { value: [] },
+        lightProbe: { value: [] },
+        directionalLights: { value: [], properties: { direction: {}, color: {} } },
+        directionalLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {} } },
+        directionalShadowMap: { value: [] },
+        directionalShadowMatrix: { value: [] },
+        spotLights: { value: [], properties: { color: {}, position: {}, direction: {}, distance: {}, coneCos: {}, penumbraCos: {}, decay: {} } },
+        spotLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {} } },
+        spotLightMap: { value: [] },
+        spotShadowMap: { value: [] },
+        spotLightMatrix: { value: [] },
+        pointLights: { value: [], properties: { color: {}, position: {}, decay: {}, distance: {} } },
+        pointLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {}, shadowCameraNear: {}, shadowCameraFar: {} } },
+        pointShadowMap: { value: [] },
+        pointShadowMatrix: { value: [] },
+        hemisphereLights: { value: [], properties: { direction: {}, skyColor: {}, groundColor: {} } },
+        rectAreaLights: { value: [], properties: { color: {}, position: {}, width: {}, height: {} } },
+        ltc_1: { value: null },
+        ltc_2: { value: null },
+        probesSH: { value: null },
+        probesMin: { value: new Vector3() },
+        probesMax: { value: new Vector3() },
+        probesResolution: { value: new Vector3() },
+    };
+}
+
 const CUBE_UV_REFLECTION_FUNCTIONS = `
 float mx_cubeuv_getFace(vec3 direction) {
     vec3 absDirection = abs(direction);
@@ -623,37 +699,39 @@ $2`
         this.environmentRadianceMode = environmentRadianceMode;
         this.specularAntialiasing = specularAntialiasing;
 
-        Object.assign(this.uniforms, {
-            // Three.js light uniforms (required when lights: true)
-            ...UniformsLib.lights,
-
-            ...getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath, pendingTextureLoads),
-            ...getUniformValues(init.shader.getStage('pixel'), init.loaders, searchPath, pendingTextureLoads),
-
-            u_worldMatrix: { value: new Matrix4() },
-            u_worldInverseMatrix: { value: new Matrix4() },
-            u_worldTransposeMatrix: { value: new Matrix4() },
-            u_worldInverseTransposeMatrix: { value: new Matrix4() },
-            u_worldViewMatrix: { value: new Matrix4() },
-            u_viewProjectionMatrix: { value: new Matrix4() },
-            u_worldViewProjectionMatrix: { value: new Matrix4() },
-            u_viewPosition: { value: new Vector3() },
-
-            u_envMatrix: { value: new Matrix4() },
-            u_envRadiance: { value: null, type: 't' },
-            u_envRadianceMips: { value: 8, type: 'i' },
-            u_envRadianceCubeUVTexelWidth: { value: 1 / 768 },
-            u_envRadianceCubeUVTexelHeight: { value: 1 / 1024 },
-            u_envRadianceCubeUVMaxMip: { value: 8 },
-            // TODO we need to figure out how we can set a PMREM here... doing many texture samples is prohibitively expensive
-            u_envRadianceSamples: { value: 8, type: 'i' },
-            u_envIrradiance: { value: null, type: 't' },
-            envMapIntensity: { value: 1.0 },
-            u_refractionEnv: { value: true },
-            u_refractionTwoSided: { value: false },
-            u_numActiveLightSources: { value: 0 },
-            u_lightData: { value: [], needsUpdate: false }, // Array of light data. We need to set needsUpdate to false until we actually update it
-        });
+        Object.assign(this.uniforms,
+            // Three.js light uniforms (required when lights: true). These use
+            // Three's merge/clone semantics; generated MaterialX texture
+            // uniforms below must keep their original object identity so async
+            // texture resolution updates the same uniform object.
+            mergeUniforms([createThreeLightUniforms()]),
+            getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath, pendingTextureLoads),
+            getUniformValues(init.shader.getStage('pixel'), init.loaders, searchPath, pendingTextureLoads),
+            {
+                u_worldMatrix: { value: new Matrix4() },
+                u_worldInverseMatrix: { value: new Matrix4() },
+                u_worldTransposeMatrix: { value: new Matrix4() },
+                u_worldInverseTransposeMatrix: { value: new Matrix4() },
+                u_worldViewMatrix: { value: new Matrix4() },
+                u_viewProjectionMatrix: { value: new Matrix4() },
+                u_worldViewProjectionMatrix: { value: new Matrix4() },
+                u_viewPosition: { value: new Vector3() },
+
+                u_envMatrix: { value: new Matrix4() },
+                u_envRadiance: { value: null, type: 't' },
+                u_envRadianceMips: { value: 8, type: 'i' },
+                u_envRadianceCubeUVTexelWidth: { value: 1 / 768 },
+                u_envRadianceCubeUVTexelHeight: { value: 1 / 1024 },
+                u_envRadianceCubeUVMaxMip: { value: 8 },
+                // TODO we need to figure out how we can set a PMREM here... doing many texture samples is prohibitively expensive
+                u_envRadianceSamples: { value: 8, type: 'i' },
+                u_envIrradiance: { value: null, type: 't' },
+                envMapIntensity: { value: 1.0 },
+                u_refractionEnv: { value: true },
+                u_refractionTwoSided: { value: false },
+                u_numActiveLightSources: { value: 0 },
+                u_lightData: { value: [], needsUpdate: false }, // Array of light data. We need to set needsUpdate to false until we actually update it
+            });
         this.ready = Promise.all(pendingTextureLoads).then(() => undefined);
 
         generateMaterialPropertiesForUniforms(this, init.shader.getStage('pixel'));
@@ -673,7 +751,7 @@ $2`
     _missingTangentsWarned = false;
 
     /**
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @param {Scene} _scene
      * @param {Camera} camera
      * @param {BufferGeometry} geometry
@@ -710,7 +788,7 @@ $2`
     specularAntialiasing = true;
 
     /**
-     * @param {WebGLRenderer} _renderer
+     * @param {import("three").WebGLRenderer} _renderer
      * @param {Object3D} object
      * @param {Camera} camera
      * @param {number} [time]

package/src/utils.js

@@ -7,7 +7,9 @@
  * @returns {boolean|string} Parameter value or false if not found
  */
 export function getParam(name) {
-    const urlParams = new URLSearchParams(window.location.search);
+    const search = globalThis.location?.search ?? globalThis.window?.location?.search;
+    if (!search) return false;
+    const urlParams = new URLSearchParams(search);
     const param = urlParams.get(name);
     if (param == null || param === "0" || param === "false") return false;
     if (param === "") return true;
@@ -35,22 +37,26 @@ export function getFrame() {
     return frame;
 }
 
-const performance = window.performance || /** @type {any} */ (window).webkitPerformance || /** @type {any} */ (window).mozPerformance;
+const performanceApi = globalThis.performance
+    || globalThis.window?.performance
+    || /** @type {any} */ (globalThis.window)?.webkitPerformance
+    || /** @type {any} */ (globalThis.window)?.mozPerformance
+    || { now: () => Date.now() };
 
 function updateTime() {
-    time = performance.now() / 1000; // Convert to seconds
+    time = performanceApi.now() / 1000; // Convert to seconds
     frame++;
-    window.requestAnimationFrame(updateTime);
+    globalThis.requestAnimationFrame?.(updateTime);
 }
 
-window.requestAnimationFrame(updateTime);
+globalThis.requestAnimationFrame?.(updateTime);
 
 
 
 
 export async function waitForNetworkIdle() {
-    if (typeof requestIdleCallback !== "undefined") {
-        return new Promise(res => requestIdleCallback(res));
+    if (typeof globalThis.requestIdleCallback !== "undefined") {
+        return new Promise(res => globalThis.requestIdleCallback(res));
     }
     else {
         console.debug("[MaterialX] Can not wait for network idle, using fallback");
@@ -61,5 +67,6 @@ export async function waitForNetworkIdle() {
 
 export function isDevEnvironment() {
     // check if we're in localhost or using an ip address
-    return window.location.hostname === "localhost" || /^\d{1,3}(\.\d{1,3}){3}$/.test(window.location.hostname);
-}
+    const hostname = globalThis.location?.hostname ?? globalThis.window?.location?.hostname;
+    return hostname === "localhost" || !!hostname && /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}

package/src/utils.texture.js

@@ -1,4 +1,4 @@
-import { WebGLRenderer, Scene, WebGLRenderTarget, PlaneGeometry, OrthographicCamera, ShaderMaterial, RGBAFormat, FloatType, LinearFilter, Mesh, EquirectangularReflectionMapping, RepeatWrapping, LinearMipMapLinearFilter, DataTexture, UnsignedByteType, Vector4 } from 'three';
+import { Scene, WebGLRenderTarget, PlaneGeometry, OrthographicCamera, ShaderMaterial, RGBAFormat, FloatType, LinearFilter, Mesh, EquirectangularReflectionMapping, RepeatWrapping, LinearMipMapLinearFilter, DataTexture, UnsignedByteType, Vector4 } from 'three';
 import { getParam } from './utils.js';
 
 const debug = getParam("debugmaterialx");
@@ -96,7 +96,7 @@ function createPrefilteredEquirectMaterial(pmremTexture, cubeUVSize) {
 
 /**
  * Renders a PMREM environment map to an equirectangular texture with specified roughness
- * @param {WebGLRenderer} renderer - Three.js WebGL renderer
+ * @param {import("three").WebGLRenderer} renderer - Three.js WebGL renderer
  * @param {Texture} pmremTexture - PMREM texture (2D CubeUV layout) to convert
  * @param {number} [roughness=0.0] - Roughness value (0.0 to 1.0)
  * @param {number} [width=1024] - Output texture width
@@ -249,7 +249,7 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
 /**
  * Renders a Three.js PMREM CubeUV texture to an equirectangular texture whose mip
  * levels encode increasing roughness for MaterialX SPECULAR_ENVIRONMENT_PREFILTER.
- * @param {WebGLRenderer} renderer
+ * @param {import("three").WebGLRenderer} renderer
  * @param {Texture} pmremTexture
  * @param {number} [width=2048]
  * @param {number} [height=1024]