`material`

Rendering & look Experimental

Material asset authoring: instance parameters and graph import and export (MGIR text).

What it’s for

This namespace covers the three things you do to materials from outside the editor: create and edit material assets, override the tweakable parameters on a material instance, and move a whole material graph in and out as readable text. It is how your assistant sets up a look, dials in a variant, or captures an existing material so it can reason about the node graph.

Material instances are the common case. A material instance inherits from a parent material and overrides named parameters (a scalar roughness, a vector tint, a texture slot, a static switch). Your assistant creates the instance from a parent, then sets those overrides one at a time with the typed setters, or all at once as a batch. Reading the instance back gives you both the current overrides and the parent metadata needed to interpret them.

The graph side is text-based. A material or material function can be decompiled to MGIR, a line-oriented text form of the expression graph, and MGIR text can be compiled back into an asset. That is what lets an assistant inspect what a material actually does, edit it as text, and write it back, rather than clicking through node panels.

For high-level authoring workflows the work goes through the material.authoring layer; for raw node-by-node edits when authoring doesn’t expose the node type you need, reach for material.graph. To move, rename, or fix references on a material asset itself, use the asset namespace instead.

This area is experimental and still improving. Method names, parameters, and MGIR text shape can change between releases, so treat it as a moving surface rather than a frozen API.

Examples

Spin up a tinted material instance

Create an instance from a parent material, then override one scalar parameter.

You: Make a red-tinted instance of M_Metal with roughness 0.2.

  call("material.authoring.create_material_instance", {name:"MI_Metal_Red",
        parentMaterial:"/Game/Materials/M_Metal", path:"/Game/Materials"})
    → {ok:true, assetPath:"/Game/Materials/MI_Metal_Red"}
  call("material.authoring.set_scalar_parameter_value",
        {assetPath:"/Game/Materials/MI_Metal_Red", parameterName:"Roughness", value:0.2})
    → {ok:true}

Done. MI_Metal_Red created with Roughness overridden to 0.2.

Apply several overrides in one pass

Set scalar, vector, and texture parameters together so a single recompile covers them all.

You: On MI_Metal_Red set the tint to red, roughness to 0.2, and swap in T_Scratches.

  call("material.authoring.set_material_instance_parameters",
        {assetPath:"/Game/Materials/MI_Metal_Red",
         scalar:{Roughness:0.2},
         vector:{BaseColor:{r:1, g:0, b:0, a:1}},
         texture:{Detail:"/Game/Textures/T_Scratches"}})
    → {ok:true}

Done. Applied 3 parameter overrides in one recompile pass.

Export a material graph as text

Decompile a material to MGIR so your assistant can read the graph before editing it.

You: Show me the node graph of M_Metal as text.

  call("material.decompile_mgir",
        {assetPath:"/Game/Materials/M_Metal", includeReferencedFunctions:true})
    → {mgir:"material M_Metal { BaseColor = ... Roughness = ... }"}

Done. M_Metal decompiled to MGIR, referenced functions included.

← Back to all namespaces