Types and Values

A type token is the first element of every declaration form in the language. The set is closed — there are 44 tokens and no user-defined types — and it is matched case-insensitively in every context.

// Properties section
[const] <type> <name> [ = <default> ] [ [ <metadata> ] ] ;

// Inputs / Outputs / Results of a material function
[opt] <type> <name> [ = <default> ] [ [ <metadata> ] ] ;

// Shader Outputs variable declaration
<type> <name> [ = <expression> ] ;

// Function / GraphFunction signature
Function [ <type> ] <name> ( [ { in | out } ] <type> <name> , … ) { … }

// Graph declaration
<type> <name> [ = { <expression> | { <brace-initializer> } } ] ;

The token families

The six contexts

The declaration positions do not share one type set. Each is a column of the matrix below.

Validity matrix

✔ accepted · ✘ rejected. Comp. is the value's width as the graph builder sees it; 0 means an opaque value that carries no channels.

1. A texture-typed in parameter of a Function also emits a companion SamplerState <Name>Sampler parameter into the generated HLSL signature, and every call site inserts <argument>Sampler after the argument. See Functions.
2. Texture, SamplerState and Substrate declarations in a Graph block must carry an initializer — there is no default value for them. Error: Graph variable type '{Type}' requires an explicit initializer.
3. SamplerState is an alias of Texture2D in every context that accepts it. It resolves to a Texture2D texture object, not to a distinct sampler value.
4. SamplerState is not in the set that triggers the companion-sampler expansion of note 1, so a SamplerState in parameter emits SamplerState <Name> into the generated HLSL and receives a texture object at the call site.
5. MaterialAttributes resolves as a Function input type, but the token is emitted verbatim into the generated HLSL signature — see Generated HLSL spelling.
6. Substrate requires since UE 5.4. On an older engine the token does not resolve at all and the position-specific "requires Unreal Engine 5.4 or newer" diagnostic is emitted.
7. Substrate resolves as a Function / GraphFunction parameter or result type and is then rejected with a dedicated message.
8. In Properties, StaticBoolParameter is a parameter-node token, not a type token: it generates a UMaterialExpressionStaticBoolParameter and accepts only true / false as its default. See Property Types.

GLSL aliases

The vec / ivec / uvec / bvec spellings are first-class tokens everywhere their float / int / uint / bool counterparts are accepted. They are not rewritten in Properties, Inputs, Outputs, Graph declarations or Graph constructors.

Because int, uint, bool and half all collapse to the same float component counts, choosing between int3, ivec3, bool3 and float3 is documentation only. The single observable difference is the integer marker set by an integer constructor call in a Graph block, which exists solely to reject integer division. See Expressions and Conversions.

Rewrites inside Function bodies

A Function / GraphFunction signature runs every type token through a normaliser, and the body runs every identifier through a superset of the same map. Both match the lower-cased whole identifier.

15 signature aliases, 18 body aliases. The rewrite is comment- and string-aware, and applies to Function and GraphFunction bodies only — a Graph block is never normalised. In a Graph block, fract and mod are real math builtins since 1.5.0 and mix is a real alias of lerp; see Math Builtins.

Matrices

There are no matrix types. mat2 / mat3 / mat4 and float2x2 / float3x3 / float4x4 are rejected by every column of the matrix above.

mat2 / mat3 / mat4 are nevertheless accepted lexically in a Function signature, because the normaliser rewrites them before any validation runs. The declaration parses; the call fails:

Function float3 Rotate(in mat3 basis, in vec3 v) { return mul(basis, v); }
// parses; a call fails with:
//   DreamShader Function 'Rotate' input 'basis' uses unsupported type 'float3x3'.

Matrix-shaped work is reachable only through the transform builtins — see UE.* Nodes.

Literals

Scalars

float a = 1.0;
float b = -0.5;
float c = 1e-3;

In a Graph block a number is a real token with an optional exponent and one optional type suffix (f F h H u U l L), and the suffix is excluded from the value: 0.55f is 0.55. In a declaration default there is no numeric token at all — the raw text is converted late and tolerantly, which is why float Strength = 1abc; silently becomes 1.0. See Lexical Elements.

Vector construction

vec2   uv    = vec2(0.5, 0.5);
vec3   color = vec3(1.0, 0.2, 0.1);
float4 rgba  = float4(color, 1.0);

A constructor's component count comes from the last character of its name: …2 → 2, …3 → 3, …4 → 4, anything else → 1. Constructors accept any mix of scalars and vectors as long as the parts add up to the target width.

Brace initializers

vec3   color = {1.0, 0.2, 0.1};
float4 rgba  = {color, 1.0};

Useful for assembling an existing scalar or vector into a target type without repeating the type name.

Booleans and strings

true and false are accepted in declaration defaults, where they convert to 1.0 / 0.0 wherever a scalar is expected. String literals are values for settings, metadata, class names and UE.* named arguments; they are not values an expression can compute with.

Settings = { Domain = "UI"; }

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

Asset references

Texture and asset-valued declarations take a Path( … ) reference rather than a literal:

Properties = {
    Texture2D   MainTex     = Path(Game, "Textures/T_Main");
    Texture2D   PluginTex   = Path(Plugins.MoonToon, "Textures/T_Plugin");
    Texture2D   DefaultTex  = Path("/Engine/EngineResources/DefaultTexture");
    TextureCube SkyTex      = Path(Engine, "EngineResources/DefaultTextureCube");
}

Every accepted spelling, both resolvers and all their diagnostics are on Asset References.

Whitespace inside a token

The scalar/vector resolver used by Fn in, Fn out, Out decl and Graph lower-cases the token and then removes every space before comparing, and the MaterialAttributes / Substrate predicates do the same. Texture, SamplerState and StaticBool tokens are compared verbatim (ignoring case only), so Texture 2D does not resolve.

The Properties dispatcher does not do this, so float 3 X; there splits as the type float and the name 3 X and fails differently.

Generated HLSL spelling

When a Function is lowered to a generated .ush helper, each declared token is written into the HLSL signature with exactly one rewrite applied:

Removed tokens

They are not special-cased anywhere; they fall through to the generic unsupported-type diagnostic of whichever context they appear in — Unsupported property type 'Scalar'. in a Properties block, Unsupported Graph variable type 'Color' for '{Name}'. in a Graph block.

Example

One token from each family, each in a context that accepts it:

ShaderFunction(Name="Functions/F_Types")
{
    Properties = {
        float     Strength = 1.0;              // scalar token
        vec3      Tint     = vec3(1, 1, 1);    // GLSL vector spelling
        Texture2D Noise    = Path(Game, "Textures/T_Noise");
    }

    Inputs = {
        vec2                   UV;             // numeric
        opt StaticBool         UseTint;        // Inputs-only token
        opt MaterialAttributes InAttrs;        // Inputs-only token
    }

    Outputs = {
        vec3 OutColor;
    }

    Graph = {
        Texture2D Src = Noise;                 // texture declarations need an initializer
        vec4   Sampled = SampleTexture2D(Src, UV);
        float3 Base    = Sampled.rgb * Strength;
        OutColor       = Base * Tint;
    }
}

Diagnostics

Where to next