Sections

带属性的块，其函数体就是一串 section。一个 section 由名字、可选的 =，以及一对花括号里以 ; 分隔的语句组成。

<section> := <section-name> [=] { <statement>… } [;]

Section 名按大小写不敏感匹配，可以任意顺序出现，也可以重复。= 是可选的语法糖（自 1.5.0 起），闭合 } 之后的 ; 也是可选的。下面四种写法是同一个 section：

Properties = { float A = 1.0; }
Properties   { float A = 1.0; }
properties = { float A = 1.0; };
PROPERTIES   { float A = 1.0 }

section 内容逐个 token 读取（自 2.0.0 起）：任意空白都能分隔单词，制表符和空格没有区别；读取器跟踪 ()、[] 和 {}，字符串是一个 token，所以 Group 体和方括号元数据块永远不会在错误的地方切断语句。

支持矩阵

1. 除非 Outputs 里的语句自己算出值 —— 带初始化式的输出声明（自 1.3.4 起），或右侧是表达式的绑定（自 2.0.0 起）。

"未知 section" 是 DSH2245。Function 和 GraphFunction 完全没有 section —— 它们的 { … } 是原始 HLSL。

重复出现时的行为

重复的 section 并不总是追加。

1.x 对这几种覆盖都不吭声；现在它们照旧生效，只是会说出来。

Properties

声明一个块生成到它自己的图里的参数节点、常量节点和 UE.* 内置节点。在 2.0 里，一个属性就是一个 uniform（或 static const），元数据写在 /// 行里；dsc migrate 按这个形式改写 section。

property-declaration := [ const ] <type-token> <name> [ = <default> ] [ [ <metadata> ] ] ;

group-scope          := Group( "<group-name>" ) { { <property-declaration> | <group-scope> }… } [ ; ]

<metadata> 外面最内层的那对 [ … ] 是字面的 DreamShaderLang 标点；外面那对是"可选"的元语法。所以带元数据的声明写起来是 float Roughness = 0.5 [Group="Surface"];。

Properties = {
    const float DebugScale = 1.0;                 // UMaterialExpressionConstant
    float Strength         = 1.0;                 // UMaterialExpressionScalarParameter
    vec3  Tint             = vec3(1.0, 1.0, 1.0); // UMaterialExpressionVectorParameter
    UE.TexCoord(Index = 0) UV;                    // a builtin node, not a parameter
}

一条声明从左到右逐个 token 读取（自 2.0.0 起）：

所以 UE.TexCoord(Index = 0) UV; 读成类型 UE.TexCoord(Index = 0) 和名字 UV，类型和名字之间写制表符也行。

警告：

名字必须是标识符（自 2.0.0 起）。1.x 只检查名字非空，于是 Properties { float 1Bad = 0; } 能解析、却永远引用不到；现在 1Bad 是畸形数字（DSH2105），这条声明是 DSH3250。in、out 这类保留字也不能当名字。同一个文件里重名是 DSH4210，比较是精确的（1.x 忽略大小写）。

属性节点在 Graph 第一次读取时才建，之后的读取共享它（自 1.3.2 起）；Graph 从没读过的属性不会产生节点。Graph 在块里其他 section 之后才读，所以写在它下面的属性也看得见：声明顺序不影响名字解析 —— 它只影响下面的自动排序计数器。

其他 token 是 DSH3252。显式 token 里有七个没有 2.0 形式，是 DSH3253（自 2.0.0 起）：DoubleVectorParameter、TextureCollectionParameter、CurveAtlasRowParameter、DynamicParameter、FontSampleParameter、SpriteTextureSampler、SparseVolumeTextureObjectParameter。在这里 StaticBool 读作 bool，声明的是动态布尔参数（自 2.0.0 起）；静态开关参数要写 StaticBoolParameter。UE.* 属性后面写 = <default> 是 DSH3259 —— 参数写在括号里。

纹理默认值除了 Path(Game, "…")、Path("/Game/…") 和带引号的绝对路径，还接受 Content Browser 的 Copy Reference 文本 Texture2D'/Game/Textures/T_X.T_X'（自 1.9.0 起）—— 裸写、加引号，或作为 Path(…) 的路径参数。引号前的类和声明的纹理类型不符是 DSH1044；根本不是纹理类是 DSH1043。

类型 token、const、默认值和元数据块的完整说明见 Properties 类型 和 元数据与分组。

Group("Name") { … } 作用域

（自 1.5.0 起）

Group 作用域把自己的名字盖到内部每一条声明上，省得在每条声明的元数据里重复写同一个分组。

Properties {
    Group("Surface") {
        ScalarParameter Roughness = 0.5 [Slider(0, 1)];
        VectorParameter BaseColor = float4(1, 1, 1, 1);
    }
}

