UE builtins

DreamShader » Builtins » UE builtins

The 27 names in the UE. namespace that 1.x implemented itself, each with a fixed argument list, and the three it special-cased. Since 2.0.0 every UE. name — these included — is a node of the reflected builtin catalog; what the 1.x names keep is their 1.x argument lists, which the legacy front end applies to a .dsm / .dsf / .dsh before the binder sees the call.

Synopsis

// expression form, inside Graph
UE.<Name> ( [ <argument> [ , <argument> ] … ] )

<argument> := <arg-name> = <expression>

// declaration form, inside Properties
UE.<Name> [ ( <key> = <value> [ , <key> = <value> ] … ) ] <property-name> ;

The namespace prefix is matched exactly (since 2.0.0): in a Graph, ue.TexCoord() reads ue as a variable and fails with DSH4200. The builtin name is matched exactly, and in a 1.x source a name that matches only when case is ignored is accepted with the warning DSH5276 — UE.texcoord() is UE.TexCoord(). Argument names are trimmed and matched the same way, and are otherwise exact — Un_Mirror_U is not UnMirrorU.

Each name is a class of the catalog: its short name (the class name without MaterialExpression) or one of the 1.x aliases the catalog carries — TexCoord, ObjectPosition, CameraVector, CameraPosition, ReflectionVector, ViewportUV, TransformVector. Any other engine class is reached the same way, by its short name (UE.Expression); a name the running engine has no class for is DSH5210.

[!WARNING] An argument a 1.x name did not read is dropped, with a warning. For the 27 names in the catalogue, the legacy front end keeps the argument list of each entry below and drops every other argument — an unknown or misspelled name, or a positional argument — with DSH5254 (since 2.0.0; 1.x dropped them without a word). UE.TexCoord(Indx = 3) still produces UV channel 0, and says why; UE.Panner(SpedX = 1) pans at the node default speed and says so. The only positional argument kept is index 0 of UE.TransformVector and UE.TransformPosition (→ Input). An argument that passes the filter is bound against the catalog like the argument of any node call.

Output widths

The type of a call is the catalog's — the engine's own description of the class, on the running engine (dsc export-catalog writes it out):

• a masked output is as wide as its mask;
• an unmasked output has the engine's value type, or, where the engine says only "a float", a width DreamShader keeps for the class: 1 for Time, PixelDepth, SceneDepth, ObjectRadius, TwoSidedSign, PerInstanceRandom, PerInstanceFadeAmount; 2 for TextureCoordinate, Panner; 3 for ObjectPositionWS, ObjectBounds, CameraVectorWS, CameraPositionWS, ReflectionVectorWS, VertexNormalWS, VertexTangentWS, PixelNormalWS, Transform, TransformPosition;
• an output the engine does not type at all is as wide as the place it is read into;
• a node with several outputs is read by naming one (UE.ScreenPosition().ViewportUV), or used whole where its first output — or the value its channel outputs make up (float4 VC = UE.VertexColor();) — fits exactly. In a 1.x source, a node whose first output has no fixed width is read as that output (DSH5287), and so is any node passed straight to a pin — UE.TransformPosition(UE.WorldPosition(), …) takes XYZ, as 1.x connected it (2.0.0 – 2.1.0 refused one whose first output has a fixed width with DSH5201).

None of these builtins produces a texture object, a MaterialAttributes value or a Substrate value. See Conversions.

Catalogue

All 27 1.x names, in 1.x registration order. The Output column is what the UE 5.8 catalog gives.

Three further names are handled apart and documented under Special-cased builtins: UE.StaticSwitchParameter, UE.CollectionParam / UE.CollectionParameter, and UE.SceneTexture.

Class names are written without the MaterialExpression prefix in the table above.

[!NOTE] 1.x registered UE.ObjectPositionWS, UE.ObjectPosition, UE.ScreenPosition and UE.ViewportUV only where their class resolved on the running editor. The catalog lists every class the running engine has, so nothing is registered conditionally (since 2.0.0).

UE.TexCoord

UE.TexCoord([Index = <int>] [, UTiling = <float>] [, VTiling = <float>]
            [, UnMirrorU = <bool>] [, UnMirrorV = <bool>])

Node UMaterialExpressionTextureCoordinate; output float2.

Index is the catalog's alias of CoordinateIndex. CoordinateIndex itself is not on the 1.x list, so in this form it is dropped with DSH5254; the declaration form takes both. A negative Index is written through without a diagnostic.

UE.Time

UE.Time([Period = <float>] [, IgnorePause = <bool>])

Node UMaterialExpressionTime; output float1. Supplying Period also turns on the node's period override: the front end adds bOverride_Period = true to the call. No range check is applied: a negative Period is written through unchanged — in the declaration form too (since 2.0.0).

