italink/unrealclientprotocol/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);
    }