Settings

DreamShader » Settings

The section that carries <key> = <value>; pairs from a source block to the asset it generates.

Synopsis

Settings [=] { <setting-statement> … }

<setting-statement> := <name> = <value> ;
<name>              := <identifier>
<value>             := <tokens up to the next ;> | "<text>"

The = between the section name and its { … } block is optional sugar (since 1.5.0). The ; after the last statement is optional.

(since 2.0.0) A name is one identifier. 1.x also read a nested path (Lightmass.DiffuseBoost) and a fixed-array index (PhysicalMaterialMap[2]) as a key of a Shader block; the legacy front end stops at the . or the [ and reports DSH3261.

A Shader's Settings is the 2.0 #pragma material(…) — see The 2.0 language.

Where a Settings block is accepted

A block may contain more than one Settings section. They merge into one list; a key written twice keeps the last value, regardless of which section it came from, and the repeat is a DSH3262 warning (since 2.0.0).

How a statement is parsed

(since 2.0.0) The legacy front end reads a Settings section from the same tokens as the rest of the file:

Because of step 4, TwoSided = true; and TwoSided = "true"; are identical, and Domain = Surface; behaves exactly like Domain = "Surface";.

Key normalization

Several normalizations act on Settings data. Confusing them is the source of most surprises on this page.

Nothing else is stripped. A key spelled Two_Sided is stored as two_sided and only matches later because the reflection lookup strips the underscore.

[!WARNING] The special Shader keys are matched by direct lookup (trim + lowercase) but skipped from the reflection pass by the reflection normalization (which also strips _). A spelling that differs from the canonical name only by underscores therefore matches neither and is applied nowhere, with no diagnostic: Blend_Mode, Render_Type, Shading_Model, Material_Domain, Back_end. Write BlendMode, RenderType, ShadingModel, MaterialDomain, Domain and Backend without separators. (A space or a hyphen cannot stand in a name at all since 2.0.0.) See Shader settings.

This is not a fixed key list

Settings in a Shader block is not a catalogue of supported keys. A handful of keys are hand-handled; every other key is resolved against the generated UMaterial by Unreal reflection.

Settings key
   ├── Backend, Substrate
   │      └── read by the compiler when the source is bound; never reach the material
   ├── blendmode rendertype shadingmodel materialdomain domain
   │      └── hand-handled: value parsed through the project's alias maps
   └── anything else
          └── alias table  →  UMaterial / UMaterialInterface / UObject property lookup
                                 (name, b-stripped name, or DisplayName)
                              →  value parsed per the property's C++ type

Two consequences a reference reader must internalise:

• Any UPROPERTY on UMaterial or one of its bases is reachable by its name. Nested struct members and fixed-array elements are not reachable from a 1.x key (since 2.0.0); a fixed-size array named without an index is DSH7121. No table in this manual can be complete for that surface, because it is the engine's property set, not the plugin's.
• Which enum values are accepted likewise comes from engine reflection, so a modified engine build contributes its own spellings automatically. See Material enums.

Material-function blocks are the opposite: exactly four keys are read and every other key is a DSH3263 warning. See Function settings.

Pages

Diagnostics

Parse time

Diagnostics raised while applying the settings are listed on Shader settings, Backend and Function settings.

Example

Shader(Name="Docs/M_SettingsGrammar")
{
    Properties { vec3 Tint = vec3(1.0, 0.5, 0.25); }

    // Two Settings sections merge into one list.
    Settings {
        Domain       = Surface;        // quotes are optional
        ShadingModel = "Unlit";
        BlendMode    = "Opaque";
    }

    Settings = {
        BlendMode           = "Translucent";   // last write wins over "Opaque" (DSH3262)
        TwoSided            = true;            // reflected onto UMaterial::TwoSided
        OpacityMaskClipValue = 0.5;            // reflected, float-typed
    }

    Outputs {
        vec3  Color;
        float Alpha;
        Base.EmissiveColor = Color;
        Base.Opacity       = Alpha;
    }

    Graph {
        Color = Tint;
        Alpha = 0.5;
    }
}

Effective settings, keys as the emitter stores them:

domain                  -> Surface
shadingmodel            -> Unlit
blendmode               -> Translucent
twosided                -> true
opacitymaskclipvalue    -> 0.5

See also

• Shader settings — the full Shader key surface
• Material enums — every ShadingModel, BlendMode and Domain spelling
• Backend — choosing the materialization strategy
• Function settings — the four material-function keys
• Project settings — the project-wide defaults and mapping maps
• Shader — the block a material Settings section lives in
• ShaderFunction — the material-function block
• VirtualFunction — Options / Settings on an existing asset
• Options — the VirtualFunction Options keys
• Lexical elements — comments, string literals and escapes
• Diagnostics index — every code