UE.Panner

UE.Panner([Coordinate = <expr>] [, Time = <expr>] [, Speed = <expr>]
          [, SpeedX = <float>] [, SpeedY = <float>] [, FractionalPart = <bool>])

Node UMaterialExpressionPanner; output float2. ConstCoordinate is dropped with DSH5254 in this form; the declaration form passes it through, and so does the class name: UE.Expression(Class = "Panner", ConstCoordinate = 1).

UE.WorldPosition

UE.WorldPosition()

Absolute world position — the node's shader-offset mode is left at its default. ShaderOffsets is dropped with DSH5254 here; use UE.TranslatedWorldPosition for the camera-relative variant, or UE.Expression(Class = "WorldPosition", WorldPositionShaderOffset = …) for the other modes. The property declaration does take ShaderOffsets.

UE.ObjectPositionWS

UE.ObjectPositionWS()

UE.ObjectPosition is an alias. The declaration form takes an Origin argument; the expression form drops it with DSH5254.

UE.CameraVectorWS

UE.CameraVectorWS()

UE.CameraVector is an alias for the same node.

UE.VertexNormalWS

UE.VertexNormalWS()

UE.VertexTangentWS

UE.VertexTangentWS()

UE.ScreenPosition

UE.ScreenPosition()

The node has two outputs, which the engine does not type: UE.ScreenPosition().ViewportUV is as wide as the place it is read into. Used as a plain value in a 1.x source the call is its first output, ViewportUV (DSH5287). UE.ViewportUV is an alias of the class.

UE.VertexColor

UE.VertexColor()

The outputs are channel views of one colour: float4 c = UE.VertexColor(); is the whole colour, and UE.VertexColor().a is the A output.

UE.PixelDepth

UE.PixelDepth()

A scene read for the current pixel: the node is created with no UV or offset input wired.

UE.SceneDepth

UE.SceneDepth()

No-argument form only; an argument is dropped with DSH5254 and the node's UV input is left unconnected. To wire one, use UE.Expression(Class = "SceneDepth", Input = <uv>).

UE.SceneColor

UE.SceneColor()

UE.TranslatedWorldPosition

UE.TranslatedWorldPosition()

Equivalent to GetTranslatedWorldPosition(Parameters) in HLSL. The front end rewrites the call to UE.WorldPosition(WorldPositionShaderOffset = CameraRelative), after dropping any argument with DSH5254; the node's default mode is absolute world position, which is the only difference from UE.WorldPosition. The catalog has no class of this name. (2.0.0 – 2.1.0 wrote the value as WPT_CameraRelative, which matched, but with the warning DSH5278 at every call.)

UE.ObjectPosition

UE.ObjectPosition()

Alias of UE.ObjectPositionWS.

UE.ObjectRadius

UE.ObjectRadius()

UE.ObjectBounds

UE.ObjectBounds()

UE.CameraVector

UE.CameraVector()

Alias of UE.CameraVectorWS.

UE.CameraPosition

UE.CameraPosition()

UE.ReflectionVector

UE.ReflectionVector()

UE.PixelNormalWS

UE.PixelNormalWS()

UE.TwoSidedSign

UE.TwoSidedSign()

UE.PerInstanceRandom

UE.PerInstanceRandom()

UE.PerInstanceFadeAmount

UE.PerInstanceFadeAmount()

UE.ViewportUV

UE.ViewportUV()

The engine has no dedicated ViewportUV expression class; this is UE.ScreenPosition under a second name — the catalog's alias of the class — and ViewportUV is the node's first output.

UE.TransformVector

UE.TransformVector({ Input = <expr> | <expr> } [, Source = <basis>] [, Destination = <basis>])

Node UMaterialExpressionTransform; output float3.

A basis is a value of the engine's enum, written without its prefix — Tangent, Local, World, View, Camera, Instance — and, in a 1.x source, also with its prefix (TRANSFORMSOURCE_World) or in another case, with the warning DSH5278. The names 1.x had of its own are written as the engine's, with the same warning: AbsoluteWorld is World, Particle and InstanceParticle are Instance (2.0.0 – 2.1.0 refused them with DSH5215). Any other value is DSH5215, which names the property that failed — TransformSourceType for Source, TransformType for Destination. Full basis reference: Transform bases.

UE.TransformPosition

UE.TransformPosition({ Input = <expr> | <expr> } [, Source = <basis>] [, Destination = <basis>]
                     [, PeriodicWorldTileSize = <expr>] [, FirstPersonInterpolationAlpha = <expr>])

Node UMaterialExpressionTransformPosition; output float3.

