元数据块

DreamShader » 参数 » 元数据块

声明末尾的 [ … ] 块：一组 Key = Value 条目，用于设置生成节点的组织字段；对于语言不认识的任何键，则直接写入该节点类的反射 UPROPERTY。

概要

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

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

上面的每个 [、]、;、,、= 和 ( ) 都是字面 DreamShaderLang 标点，不是元符号。; 和 , 可以在一个块中混用，且接受 ] 之前的末尾分隔符。Slider(…) 是唯一不带 = 的条目形式。

放置规则：

键的作用取决于属性所采取的形式 （自 2.0.0 起）：在声明上（每个紧凑 token、ScalarParameter、StaticBoolParameter、VectorParameter、TextureObjectParameter），条目成为 uniform 的 2.0 /// 指令；在于使用处展开的参数节点上（StaticSwitchParameter、两个 mask、纹理采样 token），它们成为反射调用的参数。见参数节点 token。

可识别的键

所有键的比较都不区分大小写。（自 2.0.0 起） 可识别的键只执行其自身的职责；在 1.x 中每个条目还会被推送到反射属性写入器。

没有任何设置时 SortPriority 为 32，与 Unreal 自身的节点默认值一致。任何 Group(…) 作用域之外的声明都会写出该 32。

Slider(min, max)

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

不区分大小写匹配；括号内必须恰好为两个数字。它完全等价于 [SliderMin = 0; SliderMax = 1] —— 而在一个块中组合两种形式则算重复：

滑条属于标量参数。在任何其他声明上 —— 向量、纹理、静态布尔 —— 范围会被丢弃，并给出 DSH7233 警告 （自 2.0.0 起）。单独的 SliderMin 或 SliderMax 会像其他键一样通过反射写入。在展开的 token 上，其类没有滑条，因此在构建材质时边界会被拒绝（DSH8212）。

ParameterName

ScalarParameter Rough [ParameterName = "Surface Roughness"];

声明的标识符仍然是 Graph 使用的名称；ParameterName 只更改材质向实例和蓝图公开的名称。在声明上，空值为 DSH7227 （自 2.0.0 起）。

[!NOTE] （自 2.0.0 起） ParameterName 通过反射写入一次。没有 ParameterName UPROPERTY 的类会得到 DSH8210 警告；能构建的参数节点 token 所属的类没有一个是这样的类（DynamicParameter，即 1.x 在此处拒绝的那个，为 DSH3253）。

别名重写与自动注入

键入的键决定写入什么：

在声明上，外层 Group("Name") { … } 作用域 会注入 Group（除非键入了 Group 或 Category），并注入自动 SortPriority（除非键入了 SortPriority 或 Sort）。展开的 token 两者都不会得到。

反射属性透传

在声明上，无法识别的键会在构建材质时解析为生成节点类上的 FProperty：

1. 该键与每个 UPROPERTY 名称比较，忽略大小写；
2. 若失败，第二遍会从每个 FBoolProperty 名称中去掉开头的一个 b 并再次比较。

因此 [FractionalPart = true] 绑定 bFractionalPart，而 [UseCustomPrimitiveData = true] 绑定 bUseCustomPrimitiveData。显式写出 b 同样有效。没有属性匹配的键是 DSH8210 警告，不写入 （自 2.0.0 起；1.x 报错拒绝）。

在展开 token 上，键先和类的输入引脚比对，再和它的属性比对，按引擎目录列出它们的顺序（布尔属性不带 b 的拼写作为别名）；只差大小写的 匹配给出 DSH5276。两者都不是的键报 DSH5213 —— 或者，值是数字时，被当作 以节点属性命名的引脚（DSH5291，提示）， 节点没有这个引脚时在构建材质时被拒绝（DSH8212）。

按属性类型的取值语法

数字按 Unreal 的 LexTryParseString 读，遇到第一个用不了的字符就停："0.5abc" 是 0.5。这些码都包在 DSH8213 里到达你，它会指出节点和属性并引用这个码。 在展开 token 上，绑定器先检查值的种类：枚举值按目录检查（见下），名字 或资产路径要是带引号的字符串，其余要是编译期常量（DSH5224）。

枚举字面量

