Substrate.*

DreamShader » Builtins » Substrate.*

A sibling call namespace to UE.* holding Unreal's Substrate BSDF, composition and utility material nodes. Since 2.0.0 it is the builtin catalog's Substrate namespace: every Substrate class the running engine has, by name.

Availability

Nothing is compiled in or out by version in the binder (since 2.0.0): the catalog lists the Substrate classes of the running engine, and an engine before UE 5.4 has none.

[!NOTE] Substrate must also be enabled for the project (Project Settings ▸ Engine ▸ Rendering ▸ Substrate) for a Substrate graph to compile in the engine. DreamShader reads that setting (since 2.0.0): the Substrate setting of a Shader — Legacy, Bridge or Native — says how a material is built in a project that has it on or off, and Native driving FrontMaterial with Substrate off is DSH4382. See One source, two kinds of project.

[!NOTE] The editor tooling reflects the engine. Below UE 5.4 the Bridge manifest Saved/DreamShader/Bridge/substrate-builtins.json is written with an empty entry array, supported: false and an unsupportedReason — so completion in the editor extensions offers nothing. See Bridge.

Synopsis

Substrate . <Name> ( [ <argument-name> = <expression> ]
                     [ , <argument-name> = <expression> ] …
                     [ , { Output | OutputName } = "<pin-name>" ]
                     [ , OutputIndex = <integer> ] )

Substrate and . are literal; [ … ], { a | b } and … are meta-notation.

In a 1.x source the prefix is matched case-insensitively — Substrate is a 1.x type spelling, and those are read ignoring case — and a <Name> that matches only ignoring case is accepted with the warning DSH5276: SUBSTRATE.UNLIT(…) resolves. Argument names are matched the same way — exactly, or ignoring case with DSH5276 — and are otherwise exact: no separator stripping.

Argument model

A Substrate.* call is bound like any reflected node call (UE.Expression), against the class the name selects.

Reflection-driven binding

For each remaining argument the binder tries, in order:

1. Input pin — a pin of the class by its name, or by an alias: its display name in identifier form (Diffuse_Albedo), with a property's display name also with its spaces removed.
2. Property — a reflected, editable property of the class by its name or an alias; a bool property also without its leading b, so UseParameterBlending reaches bUseParameterBlending.
3. Virtual argument — on a BSDF that has the pins it feeds, BaseColor / Metallic / Specular, Haziness, Transmittance / Thickness and IOR become the input of a conversion node in front of those pins (since 2.0.0). See Legacy parameters on a slab.
4. In a 1.x source, a name that is none of these and carries a value is kept with DSH5291 and connected by name when the node is built (DSH8212 if the node has no such pin).
5. No match → DSH5213.

A pin-name match wins over a property of the same name. A value is checked against the pin's type: a number on a Substrate pin, a Substrate value on a numeric pin and anything but a material on a MaterialAttributes pin are DSH5214.

[!NOTE] Engine pin names with spaces in them are reachable (since 2.0.0): a pin displayed as Diffuse Albedo is Diffuse_Albedo, and its property name — DiffuseAlbedo, which the tables below list — works as before.

[!NOTE] Accepted argument names follow the engine, not the plugin. The catalog is read off the running engine's UMaterialExpressionSubstrate* classes, so an input added or removed by an engine release appears or disappears with no plugin change. The tables below list the inputs these classes expose; the Completion column marks the curated subset DreamShader publishes to editor completion and the Bridge manifest, which is fixed by the plugin. Any editable non-input property of the same class — enums, floats, booleans — is also settable as a literal argument even though it is not listed here.

Selecting an output

Output= / OutputName= names an output exactly as the catalog lists it, including names that contain spaces; in a 1.x source a case-only match is accepted with DSH5276. A name no output has is DSH5201. OutputIndex= takes a 0-based index (DSH5282 past the last). Only the utility nodes below have more than one output.

Catalogue

Substrate output marks the classes whose output is a Substrate material value, bindable to Base.FrontMaterial; the four marked no are the utility nodes and return ordinary numeric values.

The two alias pairs are exact duplicates: same class, same inputs, same output typing. Neither spelling is deprecated. Since 2.0.0 two short names join them — Mix for HorizontalMix, Layer for VerticalLayer — and every class is also reachable by the catalog's short name (SubstrateSlabBSDF) and by its class name without MaterialExpressionSubstrate in front and BSDF behind, which is how a class this table does not list is called: UE 5.8's UMaterialExpressionSubstrateToonBSDF is Substrate.Toon.

