unreal-material-editing

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:

1. Define a struct with all helper functions as member methods.
2. Declare an instance immediately after the closing brace: } InstanceName;
3. Call functions via the instance: InstanceName.FunctionName(args).
4. Struct methods can call other methods in the same struct freely.
5. Multiple structs are allowed — each must have its own instance name.
6. 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

1. Outline — see what sections exist
2. ReadGraph("Properties") — check current material settings
3. ReadGraph("Material") — get the full node graph
4. Modify — edit properties and/or nodes
5. WriteGraph("Properties", text) — update settings
6. WriteGraph("Material", text) — update graph (auto-recompiles)

Key Rules

1. 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.
2. [Material] is the complete main graph — no per-output-pin splitting.
3. ReadGraph before WriteGraph — always read first.
4. All operations support Undo (Ctrl+Z).
5. Incremental diff — only changed nodes/connections are modified.
6. 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.).
7. 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.
8. 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.
9. 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.
10. 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: [...]".