语句与声明

Graph 块体是一串扁平的语句。一共十种形式，用 ; 分隔，解析器靠一串固定的文本测试来判断一段文本属于 哪一种——不是靠关键字。理解这个分类顺序，就能解释本语言里大多数令人意外的诊断信息。

语法概要

graph-statement :=
      [ <type> ] <name> [ = <expression> ] ;                      // declaration / assignment
    | <type> <name> [ = <init> ] , <name> [ = <init> ] … ;        // comma declarators
    | <name> = { <expression> , … } ;                             // brace initializer
    | <name> . <member> = { <expression> | { <expression> , … } } ;
    | <call-expression> ;                                         // statement-form call
    | if ( <condition> ) { <graph-statement> … }
      [ else { <graph-statement> … } | else if ( … ) { … } … ]

十种形式

形式 8 会展开成每个声明子一条语句。它们全部共用第一个声明子的类型 token，并且全部报告同一个 源码行列。

块体如何切分

Graph = {
    float a = 1.0;;;             // ; 之间的空语句被丢弃
    if (a > 0.5) { a = 0.0; }    // 不需要 ;，内部的 ; 也不会切分这个 if
    float b = a * 2.0            // 最后一条语句，省略 ;
}

分类顺序

拿到一条语句的文本后，解析器按顺序测试下列规则，第一条匹配的胜出。

"能切成类型和名字"的含义是：在最后一个顶层空白字符处切开，过程中跟踪 ( ) 深度和字符串状态，两半 都必须非空。这就是 UE.Panner(Speed = 0.1) P; 是一条声明的原因——参数表内部的空格不在顶层。

声明

<type> <name> [ = { <expression> | <brace-initializer> } ]
     [ , <name> [ = { <expression> | <brace-initializer> } ] ] … ;

brace-initializer := { [ <expression> [ , <expression> ] … ] }

接受的类型 token

比较不区分大小写。对数值行、MaterialAttributes 和 Substrate，匹配前会移除 token 内部所有空格，所以 float 3 解析为 float3，Material Attributes 解析为 MaterialAttributes。纹理行和 StaticBool 按原样匹配，所以 Texture 2D 不能解析。

int、uint、bool 和 half 只是同样浮点宽度的另一种拼法——token 只固定分量数，别的什么都不改。 完整的按上下文分类目录见类型与值。

不带初始值的声明

float3 c;              // Constant(0) -> AppendVector -> AppendVector
MaterialAttributes A;  // MakeMaterialAttributes，可以直接写成员
Texture2D T;           // 错误：必须带初始值

带初始值的声明

先对初始值求值，再给声明定型：

步骤 3 的转换会通过前缀 r / rg / rgb 掩码静默收窄更宽的值，并把标量 splat 到声明宽度。 它绝不会把 2 分量加宽到 3 分量。

逗号分隔声明

float a = 1, b, c = 3;

上例声明了三个 1 分量值：a 初始化为 1，b 默认为 0，c 初始化为 3。声明子不是裸标识符时报 In Graph statement '{Text}': '{Declarator}' is not a valid declarator in a comma-separated declaration.

花括号初始值

右侧文本去空白后长度至少为 2、以 { 开头、以 } 结尾时，就是花括号初始值。它会被重新序列化为 <TargetType>( <inner> ) 并按普通构造器调用求值，因此继承构造器的全部规则：只能用位置参数、单个 标量会 splat 到所有通道、多个参数的分量数必须正好等于目标宽度。见 构造器。

{} 是特例：它产生目标类型的默认值，效果等同于不写初始值。

目标类型按以下顺序确定：

步骤 3 和 4 会拒绝纹理和 Substrate 目标。

Graph = {
    float r = 1.0;
    float g = 0.5;
    float b = 0.2;
    vec3 rgb  = {r, g, b};      // -> vec3(r, g, b)
    vec4 rgba = {rgb, 1.0};     // -> vec4(rgb, 1.0)，混合宽度打包
    Color = rgba.rgb;
}

重复声明

名字已经绑定过的声明会失败，报 Graph variable '{Name}' is declared more than once. 查找先比对精确拼写，再退化为不区分大小写扫描，所以 float a = 1; float A = 2; 是重复声明错误—— 而在其他所有地方 A 和 a 指的是同一个值。要给已有名字重新绑定，请省略类型 token，写成赋值。

赋值

形式 4 和 5。目标是顶层 = 的左侧，去空白后原样取用。

