Needle MaterialX

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.

[!TIP] When using Needle Engine for Unity, this package can be added to your project via the Needle Engine component. Add it to the "NpmDef Dependencies" field. MaterialX files will then be automatically generated from compatible Shader Graphs with the "MaterialX" export type.
Learn more in the Needle Engine documentation.

Installation

npm i @needle-tools/materialx

Examples

• three.js Example on Stackblitz

How to use

Use with Needle Engine

import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
// Simply call this function in global scope as soon as possible
useNeedleMaterialX();

Use with three.js

import { useNeedleMaterialX } from "@needle-tools/materialx";
// Call the function with your GLTFLoader instance
useNeedleMaterialX(<yourGltfLoaderInstance>);

glTF Extension: NEEDLE_materials_mtlx

There is a root level glTF extension, NEEDLE_materials_mtlx, which contains an array of documents. Each document contains a MaterialX xml string, and information about textures and materials used in the document, so they can be resolved from inside the glTF buffers.

The textures array is used to resolve texture paths from inside the MaterialX document to texture pointers in the glTF file.

Materials can also contain the NEEDLE_materials_mtlx extension, which references a document and shader. This allows you to use the same MaterialX document for multiple materials in the glTF file.

Root-level extension

{
    "extensions": {
        "NEEDLE_materials_mtlx": {
            "documents": [
                {
                    "name": "Perforated_Metal",
                    "version": "1.38",
                    "xml": "<?xml version='1.0' encoding='UTF-8'?><materialx version=\"1.38\">...</materialx>",
                    "textures": [
                        {
                            "pointer": "/textures/0",
                            "name": "Perforated_Metal_diffuse"
                        },
                        {
                            "pointer": "/textures/1",
                            "name": "Perforated_Metal_normal"
                        }
                    ],
                    "shaders": [ // optional ]
                }
            ]
        }
    }
}

Material-level extension

{
    "materials": [
        {
            "name": "Perforated Metal",
            "extensions": {
                "NEEDLE_materials_mtlx": {
                    "name": "Perforated_Metal",
                    "document": 0,
                    "shader": 0
                }
            }
        }
    ]
}

Contact ✒️

🌵 Needle • Github • Twitter • Discord • Forum • Youtube