mtlx-core

Parse, validate, package, and transform MaterialX documents. Pure: runs in Node, browsers, and workers alike. Filesystem helpers live in mtlx-core/node; texture processing (which needs sharp) lives in mtlx-core/textures.

Other

MaterialXReadLimits

Resource budgets for untrusted XML documents and ZIP archives. Values must be positive safe integers.

Properties

Property	Type
maxXmlBytes	number
maxXmlDepth	number
maxXmlElements	number
maxArchiveBytes	number
maxArchiveEntries	number
maxEntryBytes	number
maxExpandedBytes	number

---

DEFAULT_MATERIALX_READ_LIMITS

const DEFAULT_MATERIALX_READ_LIMITS: Readonly<MaterialXReadLimits>;

Conservative defaults; callers processing trusted larger assets can override individual budgets.

---

nodeType()

function nodeType(spec): string | undefined;

Parameters

Parameter	Type
spec	MaterialXNodeSpec

Returns

string | undefined

---

getNodeCatalog()

function getNodeCatalog(document?, registry?): MaterialXNodeSpec[];

Catalog also accepts definitions embedded in the document; source XML remains untouched.

Parameters

Parameter	Type	Default value
document?	MaterialXDocument	undefined
registry?	MaterialXNodeSpec[]	materialXNodeRegistry

Returns

MaterialXNodeSpec[]

---

findNodeSpec()

function findNodeSpec(element, catalog): MaterialXNodeSpec | undefined;

Parameters

Parameter	Type
element	MaterialXElement
catalog	MaterialXNodeSpec[]

Returns

MaterialXNodeSpec | undefined

---

getNodeGraphScope()

function getNodeGraphScope(
   document, 
   element, 
   scope, 
   spec?
): string | undefined;

Expand only implementations whose contents are present in this document.

Parameters

Parameter	Type
document	MaterialXDocument
element	MaterialXElement
scope	string
spec?	MaterialXNodeSpec

Returns

string | undefined

---

resolveResourcePath()

function resolveResourcePath(documentPath, value): string;

Parameters

Parameter	Type
documentPath	string
value	string

Returns

string

---

relativeResourcePath()

function relativeResourcePath(documentPath, target): string;

Parameters

Parameter	Type
documentPath	string
target	string

Returns

string

---

MaterialXDependencyEdge

Extends

• ResourceReference

Properties

Property	Type	Description	Inherited from
element	MaterialXElement	-	ResourceReference.element
attribute	string	-	ResourceReference.attribute
value	string	-	ResourceReference.value
resolvedValue	string	Effective filename after the nearest inherited fileprefix is applied.	ResourceReference.resolvedValue
documentPath	string	-	-
targetPath	string	-	-
resourceId?	string	-	-

---

MaterialXResourceGraph

Properties

Property	Type
resources	object[]
edges	MaterialXDependencyEdge[]

---

buildResourceGraph()

function buildResourceGraph(pkg): MaterialXResourceGraph;

A graph snapshot retains original reference values for a single, non-cascading rewrite.

Parameters

Parameter	Type
pkg	MaterialXPackage

Returns

MaterialXResourceGraph

---

cloneMaterialXPackage()

function cloneMaterialXPackage(pkg): MaterialXPackage;

Parameters

Parameter	Type
pkg	MaterialXPackage

Returns

MaterialXPackage

---

planResourceDestinations()

function planResourceDestinations(
   pkg, 
   desired, 
   reserved?
): Map<string, string>;

Allocate a complete mapping, reserving unchanged and incoming names before suffixing.

Parameters

Parameter	Type
pkg	MaterialXPackage
desired	(resource) => string
reserved?	Iterable<string>

Returns

Map<string, string>

---

applyResourceDestinations()

function applyResourceDestinations(
   pkg, 
   destinations, 
   rootPath?
): void;

Apply one original→destination map to every dependency edge, then relocate resources/root.

Parameters

Parameter	Type	Default value
pkg	MaterialXPackage	undefined
destinations	ReadonlyMap<string, string>	undefined
rootPath?	string	pkg.rootPath

Returns

void

---

DeepReadonly

type DeepReadonly<T> = { readonly [K in keyof T]: DeepReadonly<T[K]> };

A recursively read-only view, suitable for immutable editor snapshots.

Type Parameters

Type Parameter
T

---

ReadonlyMaterialXDocument

type ReadonlyMaterialXDocument = DeepReadonly<MaterialXDocument>;

---

MaterialXValueType

type MaterialXValueType = string;

---

MaterialXElement

Properties

