MaterialX

MaterialX — High-Fidelity Materials on the Web

::: tip What's new in Needle Engine 5 MaterialX now supports vertex displacement (procedural noise and texture-based), realtime shadows for all light types, displacement animation, and alpha mode detection. See all supported features → :::

Use rich, layered materials on the web with full fidelity. Currently, you can build materials in Unity's Shader Graph and export them automatically — procedural textures, multiple surface layers all just work and Needle Engine can already load any MaterialX file regardless of where it was authored.

Why MaterialX? Under the hood, Needle Engine converts your materials to MaterialX — the industry standard for portable material definitions. This means your materials are:

• High fidelity — rendered using the official MaterialX library, not an approximation

• Future-proof — ready for WebGPU and next-gen rendering

• Pipeline-compatible — the same format used by Maya, Houdini, V-Ray, and Omniverse

• Open — load standard .mtlx files from any exporter or authoring tool

::: info Shader Graph to MaterialX requires a Pro, Edu or Enterprise plan. The MaterialX Exporter is available for users on the Pro, Edu and Enterprise plans. See plans and pricing. :::

Already have MaterialX files from your studio pipeline? Needle Engine can load those too — see Using MaterialX files created externally.

Enable MaterialX support in your project

::: tip MaterialX is now part of Needle Engine core Since Needle Engine 4.13.0, MaterialX support is included by default in Needle Engine. You no longer need to install a separate package or add dependencies manually. Simply export your Shader Graph materials with the MaterialX export type enabled and they will work out of the box. :::

::: tabs

@tab Unity

MaterialX support is built into Needle Engine and works automatically. No additional setup is required.

If you're using an older version of Needle Engine (before 4.13.0), you'll need to add the @needle-tools/materialx package as a dependency:

1. Select the Needle Engine component in your scene.

2. Find the "NpmDef Dependencies" section in the Inspector, and add a new dependency by increasing the "Size" number (e.g. from 0 to 1).

3. Click the Object Picker symbol, enable Package Visibility with the eye symbol, and select the Needle MaterialX package from the list.

@tab Other Needle integrations

MaterialX support is built into Needle Engine and works automatically. No additional setup is required.

If you're using an older version of Needle Engine (before 4.13.0), you'll need to install the MaterialX package:

1. Find and open your web project in a code editor (e.g. VS Code). Learn how to open your web project.

2. Install the Needle MaterialX package from the NPM registry in your web project.

   npm install @needle-tools/materialx

@tab three.js

You can use our MaterialX package in any three.js project, even if you're not using Needle Engine.

1. Install the MaterialX package:

   npm install @needle-tools/materialx

2. Register our MaterialX plugin with your GLTFLoader:

   import { useNeedleMaterialX } from "@needle-tools/materialx";
   import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
   
   const gltfLoader = new GLTFLoader();
   
   // ... register other plugins such as DRACOLoader, KTX2Loader, etc.
   useNeedleMaterialX(gltfLoader);
   
   // ... load a file that contains MaterialX materials
   gltfLoader.load("https://cloud.needle.tools/-/assets/Z23hmXB2qfHiF-2qfHiF/file", (gltf) => {
       scene.add(gltf.scene);
   });

3. Load GLB files that contain the NEEDLE_materials_mtlx extension. The plugin will automatically load and apply the MaterialX materials to the objects that are using them.

4. You can enable preloading of the MaterialX WebAssembly module by calling useNeedleMaterialX(gltfLoader, { preload: true }). This will load the MaterialX WebAssembly module in advance, so that it is ready when you load a GLB file with MaterialX materials.

You can find a full example of how to use MaterialX in a three.js project on StackBlitz: MaterialX in three.js.

:::

Exporting materials with MaterialX support

Currently, MaterialX export is available for Unity's Shader Graph. Blender support is on our radar. If you have existing .mtlx files from other tools, see Using MaterialX files created externally.

1. Create materials with Unity's Shader Graph.

   Example of a complex Shader Graph in Unity.

2. Select an object that has a Shader Graph-based material in your scene, or select the shader asset in the Project View.

3. In the Material properties, find the section "Needle Engine – Custom Shader Settings", and select "MaterialX" as the Shader Export Type.

   Enabling the MaterialX export type in the Shader Graph material properties.

4. When you export your scene, all materials using shaders with the "MaterialX" export type will be embedded alongside your 3D content, and loaded at runtime.

Using MaterialX files created externally

The Needle MaterialX package contains experimental support for loading MaterialX files directly. Textures can be resolved via a callback function, and materials are returned as three.js ShaderMaterial.

You can find examples for working with the Needle MaterialX package in our MaterialX collection on StackBlitz.

:::: tabs @tab From code

import { TextureLoader } from 'three';
import { Experimental_API } from '@needle-tools/materialx';

// Load a MaterialX file and its referenced textures from a URL
function load(mtlx_url) {
    const parts = mtlx_url.split('/');
    parts.pop();
    const dir = parts.join('/');

    return fetch(mtlx_url)
    .then((res) => res.text())
    .then((mtlx) => {
        const loader = new TextureLoader();
        const materialNameOrIndex = 0;
        Experimental_API.createMaterialXMaterial(mtlx, materialNameOrIndex, {
            getTexture: async (url) => {
                return await loader.loadAsync(dir + url);
            },
        }).then((mat) => {
            console.log("MaterialX material has been loaded:", mat);
        });
    });
}

