通用 UE.Expression

已注册内置节点只覆盖了 Unreal 数百个材质表达式中的 27 个。UE.Expression 是其余部分的逃生舱：它按名字创建任意非抽象的 UMaterialExpression 子类，并用命名参数填充它的输入 pin 和 UPROPERTY。

float pulse = UE.Expression(Class = "Sine", OutputType = "float1", Input = UE.Time());

还有一种更短的写法。Class 默认取函数名，所以 UE.Sine(…) 和 UE.Expression(Class = "Sine", …) 是同一个实现里的同一个调用：

float pulse = UE.Sine(OutputType = "float1", Input = UE.Time());

Expression 这个名字并不特殊，唯一的特别之处是它永远解析不出一个类 —— 这正是第一种写法必须写 Class= 的原因。

UE.Expression( Class = <class-specifier> , { OutputType | ResultType } = <type-token>
               [, { { Output | OutputName } = <text> | OutputIndex = <int> } ]
               [, <arg-name> = <expression> ] … )

UE.<ClassName>( { OutputType | ResultType } = <type-token> [, <arg-name> = <expression> ] … )

所有参数都必须是命名参数。位置参数会失败： Generic {Namespace}.{Function} calls require named arguments. 文本参数可以带引号也可以不带： Class = Sine 与 Class = "Sine" 相同，OutputType = float3 与 OutputType = "float3" 也相同。

和已注册内置节点不同，这条路径会校验每一个参数名。既匹配不上 pin 也匹配不上属性的名字是错误， 而不是被静默丢弃。

类解析

Class 必须是字面量 —— 带引号的字符串、裸标识符或带点的名字。说明符会先去掉首尾空白，然后按下列规则解析：

对说明符 S 的候选名：

前缀判断和最终比较都不区分大小写。

在 Substrate.* 路径上，类由内置描述符固定，Class= 会被直接拒绝。

解析顺序

调用按下列顺序处理。这个顺序是可观察的，因为只有第一个失败的步骤会被报出来。

OutputType

OutputType（别名 ResultType，只在没写 OutputType 时才会被读取）在这条路径上是必需的。 不写会得到：

Unsupported UE builtin call '{Function}' in Graph. For generic MaterialExpression calls, add OutputType="float1/2/3/4/Texture2D/TextureCube/Texture2DArray/VolumeTexture/Substrate".

这条提示里列了九种写法。实际接受的集合有 44 个 token。

接受的 token

全部 token 及其在各个使用面上的可用性。匹配全程不区分大小写。

† 在 property 声明这个使用面上，五个纹理 token 解析成同一种声明类别 —— 0 分量的纹理对象 property， 维度不会被记录。这和 Graph 使用面不同，那里 TextureCube 和 Texture2DArray 会产生类型不同的值。 维度要紧时请用普通类型 token 声明（TextureCube Tex;），参见类型与值。

SamplerState 只在 Graph 使用面上是 Texture2D 的可接受写法。StaticBool 和 StaticBoolParameter 都解析为 1 分量值；它们存在只是为了让值能与 StaticBool 函数输入做类型检查，除此之外和 float 没有区别。

归一化

token 的归一化并不统一 —— 用了三种不同的比较方式，当 token 带多余空白时差异是可观察的。

归一化后的 token 也参与节点复用键。两个只在 OutputType 写法上不同的调用 —— float3 与 vec3 —— 会构成不同的键，因此产生两个节点，尽管得到的值完全一样。

参数分派

有六个参数名是保留的，永远不会分派给节点：

其余每个参数按下列顺序对创建出的节点解析，第一个匹配上的胜出。

属性匹配分两遍：

输入 pin

解析到 pin 的参数 —— 无论是通过 pin 名，还是通过类型为表达式输入结构体（FExpressionInput， 或名为 MaterialAttributesInput 的结构体）的属性 —— 其值会作为 Graph 表达式求值并连接。 值携带的通道掩码会一并传递到连接上。

随后会用 pin 声明的值类型检查这个值：

pin 上不做宽度检查：把 float4 连到标量 pin 是引擎要处理的问题，不是 DreamShader 的。

字面量属性

其他匹配上的属性都用字面量写入。对象类型的属性按资产引用读取，其余按字面文本读取。

这些消息都会再包一层：UE.{Function} property '{Property}': {Message}。

枚举值

枚举值会以四种写法与该枚举的每个非隐藏条目比较。比较前双方都转小写，并去掉空格、_、-、:、.、/ 这些字符。

规则 4 正是不带前缀的写法能生效的原因，也是 UE.SceneTexture 所依赖的机制。

对象属性

对象类型的属性接受 Path(<root>, "<asset>")、Path("/Game/…") 或裸的绝对 object path。参见 Path 资产引用。

UE.Expression(Class = "TextureSample", OutputType = "float4",
              Texture = Path(Game, "Missing/T_Nope"))

选择输出

多输出的节点通过两个互斥的选择器之一读取。两个都写是错误；都不写则选择 output 0。

