# 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](https://engine.needle.tools/docs/materialx.html).

## Installation
`npm i @needle-tools/materialx`  

## Examples
- [three.js Example on Stackblitz](https://stackblitz.com/edit/needle-materialx-example?file=main.js,package.json,index.html)

## 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>);
```

## 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
```json
{
    "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
```json
{
    "materials": [
        {
            "name": "Perforated Metal",
            "extensions": {
                "NEEDLE_materials_mtlx": {
                    "name": "Perforated_Metal",
                    "document": 0,
                    "shader": 0
                }
            }
        }
    ]
}
```

<br />

# Contact ✒️
<b>[🌵 Needle](https://needle.tools)</b> • 
[Github](https://github.com/needle-tools) • 
[Twitter](https://twitter.com/NeedleTools) • 
[Discord](https://discord.needle.tools) • 
[Forum](https://forum.needle.tools) • 
[Youtube](https://www.youtube.com/@needle-tools)

