Material Settings

Settings writes properties onto the asset the enclosing block generates. In a Shader block that asset is a UMaterial, and this is the page that describes what you may write.

The most important thing to know first:

Settings key
   ├── one of  blendmode rendertype shadingmodel materialdomain domain backend
   │             └── hand-handled: value parsed through the 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

The shape of the block

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

<setting-statement> := <key> = <value> ;
<key>               := <segment> [ . <segment> ] …
<segment>           := <identifier> [ [<integer>] ]
<value>             := <bare-text> | "<text>"

The = between the section name and its { … } block is optional sugar since 1.5.0. The ; after the last statement is optional. The [<integer>] in <segment> is literal punctuation; the surrounding [ … ] is the optional-marker meta-bracket.

How a statement is parsed:

Because of step 5, TwoSided = true; and TwoSided = "true"; are identical, and Domain = Surface; behaves exactly like Domain = "Surface";. A block may contain more than one Settings section; they merge into one map and a key declared twice keeps the last value.

The six special keys

Matched after trimming, lower-casing and deleting spaces, _ and -, these six never reach the reflection resolver:

blendmode   rendertype   shadingmodel   materialdomain   domain   backend

When both a canonical key and its synonym are present, the canonical key wins: BlendMode beats RenderType, MaterialDomain beats Domain. There is no diagnostic for the conflict.

Application order

1. The whole block is validated first — every special value is resolved and every generic value is written to a throw-away transient UMaterial. A single bad value aborts before the real material is touched.
2. BlendMode, then ShadingModel, then MaterialDomain.
3. The generic keys, in the parsed map's iteration order.

Backend is consumed before any material exists — an unrecognized Backend value fails the compile before the rest of Settings is validated, so no other settings diagnostic is reported for that file.

Interaction with Base.FrontMaterial

When any output binds Base.FrontMaterial, an explicit ShadingModel that is not Substrate or Strata is a hard error; otherwise the shading model is force-set to Substrate after the block is applied. Binding Base.FrontMaterial and Base.MaterialAttributes on the same Shader is also a hard error. Substrate itself requires since UE 5.4.

The reflection resolver

Every key that is not special is resolved against the generated material by Unreal reflection.

Property-name matching

A segment matches a property when any of these three, after deleting spaces, _ and - and lower-casing, equals the segment:

The b-stripping rule is one-way and permissive: the full name still matches, so both bFullyRough = true; and FullyRough = true; resolve to the same property. A property whose name begins with a lowercase b followed by a non-uppercase character (bias, for example) is not b-stripped.

Nested and indexed paths

[N] on a property whose ArrayDim is 1 is an error; omitting [N] on a property whose ArrayDim is greater than 1 is also an error. TArray, TMap and TSet properties are not indexable this way — they fall through to the ImportText catch-all in Value grammar.

Alias table

Ten fixed key aliases are applied per path segment before the field scan. Alias keys are compared in their separator-stripped, lower-cased form, so Lighting_Mode, Lighting Mode and LIGHTINGMODE all hit the first row.

Because the alias applies per segment, Lightmass.DiffuseBoost resolves as LightmassSettings → DiffuseBoost.

Value grammar

The resolved property's C++ type decides how the value text is parsed. The value has already been unquoted, so true and "true" are the same input.

Whichever message applies is wrapped as Invalid value '{Value}' for setting '{Key}'. {TypeMessage}.

Enum literals

An enum-typed value is matched after trimming, lower-casing and deleting every space, _, -, :, . and /. Values carrying Hidden metadata are skipped. A candidate matches the short enum name (TLM_Surface), the fully-qualified name (ETranslucencyLightingMode::TLM_Surface), the display name (Surface), or the short name with everything up to the first _ removed (Surface).

This matching is separate from the ShadingModel / BlendMode / Domain alias maps on Enum Values — those three keys never reach this code.

Path( … ) values

The complete root catalogue and its errors are on Asset References.

Validation

Before anything is written to the real material, each generic key/value pair is applied to a transient probe UMaterial. The probe write and the real write use the same code, so a value that validates always applies. The only failure specific to this stage is Failed to create a transient material for Settings validation.

What an omitted setting resets to

A generated material is reset immediately before Settings is applied. An omitted key is therefore not "left as it was on the previous generation" — it takes the value below.

Every other UMaterial property keeps whatever a freshly constructed material has. Keep anything that must survive a rebuild in Settings, not as a hand edit on the generated asset.

What survives a decompile round trip

The decompiler emits Domain, ShadingModel and BlendMode unconditionally, plus each of the following when it differs from the UMaterial class default. This is the set guaranteed to survive UMaterial → .dsm → UMaterial; it is a subset of what Settings accepts, not a limit on it.

Booleans (39, in emit order)

