编辑器集成

DreamShader » 工具 » 编辑器集成

DreamShader 挂接到 Unreal 编辑器 UI 上的每一处：Tools 菜单、关卡编辑器工具栏、Content Browser 资产右键菜单、材质编辑器工具栏、Window 菜单、Custom Pass 管线的详情面板，以及它自行弹出的通知。

菜单注册是幂等的——第二次注册什么都不加——并且会在编辑器关闭期间跳过。

Tools 菜单

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

[!NOTE] 前五项和第六项由两个不同的启动回调注册进同一个 DreamShader section。它们在 section 内部的相对顺序取决于注册顺序，且不保证在两次编辑器运行之间保持一致。

关卡编辑器工具栏

一个 Dream 组合按钮，由 Dream 系列插件（DreamShader、DreamFX、DreamGUI）共用：每个插件在它还不存在时加上它，所以不管哪个先加载，它都只出现一次，并归属于所有者 DreamToolsShared，没有插件会注销它。

DreamShader 在里面的一节，标题为 DreamShader：

Window 菜单

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

Content Browser 右键菜单

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

[!WARNING] 每一个 DreamShader 右键菜单项都要求恰好选中一个资产。 选中两个或更多资产时该 section 是空的，而且没有任何提示说明原因。请右键单个资产。

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

（自 2.1.0 起）UDreamPassPipeline 在这里没有 DreamShader 条目。它的 Open Source、Revert to Source 和 Adopt Into Source 在它的详情面板上，它的源文件在 Material Content Browser 里，反编译用 dsc decompile。

材质子菜单

DreamShader.MaterialActions —— 标签为 DreamShader，工具提示为 "DreamShader actions for this Material."，图标为 Icons.Settings。仅当唯一选中的资产为 UMaterial 时构建。

第 1 节为 DreamShader.ProvenanceActions，标题为 Generated Asset —— 即下文的 生成资产一节；对于并非由 DreamShader 生成的资产，该节为空。

第 2 节为 DreamShader.DecompileActions，标题为 Decompiler：

材质函数子菜单

DreamShader.MaterialFunctionActions —— 标签为 DreamShader，工具提示为 "DreamShader actions for this Material Function."，图标为 Icons.Settings。同一个子菜单也服务于材质层和层混合。

第 1 节为 DreamShader.ProvenanceActions，标题为 Generated Asset —— 即下文的 生成资产一节。

第 2 节为 DreamShader.DecompileActions，标题为 Decompiler：

第 3 节为 DreamShader.VirtualFunctionActions，标题为 VirtualFunction （自 1.2.1 起）。其 内容取决于是否已有 VirtualFunction 声明引用此资产 —— 完整表格见 VirtualFunction 工具。

两个 extern Prototype 条目 （自 2.0.0 起） 是 VirtualFunction 块的 .dss 对应物：函数的 extern 原型及其 /// @asset 行，复制到剪贴板，或写入 一个新的 .dsh，以供 .dss 源文件 #include。

材质实例子菜单

一个 UDreamShaderMaterialInstance —— 即 ThinCustom Shader 的产物 —— 会得到子菜单 DreamShader.MaterialInstanceActions，标签为 DreamShader，工具提示为 "DreamShader actions for this generated material."，仅含生成资产一节。

任何其他 UMaterialInstanceConstant —— 即 .dsi 构建的，或 手工制作的实例 —— 会得到子菜单 DreamShader.MaterialInstanceConstantActions，标签为 DreamShader，工具提示为 "DreamShader actions for this material instance."，图标为 Icons.Settings：

生成资产一节

上述每个子菜单的第 DreamShader.ProvenanceActions 节。除非该资产带有 DreamShader 的源元数据，否则该节为空，因此手工编写的资产不会显示其中任何内容。

材质编辑器工具栏

DreamShader.MaterialEditorToolbarActions，是 AssetEditor.MaterialEditor.ToolBar 第 DreamShader 节中的一个动态条目 （自 1.2.1 起）。

Pass 管线详情面板

(自 2.1.0 起) UDreamPassPipeline —— .dsp 编译成的资产 —— 的详情面板，在管线自身属性之上有三个分类，按一帧运行它的方式读取该资产。属性保留，也保持可编辑：这个面板就是调校管线的地方，而 Adopt Into Source 会把调校结果写回它的 .dsp。

