Unreal Material Editing

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

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:

Read with ReadGraph(AssetPath, "Properties"), write with WriteGraph(AssetPath, "Properties", text).

Section Model

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 ->:

Example — ScreenPosition with named output:

N_4kVm2xRp8bNw3yLq9dJs MaterialExpressionScreenPosition
  > ViewportUV -> N_7tHn5cWs1fPx6zMr0gKu.A

Common Input Pin Names

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):

Texture sampling:

Math — binary:

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):

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):

Interpolation & logic:

Channel operations:

Other:

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:

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: [...]".