资产路径

每个会生成资产的块都带同样两个头部属性，由同一个解析器把它们变成一个目标位置。

语法概览

Shader        (Name = "<name-path>" [, Root = "<root>"]) { … }
ShaderFunction(Name = "<name-path>" [, Root = "<root>"]) { … }

<name-path> := [<folder> /] … <leaf>
<root>      := "" | Game | Plugin.<PluginName> | Plugins.<PluginName>
             | Plugin / <PluginName> | Plugins / <PluginName>
             | / <MountRoot> [/ <folder>] …
             | <folder> [/ <folder>] …

Name 是 必填 的。缺少时报 Shader(Name="...") is required.，函数类块则报 {Kind}(Name="...") is required.。Root 可选，默认是空字符串。属性名按不区分大小写匹配，所以 name= 和 ROOT= 都能识别。

解析顺序

1. Root 变成根 package 路径。 去空白；\ 换成 /；记住原串是否以 / 开头；去掉首尾的 /；按 / 切分。任何一步得到空结果都退回 /Game。
2. Name 变成若干文件夹加一个 leaf。 去空白；\ 换成 /；去掉所有首尾 /；按 / 切分。最后一段 是资产名，前面每一段都是追加到根后面的文件夹。
3. 每一段都经过 ObjectTools::SanitizeObjectName。空段被静默跳过。
4. PackageName = <root>/<folders…>/<Leaf>，ObjectPath = <PackageName>.<Leaf>。
5. PackageName 由 FPackageName::IsValidObjectPath 校验。

Root= 的分派

分派看的是 Root 的 第一段，比较时不区分大小写。

省略或为空

Game

比较不区分大小写，但输出的根永远是字面量 /Game。

Plugin.<Name> 与 Plugins.<Name>

点号形式用一段就指定了插件，后面的全部是文件夹。

Plugin/<Name> 与 Plugins/<Name>

斜杠形式要花两段来指定插件。

显式挂载根

以 / 开头、又不属于上面任何形式的 Root，会被原样当作一个挂载点。

第一段必须原样通过 SanitizeObjectName，否则报 DreamShader Root '{Root}' has an invalid package root.。挂载点本身在这里 不 检查是否存在 —— 未挂载的根会在后面的 IsValidObjectPath 闸门处失败。

裸相对路径

其余不以 / 开头的 Root 都变成 /Game 下的文件夹。

这一分支和上一分支的差别只在开头那个斜杠：Root="Foo/Bar" 是 /Game/Foo/Bar，Root="/Foo/Bar" 是 /Foo/Bar。

插件根的要求

两种插件写法走同一个校验器。下面每一道闸门都必须按顺序通过，各有各的消息。

第 7 道闸门在 UE 5.3 – 5.5 上不存在；在那些引擎上，未挂载的插件会在稍后的 object 路径校验中被抓到。

根 package 路径就是插件自己的挂载资产路径 —— 规范化成正斜杠、去掉结尾斜杠、强制加上开头斜杠。如果结果退化成空或者 /，则使用 /<PluginName>。

各资产类型

四种块的路径解析完全一致。不同的是创建的类，以及函数类块被打上的 material function usage。

当解析出来的路径上已经存在资产时，它的类必须匹配：

类匹配不等于归属检查。除 ThinCustom 路径之外，DreamShader 还会拒绝覆盖不是自己生成的资产 —— 见 重新生成。

磁盘映射

文件是 <directory>/<Leaf>.uasset，而且 只在持久化模式下 才会写出。日常编辑器工作中什么都不会落盘 —— 见 内存材质。

说明

• Name 可以带文件夹，Root 只是前缀。 Root="Game" 下的 Name="A/B/C" 得到 /Game/A/B/C，资产名是 C。
• 重复的属性名会静默覆盖前一个。 Shader(Name="A", Name="B") 解析成 B，没有任何诊断。
• 每一段都独立做净化，所以 Name="My Mat" 会得到叫 My_Mat 的 leaf，同样没有诊断。
• 空段会被丢弃：Name="A//B" 就是 A/B，Root="Game//Sub" 就是 /Game/Sub。
• Content Browser 的状态列和 Materialize 操作用的是同一个解析器，所以在这里失败的路径，在 编辑器工具 里也会显示为无法解析。
• 不要和 Path(Root, "…") 混淆，那是 另一套 路径语法 —— 它用来 引用 已有资产，而不是指定生成目标。见 Path 资产引用。

诊断

完整示例

Shader(Name="Mat/Test", Root="Plugin.MoonToon")
{
    Properties { vec3 Tint = vec3(1.0, 0.2, 0.2); }
    Settings   { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }
    Graph      { Color = Tint; }
}

解析出的目标：

Root      "Plugin.MoonToon"  ->  /MoonToon                       (plugin mount point)
Name      "Mat/Test"         ->  folders "Mat", leaf "Test"
package                          /MoonToon/Mat/Test
object path                      /MoonToon/Mat/Test.Test
on disk                          <Project>/Plugins/MoonToon/Content/Mat/Test.uasset

继续阅读