输出绑定

Shader 的 Outputs section 同时干两件事：

1. 声明 Graph 将要写入的变量；
2. 把这些变量 绑定 到 Unreal 材质属性输入，或绑定到显式创建的 UMaterialExpression 节点的 pin 上。

真正造出材质的是绑定，不是声明。只有声明、没有绑定的 Shader 会先带着警告 No Outputs block was provided. Generation requires explicit material property bindings. 解析通过，然后在生成阶段以 {File}: Outputs block is required. 失败。

语法概览

Outputs [=]
{
    <output-declaration>…
    <output-binding>…
}

output-declaration := <type> <name> [ = <expression> ] ;

output-binding     := Base. <target> = <source> ;
                    | Expression( <key> = <value> [, <key> = <value> ]… ) . Pin[ <index> ] = <source> ;

<source> 是一个输出变量名，或者保留名 return。<index> 两侧的 [ 和 ] 是 字面量。

语句归类是逐条判断的，不是按 section 判断的：

绑定目标种类

Base.<target> 清单

目标名 不区分大小写 匹配。下面列出了全部可接受的写法；没有通配符，也没有"等等"。

在 UE 5.4 及更新版本上是 46 种写法，对应 31 个不同的 EMaterialProperty。UE 5.3 上没有 FrontMaterial， 所以是 45 种写法、30 个属性。另有 5 种写法只存在于定制引擎分支中，见下面的"仅 fork 可用的目标"。

无法识别的名字会失败并报 Unsupported material output '{Name}'.

仅 fork 可用的目标

这些只有在引擎定义了 MOON_ENGINE 时才能解析。在原版 Unreal 上它们都是 Unsupported material output。

带副作用的目标

有两个 Base. 目标，仅仅因为被绑定 就会改变生成材质的渲染状态。只有这两个会这样，而且都很容易踩到。

Base.MaterialAttributes

绑定 Base.MaterialAttributes 会把 UMaterial::bUseMaterialAttributes 设为 true —— 也就是 Use Material Attributes 那个勾选框 —— 于是材质暴露的是单一的 attributes 输入，而不是各个独立属性输入。这个勾不需要你自己打， 你也无法在材质编辑器里取消：该属性在每次重新生成时都会被重置并重新应用。

被绑定的变量必须携带 MaterialAttributes 值，否则：

{File}: Material output '{Name}' expects a MaterialAttributes value.

Base.FrontMaterial

绑定 Base.FrontMaterial 会：

• 强制把着色模型设为 Substrate（MSM_Strata）；
• 要求 Settings 要么声明 ShadingModel="Substrate"（或它接受的别名 ShadingModel="Strata"），要么完全不声明 ShadingModel —— 其它情况都失败并报 {File}: Base.FrontMaterial requires ShadingModel="Substrate" or no explicit ShadingModel setting.；
• 与 Base.MaterialAttributes 互斥 —— {File}: Base.FrontMaterial and Base.MaterialAttributes cannot be used by the same Shader.；
• 无法由整表面 Custom 节点路径驱动 —— {File}: Base.FrontMaterial expects a Substrate value and cannot be driven by a material Custom node. Use a Graph block and Substrate.* nodes.；
• 在 UE 5.3 上不存在，会报 Base.FrontMaterial requires Unreal Engine 5.4 or newer.

被绑定的变量必须是 Substrate 值，由 Substrate.* 内置节点 产生：

Outputs = {
    Substrate Surface;
    Base.FrontMaterial = Surface;
}
Graph = {
    Surface = Substrate.Unlit(EmissiveColor = Color);
}

Expression( … ).Pin[i] 目标

有些 Unreal 输出根本不是材质属性输入，而是散落在图里的 custom output 节点。非 Base 的绑定形式就是用来创建这类节点、 并把源变量连到它的某个输入 pin 上的。

Expression( Class = "<ExpressionClass>" [, <key> = <value> ]… ) . Pin[ <index> ] = <source> ;

检查顺序与要求

参数键会被规范化 —— 去空白并转小写；值会去引号并去空白。

