UE.* 节点

UE. 命名空间是 DreamShaderLang 创建 Unreal 材质节点的入口。其中有 27 个名字属于已注册内置节点： DreamShader 自己实现了它们，每个对应一个 UMaterialExpression 类和一组固定参数。另有三个名字 —— UE.StaticSwitchParameter、UE.CollectionParam 和 UE.SceneTexture —— 在这张表之前被特殊处理。

命名空间里其余的名字都会落到通用反射路径 UE.Expression， 在那里 UE.<Name> 的含义就是「创建 UMaterialExpression<Name>」。所以本页没有列出的名字并不是错误， 只是走了另一条规则不同的代码路径。

命名空间前缀和内置节点名都不区分大小写：ue.texcoord() 就是 UE.TexCoord()。参数名会先去掉首尾空白再 按不区分大小写比较，但除此之外必须精确匹配 —— Un_Mirror_U 不是 UnMirrorU。

看目录之前先读这两条

语法概要

// 表达式形式，写在 Graph 中
UE.<Name> ( [ <argument> [ , <argument> ] … ] )

<argument> := <arg-name> = <expression>

// 声明形式，写在 Properties 中
UE.<Name> [ ( <key> = <value> [ , <key> = <value> ] … ) ] <property-name> ;

完整名单

全部 27 个已注册内置节点，按注册顺序排列。类名省略了 UMaterialExpression 前缀。

上表中每个宽度都是权威的，因此任何已注册内置节点都可以在分量数不一致的二元运算中充当加宽的一方。 参见运算符与转换。这些内置节点都不会产生纹理对象、MaterialAttributes 值或 Substrate 值。

别名

名单里有四个名字是已有条目的第二种写法，两种写法创建的节点类完全相同。

带参数的内置节点

UE.TexCoord

float2 uv    = UE.TexCoord(Index = 0);
float2 tiled = UE.TexCoord(Index = 0, UTiling = 2.0, VTiling = 2.0);

这里不接受 CoordinateIndex 这个写法 —— 只有声明形式接受它。表达式形式下 负的 Index 会被接受且没有任何诊断。

UE.Time

float t      = UE.Time();
float looped = UE.Time(Period = 2.0, IgnorePause = true);

写了 Period 同时也会打开节点的周期覆盖开关。Graph 中不做范围检查：负的 Period 会被原样写入。 声明形式则会拒绝它。

UE.Panner

float2 panned = UE.Panner(Coordinate = UE.TexCoord(Index = 0),
                          Time       = UE.Time(),
                          SpeedX     = 0.1,
                          SpeedY     = 0.0);

表达式形式不接受 ConstCoordinate。声明形式接受它，通用路径也可以用 UE.Expression(Class = "Panner", OutputType = "float2", ConstCoordinate = 1) 触达。

UE.TransformVector

在不同坐标系之间变换方向。只做旋转、不做平移，这也正是它不适合用于点的原因。

vec3 worldNormal = UE.TransformVector(LocalNormal, Source = "Tangent", Destination = "World");

两个坐标系参数接受同样的九种写法，对应六个引擎取值。所有写法在 UE 5.3 – 5.8 上都可用，也不存在某一侧 接受而另一侧拒绝的写法。

坐标系名会先去掉首尾空白再按不区分大小写比较，因此 "world"、"World" 和 " WORLD " 是同一个 token。 空格、下划线和连字符不会被去掉："absolute world" 和 "absolute_world" 解析不了 —— 要写 "AbsoluteWorld"。带引号的字符串和裸标识符等价，Source = World 与 Source = "World" 相同。

任何一侧解析失败都只会产生这一条消息：UE.TransformVector Source/Destination is invalid. —— 它不会告诉你是哪一侧。

UE.TransformPosition

在不同坐标系之间变换点，会应用平移。

vec3 viewP = UE.TransformPosition(UE.WorldPosition(),
                                  Source      = "World",
                                  Destination = "TranslatedWorld");

注意默认的 Source 与 UE.TransformVector 不同：这里是 "Local"，那里是 "Tangent"。

Source 和 Destination 共用同一个解析器，因此两个参数接受的集合完全一致。十三种写法对应八个引擎取值。

不带参数的内置节点

27 个里有 22 个完全不接受参数。它们创建节点时所有输入 pin 都保持未连接。

位置与几何

要用 WorldPosition 的其他 shader-offset 模式，走通用路径： UE.Expression(Class = "WorldPosition", OutputType = "float3", WorldPositionShaderOffset = …)。

向量与法线

屏幕与场景

要给场景深度读取接一个 UV，走通用路径： UE.Expression(Class = "SceneDepth", OutputType = "float1", Input = <uv>)。

逐顶点与逐实例数据

特殊处理的内置节点

这三个名字在已注册表之前被解析，不遵循那张表的规则。

UE.StaticSwitchParameter

创建一个会出现在材质实例编辑器里的静态开关，美术不用改源码就能切换分支。

vec3 color = UE.StaticSwitchParameter(Name        = "UseDetail",
                                      True        = detailColor,
                                      False       = baseColor,
                                      Default     = true,
                                      Group       = "Switches",
                                      Description = "Choose the detail branch");

输出的分量数和 MaterialAttributes 标记都取自 True 分支。两条分支必须一致：都不能是纹理对象或 Substrate 值，不能一边是 MaterialAttributes 一边是数值，分量数也必须相等。