::: info The Experimental_API.createMaterialXMaterial() method currently doesn't support loading multiple materials, or MaterialX files with additional .mtlx references. :::

::::

Supported Nodes and Features

Needle Engine supports the full MaterialX specification, including OpenPBR, Standard Surface, UsdPreviewSurface and Unlit Surface nodes, and including NPR (non-photorealistic rendering) nodes like fresnel effects. Nested nodegraph definitions and custom nodes are also supported.

MaterialX materials in Needle Engine support the following features:

• Image-Based Lighting (IBL) automatically coming from the scene's environment map

• Reflection Probes affect objects using MaterialX materials

• Light sources: Directional, point, and spot lights, with a current limit of 8 lights per scene

• Realtime shadows from directional, spot, and point lights

• Vertex displacement including procedural noise (fractal3d, position, math nodes) and texture-based displacement, with automatic normal recomputation via screen-space derivatives

• Displacement animation via animated material properties

• Alpha mode detection for mask and blend transparency

• Texture compression and progressive textures. MaterialX materials fully support the powerful texture compression and progressive loading features of Needle Engine, allowing you to use large textures. They will be only loaded when needed, and only in the resolution needed for the current view.

• Animated material properties for colors, floats, vectors. Same as other materials in Needle Engine, any numeric material property can be animated.

• All MaterialX surface models, including OpenPBR, Standard Surface, UsdPreviewSurface, and Unlit Surface.

The Needle MaterialX Exporter leverages the graph-based structure of Unity's Shader Graph for export, and converts Shader Graph nodes to MaterialX nodedefs and nodegraphs. It has support for the following features:

• Material properties like colors, floats, vectors, textures

• Operations on numbers, vectors, and matrices

• Blend nodes like Mix, Add, Multiply, and Blend with various blend modes

• Textures and color spaces

• Subgraphs with one or more levels of nesting

• Vertex colors are supported

• Vertex displacement via procedural noise or texture sampling

• Multiple UV channels are supported (up to 4)

• Shader Keywords are supported and will be exported as switch nodes in MaterialX.

Supported MaterialX Version

Needle Engine currently supports MaterialX version 1.39.4. MaterialX documents with earlier versions are also supported and will be automatically upgraded to the latest version.

Limitations of the MaterialX Exporter

Not all features that Shader Graph supports are also supported by MaterialX. If you attempt to export an unsupported node, the exporter will log an error and stop the export process. You can then fix the issue by replacing the unsupported node with a supported one, if possible.

• Baked Lightmaps: Baked lightmaps are currently not supported in MaterialX materials.

• Tangent space is not supported at the moment, which means that Shader Graph nodes specifying "Tangent" as space will look different.

• Code Nodes are not supported at the moment.

::: tip The special "MATERIALX" shader keyword If you have complex shaders with unsupported nodes, you can use the "MATERIALX" keyword to prevent exporting them. The "On" path of keyword switches will be exported, and the "Off" path will be ignored for export. You can use this to keep shaders with custom nodes or unsupported features functional, but still export them to MaterialX. :::

::: info Needle Engine vs built-in three.js MaterialX Needle Engine uses the official MaterialX JavaScript library, which means materials are represented at the highest fidelity possible. three.js has some initial built-in MaterialX support, but its custom implementation doesn't yet cover many features of the standard.

Needle is contributing to the built-in three.js MaterialX support, so that at some point we can offer both options or switch to the three.js implementation once it's more comprehensive. :::

About MaterialX

MaterialX is an open standard for describing materials and shaders in a graph-based way, independent of any rendering engine. It allows you to define complex materials with multiple surface layers and realistic lighting in a portable format. Needle Engine uses the official MaterialX JavaScript library for maximum fidelity.

MaterialX is widely used across film, VFX, and e-commerce, and is supported by professional authoring tools such as Autodesk Maya and 3ds Max, Houdini, V-Ray, and Omniverse.

Quick Tips for Unity

When working with MaterialX in Unity, here are some common scenarios and solutions:

Shader Graph Not Available

Issue: Shader Graph package is not installed or visible in Unity.

Solution:

1. Open Package Manager (Window > Package Manager)

2. Change the filter to "Unity Registry" if needed

3. Search for "Shader Graph" and install it

Material Not Exporting as MaterialX

Issue: Your Shader Graph material isn't being exported with MaterialX.

Solution:

1. Make sure you've set the Shader Export Type to "MaterialX" in the material's Needle Engine settings

2. Ensure you're using Needle Engine 4.13.0 or later (MaterialX is built-in). For older versions, you'll need to manually add the @needle-tools/materialx package dependency

3. Check the Console for any export errors or unsupported nodes in your Shader Graph

Preview Looks Different in Unity vs Web

Issue: The material looks different between Unity's Scene view and the exported web version.

Solution:

• MaterialX uses physically-based rendering which may differ from Unity's preview

• Ensure your scene has proper lighting and an environment map/skybox for accurate IBL

• Some Shader Graph nodes (like tangent space operations) are not yet fully supported and may look different

See Also

• Features Overview — full list of Needle Engine capabilities

• Progressive Loading — progressive textures and KTX2 compression, fully supported by MaterialX materials

• FastHDR Environment Lighting — high-quality environment maps for image-based lighting

• Optimization & Compression — texture compression and production build optimization

• Getting Started — get started with Needle Engine for Unity

• Unity Shader Graph Documentation — Unity's official Shader Graph reference