Properties 类型

Properties 段里的每一条声明，都会在生成的材质里变成恰好一个节点。生成哪个节点完全由你写的类型 token 决定：token 选定 Unreal 表达式类、决定默认值的写法，并且对少数几种类型来说，还决定这条声明能不能 在 Graph 里被调用以连接输入引脚。

命名类型有两种方式。紧凑 token（float、vec3、Texture2D）只说明值是什么，由 DreamShader 选节点； 显式 *Parameter token（TextureSampleParameter2D、ChannelMaskParameter）直接指定 Unreal 表达式类。 优先用紧凑 token，只有在紧凑集合做不到时才用显式 token。

声明的形状

[const] <type-token> <name> [ = <default-value> ] [ [ <metadata-entry> ; … ] ] ;

<default-value> 外面和整个元数据块外面的 [ … ] 是表示“可选”的元符号；元数据块自身的方括号是字面标点。 带元数据的声明写作 float A = 1.0 [Group="X"];。元数据语法见 元数据与分组，外层段落语法见 Section。

所有类型 token 都大小写不敏感。FLOAT3、Float3、float3 是同一个 token， texturesampleparameter2d 和 TextureSampleParameter2D 也是。

四类 token

还有第五种形式 UE.<Name>( … ) <name>;，把引擎输入节点（UV、时间、顶点色、参数集合读取）声明成属性， 见 UE.* 节点 和 通用 UE.Expression。

不匹配以上任何一种的 token 会报 Unsupported property type '{Token}'.

紧凑标量 token

七种拼写，在所有可观察的方面完全一致。

标量默认值

float A = 0.5;    float B = -2;    float C = 1e3;    float D = true;

文本按 double 解析，同时接受大小写不敏感的 true → 1.0、false → 0.0。其他内容报 Invalid scalar default value '{Text}' for property '{Name}'.

不写 = <default> 时不会写入任何值，节点保留引擎默认的 0.0。

紧凑向量 token

27 种拼写。每一种都生成 UMaterialExpressionVectorParameter，其 DefaultValue 是完整的 FLinearColor；不同的只有声明的分量数，而分量数决定了 Graph 读取时命中哪个节点输出。 分量数取自 token 的最后一个字符：2 是两分量，4 是四分量，其余都是三分量。

vec*、ivec*、uvec*、bvec* 是 float*、int*、uint*、bool* 的 GLSL 风格拼写。 没有单分量向量的紧凑 token：float1 和 half1 属于标量。

向量默认值

<anything> ( <part> [ , <part> ] … )

不写 = <default> 时节点保留引擎默认的 (1, 1, 1, 1)。

紧凑纹理 token

五种拼写，四种不同维度。每一种都生成纹理对象参数 —— 节点携带资产，但不采样它。

Texture3D 和 VolumeTexture 是严格同义词。要采样它们，在 Graph 里交给 TextureSample 内置节点， 或者直接声明 TextureSampleParameter2D。

纹理默认值

Texture2D A = Path(Game, "Textures/T_X");
Texture2D B = Path("/Game/Textures/T_X");
Texture2D C = "/Game/Textures/T_X";            // 裸的带引号绝对路径

裸引号形式自 since 1.5.0 起可用。全部 root 拼写和两套错误信息见 Path 资产引用；失败会被包装成 Invalid texture default value '{Text}' for property '{Name}'. {Inner}。

未指定资产时的默认值

维度校验

五个紧凑 token 都声明了明确的维度，因此会拿指定的资产去校验 —— 这里的 Texture2D 意思是 “不是 cube、不是 2D 数组、不是 volume”。不匹配时报

{Context} texture property '{Name}' expects {ExpectedType} but '{Path}' is a '{ActualClass}'.

其中 {Context} 对参数是 Texture，对 const 声明是 Const。加载成功后会执行 AutoSetSampleType()，所以除非元数据覆盖，SamplerType 会跟随资产。

const 声明

since 1.2.6 const 声明生成常量节点而不是参数：材质参数列表里没有它的名字，实例也无法覆盖。

const float Gamma = 2.2;                       // Constant
const vec3  Sky   = vec3(0.2, 0.4, 0.9);       // Constant3Vector
const Texture2D Lut = Path(Game, "T_Lut");     // TextureObject

const 只能和 39 个紧凑 token 搭配。和任意 *Parameter token 或 UE.* 声明搭配会被拒绝： Const property '{Name}' must use a plain scalar, vector, or texture type instead of a parameter node or UE builtin declaration.

const 声明仍然接受元数据块 —— Constant 节点上的 [Desc="…"] 有效；而 Graph 读取 const 向量时 永远命中输出 0，不走参数读取会用的 RG / RGB / RGBA 命名输出。

参数节点 token

22 个直接指定 Unreal 参数表达式类的 token。ScalarParameter、VectorParameter 和 TextureObjectParameter 走专用构造路径；其余 token 按名字解析类，依次尝试 <Token>、U<Token>、 MaterialExpression<Token>、UMaterialExpression<Token>，在所有非抽象 UMaterialExpression 子类中大小写不敏感地匹配。集合是封闭的 —— 就这 22 个。

“类型”一列是 DreamShader 的属性类型，不是 Unreal 的引脚类型。Texture 表示“资产值”：节点携带资产， 不产生数值输出。

SpriteTextureSampler 属于 Paper2D 插件。Paper2D 未启用时类无法解析，生成失败并报 Could not resolve MaterialExpression class for parameter type 'SpriteTextureSampler'.

token 使用哪个默认值解析器

= <default> 走哪个分支由 token 所属家族决定，而不是由生成的节点实际能存什么决定。