参数会以「仅编辑器」的静态开关值注册到生成的材质上；在材质函数内部则不会注册任何东西。如果同一个 property 名下已经注册过节点，会复用它而不是再建一个。

UE.CollectionParam

从 UMaterialParameterCollection 中读取标量或向量参数。UE.CollectionParameter 是可接受的第二种写法。

float wind = UE.CollectionParam(Collection = Path(Game, "Collections/MPC_Wind"),
                                Parameter  = "WindStrength");

集合会在生成时加载，参数按名字在其中查找。输出宽度取决于查到的类型：

UE.CollectionParam 也是唯一被放在负 X 坐标（-520）上的内置节点；其余已注册内置节点落在 520， 声明形式落在 -800。

Path(…) 的语法和可用根目录见 Path 资产引用。

UE.SceneTexture

纯语法糖，在所有其他 UE. 名字之前解析。

float4 scene = UE.SceneTexture(Id = "PostProcessInput0");

它会把调用改写成

UE.Expression(Class = "SceneTexture", OutputType = "float4", SceneTextureId = <Id>)

然后求值，所以节点是 UMaterialExpressionSceneTexture、输出 float4，之后 通用路径的所有规则都适用 —— 包括节点复用。

调用必须恰好有一个参数，且名字必须是 Id；其他写法都会失败： UE.SceneTexture expects exactly Id="..." (e.g. Id="PostProcessInput0").

Id 文本走反射枚举写入器，它接受带或不带枚举前缀的条目名、完全限定名和显示名，比较时忽略大小写， 并忽略空格、_、-、:、.、/ 这些字符。"PostProcessInput0"、"PPI_PostProcessInput0" 和 "ppi postprocessinput0" 都选中同一个值。

Properties 声明形式

UE.<Name>(…) 也可以出现在Properties section 中类型 token 的位置。 节点在生成时创建一次，并绑定到一个 property 名上，供 Graph 读取。

Properties {
    UE.TexCoord(Index = 0) UV;
    UE.CollectionParam(Collection = Path(Game, "MPC_Weather"), Parameter = "Wind") Wind;
}

Graph {
    Color = vec3(UV.x, UV.y, Wind);
}

最容易踩的是行内默认值。参数要写在括号里：

// 正确
UE.TexCoord(Index = 0) UV;

// 错误：UE builtin property 'UV' does not support inline defaults.
UE.TexCoord UV = 0;

可识别的名字

不在本行范围内的参数会被拒绝： UE.{Name} for property '{Property}' does not support argument '{Argument}'.

ShaderOffsets 词表 —— 转小写并去掉空格后比较：

Origin 词表 —— 转小写并去掉空格后比较：

声明的输出宽度

声明宽度取自下列第一个能解析出结果的来源：

1. 显式的 OutputType 或 ResultType 参数，取自缩减 token 集；
2. 解析器自己的名字表，见下；
3. CollectionParam / CollectionParameter，声明为 1 分量标量；
4. 都不满足则拒绝该声明。

UE.* property 上不允许写 const 限定符： Const property '{Name}' must use a plain scalar, vector, or texture type instead of a parameter node or UE builtin declaration.

一些值得知道的细节

• UE.* 调用可以直接 swizzle —— UE.TexCoord(Index = 0).x 就是普通的后缀链。参见 运算符与转换。
• UE.* 名字在用户声明之前解析，所以叫 TexCoord 的 property 或函数不会遮蔽 UE.TexCoord。不过也 没有任何机制阻止你声明一个叫 TexCoord 的 property，并以裸标识符形式读取它。参见 调用。
• 已注册内置节点从不接受 OutputType、Class、Output、OutputName 或 OutputIndex。它们只在 通用路径上被读取；在已注册内置节点上会像任何未知名字一样被静默丢弃。
• 在 GraphFunction 内部，UE.* 调用会被提升出 HLSL 体，变成生成的 Custom 节点上的输入 pin。

诊断

{Function} 是作者书写的内置节点名，保留原始大小写 —— 只有一个例外： Failed to create UE.{Function}. 打印的是注册时的写法。

声明形式在生成阶段产生的每条消息还会再包一层： UE.{Function} for property '{Property}': {Message}。完整清单见错误速查。

示例

Shader(Name="Docs/M_UEBuiltins")
{
    Properties {
        vec3 Tint = vec3(1.0, 0.6, 0.2);
        UE.TexCoord(Index = 0) UV0;
    }

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

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

    Graph {
        float2 uv   = UE.Panner(Coordinate = UV0, Time = UE.Time(), SpeedX = 0.1, SpeedY = 0.0);
        float3 wp   = UE.TranslatedWorldPosition();
        float3 nrm  = UE.TransformVector(UE.VertexNormalWS(), Source = "World", Destination = "Tangent");
        float  fade = UE.PerInstanceFadeAmount();
        float4 vcol = UE.VertexColor();

        Color = (vec3(uv.x, uv.y, wp.z) + nrm) * Tint * vcol.rgb * fade;
    }
}

生成的节点：

TextureCoordinate  (Index 0)                  <- UV0        (Properties, X = -800)
Panner             (Coordinate, Time, SpeedX) <- uv         (X = 520)
Time                                          <- Panner.Time
WorldPosition      (camera-relative)          <- wp
VertexNormalWS                                -> Transform
Transform          (World -> Tangent)         <- nrm
PerInstanceFadeAmount                         <- fade
VertexColor                                   <- vcol

接下来