---
title: MaterialX
image: /materialx/materialx-demo.webp
---
## 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 →](#supported-nodes-and-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.
[](https://engine.needle.tools/samples/material-x)
**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
- **Portable** — based on an [open industry standard](#compatible-software) used by Maya, Houdini, Unreal, and many more
- **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.](https://needle.tools/pricing)
:::
Already have MaterialX files from your studio pipeline? Needle Engine can load those too — see [Using MaterialX files created externally](#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.](./project-structure.html#opening-the-web-project-in-a-code-editor)
2. Install the Needle MaterialX package from the NPM registry in your web project.
```bash
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:
```bash
npm install @needle-tools/materialx
```
2. Register our `MaterialX` plugin with your `GLTFLoader`:
```ts
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](https://stackblitz.com/edit/needle-materialx-example?file=main.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](#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._
3. 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](
https://stackblitz.com/@marwie/collections/materialx).
:::: tabs
@tab From code
```ts
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](https://www.materialx.org/) 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](https://github.com/materialx/MaterialX) for maximum fidelity and exports **fully spec-compliant** files — validated against the official [MaterialX Viewer and Graph Editor](https://github.com/AcademySoftwareFoundation/MaterialX) reference tools.
MaterialX is widely used across film, VFX, game engines, and e-commerce.
### Compatible Software
| Software | Version | Notes |
|---|---|---|
| Autodesk Maya | 2024+ | Built-in LookdevX MaterialX plugin |
| Autodesk 3ds Max | 2024+ | Bundled MaterialX plugin |
| Autodesk VRED | 2024+ | MaterialX import |
| SideFX Houdini | 19+ | Native support via Solaris |
| Unreal Engine | 5.1+ | MaterialX import, USD workflows in 5.3+ |
| NVIDIA Omniverse | Kit 1.0.1+ | Import and rendering via MDL |
| Chaos V-Ray | 6+ | Support in Maya and Houdini |
| Pixar RenderMan | 24+ | Rendering via USD HdPrman |
| Autodesk Arnold | 5.1+ | Rendering via custom operator |
| Houdini Karma | — | Rendering in Karma CPU/XPU |
| Apple visionOS | — | Spatial computing |
For the full and up-to-date list, see the [official MaterialX Third-Party Support page](https://materialx.org/ThirdPartySupport.html).
## 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](/docs/explanation/core-concepts/features-overview) — full list of Needle Engine capabilities
- [Progressive Loading](/docs/gltf-progressive/) — progressive textures and KTX2 compression, fully supported by MaterialX materials
- [FastHDR Environment Lighting](/docs/explanation/fasthdr) — high-quality environment maps for image-based lighting
- [Optimization & Compression](/docs/how-to-guides/optimization/) — texture compression and production build optimization
- [Getting Started](/docs/unity/) — get started with Needle Engine for Unity
- [Unity Shader Graph Documentation](https://docs.unity3d.com/Packages/com.unity.shadergraph@17.3/manual/index.html) — Unity's official Shader Graph reference