Metadata block

DreamShader » Parameters » Metadata block

The trailing [ … ] block of a declaration: a list of Key = Value entries that set the generated node's organization fields and, for any key the language does not recognize, write directly to a reflected UPROPERTY of that node's class.

Synopsis

<declaration> [ <entry> ; <entry> ; … ] ;
<declaration> [ <entry> , <entry> , … ] ;

<entry> := <key> = <value>
         | Slider( <min> , <max> )

Every [, ], ;, ,, = and ( ) above is literal DreamShaderLang punctuation, not meta-notation. ; and , may be mixed within one block, and a trailing separator before ] is accepted. Slider(…) is the only entry form without an =.

Placement rules:

What a key does depends on the form the property takes (since 2.0.0): on a declaration (every compact token, ScalarParameter, StaticBoolParameter, VectorParameter, TextureObjectParameter) the entries become the 2.0 /// directives of a uniform; on a parameter node expanded at its uses (StaticSwitchParameter, the two masks, the texture-sample tokens) they become arguments of the reflected call. See Parameter node tokens.

Recognized keys

All key comparisons are case-insensitive. (since 2.0.0) A recognized key does only its own job; in 1.x every entry was also pushed through the reflected-property writer.

SortPriority is 32 when nothing sets it, matching Unreal's own node default. A declaration outside any Group(…) scope gets that 32 written out.

Slider(min, max)

ScalarParameter Roughness = 0.5 [Slider(0, 1)];

Matched case-insensitively; the parentheses must hold exactly two numbers. It is exactly equivalent to [SliderMin = 0; SliderMax = 1] — and combining the two forms in one block is a duplicate:

A slider belongs to a scalar parameter. On any other declaration — a vector, a texture, a static bool — the range is dropped with a DSH7233 warning (since 2.0.0). A lone SliderMin or SliderMax is written by reflection like any other key. On an expanded token, whose classes have no slider, the bounds are refused when the material is built (DSH8212).

ParameterName

ScalarParameter Rough [ParameterName = "Surface Roughness"];

The declared identifier stays the name the Graph uses; ParameterName changes only the name the material exposes to instances and Blueprints. On a declaration an empty value is DSH7227 (since 2.0.0).

[!NOTE] (since 2.0.0) ParameterName is written once, by reflection. A class with no ParameterName UPROPERTY would get a DSH8210 warning; none of the parameter node tokens that build is such a class (DynamicParameter, the one 1.x refused here, is DSH3253).

Alias rewriting and auto-injection

The typed key decides what is written:

On a declaration, the enclosing Group("Name") { … } scope injects Group unless Group or Category was typed, and the automatic SortPriority unless SortPriority or Sort was typed. An expanded token gets neither.

Reflected property passthrough

On a declaration, a key that is not recognized is resolved to an FProperty on the generated node's class when the material is built:

1. the key is compared against each UPROPERTY name, ignoring case;
2. if that fails, a second pass strips a leading b from every FBoolProperty name and compares again.

So [FractionalPart = true] binds bFractionalPart, and [UseCustomPrimitiveData = true] binds bUseCustomPrimitiveData. Writing the b explicitly also works. A key no property matches is a DSH8210 warning and is not written (since 2.0.0; 1.x refused it).

On an expanded token, a key is matched first against the class's input pins, then against its properties, as the engine catalog lists them (with the b-less spelling of a boolean as an alias); a match that differs only in case is DSH5276. A key that is neither is DSH5213 — or, when its value is a number, it is taken for a pin named after the node's properties (DSH5291, info) and refused when the material is built if the node has no such pin (DSH8212).

Value grammar by property type

A number is read the way Unreal's LexTryParseString reads it, which stops at the first character it cannot use: "0.5abc" is 0.5. Each of these codes reaches you inside DSH8213, which names the node and the property and quotes the code. On an expanded token the binder checks the value's kind first: an enum value against the catalog (below), a name or an asset path as a quoted string, anything else as a compile-time constant (DSH5224).

Enum literals

An enum value is normalized by trimming, lower-casing and then removing every space, _, -, :, . and /. Each enumerator that is not tagged UMETA(Hidden) is tried against four spellings:

Because of the normalization, "LinearColor", "linear color", "linear-color", "SAMPLERTYPE_LinearColor" and "linear.color" are all the same value. See SamplerType for the fully expanded table of one such enum.

That is the matcher a declaration's keys go through. On an expanded token the binder checks the value against the enumerators the engine catalog lists (since 2.0.0): an exact name passes; one of the spellings above that normalizes to an enumerator name is accepted with a DSH5278 warning; anything else — including a DisplayName that is not also an enumerator name, such as Shared: Wrap — is DSH5215.

Object properties

An object-valued UPROPERTY takes an asset reference resolved by the shared resolver documented in Path(…).