Property	Type
name	string
attributes	Record<string, string>
text?	string
children	MaterialXElement[]

---

MaterialXInput

Extends

• MaterialXPort

Properties

Property	Modifier	Type	Inherited from
name	readonly	string	MaterialXPort.name
type?	readonly	string	MaterialXPort.type
value?	readonly	string	MaterialXPort.value
attributes	readonly	Readonly<Record<string, string>>	MaterialXPort.attributes
nodeName?	readonly	string	-
output?	readonly	string	-

---

MaterialXOutput

Extends

• MaterialXPort

Properties

Property	Modifier	Type	Inherited from
name	readonly	string	MaterialXPort.name
type?	readonly	string	MaterialXPort.type
value?	readonly	string	MaterialXPort.value
attributes	readonly	Readonly<Record<string, string>>	MaterialXPort.attributes

---

MaterialXParameter

Extends

• MaterialXPort

Properties

Property	Modifier	Type	Inherited from
name	readonly	string	MaterialXPort.name
type?	readonly	string	MaterialXPort.type
value?	readonly	string	MaterialXPort.value
attributes	readonly	Readonly<Record<string, string>>	MaterialXPort.attributes

---

MaterialXNode

Properties

Property	Modifier	Type
category	readonly	string
name?	readonly	string
type?	readonly	string
attributes	readonly	Readonly<Record<string, string>>
inputs	readonly	readonly MaterialXInput[]
outputs	readonly	readonly MaterialXOutput[]
parameters	readonly	readonly MaterialXParameter[]

---

MaterialXNodeGraph

Properties

Property	Modifier	Type
name?	readonly	string
attributes	readonly	Readonly<Record<string, string>>
inputs	readonly	readonly MaterialXInput[]
outputs	readonly	readonly MaterialXOutput[]
parameters	readonly	readonly MaterialXParameter[]
nodes	readonly	readonly MaterialXNode[]

---

MaterialXNodePortSpec

Properties

Property	Type	Description
name	string	-
type?	string	-
value?	string	Literal default; absent when the definition uses implicit geometry or a connection.
attributes?	Readonly<Record<string, string>>	Original definition metadata, including uiname, enum, ranges and defaultgeomprop.

---

validateMaterialXPackage()

function validateMaterialXPackage(pkg, options?): MaterialXValidationIssue[];

Checks package dependencies by identity/base path, and document rules in resolved include scope.

Parameters

Parameter	Type
pkg	MaterialXPackage
options?	MaterialXValidationOptions

Returns

MaterialXValidationIssue[]

---

MATERIALX_VALIDATION_RULES

const MATERIALX_VALIDATION_RULES: readonly ["basic", "structure", "types", "resources", "renderer-support", "unused"];

---

MaterialXValidationRule

type MaterialXValidationRule = typeof MATERIALX_VALIDATION_RULES[number];

---

MaterialXValidationOptions

Properties

Property	Type	Description
registry?	MaterialXNodeSpec[]	-
rules?	readonly ( | "resources" | "basic" | "structure" | "types" | "renderer-support" | "unused")[]	Defaults to basic. These checks do not establish full MaterialX conformance.
availableResources?	readonly string[]	Resolved document-relative resource names, provided by the host.
supportedCategories?	readonly string[]	Categories explicitly supported by the host renderer; omission reports unassessed.

---

validateDocument()

function validateDocument(document, registryOrOptions?): MaterialXValidationIssue[];

Validates selected independent rules. The legacy custom-registry argument remains supported.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
registryOrOptions?	| MaterialXNodeSpec[] | MaterialXValidationOptions	materialXNodeRegistry

Returns

MaterialXValidationIssue[]

---

checkMaterialXText()

function checkMaterialXText(
   xml, 
   location?, 
   limits?, 
   options?
): MaterialXValidationIssue[];

Parse failures are reported as issues, rather than thrown.

Parameters

Parameter	Type	Default value
xml	string	undefined
location?	string	''
limits?	Partial<MaterialXReadLimits>	undefined
options?	MaterialXValidationOptions	undefined

Returns

MaterialXValidationIssue[]

---

createMaterialXDocument()

function createMaterialXDocument(attributes?, elements?): MaterialXDocument;

Creates a document whose typed views are always derived from its canonical element tree. Edit attributes and elements; typed views are read-only snapshots of the current tree.

Parameters

Parameter	Type	Default value
attributes?	Record<string, string>	{}
elements?	MaterialXElement[]	[]

Returns

MaterialXDocument

---

cloneMaterialXDocument()