管线概览

帧顺序中的 Pass

管线使用的每个注入点一个分组，按一帧到达它们的顺序排列，标题为 <injection point> (<number of passes>)，其中的 pass 按声明顺序 —— 即它们运行的顺序。同一注入点上另一管线的 pass 按 Order 在这些之前或之后运行。每个 pass：

Buffer

每个声明的 buffer 一行，其 tooltip 是该 buffer 的 /// @desc：格式及键，按 .dsp 的写法（R8 Resolution = Render Scale = 0.5 Clear = 0 Export = true）。导出的 buffer 会附加一个链接 exported to <render target>，在 Content Browser 中显示该渲染目标 —— 或者，在首次编译之前，已导出，但其渲染目标尚不存在：编译源文件。

编辑

这些行实时读取资产，所以在下方属性中编辑的值会立刻显示在上方。添加、删除或重命名 pass 或 buffer，把 pass 移到另一个注入点，以及更改槽位、着色器路径或导出，都会重建面板。编辑会在下一帧生效，并使管线与其 .dsp 构建出的内容分歧：在它被还原或采纳之前，对已更改的 .dsp 的重建会拒绝覆盖它。

通知

本页上唯一由 DreamShader 自行发起、而非注册后等待点击的表面。在没有 Slate 应用或无人阅读通知的地方，通知会被抑制 —— commandlet、cook、专用服务器，以及任何带 -unattended 的运行。

两个分歧通知不会超时，因为它们要提问；本页其他每个通知都是四秒的 toast，报告已经完成的事。关闭编辑器会撤销任何仍在等待答复的分歧通知。

命令语义

本页每条引用的消息中的运行时替换都以 {Placeholder} 表示。

Recompile DSM

先询问 —— 一个 Yes/No 对话框，"Recompile every DreamShader .dsm and .dsf source file? This rebuilds all generated materials and can take a while on a large tree."。选择 Yes 时，重建材质依赖图，然后把每个源根的 .dsm、.dsf、.dss、.dsi 和 .dsp 以当前时间强制戳入待处理队列。根目录 Packages 文件夹下的 .dsm 会被排除；.dsh 头文件从不入队，因为它们不构建任何东西。这些文件随后由去抖 ticker 编译，正如它们被保存过一样。

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

Clean Generated Shaders

删除生成的 .ush include 并入队一次完整扫描。

Make Ephemeral

查找并删除已物化的 ThinCustom 产物 —— 即在磁盘上有 package 的那些 —— 因为已保存的产物会遮蔽由同一源生成的自定义（Ephemeral）产物。

因为筛选基于来源，手工编写的材质永远不会被触及，而源文件已被删除或重命名的孤儿产物仍然符合条件。

日志：DreamShader made {Deleted} of {Total} Materialized product(s) Ephemeral.

显示自定义（Ephemeral）材质

翻转 bShowEphemeralMaterials 并将其直接写入工程的 DefaultEngine.ini。然后它遍历每个 package 新创建的活跃 UDreamShaderMaterialInstance，广播资产创建或资产移除，因此图块立即出现或消失，而不是等到下一次重新枚举。

[!WARNING] 当自定义（Ephemeral）材质显示时，它们也会出现在保存选择器中，而显式执行 Save 会物化其中一个。保存的副本随后会遮蔽自定义产物。用 Make Ephemeral 恢复。

材质内容浏览器中的 View ▾ ▸ Show Ephemeral materials 在同一全局设置上运行同一命令，包括 toast。

打开 Dream Shader 工作区（VSCode）

按此顺序运行：重新导出 material-expressions.json、settings.json、substrate-builtins.json、preprocessor-defines.json 和内建节点目录（dreamshader-builtin-catalog.json）；重写 DShader/DreamShader.code-workspace；然后通过三步回退链启动它 —— VSCode、操作系统默认编辑器、记事本。发现顺序和确切文件内容见工作区。

禁用集成

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

该开关按裸命令行参数解析，因此 -NoDreamShaderEditorBridge 是唯一被接受的拼写。存在时，StartupModule 在创建任何内容之前返回。

commandlet 运行通过不同途径达到相同状态：每当 IsRunningCommandlet() 为 true 时模块提前返回，仅安装 cook 时资产物化钩子，且仅当 -run= 包含 Cook 且 -cookworker 不存在时。