[!WARNING] A texture that fails to load is silently accepted. When the property is a UTexture subclass and is named exactly Texture or TextureObject, a failed load writes nullptr and the write is reported as successful. [Texture = Path(Game, "Typo")] therefore generates without any diagnostic and leaves an unbound sampler. (since 2.0.0) The same goes for the default of a texture-sample token and of a const texture, which are written to that property too; a texture-sample node then takes the engine's default texture. Check the asset path when a sampler comes out wrong.

Organization fields that are not reflected

Group, SortPriority and Desc exist on UMaterialExpressionParameter subclasses. A class that lacks one of them gets a DSH8210 warning and the value is not written. Every class the 15 building tokens make has all three.

(since 2.0.0) Any other key a declaration's class lacks is the same DSH8210 warning, where 1.x stopped the compile. On an expanded token it is DSH5213.

[!NOTE] DynamicParameter, the 1.x case that lacked all three, is DSH3253 and builds nothing.

Group(…) scopes and the SortPriority counter

A Group("Name") { … } scope in a Properties section stamps its members. The interaction with an explicit metadata entry is:

The counter starts at 0 and steps by 10. It is shared across every scope in the block, not reset per group:

Properties {
    Group("Surface") {
        ScalarParameter A = 0.5;                   // SortPriority = 0
        VectorParameter B = float4(1, 1, 1, 1);    // SortPriority = 10
    }
    Group("Detail") {
        ScalarParameter C = 1.0 [SortPriority=99]; // 99 — does not consume a slot
        ScalarParameter D = 2.0;                   // SortPriority = 20
    }
    ScalarParameter Loose = 3.0;                   // no group, SortPriority = 32
}

Notes

• The same [ … ] block is accepted on Inputs / Outputs / Results typed parameters, but there only Description / Desc / Tooltip and SortPriority / Sort have any effect. Group is parsed and retained but never applied — Unreal's function input/output nodes have no group field — and every other key is ignored rather than reflected. An input's SortPriority defaults to its declaration index. See Inputs / Outputs / Results.
• No metadata block is accepted on a Shader's Outputs statements, nor on Settings, Options or Layout entries.
• A const declaration keeps only what a constant node has: see Compact type tokens.
• An explicit [SamplerType=…] always overrides the type inferred from the asset.
• _MAX sentinels of engine enums usually carry no Hidden metadata, so on a declaration a value such as "SAMPLERTYPE_MAX" resolves rather than erroring. Do not use them. The catalog an expanded token is checked against does not list them (DSH5215).

Diagnostics

Parse time

Binding

Build time

The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_Metadata")
{
    Properties = {
        Group("11 - Specular") {
            TextureSampleParameter2D MetallicMap = Path(Game, "Textures/T_White_Linear") [
                SamplerType          = "LinearColor";
                SamplerSource        = "FromTextureAsset";
                MipValueMode         = "None";
                AutomaticViewMipBias = true;
                ConstCoordinate      = 0;
                ConstMipValue        = -1;
                Description          = "Packed metallic / roughness";
            ];

            ScalarParameter Metallic = 0.0 [Slider(0, 1); SortPriority = 51];
        }

        VectorParameter Tint = float4(1, 1, 1, 1) [
            Category               = "Look",
            Tooltip                = "Multiplied over base colour",
            UseCustomPrimitiveData = false,
            ParameterName          = "Base Tint"
        ];
    }

    Settings = { Domain = "Surface"; ShadingModel = "DefaultLit"; BlendMode = "Opaque"; }
    Outputs  = { vec3 Color; float M; Base.BaseColor = Color; Base.Metallic = M; }

    Graph = {
        vec4 S = MetallicMap(Coordinates = UE.TexCoord(Index = 0));
        Color = S.rgb * Tint.rgb;
        M     = S.b * Metallic;
    }
}

Applied properties:

MetallicMap  Desc="Packed metallic / roughness"
             SamplerType=SAMPLERTYPE_LinearColor     SamplerSource=SSM_FromTextureAsset
             MipValueMode=TMVM_None  AutomaticViewMipBias=true
             ConstCoordinate=0       ConstMipValue=-1
Metallic     Group="11 - Specular"  SortPriority=51  SliderMin=0  SliderMax=1
Tint         Group="Look"           Desc="Multiplied over base colour"
             bUseCustomPrimitiveData=false           ParameterName="Base Tint"

Metallic takes SortPriority = 51 from its own entry. MetallicMap is an expanded token, so the Group("11 - Specular") scope does not stamp it (since 2.0.0): write Group = "11 - Specular" in its own block to put it there.

See also

• Parameters — the hub and the decision table
• Compact type tokens — the tokens a metadata block can follow
• Parameter node tokens — the class-specific keys each token exposes
• SamplerType — the fully expanded value table for one reflected enum
• Path(…) — the asset-reference grammar object properties accept
• Properties (section) — Group("Name") { … } scopes and ordering
• Inputs / Outputs / Results — where the same block has a reduced effect
• Decompiler — which metadata keys a round trip always emits
• Diagnostics index — every code