UE.Expression

The registered builtins cover 27 of Unreal's several hundred material expressions. UE.Expression is the escape hatch for everything else: it creates any non-abstract UMaterialExpression subclass by name and fills its input pins and UPROPERTYs from named arguments.

float pulse = UE.Expression(Class = "Sine", OutputType = "float1", Input = UE.Time());

There is a shorter spelling. Class defaults to the function name, so UE.Sine(…) and UE.Expression(Class = "Sine", …) are the same call through the same implementation:

float pulse = UE.Sine(OutputType = "float1", Input = UE.Time());

The name Expression is not special except that it never resolves to a class — which is exactly why Class= is mandatory in the first form.

UE.Expression( Class = <class-specifier> , { OutputType | ResultType } = <type-token>
               [, { { Output | OutputName } = <text> | OutputIndex = <int> } ]
               [, <arg-name> = <expression> ] … )

UE.<ClassName>( { OutputType | ResultType } = <type-token> [, <arg-name> = <expression> ] … )

Every argument must be named. A positional argument fails with Generic {Namespace}.{Function} calls require named arguments. Text arguments may be quoted or bare: Class = Sine and Class = "Sine" are the same, as are OutputType = float3 and OutputType = "float3".

Unlike the registered builtins, this path validates every argument name. A name that matches neither a pin nor a property is an error, not a silent drop.

Class resolution

Class must be a literal — a quoted string, a bare identifier, or a dotted name. The specifier is trimmed and then resolved:

Candidate names for a specifier S:

Both the prefix guards and the final comparison are case-insensitive.

On the Substrate.* path the class is fixed by the builtin descriptor and Class= is rejected outright.

Order of resolution

The call is processed in this order. The order is observable, because the first failing step is the only error reported.

OutputType

OutputType — or its alias ResultType, consulted only when OutputType is absent — is required on this path. Omitting it produces

Unsupported UE builtin call '{Function}' in Graph. For generic MaterialExpression calls, add OutputType="float1/2/3/4/Texture2D/TextureCube/Texture2DArray/VolumeTexture/Substrate".

That hint lists nine spellings. The accepted set has 44.

Accepted tokens

Every token, on every surface. Matching is case-insensitive throughout.

† On the property-declaration surface all five texture tokens resolve to the same declared kind — a texture-object property with 0 components. The dimension is not recorded there, unlike the Graph surface where TextureCube and Texture2DArray produce distinctly typed values. Declare the dimension with a plain type token (TextureCube Tex;) when it matters; see Types and values.

SamplerState is an accepted spelling of Texture2D on the Graph surface only. StaticBool and StaticBoolParameter both resolve to a one-component value; they exist so that a value can be type-checked against a StaticBool function input, and nothing else distinguishes them from float.

Normalization

The token is not normalized uniformly — three different comparisons are used, and the difference is observable when the token carries stray whitespace.

The normalized token also participates in the node reuse key. Two calls differing only in OutputType spelling — float3 versus vec3 — build different keys and therefore produce two nodes, even though the resulting value is identical.

Argument dispatch

Six argument names are reserved and never dispatched to the node:

Every other argument is resolved against the created node in this order. The first match wins.

Property matching runs in two passes:

Input pins

An argument that resolves to a pin — by pin name, or by a property whose type is an expression-input struct (FExpressionInput, or a struct named MaterialAttributesInput) — has its value evaluated as a Graph expression and connected. Any channel mask carried by the value is transferred to the connection.

The pin's declared value type is then checked against the value:

No width check is applied at a pin: connecting a float4 to a scalar pin is the engine's problem, not DreamShader's.

Literal properties

Any other matched property is written from a literal. Object-typed properties are read as asset references; everything else is read as literal text.

All of these are wrapped as UE.{Function} property '{Property}': {Message}.

Enum values

An enum value is matched against every non-hidden entry of the enum in four spellings. Both sides are lower-cased and the characters space, _, -, :, . and / are removed before comparison.

Rule 4 is what makes prefix-less spellings work, and what UE.SceneTexture relies on.

Object properties

An object-typed property takes Path(<root>, "<asset>"), Path("/Game/…") or a bare absolute object path. See Asset references.

UE.Expression(Class = "TextureSample", OutputType = "float4",
              Texture = Path(Game, "Missing/T_Nope"))

Selecting an output

A node with several outputs is read through one of two mutually exclusive selectors. Using both is an error; using neither selects output 0.

Name resolution walks the outputs in order:

The specifier is trimmed; an empty specifier selects output 0.