按名字解析时会按顺序遍历所有输出：

说明符会去掉首尾空白；空说明符选择 output 0。

Custom 节点

UMaterialExpressionCustom 是唯一被专门处理的类 —— 它是把原始 HLSL 塞进 Graph 的方式。

float3 tinted = UE.Expression(Class = "Custom", OutputType = "float3",
                              Code = "return In * 0.5f;",
                              In   = baseColor);

结果类型与分量数

结果按下列顺序从解析出的输出的真实值类型推导。

已知宽度表：

另有五个类的宽度由实际连到输入上的值决定：

分量数为 0、又不是纹理也不是 Substrate 的结果，就是 MaterialAttributes 值。参见 类型与值。

对材质的副作用

有两个类通过这条路径创建时会被注册为材质参数，因而出现在材质实例编辑器里：

两者的 expression GUID 无效时都会被重新分配一个。

节点复用

这条使用面是会去重的。每次调用会构建两个缓存键：

输出键命中会直接返回上一次的结果。表达式键命中会复用节点、只重新解析输出 —— 这正是一个多输出节点 可以用不同 Output= 选择器服务两次读取的原因。键中的字面文本会做归一化：合并连续空格、统一换行符。 UMaterialExpressionCustom 的子类从不参与复用。

与之相对，已注册内置节点完全不查缓存，每次调用都新建节点。

SampleTexture2D

float4 texel = SampleTexture2D(BaseTex, uv);

一个保留的双参数形式，在用户 property 和函数之前解析，且区分大小写 —— sampletexture2d(t, uv) 不是它。它会被改写成

UE.Expression(Class = "TextureSample", OutputType = "float4",
              TextureObject = <arg0>, Coordinates = <arg1>)

两个参数都是位置参数，且都必需： SampleTexture2D expects exactly two positional arguments: (textureObject, uv).

声明形式

通用的 UE.<Name>(…) 也可以作为 property 类型出现在 Properties section 中， 声明形式目录之外的名字都由同一套反射机制创建。 它的规则和 Graph 形式不同：

Properties {
    UE.Expression(Class = "ObjectRadius", OutputType = "float1") Radius;
}

这个使用面额外的消息：

通常写在 Graph 里更清晰，因为输入关系在调用点就能看见。

一些值得知道的细节

• 属性名是扁平的。这里不接受带点的路径和 [index] 选择器，那些只存在于 材质 Settings 中，那是另一个解析器。
• 没有办法故意让引擎的必需 pin 保持未连接，也没有办法断开一个 pin。参数要么连一个值，要么不写。
• 因为 Class 默认取函数名，类名写错时报的是 could not resolve MaterialExpression class 而不是「未知内置节点」。UE.Sinee(OutputType="float1") 和 UE.Expression(Class="Sinee", OutputType="float1") 报的是同一条消息。
• 通用调用可以像任何表达式一样 swizzle： UE.Expression(Class = "VertexColor", OutputType = "float4").rgb。
• 编辑器会把反射出的表达式清单导出到 Saved/DreamShader/Bridge/material-expressions.json，其中列出每个可解析类及其 pin 和属性。 这是查参数名最实用的办法 —— 参见编辑器工具。

诊断

{Function} 保留作者书写的名字和大小写；{Namespace} 就是字面上的 UE 或 Substrate。

完整清单见错误速查。

示例

Shader(Name="Docs/M_Generic")
{
    Properties {
        Texture2D BaseTex = Path(Game, "Textures/T_Noise");
        vec3      Dimmed  = vec3(0.2, 0.2, 0.2);
    }

    Settings { ShadingModel = "Unlit"; }

    Outputs {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph {
        // Class 默认取函数名。
        float pulse = UE.Sine(OutputType = "float1", Input = UE.Time());

        // 显式 Class，以及不带前缀写法的枚举属性。
        float3 scene = UE.Expression(Class = "SceneTexture", OutputType = "float4",
                                     SceneTextureId = "PostProcessInput0").rgb;

        // 通过 Path(...) 写对象属性，并按 pin 名连接输入。
        float4 tex = UE.Expression(Class = "TextureSample", OutputType = "float4",
                                   Texture     = Path(Game, "Textures/T_Noise"),
                                   Coordinates = UE.TexCoord(Index = 0));

        // 宽度由所连输入决定的类。
        float3 sel = UE.Expression(Class = "StaticSwitch", OutputType = "float3",
                                   True = Dimmed, False = tex.rgb, Value = true);

        Color = (scene + sel) * pulse;
    }
}

生成的节点：

Time                                  -> Sine                       (pulse)
SceneTexture (PPI_PostProcessInput0)  -> mask .rgb                  (scene)
TextureCoordinate (Index 0)           -> TextureSample.Coordinates
TextureSample (Texture = T_Noise)                                   (tex)
Constant3Vector (0.2, 0.2, 0.2)       -> StaticSwitch.True
StaticSwitch  (Value = true)                                        (sel)
Add, Multiply                                                       (Color)

接下来