Substrate 节点

Substrate.* 是与 UE.* 并列的调用命名空间，用来包装 Unreal 的 Substrate BSDF、组合和工具材质节点。每个名字对应一个固定的表达式类 —— 24 个名字解析到 22 个不同的类， 因为其中有两对别名。

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

可用性

所有受引擎版本限制的部分：

语法概要

Substrate . <Name> ( [ <argument-name> = <expression> ]
                     [ , <argument-name> = <expression> ] …
                     [ , { Output | OutputName } = "<pin-name>" ]
                     [ , OutputIndex = <integer> ] )

命名空间前缀和名字都不区分大小写：SUBSTRATE.UNLIT(…) 能解析。参数名会去掉首尾空白并按不区分 大小写比较，但除此之外必须精确匹配 —— 不会去掉分隔符。

参数模型

每个 Substrate.* 调用都走通用反射路径，因此继承 UE.Expression 的规则。

由反射驱动的绑定

参数绑定不是查表的。对每个剩余参数，生成器按顺序尝试：

1. 输入 pin 名 —— 节点报告的每个输入 pin，去空白后不区分大小写比较。
2. UPROPERTY 名 —— 该类或父类上的任意反射属性，比较方式相同。布尔属性还额外支持去掉开头的 b 后匹配。
3. 如果属性是 FExpressionInput 或 FMaterialAttributesInput，参数成为连线输入，其值作为表达式求值； 否则作为字面量属性写入。
4. 都不匹配 → UE.{Name}: '{Argument}' is not a property on '{Class}'.

同名时 pin 名匹配优先于反射属性。

选择输出

Output= / OutputName= 按输出 pin 的名字原样比较，不区分大小写，包括含空格的名字 —— 输出 pin 名是作为整体名字匹配的，不会当成参数名解析。OutputIndex= 取 0 起始的索引。 只有四个工具节点有多个输出。

目录

Substrate 输出标记那些结果是 Substrate 材质值的包装节点 —— 0 分量，可绑定到 Base.FrontMaterial。 标为否的四个是工具节点，返回普通数值。

两对别名是完全的重复 —— 同一个类、同样的输入、同样的输出类型。两种写法都没有被弃用。

输出类型

随后会用所选输出 pin 的真实值类型检查声明的类型。如果一个声明为 Substrate 输出的包装节点解析到的 pin 不是 Substrate 值，调用会失败：Substrate.{Name} output is not a Substrate value.

Substrate 值只能：

• 赋给 Substrate 类型的 Graph 变量或 Outputs 声明；
• 传给另一个 Substrate.* 包装节点的 Substrate 类型输入；
• 绑定到 Base.FrontMaterial。

节点参考

BSDF

Substrate.Slab

通用的 Substrate BSDF slab —— 通常从它开始。

Substrate.SimpleClearCoat

带固定第二层 clear coat 波瓣的 slab。

Substrate.Unlit

只有自发光的 BSDF。最小的完整 Substrate 表面。

Substrate.Hair

Substrate.Eye

Substrate.SingleLayerWater

Substrate.VolumetricFogCloud

用于体积雾和云材质的参与介质 BSDF。

Substrate.ShadingModels

用 Substrate 材质表达的传统着色模型表面。编辑器补全不为这个包装节点提供任何参数；下面所有参数仍然可用。

域输出节点

Substrate.LightFunction

Substrate.PostProcess

Substrate.UI

转换

Substrate.ConvertMaterialAttributes

把 MaterialAttributes 值转换成 Substrate 材质。

MaterialAttributes 是反射属性名，Attributes 是引擎给同一个输入起的 pin 名；两者都绑定 input 0。 传数值进去会失败： Substrate.ConvertMaterialAttributes input '{Pin}' expects a MaterialAttributes value.

Substrate.ConvertToDecal

把 Substrate 材质转换成贴花材质。

组合

Substrate.HorizontalMix

在屏幕空间水平混合两个 Substrate 材质。也可以写成 Substrate.HorizontalMixing —— 两个名字可以互换。

Substrate.VerticalLayer

把一个 Substrate 材质叠在另一个之上。也可以写成 Substrate.VerticalLayering —— 两个名字可以互换。

Substrate.Add

Substrate.Weight

缩放一个 Substrate 材质的贡献。

Substrate.Select

在两个 Substrate 材质之间做静态选择。

工具节点