Output typing

The catalog types each output from the engine: a BSDF or composition node makes a Substrate value; a utility node makes numbers, as wide as the engine types each output — or, where the engine does not type it, as wide as the place it is read into. A node with several outputs is read by naming one.

A Substrate value can be:

• assigned to a Substrate-typed Graph variable or Outputs declaration;
• passed to a Substrate-typed input of another Substrate.* node or of a UE.Expression node;
• combined with + (Substrate.Add), weighted with * <scalar> (Substrate.Weight) and mixed with lerp(A, B, t) (Substrate.HorizontalMix) (since 2.0.0) — see Operators and lerp;
• chosen between by a static switch, or by a run-time if, which becomes Substrate.Select (since 2.0.0) — see if over Substrate values;
• bound to Base.FrontMaterial.

Any other operator over a Substrate value — -, /, A * B, a compound assignment — and a lerp of a Substrate value with a number is DSH5293; another math builtin given a Substrate value is DSH4226. An HLSL Custom node — a Function — can neither take nor return one (DSH6253).

[!NOTE] A static switch over two closures is how a master material picks a shading variant from a static parameter: UMaterialExpressionStaticSwitchParameter resolves the bool while the engine builds the material topology tree and descends only the taken branch, so the translator still sees one topology. UE.StaticSwitchParameter does not compare its two branches, so a Substrate value on one side and a number on the other is not reported by DreamShader.

Node reference

Substrate.ShadingModels

Legacy-style shading-model surface expressed as a Substrate material.

Output: Substrate value. Editor completion offers no parameters for this wrapper.

Substrate.Slab

The general-purpose Substrate BSDF slab.

Output: Substrate value.

Substrate.SimpleClearCoat

A slab with a fixed second clear-coat lobe.

Output: Substrate value.

Substrate.VolumetricFogCloud

Participating-media BSDF for volumetric fog and cloud materials.

Output: Substrate value.

Substrate.Unlit

Emissive-only BSDF. The smallest complete Substrate surface.

Output: Substrate value.

Substrate.Hair

Hair BSDF.

Output: Substrate value.

Substrate.Eye

Eye BSDF.

Output: Substrate value.

Substrate.SingleLayerWater

Single-layer water BSDF.

Output: Substrate value.

Substrate.LightFunction

Substrate output node for light-function materials.

Output: Substrate value.

Substrate.PostProcess

Substrate output node for post-process materials.

Output: Substrate value.

Substrate.UI

Substrate output node for UI-domain materials.

Output: Substrate value.

Substrate.ConvertMaterialAttributes

Converts a MaterialAttributes value into a Substrate material.

Output: Substrate value.

MaterialAttributes is the reflected property name and Attributes is the engine's pin name for the same input; both bind input 0. Passing a numeric value to it is DSH5214. See MaterialAttributes.

Substrate.ConvertToDecal

Converts a Substrate material into a decal material.

Output: Substrate value.

Substrate.HorizontalMix

Screen-space horizontal blend of two Substrate materials. Also spelled Substrate.HorizontalMixing — the two names are interchangeable.

Output: Substrate value.

Substrate.VerticalLayer

Layers one Substrate material over another. Also spelled Substrate.VerticalLayering — the two names are interchangeable.

Output: Substrate value.

Substrate.Add

Adds two Substrate materials.

Output: Substrate value.

Substrate.Weight

Scales a Substrate material's contribution.

Output: Substrate value.

Substrate.Select

Static selection between two Substrate materials.

Output: Substrate value.

Substrate.TransmittanceToMFP

Utility. Converts a transmittance colour and thickness into a mean-free-path parameterisation.

Outputs — numeric, selectable with Output= or OutputIndex=:

Substrate.MetalnessToDiffuseAlbedoF0

Utility. Converts a legacy base-colour/metallic/specular triple into the slab parameterisation.

Outputs — numeric:

Substrate.HazinessToSecondaryRoughness

Utility. Converts a haziness control into a second-roughness lobe.

Outputs — numeric:

Substrate.ThinFilm

Utility. Computes thin-film interference specular colours.

Outputs — numeric:

Binding a Substrate value to Base.FrontMaterial