22 个 token 的默认值全部可选。写了默认值时的去向：

如果这六个资产槽位在类上都不存在，生成失败并报 '{Class}' does not expose a texture/asset property for property '{Name}'.

没有纹理的采样参数照样能编译：对 UMaterialExpressionTextureSampleParameter 子类会调用 SetDefaultTexture()，随后执行 AutoSetSampleType()。这条兜底不适用于 runtime virtual texture、 sparse volume、font 和 curve atlas 节点 —— 它们仍必须绑定资产。

维度：会推断，但基本不校验

八个纹理采样 token 会按拼写做子串测试推断维度，顺序是：Cube → TextureCube，然后 Array → Texture2DArray，然后 Volume → VolumeTexture，否则 Texture2D。（TextureSampleParameterCubeArray 同时含 Cube 和 Array，Cube 先命中。这没有可观察影响 —— 生成的类仍然是正确的 cube array 类。）

三个纹理对象 token 刻意不声明维度：维度在生成时取自指定的资产。

在 Graph 中读取属性

裸标识符读取属性的值。声明的分量数决定读取命中哪个节点输出：

所以 vec2 P 读 RG，而 VectorParameter P 读 RGBA。读取是惰性且带缓存的：节点在首次引用时创建 —— 声明顺序不限制读取 —— 之后每次引用都返回同一个节点。参见 调用 和 运算符与转换。

引脚调用形式

since 1.4.1 部分参数可以被调用以连接输入引脚：

vec4 S = BaseTex(Coordinates = UV);
vec4 M = Keep(Input = S);

节点的物化方式与裸读取完全相同 —— 共用同一份缓存 —— 随后每个具名实参去匹配节点的输入引脚。 匹配时两边都只做 trim 和小写化。没有位置参数写法：每个实参都必须具名，且实参值必须是数值。

只有十个 token 会被路由到引脚连接求值器：

ChannelMaskParameter                  TextureSampleParameterCubeArray
StaticComponentMaskParameter          TextureSampleParameterVolume
TextureSampleParameter2D              TextureSampleParameterSubUV
TextureSampleParameter2DArray         RuntimeVirtualTextureSampleParameter
TextureSampleParameterCube            SparseVolumeTextureSampleParameter

其余的 —— 所有紧凑 token 以及剩下十一个 *Parameter token —— 根本不会路由到那里；对它们做调用会落到 函数调用分发器，并以“未知函数”失败。

哪些引脚可达

引脚名在生成时取自引擎节点，所以可达性既取决于节点，也取决于调用前应用的元数据 —— 元数据在节点创建时 应用，而节点创建早于任何引脚连接。

StaticSwitchParameter

静态开关有专属调用形式，而且不能当作值读取：

vec3 C = UseDetail(True = DetailColor, False = BaseColor);
vec3 D = UseDetail(A = DetailColor, B = BaseColor);
vec3 E = UseDetail(DetailColor, BaseColor);          // 位置参数，按此顺序

true 分支依次取 True=、A=、第一个位置实参；false 分支依次取 False=、B=、第二个位置实参。 两个分支都必填。任一分支都不能是纹理对象或 Substrate 值，两个分支不能一边是 MaterialAttributes 一边是数值，且分量数必须相同。裸写 UseDetail（或 UseDetail.r）会失败并报 Unknown Graph identifier 'UseDetail'.

在 Properties 中无效的 token

这些在别处是真实存在的 DreamShaderLang 类型 token，但写在 Properties 声明里都会落到 Unsupported property type '{Token}'.

完整的跨上下文矩阵见 类型与值。

命名规则

• 属性名只要求非空，从不按标识符校验，所以 float 1Bad = 0; 能解析 —— 但它在 Graph 里不可达， 因为那里按标识符查名字。
• 在一个 Shader 内属性名必须忽略大小写后唯一。在材质函数内，属性名还不能与输入名冲突。
• [ParameterName="…"] 只改变材质暴露给实例和蓝图的名字；Graph 使用的仍是声明的标识符。

诊断

按阶段罗列的完整清单见 错误速查。

示例

Shader(Name="Docs/M_ParameterNodes")
{
    Properties = {
        const float Gamma = 2.2;                       // Constant

        Group("Surface") {
            TextureSampleParameter2D BaseTex = Path(Game, "Textures/T_White") [
                SamplerType   = "LinearColor";
                SamplerSource = "FromTextureAsset";
                MipValueMode  = "None";
            ];
            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"];

        UE.TexCoord(Index = 0) UV;
    }

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

    Outputs = {
        vec3  Color;
        float Rough;

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

    Graph = {
        vec4  Sample = BaseTex(Coordinates = UV);
        vec4  Masked = Keep(Input = Sample);
        float Chan   = Pick(Input = Sample);

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

生成的节点：

Constant(2.2)                 Gamma
TextureSampleParameter2D      BaseTex    Group="Surface" SortPriority=0  SamplerType=LinearColor
ScalarParameter               Roughness  Group="Surface" SortPriority=10 SliderMin=0 SliderMax=1
VectorParameter               Tint       Group="Surface" SortPriority=20
ChannelMaskParameter          Pick       Group="Masks"   SortPriority=30 MaskChannel=Red
StaticComponentMaskParameter  Keep       Group="Masks"   SortPriority=40
StaticSwitchParameter         UseDetail  Group="Switches"
TextureCoordinate             UV         CoordinateIndex=0

下一步

• 元数据与分组 —— [ … ] 块、Slider(…)、分组与排序
• Path 资产引用 —— 每种 Path(…) root 拼写及其错误
• UE.* 节点 —— 把引擎输入节点声明成属性
• 调用 —— 这些形式所属的通用调用语法