function cloneMaterialXDocument(document): MaterialXDocument;

Parameters

Parameter	Type
document	ReadonlyMaterialXDocument

Returns

MaterialXDocument

Packaging

MaterialXZipEntry

One file entry read from a .mtlx.zip archive.

Properties

Property	Type
path	string
data	Uint8Array

---

MaterialXZipArchive

The result of inspectMaterialXZipArchive.

Properties

Property	Type
entries	MaterialXZipEntry[]
rootEntry?	MaterialXZipEntry
issues	MaterialXValidationIssue[]

---

inspectMaterialXZipArchive()

function inspectMaterialXZipArchive(data, overrides?): MaterialXZipArchive;

Unzips .mtlx.zip bytes in memory and locates the root .mtlx entry. Works in Node and the browser.

Parameters

Parameter	Type
data	Uint8Array
overrides?	Partial<MaterialXReadLimits>

Returns

MaterialXZipArchive

---

createMaterialXZipArchive()

function createMaterialXZipArchive(entries): Uint8Array;

Builds a DEFLATE-compressed .mtlx.zip archive in memory. No ordering, compression, or alignment constraints.

Parameters

Parameter	Type
entries	MaterialXPackageEntry[]

Returns

Uint8Array

---

MaterialXFormat

type MaterialXFormat = "mtlx" | "mtlx.zip";

A MaterialX file format, detected from its file extension.

• mtlx — a loose XML document with resources referenced by relative path.
• mtlx.zip — a relaxed, ordinary zip containing a .mtlx document plus resources.

---

detectFormat()

function detectFormat(filePath): MaterialXFormat;

Detects the MaterialXFormat of a path from its extension. Anything that is not .mtlx.zip is treated as a loose .mtlx document, except .mtlz, which is rejected: the bespoke .mtlz container format is no longer supported.

Parameters

Parameter	Type
filePath	string

Returns

MaterialXFormat

---

MaterialXResource

One resource (texture, library, or other file) referenced by a MaterialX document.

archivePath is the normalized, archive-relative POSIX path (textures/albedo.png) that the document now references; sourcePath is the path it was originally read from.

Properties

Property	Type	Description
id?	string	Stable identity in a resolved dependency graph.
document?	MaterialXDocument	Canonical tree for an included MaterialX document; serialized on output.
archivePath	string	-
sourcePath	string	-
data	Uint8Array	-

---

MaterialXPackage

A MaterialX document together with every resource it references, held in memory.

This is the unit that transform pipelines operate on and that the Node entry point (mtlx-core/node) reads from and writes to either MaterialXFormat. The document's file references always point at resources[i].archivePath.

Example:

import { loadMaterialXPackage, writeMaterialXPackage } from 'mtlx-core/node';
import { transform } from 'mtlx-core';
import { resizeTextures } from 'mtlx-core/textures';

const pkg = await loadMaterialXPackage('material.mtlx');
await transform(pkg, resizeTextures({ maxImageSize: 1024, targets: [{ format: 'webp' }] }));
await writeMaterialXPackage(pkg, 'material.mtlx.zip');

Properties

Property	Type	Description
rootPath	string	Archive-relative path of the root .mtlx document, e.g. material.mtlx.
document	MaterialXDocument	-
resources	MaterialXResource[]	-

---

MaterialXPackageEntry

A { path, data } pair, the input to createMaterialXZipArchive.

Properties

Property	Type
path	string
data	Uint8Array

---

ResourceReader

type ResourceReader = (relativePath) => Promise<Uint8Array>;

Reads the bytes of a resource referenced by a document, given its normalized root-relative POSIX path. Callers supply this so the library never touches a filesystem itself: the Node entry point wraps fs.readFile, a browser can serve entries from an unzipped archive.

Parameters

Parameter	Type
relativePath	string

Returns

Promise<Uint8Array>

---

resolveMaterialXResources()

function resolveMaterialXResources(
   document, 
   readResource, 
   options?
): Promise<MaterialXResource[]>;

Collects every file referenced by a document and rewrites the references to archive paths.

Walks file/filename/href/uri/source attributes and any type="filename" value, rejects external (http:), absolute, or root-escaping references, reads each unique file via readResource, assigns it an archive path under textures/, libraries/, or resources/, and rewrites the document's attributes in place to those paths.

Example:

const resources = await resolveMaterialXResources(document, (rel) => readFile(path.join(rootDir, rel)));

Parameters

Parameter	Type
document	MaterialXDocument
readResource	ResourceReader
options?	{ rootPath?: string; limits?: Partial<MaterialXReadLimits>; }
options.rootPath?	string
options.limits?	Partial<MaterialXReadLimits>