枚举值先 trim、小写，再删除所有空格、_、-、:、 . 和 /。每个未标记 UMETA(Hidden) 的枚举项按四种拼写逐一尝试：

由于这套规范化，"LinearColor"、"linear color"、"linear-color"、 "SAMPLERTYPE_LinearColor" 和 "linear.color" 都是同一个值。这样一个枚举的完整展开表见 SamplerType。

这就是声明上的键走的匹配器。在展开 token 上，绑定器把值和引擎目录列出的枚举项比较 （自 2.0.0 起）：精确的名字通过；上面某种拼写 规范化后等于枚举项名的，接受并给出 DSH5278 警告；其他 —— 包括不同时也是枚举项名的 DisplayName，如 Shared: Wrap —— 报 DSH5215。

对象属性

对象类型的 UPROPERTY 接受资产引用，由 Path(…) 里记录的共享解析器处理。

[!WARNING] 加载失败的纹理会被静默接受。 当属性是 UTexture 子类 且名字恰好为 Texture 或 TextureObject 时，加载失败会写入 nullptr，并把这次写入 报告为成功。于是 [Texture = Path(Game, "Typo")] 不产生任何诊断就生成完毕， 留下一个未绑定的采样器。（自 2.0.0 起） 纹理采样 token 和 const 纹理的默认值也写到这个属性上，同样如此；纹理采样节点随后 取引擎默认纹理。采样器出来不对时，先检查资产路径。

不走反射的组织字段

Group、SortPriority 和 Desc 存在于 UMaterialExpressionParameter 子类上。缺少其中之一的类 得到 DSH8210 警告，值 不写入。能构建的 15 个 token 生成的类都有这三个字段。

（自 2.0.0 起） 声明的类缺少的其他键也是同一个 DSH8210 警告，而 1.x 会让编译失败。在展开 token 上它是 DSH5213。

[!NOTE] DynamicParameter，1.x 里三个字段都缺的那个情况，现在是 DSH3253，什么都不构建。

Group(…) 作用域与 SortPriority 计数器

Properties 段里的一个 Group("Name") { … } 作用域会给 成员打标记。它与显式元数据条目的交互如下：

计数器从 0 开始，步长 10，并且在整个块内的所有作用域间共享，不会 按分组重置：

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
}

备注

• 同一個 [ … ] 块可被 Inputs / Outputs / Results 类型化参数接受，但那里 只有 Description / Desc / Tooltip 和 SortPriority / Sort 有任何效果。Group 会被 解析并保留但从不应用 —— Unreal 的函数输入/输出节点没有分组字段 —— 其余每个键都会被忽略，而不是被反射。输入的 SortPriority 默认为其 声明序号。参见输入 / 输出 / 结果。
• Shader 的 Outputs 语句上不接受任何元数据块，Settings、Options 或 Layout 条目上也不接受。
• const 声明只保留常量节点所拥有的内容：参见 紧凑类型 token。
• 显式的 [SamplerType=…] 总是覆盖从资产推导出的类型。
• 引擎枚举的 _MAX 哨兵通常不带 Hidden 元数据，因此在声明上诸如 "SAMPLERTYPE_MAX" 的值会解析而不是报错。不要使用它们。展开 token 所对照的目录中并不列出它们（DSH5215）。

诊断

解析期

绑定期

构建期

完整列表见诊断索引。

示例

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;
    }
}

应用的属性：

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 从它自己的条目取得 SortPriority = 51。MetallicMap 是展开 token，所以 Group("11 - Specular") 作用域不会给它打标记 （自 2.0.0 起）：要把它放入该分组，就在它 自己的块里写 Group = "11 - Specular"。

另见

• 参数 —— 中心与决策表
• 紧凑类型 token —— 元数据块可以跟随的 token
• 参数节点 token —— 每个 token 暴露的类专属键
• SamplerType —— 一个反射枚举的完全展开值表
• Path(…) —— 对象属性所接受的资产引用语法
• 属性（章节） —— Group("Name") { … } 作用域与排序
• 输入 / 输出 / 结果 —— 同一个块效果被削弱的地方
• 反编译器 —— 往返时总会发出的元数据键
• 诊断索引 —— 每一个代码