编辑器工具

DreamShader 加进 Unreal 编辑器的所有东西都在一个 editor-only 模块里。本页是那张地图：什么出现在哪、每条命令实际做了什么， 以及 Material Content Browser 面板怎么用。

打包出来的游戏里这些一个都没有 —— 模块是 editor-only 的，运行时 DreamShader 模块完全不带 UI。菜单注册是幂等的， 第二次注册什么都不加；编辑器正在关闭时则整个跳过。

启动了什么，按什么顺序

bridge 自己的启动流程随后会重置 bridge.db、导出三份 manifest、执行 VirtualFunction 同步、排入一次全量扫描、在端口 17864 上打开预览 WebSocket 服务、注册源目录 watcher， 并安装菜单。

Tools 菜单

Tools ▸ DreamShader，扩展 LevelEditor.MainMenu.Tools，section DreamShader。

关卡编辑器工具栏

扩展 LevelEditor.LevelEditorToolBar.AssetsToolBar，section DreamShader。两个按钮，都是 Tools 菜单项的复制。

Window 菜单

Material Content Browser 注册的是一个 nomad tab，因此它同时出现在 Window ▸ Tools 下。

Content Browser 右键菜单

所有条目都加进按类划分的资产右键菜单里那个标准的 GetAssetActions section。

Unreal 里的菜单名是按精确类名索引的，所以实例那一项注册了两遍 —— 一遍给标准类，一遍给 DreamShader 子类。

Material 子菜单

标签 DreamShader，tooltip "DreamShader actions for this Material."，图标 Icons.Settings。 只有当唯一选中的资产是 UMaterial 时才会构建。一个 section，Decompiler：

Material Function 子菜单

标签 DreamShader，tooltip "DreamShader actions for this Material Function."，图标 Icons.Settings。两个 section。

Decompiler：

VirtualFunction since 1.2.1 —— 内容取决于是否已经有一个 VirtualFunction 声明指向这个资产。 见 VirtualFunction 工具。

材质编辑器工具栏

AssetEditor.MaterialEditor.ToolBar 的 DreamShader section 中的一个动态条目 since 1.2.1。

各命令的行为

引用消息里的运行期替换写作 {Placeholder}。

Recompile DSM

重建材质依赖图，然后把每个项目 .dsm 和 .dsf 以当前时间戳打进待处理队列。DShader/Packages 下的 .dsm 被排除， 那里的 .dsf 不会 —— 见 Package。排队的文件随后由防抖 ticker 编译， 和你手动保存它们完全一样。

日志：DreamShader queued a full .dsm/.dsf recompile scan.

Clean Generated Shaders

删除生成的 .ush include，并排入一次全量扫描。

Clean Persisted Generated Assets

找出并删除磁盘上存在的 DreamShader 生成资产 —— 因为已保存的资产会遮蔽同一源文件生成的纯内存材质。

因为过滤依据是来源元数据，手写材质永远不会被碰 —— 而源文件已被删除或改名的孤儿资产仍然会被命中。

Show In-Memory Materials

翻转 bShowInMemoryMaterialsInContentBrowser 并直接写进项目的 DefaultEngine.ini。随后它会遍历每一个 package 仍是 newly-created 的活 UDreamShaderMaterialInstance 并广播资产创建或移除，所以图块立刻出现或消失， 而不是等到下一次重新枚举。

Material Content Browser 的 Project 页上有一个复选框，驱动的是同一个全局设置。 复选框在值没变时会提前返回、不弹 toast；菜单项则总会弹。菜单项的勾选状态实时读自设置对象， 所以在 Project Settings 里改值会更新那个勾。

Open Dream Shader Workspace (VSCode)

重新导出 material-expressions.json、settings.json 和 substrate-builtins.json，重写 DShader/DreamShader.code-workspace，然后走三级回退链启动它 —— VSCode、系统默认编辑器、Notepad。 探测顺序、文件的确切内容，以及"这个文件会被整体重写"的警告，都在 VSCode 与 Rider。

