UE.Expression

DreamShader » Builtins » UE.Expression

The reflected node call: creates any UMaterialExpression class of the builtin catalog by name and fills its input pins and properties from the arguments.

Synopsis

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

UE.<ClassName>( [ <arg-name> = <expression> ] … )

The two forms are one path through the binder. A call names its class with Class, or else with the name after UE., so UE.Sine(…) and UE.Expression(Class = "Sine", …) are identical; a Class argument on another name wins over the name. Expression names no class, which is why the first form needs Class — without it the call is DSH5218.

OutputType is no longer required (since 2.0.0): the catalog knows what every class makes. See OutputType.

Arguments are named. A positional argument binds only on the classes the catalog gives an argument order — TextureCoordinate, Constant, Constant2Vector, Constant3Vector, Constant4Vector, Transform, TransformPosition, Panner, ComponentMask, Time, and the five Substrate composition nodes — and is DSH5220 elsewhere, DSH5221 past the end of the order (since 2.0.0). On the 27 1.x names of the UE.* catalogue the legacy front end drops a positional argument first (DSH5254), except Input of the two transforms.

Text arguments may be quoted or bare: Class = Sine and Class = "Sine" are the same, as are OutputType = float3 and OutputType = "float3".

Order of resolution

A call goes through the stages of the compiler. Each stage reports all of its errors, and a stage with errors stops the pipeline before the next one (since 2.0.0; 1.x stopped at the first failing step).

Class resolution

Class takes a quoted string, a bare word or a dotted name (DSH5217 otherwise). The specifier is trimmed and looked up in the catalog, in this order:

Nothing matched is DSH5212. Rows 1–5 are case-sensitive.

[!IMPORTANT] UMaterialExpressionSine resolves (since 2.0.0; 1.x compared against the reflected name and never matched a U-prefixed spelling). USine does not.

[!NOTE] The catalog lists the classes loaded when it is built, abstract and deprecated ones left out. An expression class living in a plugin module the editor has not loaded is not in it.

On the Substrate.* path the name is the class, and Class= is DSH5216.

OutputType

OutputType — or its alias ResultType — is not required (since 2.0.0). The legacy front end takes it off the call, and the type of the value comes from the catalog. It still matters in two places:

• on a Custom node it is the node's output type — see Custom nodes;
• on a node with one numeric output, a numeric type token is the width the value is typed with, as in 1.x, and the node is wired whole.

Everything else it was — a texture, MaterialAttributes or Substrate token, a misspelled token — is dropped without a diagnostic. The token tables are on the OutputType page.

Argument dispatch

These names are not dispatched:

Every other argument is resolved against the class's catalog entry in this order. The first match wins.

An input-pin name beats a property of the same name; a real pin or property name beats an alias. The same pin or property twice is DSH4215.

The aliases are:

The catalog lists the input pins and the properties that are editable and neither deprecated nor transient; 1.x reached any UPROPERTY, editable or not (since 2.0.0). Argument names are otherwise exact: no separator is stripped.

Input pins

An argument that resolves to a pin is an expression and is connected. Its type is checked against the pin's as the catalog types it:

Literal properties

Any other matched name is a property, written into the node when it is built. The binder checks the value; the emitter writes it with the 1.x literal writer, and a value it cannot write is DSH8213, whose message carries the writer's own code.

A value the binder does not accept is DSH5224: a computed value for a numeric property, or a number for a text property.

[!WARNING] FStrProperty and FNameProperty never fail. Whatever text the argument carries — including an unresolvable path — is stored verbatim. Neither a diagnostic nor a fallback value is produced.

Enum values

The binder matches an enum value against the values the catalog lists for the property — hidden values left out, each written without its prefix (PostProcessInput0 for PPI_PostProcessInput0).

The 1.x match (rule L12) ignores case, spaces, tabs and the characters _, -, :, . and /, and tries the value whole, after an Enum:: scope, and after its own prefix. The node is written with the catalog's spelling. UE.SceneTexture and the transform bases rely on this.

Object properties

An object property takes Path(<root>, "<asset>"), a quoted object path "/Game/…", or Class'/Game/…'. A Path(…) argument is carried as text and resolved when the node is built. See Path(…).