类解析

含 / 或 . 的值会被直接当作 object 路径加载，且只有当加载到的类派生自 UMaterialExpression 时才被接受。否则会构造一个候选列表 —— <Value>，以及在 <Value> 尚未以对应前缀开头时加上 U<Value>、MaterialExpression<Value> 和 UMaterialExpression<Value> —— 然后扫描每一个非抽象的 UMaterialExpression 子类，找名字与任一候选相等（忽略大小写）的那个。

Class= 出现的其它所有地方都适用同一条规则 —— 见 通用 UE.Expression。

其它参数

除 Class 之外的每个参数，都会用与声明元数据相同的字面量语法，写入所创建节点上同名的反射属性。 Class 仍留在参数表里，但在写反射属性时被跳过，所以它永远不会引发"不是属性"的错误。

Pin 索引与节点复用

• Pin[<index>] 是节点输入列表的零基索引，顺序按引擎声明的顺序。 Expression(Class="ThinTranslucentMaterialOutput").Pin[0] 是 TransmittanceColor，.Pin[1] 是 SurfaceCoverage。
• 索引越界会失败并报 Output target '{Target}' does not have Pin[{Index}].
• 每个 pin 只能绑定 一次：Output target pin '{Target}' is bound more than once.
• 节点按 类加上排序后的参数列表 去重。两条 Expression( … ) 规格完全相同的绑定共用一个节点、绑不同的 pin； 任何一个参数不同都会创建第二个节点。
• 源变量必须已经在 Outputs 中 声明： Output variable '{Name}' must declare an explicit type before binding to expression target '{Target}'.
• 创建出来的输出目标节点放在图的 X 1200 处，Y 从 200 开始，每个 +220。

Outputs = {
    float3 Transmittance;
    float  Coverage;
    float3 CoatNormal;

    // Both statements reuse one ThinTranslucentMaterialOutput node.
    Expression(Class="ThinTranslucentMaterialOutput").Pin[0] = Transmittance;
    Expression(Class="ThinTranslucentMaterialOutput").Pin[1] = Coverage;

    // A different class -> a second node.
    Expression(Class="ClearCoatNormalCustomOutput").Pin[0] = CoatNormal;
}

保留名 return

return 可以作为绑定的 源，但绝不能作为声明名。

实际用法中，return 属于整表面 Custom 节点路径，那种 Shader 没有 Graph 块。任何带 Graph 块的材质都应该声明具名输出变量。

校验规则

在解析之后、创建任何节点之前执行。

说明

• 绑定和声明可以自由穿插；绑定可以引用同一 section 中稍后才声明的变量。
• 重复出现的 Outputs section 会分别追加到两份列表。
• Shader 的任何 Outputs 语句都不接受 [ … ] 元数据块。
• 每条绑定都会经过一对生成的 NamedReroute，好让大图里的材质根节点保持可读。声明命名为 DS_<Sanitized> 加索引后缀。
• 绑定到当前着色模型或混合模式用不到的属性 不会 被诊断出来 —— Unreal 只是不去读那个输入。请看材质编辑器里变灰的输入。

常见错误

跨阶段的完整列表在错误速查。

完整示例

Shader(Name="DreamShaderTests/Corpus/M_Outputs")
{
    Properties = {
        vec3  Tint = vec3(0.4, 0.8, 1.0);
        float A    = 0.75;
    }

    Settings = {
        Domain       = "Surface";
        ShadingModel = "Unlit";
    }

    Outputs = {
        vec3  Color;
        float Alpha;

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

    Graph = {
        Color = Tint;
        Alpha = A;
    }
}

生成的连接：

UMaterial /Game/DreamShaderTests/Corpus/M_Outputs
  MP_EmissiveColor  <- NamedReroute DS_Color_<n>  <- VectorParameter "Tint"  RGB output
  MP_Opacity        <- NamedReroute DS_Alpha_<n>  <- ScalarParameter "A"     R output
  bUseMaterialAttributes = false

继续阅读