A basis is a value of the engine's enum, written without its prefix — Local, World, TranslatedWorld, View, Camera, Instance, and on the engines that have them PeriodicWorld and FirstPersonTranslatedWorld — and, in a 1.x source, also with its prefix or in another case (DSH5278). The 1.x names are written as the engine's, with the same warning: AbsoluteWorld is World, CameraRelativeWorld is TranslatedWorld, FirstPerson is FirstPersonTranslatedWorld, Particle and InstanceParticle are Instance (2.0.0 – 2.1.0 refused them with DSH5215). A value the running engine's enum does not have is DSH5215.

[!WARNING] The two optional pins follow the engine. On an engine whose class lacks a pin, the argument is no pin of the node: in a 1.x source it is kept with the info DSH5291, and building the node fails with DSH8212 (since 2.0.0; 1.x dropped PeriodicWorldTileSize silently and refused FirstPersonInterpolationAlpha with an error of its own).

[!NOTE] The node's own Destination is Local; 1.x wrote World, and the front end writes it too, so a call without Destination still goes to world space and dsc migrate writes Destination = World out. (2.0.0 – 2.1.0 wrote nothing, and such a call went to Local.)

Special-cased builtins

UE.StaticSwitchParameter and UE.SceneTexture are rewritten by the legacy front end into UE.Expression calls before the binder sees them. UE.CollectionParam is not: the catalog knows it as a second name of UE.CollectionParameter.

UE.StaticSwitchParameter

(since 1.2.3)

UE.StaticSwitchParameter(Name = "<parameter-name>",
                         { True = <expr> | <expr> }, { False = <expr> | <expr> }
                         [, Default = <bool>] [, Group = "<text>"]
                         [, Description = "<text>"] [, SortPriority = <int>])

The call becomes UE.Expression(Class = "StaticSwitchParameter", ParameterName = …, DefaultValue = …, Group = …, Desc = …, SortPriority = …, A = <True>, B = <False>); any other argument is dropped with DSH5254. Node UMaterialExpressionStaticSwitchParameter.

The output follows the branches: it is as wide as the wider numeric branch, or the Substrate or MaterialAttributes value a branch carries. The two branches are not compared with each other (since 2.0.0); a texture in either is DSH5214.

The parameter is registered with an editor-only static-switch value on the generated material — or material function — so it appears in the instance editor. Two calls with the same arguments are one node.

[!NOTE] Group and Description are written to the node's Group and Desc properties; a value that is neither a quoted string nor a word is DSH5224 (since 2.0.0; 1.x discarded it without a diagnostic).

UE.CollectionParam

(since 1.2.3)

UE.CollectionParameter(Collection = Path(<root>, "<asset>"), Parameter = "<name>"
                       [, Group = "<text>"] [, SortPriority = <int>] [, Desc = "<text>"])

UE.CollectionParam and the engine's name, UE.CollectionParameter, are one class, in a Graph body and in the declaration form. (2.0.0 – 2.1.0 refused UE.CollectionParam in a Graph body with DSH5210.)

Node UMaterialExpressionCollectionParameter. The collection is loaded and the parameter looked up when the node is built: a collection that does not resolve or load is DSH8213, a name that is neither a scalar nor a vector parameter of it is DSH8254. A call without Collection or Parameter is not checked (since 2.0.0). Description is not an argument of this call — the node's description property is Desc — and is DSH5213.

The engine does not type the node's output, so the value is as wide as the place it is read into (since 2.0.0; 1.x read the width off the loaded collection: float4 for a vector parameter, float1 for a scalar). The declaration form declares it float4 unless it says otherwise.

[!WARNING] Group and SortPriority are taken only where the running engine's class has them. On an engine whose class lacks them, Group is DSH5213, and SortPriority — a number — is kept with DSH5291 and fails with DSH8212 when the node is built (since 2.0.0; 1.x dropped both silently below its version gate).

Path(…) grammar and its accepted roots: Path(…).

UE.SceneTexture

UE.SceneTexture(Id = "<scene-texture-id>")

Pure sugar. The front end rewrites the call to

UE.Expression(Class = "SceneTexture", SceneTextureId = <Id>)[0]

— output 0 of UMaterialExpressionSceneTexture, Color, a float4. The call must have exactly one argument and it must be named Id; anything else, an output selector included, is DSH5255. The node's other properties and its Size / InvSize outputs need UE.Expression(Class = "SceneTexture", …).

The Id is a value of ESceneTextureId, written without its prefix — "PostProcessInput0". In a 1.x source the prefixed name ("PPI_PostProcessInput0"), the ESceneTextureId:: scope and another case are accepted with DSH5278; a display name, or a spelling with spaces in it ("ppi postprocessinput0"), is DSH5215 (since 2.0.0). See enum values.

Properties declaration form

