Expressions and Conversions

The value-producing half of the Graph language: literals, identifiers, calls, member access and four arithmetic operators, evaluated into UMaterialExpression nodes. Everything on this page also applies inside an Outputs binding expression and an Outputs declaration default, which are single expressions in the same grammar.

Synopsis

<expression>     := <additive>
<additive>       := <multiplicative> [ { + | - } <multiplicative> ] …
<multiplicative> := <unary> [ { * | / } <unary> ] …
<unary>          := { + | - } <unary> | <postfix>
<postfix>        := <primary> [ <postfix-op> ] …
<postfix-op>     := . <identifier> | :: <identifier> | ( [ <argument> [ , <argument> ] … ] )
<primary>        := <identifier> | <number-literal> | <string-literal> | ( <additive> )
<argument>       := [ <identifier> = ] <additive>

That is the whole grammar. ( ) , . :: = + - * / are the only punctuation it knows.

Precedence and associativity

Highest binding first. The parser implements exactly these four levels — there is no fifth.

Operators that do not exist

Operand rules

Both operands of + - * / are tested in this order.

Rule 5 in full: the widened operand must be the one without an authoritative count, the authoritative count must be greater than zero, and the other operand's count must be less than or equal to it. Narrowing is never attempted at an operator — dropping channels there is deliberately refused so the size error surfaces instead.

There is no separate scalar-promotion step. A scalar operand is passed to the material node as-is and Unreal replicates it, so A * K with A a vec3 and K a float produces a single Multiply node, not an AppendVector splat.

Result of a binary operator

Unary operators

-2.0 is not folded into a negative literal by the expression evaluator: it becomes Constant(2.0) * Constant(-1). Inside a constructor argument it is folded, because constant folding accepts a leading + or - on a literal — vec3(-1.0, 0.0, 1.0) emits a single Constant3Vector.

Integer division

/ is the only operator with an extra type rule:

Integer division is not supported by the material graph; use float() or floor(a/b).

It fires when both operands carry the integer marker. That marker is set by exactly one thing: a direct call to an integer constructor (int, int2..4, ivec2..4, uint, uint2..4, uvec2..4). It is not set by literals, by variables, by suffixed literals such as 3u, or by the result of any operator.

Literals

Numeric literals

<number-literal> := { <digit> | . } … [ { e | E } [ { + | - } ] <digit> … ] [ <suffix> ]
<suffix>         := { f | F | h | H | u | U | l | L }

Every numeric literal is a 1-component floating-point value. There is no integer literal type.

Lexing details:

• Digits and . are consumed greedily into one token. Multiple . are accepted, and the numeric conversion is permissive: it takes the longest valid prefix and throws the remainder away without a diagnostic, so 0.5.5 is 0.5 and 0..5 is 0.
• At most one exponent is consumed. A second e / E terminates the token and begins an identifier.
• There is no hexadecimal, binary or octal notation, and no digit separators.
• A leading - is not part of the literal; it is the unary minus operator.

The eight suffixes f F h H u U l L are consumed and excluded from the token text. They have no semantic effect at all — not on the type, not on the width, not on the integer marker. Exactly one suffix character is allowed, and it is consumed only when the next character is not alphanumeric and not _. That is what distinguishes 0.55f; from 1.0fx.

String literals

A string literal is tokenized with escapes decoded and never evaluates to a value. It is legal only where an argument handler reads the literal text rather than evaluating it: a named UE.* or Substrate.* argument, an Output= / OutputName= selector, or a Path(…) asset reference.

vec4 Scene = UE.SceneTexture(Id = "PostProcessInput0");   // fine
float x    = "0.5";   // String literals can only be used in named UE builtin arguments.

Boolean literals

true and false (unreleased) lex as ordinary identifiers and resolve late — after Graph variables and after declared properties. They produce a UMaterialExpressionStaticBool node with one component, matched case-insensitively, and are the only way to feed a StaticSwitch input or a StaticBool function input from a Graph block.

