Parameter node tokens

DreamShader » Parameters » Parameter node tokens

The 22 type tokens that name an Unreal parameter expression class directly, so a Properties declaration generates that exact node instead of the compact scalar / vector / texture-object node.

Synopsis

<parameter-node-token> <name> [ = <default> ] [ [ <metadata> ] ] ;

Tokens are matched case-insensitively. The set is closed: exactly the 22 tokens below. const is legal only with ScalarParameter, VectorParameter and TextureObjectParameter (since 2.0.0); on any other token it is DSH3253.

The 22 tokens

(since 2.0.0) Each token takes one of three 2.0 forms:

• a declaration — ScalarParameter, StaticBoolParameter, VectorParameter and TextureObjectParameter are the uniform a compact token would make (float, a /// @static bool, float4, Texture2D), with one parameter node however often it is read;
• expanded at each use — the other eleven that build are no declaration: every read or call of the property is a reflected UE.Expression(Class = "<Token>", ParameterName = …, …) call carrying the default and the metadata, and identical uses share one node;
• no 2.0 spelling — seven tokens are DSH3253. Move such a material to a .dss and build the node with UE.Expression.

The class of an expanded token is looked up in the engine's node catalog; a class this engine does not have is DSH5212. The Graph use is summarised here; the pin table is in Using parameters in Graph.

Type-specific metadata slots

Every token also accepts the generic metadata keys (Group, Description, SortPriority, Slider(min, max), ParameterName) plus any reflected UPROPERTY of its class. The class-specific slots that matter in practice:

Boolean UPROPERTYs are matched with the leading b optional, so [bBlend=true] and [Blend=true] both bind bBlend. How a key the class does not have is reported depends on the form: a warning on a declaration, an error on an expanded token — see Metadata.

Which default parser a token uses

[!WARNING] A RuntimeVirtualTextureSampleParameter or SparseVolumeTextureSampleParameter default is ignored. = Path(…) on either token reaches no property of the node, and nothing says so. Bind the asset through metadata instead — [VirtualTexture = Path(…)], [SparseVolumeTexture = Path(…)].

What the default is written to

Texture-dimension inference

A texture-sample token fixes a dimension by the suffix after TextureSampleParameter:

(since 2.0.0) The suffix is compared whole, so TextureSampleParameterCubeArray is no longer taken for a cube. The dimension is used for one thing only: judging the class a Class'…' default names.

TextureObjectParameter declares no dimension: it takes the dimension of the asset its default loads — a cube, a 2D array or a volume, else Texture2D — which is what lets it accept any of them (since 1.6.0).

Dimension validation asymmetry

[!WARNING] A TextureSampleParameterCube assigned a plain 2D texture by its plain object path generates without a DreamShader diagnostic; only a Texture2D'…' shell gives the mismatch away (DSH1044). The mismatch otherwise surfaces later as an Unreal shader-compile error on the material. Assign the right dimension.

Notes

• A default value is optional for every token that has a 2.0 form. The test DreamShader.Lang.ParameterExpressions.ParseAll covers each of the 15, covers ScalarParameter, VectorParameter and TextureObjectParameter with and without an inline default, and checks that each of the seven others is DSH3253.
• A sampler parameter with no texture still compiles. When an expanded node derives from UMaterialExpressionTextureBase and its Texture is null, SetDefaultTexture() is called for a UMaterialExpressionTextureSampleParameter subclass. Without that, a default-less sampler parameter would fail with Missing input Texture. The runtime-virtual-texture and sparse-volume nodes are not such subclasses and still need their asset bound.
• An explicit SamplerType always wins. AutoSetSampleType() runs only on a node whose source gives no SamplerType. See SamplerType.
• StaticSwitchParameter cannot be read as a value. A bare reference is not a declared name (DSH4200); it must be called. See Using parameters in Graph.
• A Group(…) scope does not stamp an expanded token (since 2.0.0): such a member gets no group and no automatic SortPriority from the scope, and does not use up a counter slot. Write Group / SortPriority in its own metadata block. See Metadata.
• The decompiler emits SamplerType and the texture-sample metadata keys explicitly on every export, even at their defaults, so a decompile → recompile round trip is stable.

Diagnostics

The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_ParameterNodes")
{
    Properties = {
        Group("Surface") {
            TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_White") [
                SamplerType  = "LinearColor";
                SamplerSource = "FromTextureAsset";
                MipValueMode = "None";
                AutomaticViewMipBias = true;
            ];
            ScalarParameter Roughness = 0.55 [Slider(0, 1)];
            VectorParameter Tint      = float4(1.0, 0.8, 0.6, 1.0);
        }

        Group("Masks") {
            ChannelMaskParameter         Pick = float4(1, 0, 0, 0) [MaskChannel = "Red"];
            StaticComponentMaskParameter Keep = float4(1, 1, 0, 0);
        }

        StaticSwitchParameter UseDetail = true [Group="Switches"];
    }

    Settings = { Domain = "Surface"; ShadingModel = "DefaultLit"; BlendMode = "Opaque"; }

    Outputs = {
        vec3  Color;
        float Rough;

        Base.BaseColor = Color;
        Base.Roughness = Rough;
    }

    Graph = {
        vec2  UV     = UE.TexCoord(Index = 0);
        vec4  Sample = BaseTex(Coordinates = UV);
        vec4  Masked = Keep(Input = Sample);
        float Chan   = Pick(Input = Sample);

        Color = UseDetail(True = Masked.rgb, False = Tint.rgb);
        Rough = Roughness * Chan;
    }
}

Generated nodes:

TextureSampleParameter2D      BaseTex    SamplerType=LinearColor
ScalarParameter               Roughness  Group="Surface" SortPriority=0  SliderMin=0 SliderMax=1
VectorParameter               Tint       Group="Surface" SortPriority=10
ChannelMaskParameter          Pick       MaskChannel=Red
StaticComponentMaskParameter  Keep
StaticSwitchParameter         UseDetail  Group="Switches"
TextureCoordinate             UV         CoordinateIndex=0

BaseTex, Pick and Keep are expanded tokens, so their Group(…) scopes do not stamp them and Roughness takes counter slot 0. Keep's float4 default is dropped with DSH5288: write [DefaultR = true; DefaultG = true] for that mask.

See also

• Parameters — the hub and the decision table
• Compact type tokens — the 39 built-in tokens and the checks they get
• Metadata block — how [MaskChannel=…] and every other key is written
• SamplerType — every sampler-type value, and SamplerSource
• Path(…) — the asset-reference grammar these defaults use
• Using parameters in Graph — reads, the pin call form, and StaticSwitchParameter
• Properties (section) — the enclosing section grammar
• UE.Expression — the generic reflected form for classes with no token
• Decompiler — which of these tokens a UMaterial export produces
• Testing — the parameter matrix fixture that pins this table