A Substrate material reaches the generated UMaterial through the Base.FrontMaterial output binding.

Outputs = {
    Substrate Surface;              // declared-type token; case-insensitive, no other spelling
    Base.FrontMaterial = Surface;
}
Graph = {
    Surface = Substrate.Unlit(EmissiveColor = Color);
}

[!NOTE] Strata is the pre-rename spelling. It is accepted as a Settings = { ShadingModel = … } value (an alias for the same shading model) but never as a type token and never as a call namespace. See Enum values.

Notes

• Every Substrate class is a name. A class with no row in the catalogue is called by its derived name — Substrate.Toon on UE 5.8 — or by its class through UE.Expression(Class = "SubstrateToonBSDF", …), which resolves SubstrateToonBSDF, MaterialExpressionSubstrateToonBSDF, UMaterialExpressionSubstrateToonBSDF and the full /Script/Engine.… path (since 2.0.0). See UE.Expression.
• UE.* names do not apply inside this namespace. Substrate.TexCoord(…) is not a thing; a name the namespace does not have is DSH5210.
• Substrate nodes take part in node reuse: two identical Substrate.Slab(…) calls over identical argument values are one node. See Node reuse.
• A Substrate. call inside a GraphFunction body is not lifted into a node input, because no Custom node input carries a Substrate value; it stays in the HLSL text, with the warning DSH6316.
• The decompiler exports an existing Substrate graph back to source, deriving channel swizzles from each connection's write mask (since 1.5.0), and writes each node under the name sources use — see Decompiling.
• The Substrate.* surface is exported for editor tooling to Saved/DreamShader/Bridge/substrate-builtins.json (schema DreamShader.SubstrateBuiltins, version 1), one entry per name with its qualifiedName, className, outputType, isSubstrateOutput and curated parameters. See Bridge.

Diagnostics

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

Call site

Substrate values elsewhere in the pipeline

Example

Shader(Name="Docs/M_Substrate")
{
    Properties = {
        vec3  BaseColor = vec3(0.6, 0.1, 0.1);
        float Metallic  = 0.0;
        float Specular  = 0.5;
        float Rough     = 0.3;
        vec3  Glow      = vec3(0.1, 0.6, 1.0);
    }

    Outputs = {
        Substrate Surface;
        Base.FrontMaterial = Surface;
    }

    Graph = {
        // Utility node: two numeric outputs, selected by name.
        vec3 Albedo = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "DiffuseAlbedo");
        vec3 F0 = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "F0");

        Substrate Body = Substrate.Slab(
            DiffuseAlbedo = Albedo,
            F0            = F0,
            Roughness     = Rough);

        Substrate Emissive = Substrate.Unlit(EmissiveColor = Glow);

        Surface = Substrate.Add(A = Body, B = Emissive);
    }
}

Generated nodes:

SubstrateMetalnessToDiffuseAlbedoF0   -> output "DiffuseAlbedo"  -> Albedo
                                      -> output "F0"             -> F0
                                         (one node, read for both)
SubstrateSlabBSDF                     -> Body                    (Substrate value)
SubstrateUnlitBSDF                    -> Emissive                (Substrate value)
SubstrateAdd                          -> Surface                 (Substrate value)

Since 2.0.0 the same graph is Surface = Substrate.Slab(BaseColor = BaseColor, Metallic = Metallic, Specular = Specular, Roughness = Rough) + Substrate.Unlit(EmissiveColor = Glow); — the virtual arguments put the conversion node in front of the slab, and + is Substrate.Add.

See also

• Builtins — the call surfaces available inside Graph
• UE.* catalogue — the sibling namespace
• UE.Expression — the binding rules every node call shares
• Substrate sugar — operators, lerp, branches, virtual arguments, builders, Substrate =
• OutputType values — dropped on this namespace
• Math builtins — the unprefixed numeric call surface
• Transform builtins — UE.TransformVector / UE.TransformPosition
• Output bindings — Base.FrontMaterial and the full target list
• MaterialAttributes — the value type ConvertMaterialAttributes consumes
• Types — the Substrate declared-type token
• Enum values — ShadingModel = "Substrate" / "Strata"
• Calls — named-argument syntax
• Node reuse — identical calls and nodes
• Bridge — substrate-builtins.json and the editor completion manifest
• Decompiler — exporting an existing Substrate graph back to source
• Diagnostics index — every code