Identifier resolution

A bare identifier is looked up on three surfaces, in order:

Step 1 compares the exact spelling first, then falls back to a case-insensitive scan. Step 2 is where a parameter becomes a node: it is created lazily on first read and inserted into the value map, so every later read is served by step 1.

Graph variable lookup is case-insensitive, but the value map is keyed by the spelling used at the assignment. float3 Color = …; followed by color = …; writes a second entry; later reads take whichever the exact-match test finds, and fall back to the first case-insensitive hit otherwise. Keep one spelling per variable.

Constructors

<constructor-call> := <constructor-name> ( <expression> [ , <expression> ] … )

34 names, all matched case-insensitively. Component count is decided purely by the last character of the name: 2 → 2, 3 → 3, 4 → 4, anything else → 1.

Names that look like they should exist and do not: vec1, ivec1, uvec1, bvec1 (the GLSL families start at 2); int1, uint1, bool1 (only float1 and half1 have a 1 spelling); hvec2..4 (no GLSL half family); double, dvec2..4; float2x2, float3x3, float4x4, mat2, mat3, mat4 (there are no matrix types anywhere in the language); and the removed aliases Scalar, Vector, Color. Each of those lexes as an ordinary identifier, falls through to the user-function lookup, and reports Unknown Graph function '{Name}'.

Argument rules

Arguments are evaluated left to right and screened before any arity check.

Then, with N the constructor's component count:

Rule 9 is a straight left-to-right concatenation of channels; mixed widths are fine as long as the total is exact.

Constant folding

When N >= 2, the name is not an integer constructor, and every argument is unnamed and a numeric literal (optionally with a leading unary + or -), the whole call collapses to one constant-vector node.

The folded node is the only constructor result that carries an authoritative component count. Folded vectors dedupe by value, so vec3(0.5) written five times is one Constant3Vector.

Swizzles

<swizzle>  := <expression> . <channels>
<channels> := <channel> [ <channel> ] [ <channel> ] [ <channel> ]
<channel>  := { x | y | z | w | r | g | b | a }

Exactly two sets exist: xyzw and rgba. There is no stpq set and no uv set — neither u nor v resolves, so .uv fails. Channel characters are case-insensitive, and mixing the two sets in one swizzle is accepted: .xg is channels 0 and 1, exactly like .xy.

Length and bounds

A swizzle can only narrow or rearrange; it can never read past the base width.

Lowering

Three strategies, tried in this order.

"Strictly increasing" is judged on the source channel of the underlying node, not on the letters written.

Composition

A swizzle of an already-masked value re-maps through the existing mask, so the numbering is always relative to the value being swizzled, not to the original node.

Composition folds into a single mask wherever the result is still sequential, so v.rgb.rg costs no nodes at all. Selecting an entry that does not exist in the outer list is a bounds failure against the masked width: v.ga.b reports Swizzle 'b' is invalid for a value with 2 components.

Because . is an ordinary postfix operator, any call result can be swizzled directly — no temporary is required:

float u  = UE.TexCoord().x;
vec3  c  = SampleTexture2D(Albedo, uv).rgb;
vec2  yx = vec4(1.0, 2.0, 3.0, 4.0).yx;
float m  = MyFunction(A, B).r;

Non-swizzlable bases

Conversions

Coercion is never written by the author. It is applied automatically wherever a value meets an expected shape, and it is the mechanism behind most silent width changes in a generated material.

Where it applies

Assignment to a name that is neither an existing variable nor an Outputs declaration performs no conversion at all: the new variable takes the value's own shape.

Rule order

Input width down the side, expected width across the top:

And across kinds:

The four texture dimensions are distinct expected shapes. Texture2D and SamplerState both mean Texture2D; Texture3D and VolumeTexture both mean VolumeTexture; TextureCube and Texture2DArray stand alone. A TextureCube never converts to a Texture2D.