Material Content Browser

一个可停靠面板，两个页面：一个用来浏览项目材质并创建实例，一个用来看 DreamShader 源文件和它们生成的资产。

怎么打开

这个 tab 只在 editor bridge 启动时才注册，所以 -NoDreamShaderEditorBridge 会同时去掉两个入口。

根控件是两个 radio 风格复选框组成的标题栏加一个 widget switcher。只有被勾选的那次跳变会被处理， 所以重复点击你已经在的那一页什么都不会发生。两页各自保留状态，切换不会刷新任何一页。

Project 页

一个水平分割器：资产选择器占宽度的 0.62，详情面板占 0.38。

资产选择器

顶部控件

详情面板

空态："Select a material to see its inheritance and settings." 缩略图 96×96，取自一个由 0.05 秒定时器刷新的 16 项池。

Dream Shader Gen 页

一个水平分割器：源文件列表占宽度的 0.6，预览面板占 0.4。缩略图取自一个由 0.05 秒定时器刷新的 8 项池。

顶部控件与过滤

这一页列出源目录下递归找到的 .dsm、.dsh 和 .dsf。DShader/Packages 下的一切都被排除 —— 包括 package 里的头文件和函数文件，所以它们从不出现在这里。

状态取值

每一行先画状态字形 —— 它的 tooltip 就是状态细节 —— 然后是文件名，然后是一行弱化的副标签。 .dsf 和 .dsh 的副标签是 function · used by {N} material(s)。

刷新流程

单项状态的计算：

步骤 2 会读文件并在解析前剥掉每一行 import —— import 行不带顶层块，会干扰块检测 —— 然后按资产路径描述的方式解析资产目标。

错误叠加

这一页的错误直接读自 <Project>/Saved/DreamShader/Bridge/diagnostics.json，而不是 bridge 的内存存储 —— 这一页是刻意和 bridge 内部解耦的。

编译操作

两个操作都在内存中生成，并强制重建，忽略 source hash 缓存。

Compile all 跳过头文件，因为它们的依赖方已经在目标集合里了。单个编译失败还会以 Error 级别记 Material Content Browser compile failed: {Message}，并把消息钉在该项上，所以预览面板能显示原因。

预览面板

空态："Select a source file to preview its material."

占位图块对 .dsf / .dsh 显示 "function library"，其他情况显示 "not compiled yet"。 材质通过加载 object path 解析，且只对非函数项这么做。

按钮下方依次是：大字号文件名、状态字形与标签、小字号绝对源路径、函数和头文件的 used by {N} material(s)， 以及 —— 只对 compile error 和 unresolved —— 红色的错误细节。

对从未编译过的项点 Create instance，会先强制编译再重新解析对象。如果它仍然缺失，toast 是 Compile {File} first.

创建材质实例

入口有四个：Project 页的按钮、详情面板、Gen 页的预览面板，以及 Content Browser 的 Create DreamShader instance。

成功时 toast 是 Created {Name} —— Name 框里的资产名，不是 object path —— 窗口关闭。 失败时错误被 toast 出来，而窗口保持打开，方便修正名字或文件夹。

给纯内存的父级创建实例时会先把父级落盘，因此子实例永远不会引用一个 transient 对象。

Materialize

Materialize 把纯内存材质，以及它包着的隐藏 base，一起写到磁盘。

Gen 页的 Materialize 按钮刻意在点击时按 object path 重新解析材质，而不是握着构建面板时捕获的指针， 这样构建到点击之间发生的删除或 GC 就不会导致崩溃。整套内存模型见内存材质。

预览

存在两套不同的渲染器，很容易混淆。

只有 .dsm 能被预览；.dsf 或 .dsh 会被拒绝，消息是 DreamShader preview only supports .dsm material files: '{File}'. 材质总是以 transient 方式编译 —— 预览永远不写资产。

