Shader

DreamShader » DreamShaderLang » Shader

A top-level block that declares one Unreal material asset: its parameters, its render-state settings, its output bindings, and the node graph that feeds them.

Synopsis

Shader(Name = "<asset-path>" [, Root = "<root>"])
{
    [Properties [=] { <property-declaration> ; … }]
    [Settings   [=] { <key> = <value> ; … }]
    [Outputs    [=] { { <output-declaration> ; | <output-binding> ; | Expression( … ) { Pin[i] = <source> ; … } } … }]
    [Graph      [=] { <graph-statement> … }]
    [Layout     [=] { { Node( … ) | Comment( … ) } ; … }]
}

The = between a section name and its { … } block is optional sugar (since 1.5.0); a ; after a section's closing } is optional. Sections may appear in any order and may be repeated.

The keyword Shader is matched case-sensitively; section names are matched case-insensitively. See Lexical elements.

A .dss writes the same material as #pragma material(...), uniforms and one export void <Name>(inout material m) — see DreamShaderLang 2.0; dsc migrate rewrites a .dsm that way.

Header attributes

Attribute keys are matched case-insensitively (name= works). Values may be quoted or bare; a bare value ends at the first , or ). A duplicate key keeps the later value, with the warning DSH2244 (since 2.0.0; silent before). A trailing comma before ) is accepted, as in 1.x (2.0.0 – 2.1.0 refused it with DSH2243).

Full Name / Root grammar, the accepted root spellings, and the resulting on-disk path are specified in Asset paths.

Sections

Properties in a Shader declares parameter, const and UE.* builtin nodes. This is not the same grammar Properties gets inside a VirtualFunction, where it is a synonym for Inputs.

The Outputs / Graph relationship

Outputs holds two kinds of statement, disambiguated per statement:

The rule that governs whether Graph is required is evaluated after the whole block is read:

• A Shader with no Graph section and an empty Outputs is DSH2255. Without a Graph, the Outputs statements have to compute the values themselves — an output declaration with an initializer, or (since 2.0.0) a binding whose right side is an expression, such as Base.FrontMaterial = Substrate.Layer(Coat, Body);.
• An empty Graph = { } is legal.
• Bindings are what actually connect the material. A Shader with no Outputs section is the warning DSH2256: the material builds, with nothing wired to it (since 2.0.0; through 1.9.x generation then failed).

// Legal: no Graph body needed, the output declaration carries its own initializer.
Shader(Name="M_Flat")
{
    Properties = { vec3 Tint = vec3(1.0, 0.2, 0.2); }
    Outputs = {
        vec3 Color = Tint;
        Base.EmissiveColor = Color;
    }
    Graph = { }
}

Generated asset

Name + Root resolve to a package path exactly as described in Asset paths. Which UClass lands there depends on the resolved backend:

The backend comes from Settings = { Backend = "…"; } if present, otherwise from the project's Default Compiler Backend setting. See Backend and Project settings.

[!NOTE] A Graph-backend UMaterial is an ordinary asset and is saved on every successful build (since 2.0.0). A ThinCustom product stays Ephemeral — in memory, no package on disk — until a cook, an explicit Materialize, or a child instance gives it one, and once it has a package it stays on disk. See Ephemeral materials.

[!WARNING] Regeneration clears the target graph. Node positions not pinned by Layout, added nodes, node property tweaks, and comment boxes whose text begins with DreamShader: are destroyed. Only comment boxes that do not carry the DreamShader: prefix survive. Under the ThinCustom backend the instance's parameter overrides are cleared too, but they are captured first and restored afterwards (since 1.9.0) — a parameter the source no longer declares is the one case that loses its value. See Regeneration.

Notes

• At most one Shader per file (DSH2250). Through 1.9.x imports were inlined into one text before parsing, so the rule spanned the import closure; a header is read on its own now and cannot hold a Shader (DSH2249), so an import never adds one. The .dsh check reads tokens, not text: a comment that mentions Shader( is fine. See Source files.
• Shader() with no attributes is DSH2242, the missing Name.
• Shader may share a .dsm with VirtualFunction, Function, GraphFunction and Namespace blocks, which are helpers of the material, and with ShaderFunction, ShaderLayer and ShaderLayerBlend blocks: one compile of the file builds them all, each into its own asset, and the material may call such a function by name (2.0.0 – 2.1.0 refused it with DSH6201). A Shader in a .dsf is DSH2259.
• A .dsm that declares no Shader block is still compilable — it simply produces whatever function assets it does declare.
• Binding Base.MaterialAttributes turns on Use Material Attributes on the material. See Output bindings for Base.FrontMaterial and the other targets.

Diagnostics

Every stage reports all of its errors, each at its own line and column (since 2.0.0).

Parse time

Bind and generation time

The messages of Properties, Settings, Outputs and Graph are on their own pages. Every code: diagnostics.

Example

Shader(Name="Materials/M_Emissive", Root="Game")
{
    Properties = {
        Group("Look") {
            vec3  Tint      = vec3(1.0, 0.4, 0.1) [Description="Emissive tint"];
            float Intensity = 2.0                 [Slider(0, 10)];
        }
        TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_Noise");
    }

    Settings = {
        ShadingModel = "Unlit";
        BlendMode    = "Translucent";
        TwoSided     = true;
    }

    Outputs = {
        vec3  Color;
        float Alpha;

        Base.EmissiveColor = Color;
        Base.Opacity       = Alpha;
    }

    Graph = {
        vec2 UV  = UE.TexCoord(Index = 0);
        vec4 Tex = BaseTex(Coordinates = UV);
        Color = Tex.rgb * Tint * Intensity;
        Alpha = Tex.a;
    }

    Layout = {
        Comment(Name="Sampling", X=-1200, Y=-200, W=900, H=400);
        Node(Var="UV", X=-1100, Y=-120);
    }
}

Generated asset:

package     /Game/Materials/M_Emissive
object path /Game/Materials/M_Emissive.M_Emissive
on disk     <Project>/Content/Materials/M_Emissive.uasset      (once Materialized, or under the Graph backend)

[!NOTE] BaseTex is declared as TextureSampleParameter2D, not as the compact Texture2D, because only the sample-parameter family owns the input pins the BaseTex(Coordinates = UV) call form wires. A compact Texture2D generates a texture object parameter, which has no such pins; calling it falls through to the function dispatcher and fails. See Using parameters in Graph.

See also

• Source files — which block kinds each of .dsm / .dsh / .dsf may contain
• DreamShaderLang 2.0 — the .dss form of a material
• Properties — the Properties section grammar
• Inputs / Outputs / Results — typed-parameter sections (functions only)
• Output bindings — the full Base.* target catalogue and Expression(…).Pin[i]
• Layout — Node / Comment placement directives and #Region
• Graph — the statement/expression language inside Graph
• Shader settings — every key a Shader's Settings accepts
• Backend — Graph vs ThinCustom, and the deprecated Instance alias
• Asset paths — Name= + Root= → package path
• Ephemeral materials — memory-only generation and materializing to disk
• Regeneration — what survives a rebuild and what does not
• ShaderFunction — the reusable UMaterialFunction block
• Diagnostics — every code