vec4   Src = vec4(0.1, 0.2, 0.3, 0.4);
float3 Rgb = Src;      // silently becomes Src.rgb — channel A is dropped
float  R   = Src;      // silently becomes Src.r

Narrowing is deliberately not applied at binary-operator operands (the size-mismatch error fires instead), at constructor arguments, or at swizzle bounds.

The only widening rule is scalar splat. There is no zero-fill and no partial widening: float3 v = SomeFloat2; is Expected 3 component(s) but got 2. Use a constructor to say what the extra channels contain.

Float, int and bool

There are no numeric-representation conversions in the Graph language at all.

So int x = 7.9; stores 7.9 — use floor(…) if truncation is wanted — and bool b = 0.5; stores 0.5. The only observable difference between an integer and a float value is the integer marker, and its only effect is the integer-division rejection.

Authoritative component counts

A value carries an authoritative component count when its width is known from the engine rather than inferred from a declaration.

Known-width builtin node classes:

Every other node's output width is unknown to the generator.

The flag changes two things.

Effect 1 — the operator rescue. When + - * / receives two incompatible widths, one operand may be widened to the authoritative one, but only upward. This is why UE.CameraVectorWS() * Tint fails when Tint is a 4-component VectorParameter: the builtin is an authoritative 3, the parameter a non-authoritative 4, and 4 is greater than 3, so the rescue is blocked and the size error is raised.

Effect 2 — a declared width can be ignored.

float2 dir = UE.CameraVectorWS();   // stored as 3 components; float2 is ignored, no error
Color = dir * Tint;                 // fails HERE if Tint is 4 components

Effect 3 — branch merging. The authoritative flag and the integer flag are not compared when deciding whether an if branch changed a value, so two values differing only in those flags are treated as identical and the name is not merged.

Node reuse

Textually identical subexpressions over identical operand values collapse to one node. A + B written twice yields one Add; every occurrence of 0.5 in one asset maps to one Constant; the Constant(-1) behind unary minus is shared by every unary minus. The cache is keyed on a value identity token — node, output index, component count, all five mask fields, and the texture, attribute, Substrate, authoritative and integer flags — so int(2) and float(2) never collide, and re-assigning a variable between two textually identical calls correctly produces two nodes.

F_Tint(a, b) and F_Tint(b, a) are different keys because positional arguments are keyed by index; F_Tint(Color = a) and F_Tint(color = a) are the same key because argument names are normalised. Which call kinds dedupe at all is covered on Calls.

Diagnostics

Example

Shader(Name="Docs/M_Expressions")
{
    Properties {
        vec3 A = vec3(1.0, 0.5, 0.2);
        vec3 B = vec3(0.1, 0.2, 0.3);
        float K = 2.0;
    }
    Settings { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs { vec3 Color; Base.EmissiveColor = Color; }
    Graph {
        vec3 Sum    = A + B;
        vec3 Diff   = A - B;
        vec3 Scaled = A * K;
        vec3 Ratio  = A / K;
        vec3 Neg    = -Scaled;
        Color = (Sum + Diff - Scaled + Ratio) * 0.25 + Neg;
    }
}

VectorParameter A, VectorParameter B, ScalarParameter K   (property nodes)
Add(A, B)                                        -> Sum
Subtract(A, B)                                   -> Diff
Multiply(A, K)                                   -> Scaled
Divide(A, K)                                     -> Ratio
Multiply(Scaled, Constant(-1))                   -> Neg
Add / Subtract / Add chain, Multiply(..., 0.25), Add(..., Neg)

See also

• Statements — the statement forms an expression appears in
• Calls — call syntax, named arguments, output selection
• Math Builtins — fmod, pow, min, max, lerp, saturate
• UE.* Nodes — which builtins have a known output width
• What Graph Is Not — every rejected and every silently-truncated construct