这四个返回普通数值而不是 Substrate 值，也是唯一有多个输出的包装节点。用 Output= 或 OutputIndex= 选择。

Substrate.TransmittanceToMFP

把透射颜色和厚度转换成平均自由程参数化。

Substrate.MetalnessToDiffuseAlbedoF0

把传统的 base color / metallic / specular 三元组转换成 slab 参数化。

Substrate.HazinessToSecondaryRoughness

把 haziness 控制量转换成第二粗糙度波瓣。

注意这些输出名里带空格。它们是作为整体名字匹配的，所以 Output = "Second Roughness Weight" 可用 —— 尽管带空格的 pin 名作为参数名是无法触达的。

Substrate.ThinFilm

计算薄膜干涉的高光颜色。

绑定到 Base.FrontMaterial

Substrate 材质只能通过 Base.FrontMaterial 输出绑定进入生成的 UMaterial，没有别的途径。

Outputs = {
    Substrate Surface;              // 声明类型 token；不区分大小写，没有别的写法
    Base.FrontMaterial = Surface;
}
Graph = {
    Surface = Substrate.Unlit(EmissiveColor = Color);
}

一些值得知道的细节

• 并非每个 Substrate 类都有包装节点。 UMaterialExpressionSubstrateToonBSDF 在目录里没有条目。 要用它 —— 以及将来任何新的 Substrate 类 —— 走通用路径：

  UE.Expression(Class = "SubstrateToonBSDF", OutputType = "Substrate", …)

  类名解析接受 SubstrateToonBSDF、MaterialExpressionSubstrateToonBSDF 和完整的 /Script/Engine.… object path，三者等价。带 U 前缀的 C++ 写法不被接受 —— 参见 类解析。

• 已注册的 UE.* 语法糖在这个命名空间里不适用。 没有 Substrate.TexCoord(…) 这种东西； 未知名字会失败于 Unsupported Substrate builtin call '{Name}' in Graph.

• Substrate 节点会参与节点复用：两个文本相同、参数值也相同的 Substrate.Slab(…) 调用会合并成 一个节点。这和通用 UE.Expression 路径用的是同一套缓存， 也正因如此，一个多输出的工具节点可以用不同的 Output= 选择器服务两次读取。

• 反编译器可以把已有的 Substrate 图导回 DreamShaderLang， 并从每条连接的写掩码推导通道 swizzle since 1.5.0。

• 完整的 Substrate.* 使用面会导出给编辑器工具链，写入 Saved/DreamShader/Bridge/substrate-builtins.json（schema DreamShader.SubstrateBuiltins， version 1），每个名字一条，含 qualifiedName、className、outputType、isSubstrateOutput 和精选的 parameters。参见编辑器工具。

诊断

调用点

管线其他环节中的 Substrate 值

完整清单见错误速查。

示例

Shader(Name="Docs/M_Substrate")
{
    Properties = {
        vec3  BaseColor = vec3(0.6, 0.1, 0.1);
        float Metallic  = 0.0;
        float Specular  = 0.5;
        float Rough     = 0.3;
        vec3  Glow      = vec3(0.1, 0.6, 1.0);
    }

    Outputs = {
        Substrate Surface;
        Base.FrontMaterial = Surface;
    }

    Graph = {
        // 工具节点：两个数值输出，按名字选择。
        vec3 Albedo = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "DiffuseAlbedo");
        vec3 F0 = Substrate.MetalnessToDiffuseAlbedoF0(
            BaseColor = BaseColor, Metallic = Metallic, Specular = Specular,
            Output = "F0");

        Substrate Body = Substrate.Slab(
            DiffuseAlbedo = Albedo,
            F0            = F0,
            Roughness     = Rough);

        Substrate Emissive = Substrate.Unlit(EmissiveColor = Glow);

        Surface = Substrate.Add(A = Body, B = Emissive);
    }
}

生成的节点：

SubstrateMetalnessToDiffuseAlbedoF0   -> output "DiffuseAlbedo"  -> Albedo    (3 components)
                                      -> output "F0"             -> F0        (3 components)
                                         (one node, reused for both reads)
SubstrateSlabBSDF                     -> Body                    (Substrate value)
SubstrateUnlitBSDF                    -> Emissive                (Substrate value)
SubstrateAdd                          -> Surface                 (Substrate value)
Material ShadingModel forced to Substrate by the Base.FrontMaterial binding

接下来