Returns

Promise<MaterialXResource[]>

---

relocateTextureResources()

function relocateTextureResources(pkg, libraryPath): void;

Moves every image resource's archive path under libraryPath, rewriting document references to match. Used for loose .mtlx output when --texture-library is given; irrelevant to .mtlx.zip, which retains archive-relative resources. Non-image resources (other .mtlx libraries, misc files) are left where they are.

Parameters

Parameter	Type
pkg	MaterialXPackage
libraryPath	string

Returns

void

---

packageToEntries()

function packageToEntries(pkg, options?): MaterialXPackageEntry[];

Flattens a package into { path, data } entries, root document first. By default throws on unsafe archive paths so nothing downstream can write outside its target directory — pass { validate: false } only for loose .mtlx output whose resources were deliberately relocated (e.g. via relocateTextureResources) to an absolute or ..-relative disk path, which is not a valid archive path but is a valid write target on a real filesystem.

Parameters

Parameter	Type
pkg	MaterialXPackage
options?	{ validate?: boolean; }
options.validate?	boolean

Returns

MaterialXPackageEntry[]

---

mergeMaterialXPackages()

function mergeMaterialXPackages(packages): MaterialXPackage;

Combines multiple packages into one, root document first. Resources are concatenated, renaming (and rewriting references to) any archive path that collides with one already taken. Throws if two inputs share a top-level element name (materials, nodegraphs, etc.), since MaterialX names must be unique within a document and there's no safe way to rename one without also rewriting every reference to it.

A single-package input is returned as-is.

Parameters

Parameter	Type
packages	MaterialXPackage[]

Returns

MaterialXPackage

---

packageFromArchive()

function packageFromArchive(archive, options?): MaterialXPackage;

Builds a package from an inspected archive. Accepts the result of inspectMaterialXZipArchive; throws if the archive reported errors or has no root document.

Parameters

Parameter	Type
archive	{ entries: object[]; rootEntry?: { path: string; data: Uint8Array; }; issues: object[]; }
archive.entries	object[]
archive.rootEntry?	{ path: string; data: Uint8Array; }
archive.rootEntry.path	string
archive.rootEntry.data	Uint8Array
archive.issues	object[]
options?	{ limits?: Partial<MaterialXReadLimits>; }
options.limits?	Partial<MaterialXReadLimits>

Returns

MaterialXPackage

Parsing

MaterialInfo

A node's name and category.

Properties

Property	Type
name?	string
category	string

---

MaterialXSummary

The result of summarizeMaterialX.

Properties

Property	Type	Description
path	string	-
version?	string	-
colorspace?	string	-
nodeGraphCount	number	-
topLevelNodeCount	number	-
nodeCategories	string[]	-
materials	MaterialInfo[]	-
referencedTextures	string[]	-
nodes	MaterialInfo[]	Actual nodes from every graph depth, excluding graph containers, ports, and metadata.

---

summarizeMaterialX()

function summarizeMaterialX(path, document): MaterialXSummary;

Summarizes a parsed document: version, colorspace, materials, referenced textures, and nodes. Powers the CLI's info command and the VS Code extension's stats panel.

Example:

const summary = summarizeMaterialX('material.mtlx', document);
console.log(summary.materials.map((material) => material.name));

Parameters

Parameter	Type
path	string
document	MaterialXDocument

Returns

MaterialXSummary

---

MaterialXDocument

The in-memory form of a .mtlx file, mirroring its XML structure.

nodes and nodeGraphs are derived read-only snapshots; elements is the canonical tree that serializeMaterialX writes back out.

Properties

Property	Modifier	Type
attributes	public	Record<string, string>
nodes	readonly	readonly MaterialXNode[]
nodeGraphs	readonly	readonly MaterialXNodeGraph[]
elements	public	MaterialXElement[]

---

parseMaterialX()

function parseMaterialX(xml, limits?): MaterialXDocument;

Parses MaterialX XML text into a MaterialXDocument.

Preserves ordered elements, explicit attributes, text and comments semantically. Source whitespace, quote style and XML declarations are not preserved byte-for-byte. Throws with line and column on malformed XML, a missing <materialx> root, or comments outside that root.

Example:

const document = parseMaterialX(await readFile('material.mtlx', 'utf8'));
console.log(document.attributes.version, document.nodeGraphs.length);

Reference:

• MaterialX Specification

Parameters

Parameter	Type
xml	string
limits?	Partial<MaterialXReadLimits>