UE.<Name>(…) may also stand where a type token would in a Properties section. It declares no parameter. The legacy front end keeps the text and, in every Graph body that reads the property, declares a local of that name at the head of the body, initialised with the call — float2 UV = UE.TexCoord(Index = 0); — one per such body, in property order. A body that does not read the property gets no node. From there the call is an ordinary UE. call, bound against the catalog (since 2.0.0).

Properties {
    UE.TexCoord(Index = 0) UV;
    UE.CollectionParam(Collection = Path(Game, "MPC_Weather"), Parameter = "Wind") Wind;
}

The 1.x names, as this form takes them:

ShaderOffsets takes the values of EWorldPositionIncludedOffsets without their prefix — Default, ExcludeAllShaderOffsets, CameraRelative, CameraRelativeNoOffsets — and, in another case or with the WPT_ prefix, with DSH5278. Origin takes Absolute and CameraRelative. The 1.x spellings that are no value of the enum (IncludingShaderOffsets, Absolute and NoOffsets for ShaderOffsets, World for Origin, …) are DSH5215 (since 2.0.0).

Declared output width

The type of the local comes from the first of these that applies:

1. an OutputType or ResultType argument naming a type — see OutputType;
2. the name, compared ignoring case: TexCoord, Panner → float2; Time → float; WorldPosition, CameraVectorWS, ObjectPositionWS, VertexNormalWS, VertexTangentWS → float3;
3. every other name → float4: ScreenPosition, VertexColor, CollectionParam / CollectionParameter, and any name outside the list (since 2.0.0; 1.x rejected such a name without an OutputType).

The call initialises the local like any initializer: a scalar output is spread across the local's width, a wider one is cut down (DSH5289), and a narrower vector — a float3 node under a name outside the list — is DSH4228. An output the engine does not type, such as a collection parameter's, takes the local's width. Give such a declaration an OutputType; a scalar collection parameter is OutputType = float1.

A const in front of a UE.* declaration is read and ignored (since 2.0.0; 1.x rejected it).

Notes

• A UE.* call may be swizzled directly: UE.TexCoord(Index = 0).x is a postfix chain. On a node of channel outputs a swizzle that one output publishes is that output (UE.VertexColor().a). See Swizzle.
• Two identical calls in one graph are one node, whichever builtin they are: the IR merges nodes with the same class, properties and inputs (since 2.0.0; 1.x merged only the generic and Substrate.* calls). See Node reuse.
• A property, local or parameter named TexCoord does not shadow UE.TexCoord; one named UE does — UE.X(…) is then a member call on that variable (since 2.0.0). See Name resolution.
• On the 27 names, OutputType, ResultType and Class are dropped with DSH5254 like any argument the name does not read. Output, OutputName and OutputIndex select an output of the node, as on every call (since 2.0.0).
• Inside a GraphFunction, UE.* calls are lifted out of the HLSL body and become generated input pins on the emitted Custom node.

Diagnostics

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

Expression form

UE.StaticSwitchParameter

UE.CollectionParameter

Declaration form

Example

Shader(Name="Docs/M_UEBuiltins")
{
    Properties {
        vec3 Tint = vec3(1.0, 0.6, 0.2);
        UE.TexCoord(Index = 0) UV0;
    }

    Settings {
        Domain       = "UI";
        ShadingModel = "Unlit";
    }

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

    Graph {
        float2 uv    = UE.Panner(Coordinate = UV0, Time = UE.Time(), SpeedX = 0.1, SpeedY = 0.0);
        float3 wp    = UE.TranslatedWorldPosition();
        float3 nrm   = UE.TransformVector(UE.VertexNormalWS(), Source = "World", Destination = "Tangent");
        float  fade  = UE.PerInstanceFadeAmount();
        float4 vcol  = UE.VertexColor();

        Color = (vec3(uv.x, uv.y, wp.z) + nrm) * Tint * vcol.rgb * fade;
    }
}

Generated nodes:

TextureCoordinate  (CoordinateIndex 0)        <- UV0        (a local at the head of Graph)
Panner             (Coordinate, Time, SpeedX) <- uv
Time                                          <- Panner.Time
WorldPosition      (camera-relative)          <- wp
VertexNormalWS                                -> Transform
Transform          (World -> Tangent)         <- nrm
PerInstanceFadeAmount                         <- fade
VertexColor                                   <- vcol

See also

• Builtins — the call surfaces and how a callee is resolved
• UE.Expression — every engine class by its name
• OutputType — what the argument still does in a 1.x source
• Transform bases — the basis values
• Substrate — the sibling namespace
• Math builtins — pow, fmod, min, max and the rest
• Properties — the section grammar the declaration form lives in
• Parameter nodes — the explicit *Parameter tokens
• Path(…) — asset references for UE.CollectionParameter
• Node reuse — identical calls and nodes
• Conversions — widening and cutting down
• dsc migrate — the .dss spelling of each 1.x call
• Diagnostics index — every code