Custom nodes

UMaterialExpressionCustom is the one class with dedicated handling — it is how you drop raw HLSL into a Graph.

float3 tinted = UE.Expression(Class = "Custom", OutputType = "float3",
                              Code = "return In * 0.5f;",
                              In   = baseColor);

Result type and component count

The result is derived from the resolved output's real value type, in this order.

The known-width table:

Five classes then override the width from the values actually bound to their inputs:

A result with 0 components that is neither a texture nor a Substrate value is a MaterialAttributes value. See Types and values.

Side effects on the material

Two classes are registered as material parameters when created through this path, so they appear in the material instance editor:

Both are given a fresh expression GUID when theirs is invalid.

Node reuse

This is the surface that does deduplicate. Two cache keys are built per call:

An output-key hit returns the previous result immediately. An expression-key hit reuses the node and re-resolves only the output — which is how one multi-output node can serve two reads with different Output= selectors. Literal text in a key is normalized by collapsing runs of spaces and normalizing line endings. UMaterialExpressionCustom subclasses never participate.

Contrast this with the registered builtins, which consult no cache at all and create a fresh node per call.

SampleTexture2D

float4 texel = SampleTexture2D(BaseTex, uv);

A reserved two-argument form, resolved before user properties and functions and matched case-sensitively — sampletexture2d(t, uv) is not it. It rewrites to

UE.Expression(Class = "TextureSample", OutputType = "float4",
              TextureObject = <arg0>, Coordinates = <arg1>)

Both arguments are positional and both are required: SampleTexture2D expects exactly two positional arguments: (textureObject, uv).

Declaration form

A generic UE.<Name>(…) may also stand as a property type inside a Properties section, where any name outside the declaration-form catalogue is created by the same reflection machinery. The rules differ from the Graph form:

Properties {
    UE.Expression(Class = "ObjectRadius", OutputType = "float1") Radius;
}

Additional messages from this surface:

Writing the call in Graph is usually clearer, because the input relationships are visible at the call site.

Notes worth knowing

• Property names are flat. Dotted paths and [index] selectors are not accepted here; those exist only in material settings, which is a different resolver.
• There is no way to leave a required engine pin unconnected on purpose and no way to disconnect one. An argument either connects a value or is absent.
• Because Class defaults to the function name, a typo in a class name produces could not resolve MaterialExpression class rather than "unknown builtin". UE.Sinee(OutputType="float1") and UE.Expression(Class="Sinee", OutputType="float1") report the same thing.
• A generic call may be swizzled like any other expression: UE.Expression(Class = "VertexColor", OutputType = "float4").rgb.
• The editor exports a reflected expression manifest to Saved/DreamShader/Bridge/material-expressions.json, listing every resolvable class with its pins and properties. That is the practical way to discover argument names — see Editor tools.

Diagnostics

{Function} preserves the author's spelling and casing; {Namespace} is literally UE or Substrate.

The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_Generic")
{
    Properties {
        Texture2D BaseTex = Path(Game, "Textures/T_Noise");
        vec3      Dimmed  = vec3(0.2, 0.2, 0.2);
    }

    Settings { ShadingModel = "Unlit"; }

    Outputs {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        // Class defaults to the function name.
        float pulse = UE.Sine(OutputType = "float1", Input = UE.Time());

        // Explicit Class, plus an enum property written without its prefix.
        float3 scene = UE.Expression(Class = "SceneTexture", OutputType = "float4",
                                     SceneTextureId = "PostProcessInput0").rgb;

        // An object property through Path(...), and a pin reached by its pin name.
        float4 tex = UE.Expression(Class = "TextureSample", OutputType = "float4",
                                   Texture     = Path(Game, "Textures/T_Noise"),
                                   Coordinates = UE.TexCoord(Index = 0));

        // A class the generator sizes from its bound inputs.
        float3 sel = UE.Expression(Class = "StaticSwitch", OutputType = "float3",
                                   True = Dimmed, False = tex.rgb, Value = true);

        Color = (scene + sel) * pulse;
    }
}

Generated nodes:

Time                                  -> Sine                       (pulse)
SceneTexture (PPI_PostProcessInput0)  -> mask .rgb                  (scene)
TextureCoordinate (Index 0)           -> TextureSample.Coordinates
TextureSample (Texture = T_Noise)                                   (tex)
Constant3Vector (0.2, 0.2, 0.2)       -> StaticSwitch.True
StaticSwitch  (Value = true)                                        (sel)
Add, Multiply                                                       (Color)

Where to next