Returns

MaterialXDocument

---

serializeMaterialX()

function serializeMaterialX(document): string;

Serializes a MaterialXDocument back to XML text. The inverse of parseMaterialX; a parse → serialize → parse round trip yields the same document.

Parameters

Parameter	Type
document	ReadonlyMaterialXDocument

Returns

string

Transforms

Transform

type Transform = (pkg) => void | Promise<void>;

A step in a transform pipeline. Transforms mutate the package in place and may be async. Functions that take options return a Transform, so they read as a declarative list:

await transform(pkg, resizeTextures({ maxImageSize: 2048 }), myCustomTransform);

Parameters

Parameter	Type
pkg	MaterialXPackage

Returns

void | Promise<void>

---

transform()

function transform(pkg, ...transforms): Promise<MaterialXPackage>;

Applies transforms to a package in order, awaiting each one. Returns the same package for chaining.

Parameters

Parameter	Type
pkg	MaterialXPackage
...transforms	Transform[]

Returns

Promise<MaterialXPackage>

---

rewriteResourcePath()

function rewriteResourcePath(
   document, 
   from, 
   to
): number;

Rewrites resource-reference attributes equal to from, returning how many were changed. Use this when a transform renames a resource (e.g. textures/a.png → textures/a.webp).

Parameters

Parameter	Type
document	MaterialXDocument
from	string
to	string

Returns

number

Validation

MaterialXAsset

One file that makes up a material: the root document, a texture, or a nested document.

Properties

Property	Type	Description
path	string	Relative to the root document's directory; for archives, the entry path.
bytes?	number	Uncompressed size; undefined when the resource could not be read.

---

MaterialXInspection

Results of every available rule, with explicit resource coverage.

Properties

Property	Type	Description
issues	MaterialXValidationIssue[]	-
summary?	MaterialXSummary	-
parseError?	string	-
resourcesChecked	boolean	-
assets	MaterialXAsset[]	Root document first, then every dependency that was attempted.
totalBytes	number	Sum of every readable asset.
resourcePaths	string[]	All attempted paths, including missing files, relative to the root document's directory.
resources	MaterialXResource[]	Successfully read loose resources; hosts may reuse their bytes for rendering.

---

inspectMaterialX()

function inspectMaterialX(
   raw, 
   fileName, 
   options?
): Promise<MaterialXInspection>;

Inspects XML or ZIP bytes using all validation rules. A host reader enables recursive loose dependency checks without mutating source bytes; archives use their own inventory. Reader failures are collected so one missing file does not hide other issues. The host must bound each read; this function also bounds dependency count and total retained bytes.

Parameters

Parameter	Type
raw	Uint8Array
fileName	string
options?	{ readResource?: ResourceReader; supportedCategories?: readonly string[]; }
options.readResource?	ResourceReader
options.supportedCategories?	readonly string[]

Returns

Promise<MaterialXInspection>

---

checkMaterialXZipArchive()

function checkMaterialXZipArchive(
   data, 
   limits?, 
   validation?
): MaterialXValidationIssue[];

Inspects .mtlx.zip bytes and validates the root document it contains.

Parameters

Parameter	Type
data	Uint8Array
limits?	Partial<MaterialXReadLimits>
validation?	MaterialXValidationOptions

Returns

MaterialXValidationIssue[]

---

materialXNodeRegistry

const materialXNodeRegistry: MaterialXNodeSpec[];

Every node category validateDocument recognizes: the standard library generated from the MaterialX node definitions plus a few built-in structural elements.

---

MaterialXNodeSpec

A node definition entry in the materialXNodeRegistry.

Properties

Property	Type
category	string
nodeDefName?	string
type?	string
nodeGroup?	string
attributes?	Readonly<Record<string, string>>
inputs	MaterialXNodePortSpec[]
outputs	MaterialXNodePortSpec[]
parameters	MaterialXNodePortSpec[]

---

MaterialXValidationIssue

One finding from validation. Errors make a file unusable; warnings are advisory.

Properties

Property	Type	Description
graph?	object	Optional graph coordinates for highlighting nodes and connections in a UI.
graph.scope	string	Slash-separated nodegraph path; empty for the document scope.
graph.containers?	object[]	All enclosing graph containers and compound instances affected by this finding.
graph.nodeIds	string[]	-
graph.input?	string	-
graph.source?	string	-
graph.output?	string	-
code?	string	Stable machine-readable identifier when supplied by the producing rule.
rule?	string	-
level	"error" | "warning"	-
message	string	-
location	string	-