插件侧没有 pitch 钳制 —— 编辑器扩展在发送前会钳到约 ±89°，不这么做的客户端会把相机翻过去。 运动模糊、抗锯齿和动态屏幕百分比都是关的，alpha 被强制成不透明，UI domain 材质总是画在平面上。 这套协议的客户端一侧见 VSCode 与 Rider。

VirtualFunction 工具

为已有 UMaterialFunction 资产生成、打开和刷新 VirtualFunction 块的那组操作。

这个 section 每次右键都会重新构建。构建之前，编辑器会在所有项目源文件里搜索一个解析出的资产与当前选中项一致的 VirtualFunction 声明 —— 你拿到的条目取决于这个答案。

文件名是 <净化后的 MaterialFunction 名>.dsh，冲突时是 <净化后的名字>_<object path 的 crc32>.dsh， CRC 用八位小写十六进制。写在这里的 .dsh 会像其他头文件一样被源目录 watcher 捡到， 所以 import 它的材质会自动重编。生成的声明带 Options.Asset = Path(Game|Engine|Plugins.<Name>, "…") —— 见 Path 资产引用 —— 每个函数输入一条 Inputs，每个输出一条 Outputs。复制出来的调用示例总是以 OutputIndex=0 结尾， 哪怕函数只有一个输出。

启动同步服务

每个编辑器会话一次，在 bridge 启动时，DreamShader 会重读项目里每一段 VirtualFunction 声明， 从活资产重建它，并在文本发生变化时把文件写回。

同步问题会以 stage virtualFunctionSync、code virtual-function-sync、severity error 发布成诊断； 完整清单见错误速查。汇报日志： DreamShader refreshed {Count} VirtualFunction definition(s) in '{File}'. 和 DreamShader scanned {Scanned} VirtualFunction definition(s), refreshed {Refreshed}, reported {Issues} issue(s).

Bridge 产物

编辑器会在 <Project>/Saved/DreamShader/Bridge/ 下写一组文件供外部工具读取。其中三份是目录清单， 在 bridge 启动时导出，并在每次 Open Dream Shader Workspace 时重新导出；其余的随工作产生。

每份 manifest 都带一个 generatedAt ISO-8601 UTC 时间戳。插件唯一会读回来的是 diagnostics.json —— Gen 页读它。这些 schema 和请求协议从消费端的角度记在 VSCode 与 Rider。

关闭整套集成

UnrealEditor.exe "<Project>.uproject" -NoDreamShaderEditorBridge

这个开关按裸命令行参数解析，所以 -NoDreamShaderEditorBridge 是唯一被接受的写法。存在时， StartupModule 在创建任何东西之前就返回。

commandlet 运行会以另一条路径到达同样的状态：模块一旦检测到自己在 commandlet 进程里就提前返回， 只安装 cook 期的落盘钩子，而且仅当 -run= 含 Cook 且没有 -cookworker 时。

说明

• 四个 VirtualFunction 条目标签是没有空格的驼峰 —— OpenVirtualFunction、CopyVirtualFunction、 CreateVirtualFunction、CopyVirtualFunctionCall —— 而第五个写作 Copy Virtual Function Reference。 这个不一致存在于出厂的标签里。
• bridge 弹出的 toast 4 秒后消失；Dream Shader Gen 页弹出的 3.5 秒后消失。
• 编辑器从不主动写出每材质的 .uasset。落盘发生在 cook、通过命令行， 或者显式的 Materialize。
• 在 Project Settings 里改 Default Compiler Backend 会在内存中重新生成每个源文件， 并在已持久化资产会遮蔽结果时弹一条 toast。没有其他设置属性会触发反应。

示例

先关掉集成启动编辑器，再无头地做同样的事：

# 没有菜单，没有 watcher，没有 bridge。
& "$Engine\Binaries\Win64\UnrealEditor.exe" "I:\Project\Project.uproject" -NoDreamShaderEditorBridge

# commandlet 不受这个开关影响。
& "$Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "I:\Project\Project.uproject" `
    -run=DreamShader compile -All -Force -unattended -nopause -nosplash -stdout -log

继续阅读