TwoSided                    Wireframe                     DitheredLODTransition
DitherOpacityMask           bAllowNegativeEmissiveColor   bCastDynamicShadowAsMasked
bEnableResponsiveAA         bScreenSpaceReflections       bContactShadows
bDisableDepthTest           bOutputTranslucentVelocity    bTangentSpaceNormal
bFullyRough                 bIsSky                        bIsThinSurface
bHasPixelAnimation          bUsedWithSkeletalMesh         bUsedWithMorphTargets
bUsedWithClothing           bUsedWithNanite               bUsedWithEditorCompositing
bUsedWithParticleSprites    bUsedWithBeamTrails           bUsedWithMeshParticles
bUsedWithNiagaraSprites     bUsedWithNiagaraRibbons       bUsedWithNiagaraMeshParticles
bUsedWithGeometryCache      bUsedWithStaticLighting       bUsedWithSplineMeshes
bUsedWithInstancedStaticMeshes                            bUsedWithGeometryCollections
bUsedWithHairStrands        bUsedWithWater                bUsedWithVirtualHeightfieldMesh
bCastRayTracedShadows       bWriteOnlyAlpha               BlendableOutputAlpha
bAlwaysEvaluateWorldPositionOffset

bHasPixelAnimation is emitted only on since UE 5.4.

Enums (1) — MaterialDecalResponse.

Reachable but never emitted, and therefore lost on a round trip: OpacityMaskClipValue, NumCustomizedUVs, TranslucencyLightingMode, RefractionMethod, RefractionDepthBias, TranslucencyPass, ShadingRate, FloatPrecisionMode, BlendableLocation, BlendablePriority, bIsBlendable, UserSceneTexture, StencilCompare, StencilRefValue, bEnableStencilTest, MaxWorldPositionOffsetDisplacement, PhysMaterial, PhysMaterialMask, PhysicalMaterialMap[N], Lightmass.*, DisplacementScaling.*, NaniteOverrideMaterial.*, and every other engine property the resolver can reach.

Material function settings

A Settings block on a ShaderFunction, ShaderLayer or ShaderLayerBlend does not share any of the behaviour above. Exactly four keys are read there:

Settings = {
    Description        = "Multiplies a colour by a tint.";
    UserExposedCaption = "Tint";
    ExposeToLibrary    = true;
    LibraryCategories  = "DreamShader, Color";
}

Keys here are matched by trim and lower-case only — spaces, underscores and hyphens are not folded, so Expose_To_Library is not ExposeToLibrary.

Notes

• The reflection surface is the engine's, not the plugin's. A custom or modified engine build exposes its own properties and its own enum values through the same resolver, so this page describes the stock UE 5.3 – 5.8 surface only.
• Under the ThinCustom backend every setting lands on the hidden base UMaterial, not on the emitted instance. Reading the blend mode off the instance shows the inherited value.
• Because keys are lower-cased when stored, the {Key} quoted in a diagnostic is the lower-cased spelling, not what the source wrote. Every message is also prefixed with the source file path.

Diagnostics

Unsupported Backend '{Value}'. Supported values: Graph, Instance, ThinCustom. is raised earlier, by the backend resolver — see Backend.

Example

Shader(Name="Docs/M_ShaderSettings", Root="Game")
{
    Properties {
        VectorParameter BaseColor = float4(0.8, 0.8, 0.8, 1.0) [Group="Surface"];
        ScalarParameter Roughness = 0.55                       [Group="Surface"; Slider(0, 1)];
    }

    Settings {
        // Special keys.
        Domain       = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode    = "Masked";

        // Reflected booleans; the b-prefix is optional.
        TwoSided   = true;
        FullyRough = true;
        bIsSky     = false;

        // Reflected scalar and enum.
        OpacityMaskClipValue  = 0.25;
        MaterialDecalResponse = "ColorNormalRoughness";

        // Alias -> TranslucencyLightingMode, matched by display name.
        LightingMode = "Surface";

        // Nested struct path.
        Lightmass.DiffuseBoost = 1.5;

        // Object reference.
        PhysicalMaterial = Path(Engine, "EngineMaterials/DefaultPhysicalMaterial");
    }

    Outputs {
        vec3  Color;
        float Rough;
        float Mask;
        Base.BaseColor   = Color;
        Base.Roughness   = Rough;
        Base.OpacityMask = Mask;
    }

    Graph {
        Color = BaseColor.rgb;
        Rough = Roughness;
        Mask  = BaseColor.a;
    }
}

Resulting material state:

BlendMode                = BLEND_Masked
MaterialDomain           = MD_Surface
ShadingModel             = MSM_DefaultLit
TwoSided                 = true
bFullyRough              = true
bIsSky                   = false
OpacityMaskClipValue     = 0.25
MaterialDecalResponse    = MDR_ColorNormalRoughness
TranslucencyLightingMode = TLM_Surface
LightmassSettings.DiffuseBoost = 1.5
PhysMaterial             = /Engine/EngineMaterials/DefaultPhysicalMaterial

Next

• Enum Values — every accepted ShadingModel, BlendMode and Domain spelling
• Backend — the sixth special key, and what each backend produces
• Project Settings — the mapping maps that extend the enum spellings
• Regeneration — what a rebuild resets