示例

在集成关闭的情况下启动编辑器，然后以无头方式做同样的工作：

# No menus, no watcher, no bridge.
& "$Engine\Binaries\Win64\UnrealEditor.exe" "I:\Project\Project.uproject" -NoDreamShaderEditorBridge

# The commandlet is unaffected by the switch.
& "$Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "I:\Project\Project.uproject" `
    -run=DreamShader compile -All -Force -unattended -nopause -nosplash -stdout -log

说明

• VirtualFunction 条目标签中有四个是 CamelCase 且没有空格 —— OpenVirtualFunction、CopyVirtualFunction、CreateVirtualFunction、CopyVirtualFunctionCall —— 而第五个是 Copy Virtual Function Reference。这种不一致存在于已发布的标签中。
• 在两套 VirtualFunction 条目之间做决定会从磁盘重新读取并重新词法分析每个工程源文件，且发生在每次右键点击 Material Function 资产时。在有很多源文件的工程上，菜单打开会明显更慢。见 VirtualFunction 工具。
• Show Ephemeral Materials 开关的勾选状态实时从设置对象读取，因此在项目设置中更改该值会更新菜单勾选标记。
• 在项目设置中更改 Default Compiler Backend、三个枚举映射表之一或 Preprocessor Defines 会重新生成每个源文件 —— 不是强制的：它们中每一个都是构建键的一部分，所以恰好是它影响的源文件无法通过跳过检查 —— 并在已物化的 ThinCustom 产物会遮蔽结果时引发失败状态 toast：{Count} previously generated asset(s) are still saved on disk and shadow the Ephemeral materials. Run Tools > DreamShader > Make Ephemeral to remove them. 没有其他设置属性会触发反应。

材质编辑器节点上下文菜单

（自 2.0.0 起） 在材质编辑器图表中右键点击 DreamShader 生成的节点会在节点自身上下文菜单的 DreamShader 区段中添加一个 DreamShader 子菜单。

[!NOTE] 没有记录的源位置的节点得到完全没有菜单 —— 不是禁用的菜单。工程中每个手工编写材质的每个节点都处于该状态，给它们全都显示一个变灰的条目只会是噪音。最后一次由 1.x 生成器构建的、早于 2.0.0 的资产也是如此，它没有写入 span 表；现在每个源（包括 .dsm 和 .dsf）都由 2.0 管线构建，所以强制重建（compile -Force）会为其节点提供条目。

失败时是一个四秒的失败 toast 加上一条带 DSH9058 的 LogDreamShader 错误 —— 要么源文件已不存在，要么没有启动器可以启动。

reveal-node — 反方向

(自 2.0.0 起) bridge 请求中方向相反的那一个：从一行源码到材质编辑器中的 节点。它就是 VSCode 扩展的 Reveal in Material Editor 命令所发送的内容。

同步处理：它会找到带有该源文件标记的资产，挑选跨度落在该行上的表达式，为拥有它们的资产打开材质编辑器， 并选中第一个。起始于该行的节点优先于仅仅是从该处某个调用内联而来的节点。

响应是普通的 Responses/<requestId>.json 信封，外加四个字段：

失败会以 ok: false 返回，原因写在 diagnostics（stage: "navigate"）中，编码为 DSH9050–DSH9057。其中两个值得了解：DSH9051 表示来自该源文件的资产没有加载到 此编辑器中 —— 请先编译该文件 —— 而 DSH9052 表示资产存在，但构建于 节点导航之前，因此它们不携带跨度表，需要一次 -Force 重建。

另见

• 工具 — 编辑器工具入口
• 材质内容浏览器 — 工具菜单打开的标签页
• 反编译器 — Export .dss、Export .dsi 和两个 Export Legacy 条目产出什么
• VirtualFunction 工具 — 条件性的 VirtualFunction 区块
• 工作区 — 工作区文件、VSCode 发现和启动回退链
• Bridge — 该开关禁用的文件与 WebSocket 接口
• 命令行 — 无头入口点
• 项目设置 — 这些命令所读取或写入的每一项设置
• 临时材质 — 为什么已持久化的资产会遮蔽生成的资产
• 生成的 HLSL — Clean Generated Shaders 会删除什么
• 分歧 — 对于在细节面板中编辑过的管线，使用 Revert 和 Adopt