<target> = <expression> ;
<target> = { <expression> , … } ;

目标按以下顺序解析：

规则 2 和 3 的查找不区分大小写。

规则 4 意味着 = 左侧出现未声明的名字并不是错误：

Graph = {
    vec3 Base = Tint * 2.0;
    Scratch   = Base.rgb;    // 合法：创建 3 分量的 'Scratch'
    Color     = Scratch;     // 'Color' 是 Outputs 声明 -> 转换到它的类型
}

表达式语句

形式 9。既不是声明也不是赋值的语句会按表达式求值，且只有它是调用时才被接受：

语句形式下，参数是先声明的输入，然后每个输出对应一个普通变量名，按声明顺序排列。对所有被调方种类， 语句调用都只支持位置参数。完整参数规则见调用。

MaterialAttributes 成员写入

形式 6 和 7 写入 MaterialAttributes 值的一个属性。这是一个类似结构体的 Graph 值类型，分量数为 0 since 1.2.5，它把整个材质的属性集合当作一条连线携带。

Outputs = { MaterialAttributes Attrs; Base.MaterialAttributes = Attrs; }
Graph   = {
    MaterialAttributes Attrs;      // Outputs 声明并不会创建它
    Attrs.BaseColor = Tint;
    Attrs.Roughness = {0.35};
    float Rough = Attrs.Roughness; // 读取：BreakMaterialAttributes
}

每次成员写入都会在变量当前值上链接一个新的 SetMaterialAttributes 节点并把变量重新绑定过去； N 次写入产生 N 个节点。每次成员读取都会创建一个新的 BreakMaterialAttributes 节点——读取不去重。

成员列表

成员名在读写两侧都不区分大小写。别名是完全等价的同义词。

MaterialAttributes 及其别名 Attributes 能作为材质属性解析出来，但被显式拒绝作为成员使用。任何无法 识别的名字都报 Unsupported MaterialAttributes member '{Member}'.

读取时先按名字挑选 Break 输出——把属性的显示名与节点上每个输出名做不区分大小写比较——只有名字都不 匹配时才退回旧版索引。

成员写入规则

作用域

没有块作用域。 每个构建器只有一张值表——每个 Shader 一张，每个生成的材质函数一张——所有声明都写进 这张表。

分支在所在值表的副本上执行，之后再把副本合并回来：

合成语句

所在块中每个带默认值的 Outputs 声明都会被转成一条声明语句，并插到 Graph 块体第一条语句之前。 这些语句没有源码位置，所以它们的诊断不带可用的行号。

这也是 Graph = { } 对 Shader 合法的原因：带初始值的输出声明就是块体。见 输出绑定。

诊断

语句执行期间的进度文本为 Building DreamShader graph nodes ({N} statements)... 和 Evaluating DreamShader graph statement {I} of {N}...。语句数超过 512 时，只有每第 64 条语句才更新文本。

跨阶段的完整清单见错误速查。

示例

一个块体里写全所有语句形式：

ShaderFunction(Name="Functions/F_AllForms")
{
    Properties = { vec3 Tint = vec3(1.0, 0.4, 0.1); float K = 2.0; }
    Inputs     = { vec2 UV; }
    Outputs    = { MaterialAttributes Attrs; vec3 Debug; }

    Graph = {
        MaterialAttributes Attrs;              //    Outputs 声明不会创建它
        float3 c;                              // 1  声明，无初始值
        float3 scaled = Tint * K;              // 2  声明 + 表达式
        vec4   packed = {scaled, 1.0};         // 3  声明 + 花括号初始值
        c = packed.rgb;                        // 4  赋值
        Debug = {0.0, 0.0, 0.0};               // 5  赋值 + 花括号初始值
        Attrs.BaseColor = c;                   // 6  成员写入
        Attrs.Roughness = {0.35};              // 7  成员写入 + 花括号初始值
        float a = 1, b, d = 3;                 // 8  逗号分隔声明

        if (K > 1.0) {                         // 10 if / else
            Debug = c * a;
        } else {
            Debug = c * b;
        }
    }
}

这里唯一缺席的是形式 9，语句形式调用——它需要一个被调方，所以有自己独立的一页。

参见

• 运算符与转换 —— = 右侧可以写什么
• if / else —— 形式 10 的完整规则与合并
• 调用 —— 形式 9、out 目标与参数规则
• 不支持的写法 —— 为什么 return、for、+= 报的是变量类型错误