Group(…) 是唯一可以在 Properties 内打开 { 的构造。其他任何 { 都是 DSH3250，而缺少 } 的分组会一直读到文件末尾（DSH2150）。

作用域可以嵌套任意深度。嵌套作用域的有效名字是外层名字、一个 |，以及内层名字 —— 这正是 Unreal 自己的子分类写法。在名字里手写的 | 会原样保留：

Properties {
    Group("Surface") {
        float A = 0;                    // Group = "Surface"
        Group("Detail") {
            float B = 0;                // Group = "Surface|Detail"
            Group("Micro") {
                float C = 0;            // Group = "Surface|Detail|Micro"
            }
        }
    }
}

声明上写的显式键总是胜出。只有当成员的元数据里既没有写 Group 也没有写 Category 时，继承来的分组才会生效：

Group("Surface") {
    float A = 0;                        // Group = "Surface"    (inherited)
    float B = 0 [Group="Override"];     // Group = "Override"   (explicit wins)
    float C = 0 [Category="Other"];     // Group = "Other"      (Category is the alias)
}

自动 SortPriority

分组作用域里的成员按声明顺序自动编号。

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];  // SortPriority = 99, no slot consumed
        ScalarParameter D = 2.0;                    // SortPriority = 20  (counter continued)
    }
    ScalarParameter Loose = 3.0;                    // no group, no auto sort
}

注意：

计数器是每个 Properties section 播种一次的。一个块声明了两次 Properties，第二个 section 会拿到一个 从 0 重新开始的新计数器，于是两个 section 里的两个分组可能撞上重叠的排序优先级。

当分组作用域和显式元数据都没有提供值时，参数取 32 —— 引擎给参数节点自身的默认值，也就是 1.x 留下的值。

元数据

尾随的 [ … ] 块里，条目以 ; 或 , 分隔，键忽略大小写匹配， 同一个键写两次是 DSH3256。

表里没有列出的键都通过反射写到节点上（自 2.0.0 起）：参数节点类没有的键是警告 DSH8210、 值不写入（1.x 直接拒绝），属性接受不了的值是 DSH8213。滑条范围只属于标量参数， 写在向量、纹理或布尔参数上是一条警告 DSH7233，范围被丢弃 （自 2.1.0 起）。完整语法见 元数据与分组。

Inputs、Outputs 与 Results

类型化参数 section。它们声明生成的材质函数的引脚，或者 VirtualFunction 所描述的接口。

parameter-declaration := [ opt ] <type> <name> [ = <default-expression> ] [ [ <metadata> ] ] ;

Results 是 Outputs 的纯同义词 —— 它追加进同一个列表，没有任何警告。

不符合 [opt] <type> <name> [= <default>] [[ … ]] ; 的语句是 DSH3271，= 后面为空的默认值也是。 opt、类型和名字之间任意空白都行（自 2.0.0 起）；类型是一个单词，所以 Material Attributes X; 或 float 4 Colour; 是 DSH3271。不是类型的单词是 DSH4201； 同一个 section 里两个同名参数是 DSH4214。

注意：

in 和 out 在这些 section 里不是限定符。它们只存在于 Function / GraphFunction 的签名形式里，那是另一套 语法。Inputs = { in float X; } 是 DSH3271：in 是关键字，不是类型。

输入默认值

输入上的默认值是调用方不连线时引脚取的值，并让这个输入变成可选 —— 1.x 只给它一个预览值，引脚仍然必需 （自 2.0.0 起）。

正是这条图表达式路径，让默认值可以引用块自身生成的节点 （自 1.2.6 起）：

ShaderFunction(Name="Functions/F_Sample")
{
    Properties = {
        const Texture2D PreviewTex = Path(Engine, "EngineResources/DefaultTexture");
    }
    Inputs = {
        opt Texture2D Tex = PreviewTex;      // preview graph, not a literal
        opt float     Mix = 0.5;             // constant → PreviewValue
    }
    Outputs = { vec4 OutColor; }
    Graph   = { OutColor = Tex(Coordinates = UE.TexCoord(Index = 0)) * Mix; }
}

默认值按赋值的规则转换到输入的类型：装不下是 DSH4226，更宽的向量被截到前几个分量并给出 info DSH5289。 StaticBool 输入的默认值会变成接在 Preview 引脚上的 StaticBool 节点，因为引擎 在那里忽略 PreviewValue。

输出

• 材质函数 Outputs / Results 条目上的 = <expression> 会被丢弃并给出警告 DSH3273；写在输出上的 opt 是警告 DSH3272。函数输出只由 Graph 驱动。这不适用于 Shader 的 Outputs，那里的初始化式是有意义的。
• 名字恰好叫 Result 的第一个输出是函数的返回值，从零开始；其余每个输出都必须在 Graph 里被赋值 （DSH6211）。函数至少要声明一个输出（DSH4315），VirtualFunction 也一样（DSH6313）。
• MaterialAttributes 输出从空材质开始，所以 Attrs.BaseColor = …; 这类成员写入有目标；层的输出从流入的材质开始。

