| name | unreal-material-editing |
| description | Edit UE material node graphs and properties via text (ReadGraph/WriteGraph). Use when the user asks to add, remove, or rewire material expression nodes, or change material properties like ShadingModel or BlendMode. |
Material Editing
Material editing covers both material properties (ShadingModel, BlendMode, etc.) via the [Properties] section, and node graph (expression nodes and connections) via the [Material] section. Both use the same unified API.
Prerequisite: UE editor running with UCP plugin enabled.
API
CDO: /Script/UnrealClientProtocolEditor.Default__NodeCodeEditingLibrary
| Function | Params | Description |
|---|
Outline | AssetPath | Returns available sections (Properties, Material, Composite:Name) |
ReadGraph | AssetPath, Section | Returns text. Empty Section = all. "Material" = main graph only. |
WriteGraph | AssetPath, Section, GraphText | Overwrite section. Auto-recompiles, relayouts, refreshes editor. |
Material Properties
Use the [Properties] section to read/write material-level settings:
[Properties]
ShadingModel: MSM_DefaultLit
BlendMode: BLEND_Opaque
TwoSided: true
OpacityMaskClipValue: 0.333
Common properties:
| Property | Example Values |
|---|
ShadingModel | MSM_DefaultLit, MSM_Unlit, MSM_Subsurface, MSM_ClearCoat |
BlendMode | BLEND_Opaque, BLEND_Masked, BLEND_Translucent, BLEND_Additive |
MaterialDomain | MD_Surface, MD_DeferredDecal, MD_LightFunction, MD_PostProcess, MD_UI |
TwoSided | true, false |
Read with ReadGraph(AssetPath, "Properties"), write with WriteGraph(AssetPath, "Properties", text).
Section Model
| Section | Description |
|---|
[Properties] | Material-level properties (ShadingModel, BlendMode, etc.) |
[Material] | Complete main graph — all non-composite nodes, read/write as one unit |
[Composite:Name] | Composite subgraph (physically isolated) |
The [Material] section contains the entire main graph. Output pins are expressed as graph output connections: > RGB -> [BaseColor].
Text Format
[Material]
N_4kVm2xRp8bNw3yLq9dJs MaterialExpressionTextureSample {Texture:"/Game/Textures/T_Wood_BC"}
> RGB -> [BaseColor]
> A -> N_7tHn5cWs1fPx6zMr0gKu.A
N_9aEo3jXv2hQy8bFt4iLw MaterialExpressionScalarParameter {ParameterName:"Roughness", DefaultValue:0.5}
> -> N_7tHn5cWs1fPx6zMr0gKu.B
N_2dGq6lZx4jSa0cHv8kNy MaterialExpressionVectorParameter {ParameterName:"EmissiveColor", DefaultValue:{"R":1,"G":0.5,"B":0}}
> -> N_5fIr7mBz3kTb1eJw9lOa.A
N_7tHn5cWs1fPx6zMr0gKu MaterialExpressionMultiply
> -> [Roughness]
N_5fIr7mBz3kTb1eJw9lOa MaterialExpressionMultiply
> -> [EmissiveColor]
N_0hKt8nDc5lUd2gLx6mPb MaterialExpressionConstant {R:5.0}
> -> N_5fIr7mBz3kTb1eJw9lOa.B
N_3jMv0pFe7nWf4iNz8oCd MaterialExpressionTextureSample {Texture:"/Game/Textures/T_Wood_N"}
> -> [Normal]
N_6lOx2rHg9pYh5kPb1qEf MaterialExpressionTime
> -> N_8nQz4tJi0rAj7mRd3sFg.A
N_8nQz4tJi0rAj7mRd3sFg MaterialExpressionSine {Period:6.283185}
> -> N_1pSb6vLk2tCl9oTf5uGh.B
N_1pSb6vLk2tCl9oTf5uGh MaterialExpressionMultiply
> -> [WorldPositionOffset]
N_4rUd8xNm3vEn0qVh7wIj MaterialExpressionWorldPosition
> -> N_1pSb6vLk2tCl9oTf5uGh.A
Note how Time and WorldPosition — source-only nodes with no inputs — both have > -> lines. Without these lines they would be deleted as orphans.
Nodes
N_<id>: node reference ID. Two forms:
- Existing nodes:
N_<base62> — a 22-character Base62-encoded GUID (e.g. N_4kVm2xRp8bNw3yLq9dJs). ReadGraph always outputs this form. Preserve these IDs when writing back — they are the node's stable identity.
- New nodes:
N_new<int> — temporary ID for nodes you are creating (e.g. N_new0, N_new1). The system assigns a real GUID after WriteGraph.
<ClassName>: UMaterialExpression class name (e.g. MaterialExpressionMultiply, MaterialExpressionConstant3Vector){...}: non-default properties, single line
Connections
Connections are declared on the source (output) node only. Each > line under a node declares where that node's output goes. There is no "reverse" declaration — if a node has no > lines, it has no outgoing connections.
> OutputPin -> N_<target>.InputPin # named output to named input
> OutputPin -> [GraphOutput] # named output to material output
> -> N_<target>.InputPin # single-output node to named input
> -> N_<target> # single-output to single-input (both omitted)
CRITICAL — Orphan cleanup: After WriteGraph, any node not reachable from the material output pins is automatically deleted as an orphan. This means:
- Every node must be part of a connected chain that reaches a
[GraphOutput]. If you create a node but forget to write its > -> output connections, it will be silently deleted.
- Source-only nodes (nodes with no inputs, only outputs — e.g.
Time, ScreenPosition, ViewSize, TexCoord, WorldPosition, CameraPositionWS, VertexColor, constants) are especially prone to this. They must have > -> lines connecting their output to downstream nodes.
Multi-Output Nodes
Some nodes have multiple named outputs. Use the output name before ->:
| Node | Outputs |
|---|
MaterialExpressionScreenPosition | ViewportUV (float2, index 0), PixelPosition (float2, index 1) |
MaterialExpressionTextureSample | RGB, R, G, B, A, RGBA |
MaterialExpressionWorldPosition | (single output, omit name) |
MaterialExpressionViewSize | (single output float2, omit name) |
Example — ScreenPosition with named output:
N_4kVm2xRp8bNw3yLq9dJs MaterialExpressionScreenPosition
> ViewportUV -> N_7tHn5cWs1fPx6zMr0gKu.A
Common Input Pin Names
| Node Type | Input Pins |
|---|
Single-input nodes (Sine, Cosine, Tangent, Abs, OneMinus, Frac, Floor, Ceil, Saturate, SquareRoot, Length, Normalize) | Input (can be omitted) |
ComponentMask | Input (can be omitted) |
Binary math (Multiply, Add, Subtract, Divide) | A, B |
Power | Base, Exponent |
DotProduct, CrossProduct, Distance | A, B |
AppendVector | A, B |
LinearInterpolate | A, B, Alpha |
Clamp | Input, Min, Max |
If | A, B, AGreaterThanB, AEqualsB, ALessThanB |
Arctangent2Fast | Y, X |
Graph Outputs
Material output pins are expressed as [PinName]:
> RGB -> [BaseColor]
> -> [Roughness]
> -> [Normal]
> -> [EmissiveColor]
> -> [Opacity]
> -> [OpacityMask]
> -> [Metallic]
> -> [WorldPositionOffset]
Common Expression Classes
Source-only nodes (no inputs — must always have > -> output lines or they will be deleted as orphans):
| ClassName | Output | Description |
|---|
MaterialExpressionConstant | float1 | Float constant (property: R) |
MaterialExpressionConstant2Vector | float2 | Vector2 constant |
MaterialExpressionConstant3Vector | float3 | Vector3 constant (property: Constant:(R=,G=,B=,A=)) |
MaterialExpressionConstant4Vector | float4 | Vector4 constant |
MaterialExpressionScalarParameter | float1 | Float parameter |
MaterialExpressionVectorParameter | float3 | Vector parameter |
MaterialExpressionTexCoord | float2 | Texture coordinates |
MaterialExpressionTime | float1 | Time value |
MaterialExpressionScreenPosition | float2 × 2 | Outputs: ViewportUV, PixelPosition |
MaterialExpressionViewSize | float2 | Viewport resolution in pixels |
MaterialExpressionWorldPosition | float3 | World position |
MaterialExpressionVertexColor | float4 | Vertex color (outputs: R, G, B, A, RGB) |
MaterialExpressionCameraPositionWS | float3 | Camera position |
MaterialExpressionTextureObject | Texture | Texture reference |
Texture sampling:
| ClassName | Description |
|---|
MaterialExpressionTextureSample | Sample a texture (outputs: RGB, R, G, B, A, RGBA) |
MaterialExpressionTextureSampleParameter2D | Texture parameter |
Math — binary:
| ClassName | Inputs | Unconnected-default properties | Description |
|---|
MaterialExpressionMultiply | A, B | ConstA, ConstB (float) | A * B |
MaterialExpressionAdd | A, B | ConstA, ConstB (float) | A + B |
MaterialExpressionSubtract | A, B | ConstA, ConstB (float) | A - B |
MaterialExpressionDivide | A, B | ConstA, ConstB (float) | A / B |
MaterialExpressionPower | Base, Exponent | ConstExponent (float) | Base ^ Exponent |
MaterialExpressionDotProduct | A, B | (none) | Dot(A, B) → float1 |
MaterialExpressionCrossProduct | A, B | (none) | Cross(A, B) → float3 |
MaterialExpressionDistance | A, B | (none) | Distance(A, B) → float1 |
MaterialExpressionAppendVector | A, B | (none — both inputs required) | Append(A, B) — concatenates dimensions. Max output is float4. float1+float1→float2, float2+float2→float4. float3+float2 or larger FAILS. |
ConstA/ConstB are only available on the four basic arithmetic nodes (Multiply, Add, Subtract, Divide). They provide a scalar fallback when the corresponding input pin is unconnected. All other binary nodes require explicit input connections — use a MaterialExpressionConstant node to supply fixed values.
Math — unary (input: Input, can be omitted in connection):
| ClassName | Description |
|---|
MaterialExpressionOneMinus | 1 - X |
MaterialExpressionAbs | Absolute value |
MaterialExpressionNormalize | Normalize → same dimension |
MaterialExpressionLength | Length → float1 |
MaterialExpressionSquareRoot | sqrt |
MaterialExpressionFrac | Fractional part |
MaterialExpressionFloor | Floor |
MaterialExpressionCeil | Ceiling |
MaterialExpressionSaturate | Clamp to 0-1 |
Trig (input: Input; Period property: default 1 maps input range [0,1] to one full cycle. WARNING: Period:0 is BROKEN — it injects a float4 multiply that corrupts dimensions. For raw radians use Period:6.283185 (= 2π), which maps [0, 2π] to one full cycle):
| ClassName | Description |
|---|
MaterialExpressionSine | sin |
MaterialExpressionCosine | cos |
MaterialExpressionTangent | tan |
MaterialExpressionArctangent2Fast | atan2(Y, X) — inputs: Y, X |
Interpolation & logic:
| ClassName | Description |
|---|
MaterialExpressionLinearInterpolate | Lerp(A, B, Alpha) |
MaterialExpressionClamp | Clamp(Input, Min, Max) |
MaterialExpressionIf | If(A, B, AGreaterThanB, AEqualsB, ALessThanB) |
MaterialExpressionStaticSwitchParameter | Static bool parameter |
Channel operations:
| ClassName | Description |
|---|
MaterialExpressionComponentMask | Mask channels (properties: R, G, B, A booleans) |
Other:
| ClassName | Description |
|---|
MaterialExpressionPanner | UV panning |
MaterialExpressionTransform | Transform vector between spaces |
MaterialExpressionCustom | Custom HLSL code |
MaterialExpressionMaterialFunctionCall | Call a material function |
MaterialExpressionSetMaterialAttributes | Set material attributes |
Custom HLSL
For MaterialExpressionCustom, the Code property contains HLSL and InputNames defines custom inputs:
N_new0 MaterialExpressionCustom {Code:"float3 result = Input1 * Input2;\nreturn result;", OutputType:CMOT_Float3, InputNames:["A","B"]}
Defining Functions via Struct Wrapping
UE's Custom node does support function definitions — wrap them inside a struct. Direct top-level function definitions (float Foo(){...}) are rejected by the compiler, but struct member functions work:
struct MyHelpers
{
float Hash(float t)
{
return frac(sin(t * 613.2) * 614.8);
}
float2 Hash2D(float t)
{
return float2(
frac(sin(t * 213.3) * 314.8) - 0.5,
frac(sin(t * 591.1) * 647.2) - 0.5
);
}
float3 Compute(float2 uv, float time)
{
float h = Hash(time);
float2 offset = Hash2D(time);
return float3(uv + offset, h);
}
} Helpers; // <-- instance name after closing brace
return Helpers.Compute(UV, Time); // call via instance
Key rules:
- Define a
struct with all helper functions as member methods.
- Declare an instance immediately after the closing brace:
} InstanceName;
- Call functions via the instance:
InstanceName.FunctionName(args).
- Struct methods can call other methods in the same struct freely.
- Multiple structs are allowed — each must have its own instance name.
- Prefer struct functions over
#define macros — they support proper scoping, recursion-free multi-line logic, and the compiler gives better error messages.
Material Instances
Material instance parameter editing uses SetObjectProperty from the unreal-object-operation skill, not NodeCode. NodeCode is for editing the parent material's node graph.
Workflow
- Outline — see what sections exist
- ReadGraph("Properties") — check current material settings
- ReadGraph("Material") — get the full node graph
- Modify — edit properties and/or nodes
- WriteGraph("Properties", text) — update settings
- WriteGraph("Material", text) — update graph (auto-recompiles)
Key Rules
- Preserve node IDs — existing nodes have
N_<base62> IDs that encode their GUID. Always keep them unchanged when writing back. Use N_new<int> only for genuinely new nodes.
[Material] is the complete main graph — no per-output-pin splitting.- ReadGraph before WriteGraph — always read first.
- All operations support Undo (Ctrl+Z).
- Incremental diff — only changed nodes/connections are modified.
- Every node needs output connections — nodes without
> -> lines that aren't reachable from material outputs will be deleted as orphans. This is especially important for source-only nodes (constants, Time, ScreenPosition, ViewSize, etc.).
- Connections are output-side only — you declare where a node's output goes by writing
> -> lines under it. There is no way to declare an incoming connection on the target side.
- Track dimensions through the graph — UE material nodes have strict type rules. Binary math nodes broadcast (
float1 op floatN → floatN). AppendVector concatenates dimensions with a max of float4. ComponentMask reduces dimensions. DotProduct and Length always output float1. When building complex graphs, mentally track the dimension at each node to avoid overflow at AppendVector. See the Dimension Rules section below.
- Verify all node IDs before writing — every
N_<id> referenced in > -> connection lines must be defined as a node line in the same graph. Referencing an undefined ID will silently drop that connection.
- Pin name rule — single-input nodes (
Sine, Cosine, Abs, Saturate, OneMinus, ComponentMask, Length, etc.) use Input as their pin name or omit it entirely. NEVER use .A or .B for single-input nodes — those names only exist on binary nodes (Multiply, Add, DotProduct, etc.).
Dimension Rules
UE material compiler enforces strict dimension rules. Track the float-width through your node chain:
| Operation | Output dimension |
|---|
Multiply/Add/Subtract/Divide(floatN, floatN) | floatN |
Multiply/Add/Subtract/Divide(float1, floatN) | floatN (broadcast) |
AppendVector(floatA, floatB) | float(A+B), max float4 |
ComponentMask with K channels enabled | floatK |
DotProduct(floatN, floatN) | float1 |
CrossProduct(float3, float3) | float3 |
Length(floatN) | float1 |
Distance(floatN, floatN) | float1 |
Normalize(floatN) | floatN |
Sine/Cosine/Tangent(floatN) | floatN |
Abs/OneMinus/Saturate/Frac/Floor/Ceil(floatN) | floatN |
Arctangent2Fast(float1, float1) | float1 |
Common pitfall: passing a float2 through Multiply(float2, float2) still yields float2, but then AppendVector(float2, float2) yields float4. Another AppendVector with that float4 will fail to compile.
Error Handling
- Check
diff object in response for changes applied.
- Unknown expression class:
"Unknown expression class: ...".
- Pin not found:
"Input 'X' not found on N_... (ClassName). Available: [...]".
