元数据与分组

声明后面可以跟一个 [ … ] 块：一串 Key = Value 条目，用来设置生成节点的组织字段；对于解析器不认识的 键，则直接写入该节点类的反射 UPROPERTY。

最后这一点才是这个块真正好用的地方。只有五种条目形式是特殊处理的，其余全部通过反射在 Unreal 类上查找 —— 也就是说，你生成的那个节点上引擎暴露的任何属性，都可以从源码里设置。

写一个块

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

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

上面的每个 [、]、;、,、= 和 ( ) 都是字面标点。同一个块里 ; 和 , 可以混用， ] 之前多写一个分隔符也会被接受。Slider(…) 是唯一不带 = 的条目形式。

ScalarParameter Roughness = 0.5 [Group="Surface"; Slider(0, 1); Desc="Micro-surface roughness"];

分号分隔形式自 since 1.2.4 起可用，元数据块本身自 since 1.2.3 起可用。

可识别的键

所有键比较都不区分大小写。每个条目 —— 包括可识别的那些 —— 同时以小写键存入并推给反射属性写入器， 所以可识别的键只是额外带有类型化效果，并不是另一套命名空间。

无人设置时 SortPriority 默认为 32，与 Unreal 自身的节点默认值一致。

Slider(min, max)

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

大小写不敏感匹配，必须以 ) 结尾，且内部文本按顶层 , 拆分后必须恰好是两个数值。两者都作为反射属性 SliderMin / SliderMax 写入，因此与 [SliderMin = 0; SliderMax = 1] 完全等价 —— 两种写法混用算重复。

SliderMin / SliderMax 存在于 UMaterialExpressionScalarParameter 上。在没有这两个属性的类上， 该条目会以“非反射属性”失败。

ParameterName

ScalarParameter Rough [ParameterName = "Surface Roughness"];

声明的标识符仍然是 Graph 使用的名字；ParameterName 只改变材质暴露给实例和蓝图的名字。 值为空时回退到声明的名字。

别名重写与自动注入

在写入任何内容之前，条目列表会先被补全，键也会被重写：

第 1–3 步的注入，正是把来自本块之外的值应用上去的机制 —— 最常见的来源就是外层的 Group("Name") { … } 作用域。

反射属性透传

除 Slider(…) 之外的任何键，都会被解析成生成节点类上的一个 FProperty：

1. 键先 trim、小写，再与每个 UPROPERTY 名做大小写不敏感比较；
2. 若失败，第二轮会去掉每个 FBoolProperty 名开头的 b 再比较一次。

于是 [FractionalPart = true] 绑定到 bFractionalPart，[UseCustomPrimitiveData = true] 绑定到 bUseCustomPrimitiveData。显式写出 b 同样有效。

按属性类型的取值语法

枚举字面量

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

由于这套规范化，"LinearColor"、"linear color"、"linear-color"、"SAMPLERTYPE_LinearColor" 和 "linear.color" 都选中同一个值。

对象属性

对象类型的 UPROPERTY 接受资产引用，由 Path 资产引用 里描述的元数据解析器处理。

不走反射的组织字段

Group、SortPriority 和 Desc 存在于 UMaterialExpressionParameter 子类上 —— 但并非每个参数节点 都是它的子类，UMaterialExpressionDynamicParameter 就不是。当类上缺少这三个字段之一时，会跳过并 警告，而不是报错：

'{Class}' does not expose the '{Field}' organization field; ignoring it for this parameter.

而其他无法解析的键都是硬错误：

Metadata property '{Key}' is not a reflected property on '{Class}'.

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

since 1.5.0 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 —— 不消耗槽位
        ScalarParameter D = 2.0;                   // SortPriority = 20
    }
    ScalarParameter Loose = 3.0;                   // 无分组，无自动排序
}

纹理相关键

写得最多的其实是纹理节点上的反射键。它们没有专门的代码路径 —— SamplerType 就是一个普通反射键， 只是恰好落在 TEnumAsByte<EMaterialSamplerType> UPROPERTY 上 —— 但值得逐个记住。

MipValueMode 是唯一会改变节点引脚集合的键，因而也决定了 引脚调用形式能连哪些引脚。

SamplerType 取值

17 个枚举项。同一行的四种拼写都能选中它，比较时忽略大小写并删除 、_、-、:、.、/。

DistanceFieldFont 和 External 没有 virtual 版本。

SamplerSource 取值

SSM_TerrainWeightmapGroupSettings 带 UMETA(Hidden)，因此不可选。由于 Shared: Wrap 规范化后是 sharedwrap，[SamplerSource="Shared: Wrap"] 和 [SamplerSource="SharedWrap"] 选中的是同一个值。

应用顺序

因为元数据最后应用，显式 [SamplerType=…] 永远压过推导值。不写这个键则意味着值跟随资产 —— 资产以后换了压缩设置，值也会变。因此反编译器在每次导出时都会显式写出 SamplerType 和纹理采样相关键，让反编译 → 重新编译的往返保持稳定。

这个块还能用在哪

• 材质函数 Inputs / Outputs / Results 的类型化参数上，但那里只有 Description / Desc / Tooltip 和 SortPriority / Sort 有效。Group 会被解析并保留但从不应用 —— Unreal 的函数 输入/输出节点没有分组字段 —— 其他键则被忽略而不是走反射。输入的 SortPriority 默认取声明序号。
• 不能用在 Shader 的 Outputs 语句上，也不能用在 Settings、Options 或 Layout 条目上。
• 可以用在 const 声明上：Constant 节点上的 [Desc="…"] 有效。

诊断

解析期

生成期

示例

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  Group="11 - Specular"  SortPriority=0   Desc="Packed metallic / roughness"
             SamplerType=SAMPLERTYPE_LinearColor     SamplerSource=SSM_FromTextureAsset
             MipValueMode=TMVM_None  bAutomaticViewMipBias=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，因此不消耗计数器槽位；槽位 0 被 MetallicMap 取走。

下一步

• Properties 类型 —— 元数据块能跟在哪些 token 后面，以及每个 token 暴露的专属键
• Path 资产引用 —— 对象类型条目接受的语法
• 材质 Settings —— 同一套反射思路，作用在 UMaterial 上
• 反编译导出 —— 往返时一定会写出哪些键