元数据与顺序

只有 Description / Desc / Tooltip 和 SortPriority / Sort 有效；其他每个键 —— 包括 Group —— 都被接受并静默忽略：函数输入和输出节点没有分组字段， 也不会做反射写入。一个 section 的引脚按 SortPriority 稳定排序（没写的 按声明序号算），资产上得到连续的优先级 0, 1, 2, …（自 2.0.0 起）。 引脚 GUID 按名字跨重新生成缓存，所以重新生成 ShaderFunction 不会弄断 已有的调用点。

Properties 与 Inputs

两者都往生成的函数里放东西，但它们是产出不同节点的不同语法。

Outputs 里的 Shader

Shader 的 Outputs 用一段函数体填两个列表；逐条语句按开头的 token 分类：

Outputs = {
    vec3  Color;
    float Alpha;

    Base.EmissiveColor = Color;
    Base.Opacity       = Alpha;
}

• 声明和绑定可以自由交错；绑定可以引用同一 section 中后面才声明的变量。
• <source> 是一个表达式 （自 2.0.0 起）：1.x 写法里的输出变量名，或者 Graph 表达式能写的任何东西，在 Graph 运行之后求值。= 后面为空是 DSH3270。
• return 是关键字 （自 2.0.0 起）：它不能做输出声明的名字（DSH3266），也不是绑定源。
• Shader 的 Outputs 语句上不接受 [ … ] 元数据块（DSH3266）。同名声明两次是 DSH4220。

块形式把 Expression( … ) 的说明只写一次。说明本身就是节点去重的键，所以语句形式里每个引脚漏写一个参数就会把节点悄悄拆成两个；块形式里的 N 个引脚永远落在一个节点上：

Outputs = {
    float _PhaseG_Out;
    float _PhaseG2_Out;

    Expression(Class="VolumetricAdvancedMaterialOutput", PerSamplePhaseEvaluation="false")
    {
        Pin[0] = _PhaseG_Out;
        Pin[1] = _PhaseG2_Out;
    }
}

块内只能写 Pin[<i>] = <source>; 语句（否则 DSH3267）；空块是 DSH3269；同一个节点的同一个引脚绑两次是 DSH3268，跨块形式和语句形式都算。块形式和说明完全相同的语句形式指向同一个节点，可以混用。

完整的 Base.* 目录和 Expression( … ).Pin[i] 规则见 输出绑定。

Settings 与 Options

两者共用一套语句语法：<Key> = <Value> ;。键忽略大小写匹配、按原样保存；值一直到括号之外的 ;，单个带引号的字符串取它的文本（转义已解析），其他取 token 的文本。键不是单词、缺 = 或缺值是 DSH3261；同一个键写两次时后写的胜出并给出警告 DSH3262 （自 2.0.0 起）。

提示：

那三个函数键每次构建都会应用，缺省时会被重置，所以从源码里删掉一个键就等于从资产上删掉它。LibraryCategories 按逗号切分，每项去空白，空项丢弃。ExposeToLibrary 只有为 true 且 LibraryCategories 非空时才会置位 （自 2.0.0 起）；它的值不是 true / false 时是警告 DSH3265，按 false 处理。UserExposedCaption 不再写入 —— 给出警告 DSH3264，值保留给 dsc migrate （自 2.0.0 起）。其他任何键是警告 DSH3263 并被忽略。

Graph

节点图的函数体。它和块里其他 section 在同一次解析中读取、但排在它们之后，由 2.0 的语句与表达式解析器处理 （自 2.0.0 起）；1.x Graph 没有的写法会被点名拒绝（DSH2200–DSH2222）。注释在这里照常识别，#Region 指令只在这里有效，#if 预处理指令在这里也能用（Graph 是 DreamShaderLang，不是 HLSL）。

Graph = {
    vec2 UV  = UE.TexCoord(Index = 0);
    vec4 Tex = BaseTex(Coordinates = UV);
    Color = Tex.rgb * Tint;
}

语句和表达式语言见 Graph 求值。

Layout

固定生成节点的位置并声明注释框。见 Layout 与 #Region。

诊断

继续阅读

• 类型与值 — 哪个类型 token 在哪个 section 里合法。
• Properties 类型 — 紧凑类型、const，以及 22 个显式参数节点。
• 元数据与分组 — [ … ] 块、Slider(…) 与反射透传。
• 输出绑定 — Base.* 目录与 Expression( … ).Pin[i]。