[!WARNING] The null-on-failure rule is silent. UE.Expression(Class = "TextureSample", Texture = Path(Game, "Missing/T_Nope")) compiles with an unassigned texture instead of reporting the missing asset. Only the two property names Texture and TextureObject on UTexture-typed properties behave this way.

Selecting an output

A node with several outputs is read through one of two mutually exclusive selectors, which the front end turns into a selection on the call.

The name is compared with the outputs the catalog lists, exactly; in a 1.x source a name that matches only ignoring case is accepted with DSH5276. It may contain spaces (Output = "Second Roughness"). An unnamed masked output of a node with several outputs is listed under the channels its mask keeps (RGB, R, A); see output names.

Using neither selector, the call is the node: see Result type and component count.

Custom nodes

UE.Expression(Class = "Custom", …) — MaterialExpressionCustom too — makes a node whose pins are the call's (rule L4):

Result type and component count

The value of a call, by what the catalog says of the class:

In a 1.x source, a numeric OutputType on a class of row 4 or 5 types the value instead, as above.

An output's type is its mask's width when it has a mask, else the engine's value type; where the engine says only "a float", a table of known widths decides — 1.x's own, consulted for a class with one output, and a few rows the catalog adds:

A MaterialAttributes result is a material value.

Side effects on the material

Two classes are registered as material parameters when they are built, so they appear in the material instance editor:

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

Node reuse

The IR merges two nodes of the same class with the same properties and the same inputs into one, and everything that read the second reads the first (since 2.0.0). The comparison is of the nodes, not of the calls' spelling: argument order, an alias or a case-only difference play no part, and a Custom node merges like any other. A statement — a node with no output — never merges. See Node reuse.

SampleTexture2D

SampleTexture2D(<texture-object>, <uv>)

A reserved two-argument form, resolved by the legacy front end before user properties and functions and matched case-sensitively. It rewrites to

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

and the call stands for the whole sample: float4 t = SampleTexture2D(T, uv) is the RGBA output, float3 c = … the RGB output, .a the A output. Both arguments are positional and both are required; any other shape — a named argument, a third argument, an output selector — is DSH5256.

A property declared with a texture-sample parameter token (TextureSampleParameter2D and its kin) is called with its pins instead — BaseTex(Coordinates = uv). See Parameters in Graph.

Declaration form

A UE.<Name>(…) — UE.Expression(Class = …) included — may stand as a property type inside Properties. It is the declaration form of any UE. call: a local at the head of each Graph body that reads the property, bound like the Graph form. What differs from 1.x (since 2.0.0):

Notes

• Property names are flat. Dotted paths and [index] selectors are not accepted here; those exist only in the Settings section, which is a different resolver.
• A required pin left unconnected is a warning — DSH5279 in a 1.x source — and the engine reports it when the material compiles if the node needs the pin.
• A typo in a name and a typo in Class are two codes: UE.Sinee() is DSH5210, UE.Expression(Class = "Sinee") is DSH5212.
• A call may be swizzled like any other expression: UE.Expression(Class = "VertexColor").rgb. See Swizzle.
• dsc export-catalog writes out every class with its pins, properties, aliases and outputs — the practical way to discover argument names. The editor also exports a manifest to Saved/DreamShader/Bridge/material-expressions.json; see Bridge.

Diagnostics

Every code is listed with its message and its full description on its page in Diagnostics.

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(Input = UE.Time());

        // Explicit Class, an enum property by its value's name, then output 0 swizzled.
        float3 scene = UE.Expression(Class = "SceneTexture",
                                     SceneTextureId = "PostProcessInput0").Color.rgb;

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

        // Pins by their display names (True, False for A, B), and a bool property.
        float3 sel = UE.Expression(Class = "StaticSwitch",
                                   True = Dimmed, False = tex.rgb, DefaultValue = true);

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

Generated nodes:

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

See also

• Builtins — the call surfaces and the resolution order
• UE.* catalogue — the 1.x names and their argument lists
• OutputType — what the argument still does, and the output names
• Substrate — the sibling namespace that shares this path
• Substrate sugar — virtual arguments and operators
• Path(…) — asset-reference syntax for object properties
• Parameters in Graph — the parameter pin-call form
• Material attributes — the material value kind
• Conversions — widths and how values fit
• Node reuse — identical nodes
• Graph functions — UE.* calls hoisted into Custom-node pins
• Bridge — the exported reflected expression manifest
• Diagnostics index — every code