材质内容浏览器

DreamShader » 工具 » 材质内容浏览器

一个可停靠的编辑器标签页，涵盖项目中的每个 DreamShader 源文件和每个材质：每个源文件编译成什么、该资产是否为最新、是否有人手动编辑过它、它导入了什么以及什么继承了它——以及由每个答案所引出的操作。

打开它

该标签页仅在编辑器桥接启动时注册。使用 -NoDreamShaderEditorBridge 启动编辑器会移除所有途径——请参阅编辑器集成。

布局

┌────────────────────────────────────────────────────────────────────────────┐
│ [⟳ Refresh] [▶ Compile ▾] [+ New ▾] │ search…          │ [View ▾] [VSCode] [⚙] │
├──────────────┬──────────────────────────────────┬──────────────────────────┤
│ NAVIGATION   │ LIST                              │ INSPECTOR                │
│ ▾ Sources    │ Sources mode: columns or tiles    │ live preview · mesh      │
│   ▾ Project  │ Assets mode: the asset picker     │ name · status · storage  │
│     Materials│                                   │ actions                  │
│   ▸ PluginA  │                                   │ Root / Source / Asset /  │
│ ▾ Content    │                                   │   Domain / Blend / …     │
│   ▸ /Game    │                                   │ Diagnostics (N)          │
│ ──────────── │                                   │ Provenance               │
│ Quick filters│                                   │ Imports / Used by        │
│ ☐ Errors …   │                                   │ Inheritance · Children   │
├──────────────┴──────────────────────────────────┴──────────────────────────┤
│ 14 sources · 9 ok · 3 stale · 1 errors · 1 edited by hand · 5 Ephemeral │ bridge: idle │
└────────────────────────────────────────────────────────────────────────────┘

水平分隔条中的三个窗格，上方是工具栏，下方是状态栏。窗格比例、模式、导航范围、过滤器、排序、列表/平铺选择、预览网格和上次选择均按用户和按项目保存（UDreamShaderBrowserUserSettings、EditorPerProjectUserSettings），并在下次打开标签页时恢复。

工具栏

从此标签页启动的每次编译都通过编辑器桥接进行，因此其结果会像保存时编译一样到达诊断存储、diagnostics.json 和 VSCode 扩展，并且成功会清除该文件之前的错误。

导航

一棵包含两个组的树。选择节点会限定列表范围并切换模式。

快速过滤器

树下的复选框。四个状态过滤器之间是或关系：勾选错误和过期会显示二者之一存在的条目。

状态栏计数与这些过滤器相同：单击某个计数会单独启用它，再次单击会将其关闭，而单击 ok 计数会清除全部四个。

源文件模式

每个通过范围、过滤器和搜索的已扫描源文件，以带可排序列的列表形式或——视图 ▸ 平铺——缩略图网格形式显示。支持多选；右键单击打开上下文菜单；双击打开材质（若有），否则打开源文件。

列出的文件

.dss、.dsi、.dsp、.dsm、.dsf 和 .dsh 在每个源文件根目录下递归找到，排除每个根目录的 Packages 文件夹——此外，在 源文件 标题和 不由 DreamShader 管理 节点下，还有未管理的材质。选择在刷新后仍然保留：条目按路径重新选择。

管线

（自 2.1.0 起） .dsp 像材质源文件一样列出——其状态是其管线的状态，由相同的规则解析和判断——但其资产是 UDreamPassPipeline，这是此标签页中唯一一种不是材质的产品，而各行也如此说明：

管线仅通过其 .dsp 列出：没有被任何已扫描源构建的 UDreamPassPipeline 不是 非托管行，其导出缓冲区的渲染目标也不是。

非托管材质

内容根目录下（/Game 以及每个附带 DreamShader 源的插件的挂载点）的每个 UMaterial 和 UMaterialInstanceConstant，如果没有任何已扫描源解析到它，那么该标签页会覆盖整个项目，而不仅仅是 DreamShader 的角落。它们通过资产注册表找到，并且绝不会为了列出而加载——一个有一千个手工制作材质的项目只耗费一次注册表查询，而不是一千次加载；只有被选中时才会加载某一行，此时检查器会读取其真实来源（一个孤立的生成资产会显示为 Unstamped 或 Generated，手工制作的则保持 Foreign）并将其合并回该行。

状态栏计数 未管理 会跳转到该节点，而不是切换过滤器。精简后端的隐藏 MB_DreamThinBase_* 基类 从不会被列出。对其中的某一个执行 Export .dss（对于普通材质实例而言是 .dsi） 就是它进入 DreamShader 管理的方式。

状态值

对于除 .dsf / .dsh 之外的每个源的状态计算 （自 2.0.0 起）：

构建键涵盖编译所标记的内容——预处理后的文件及其包含的每个头文件、它们所读取的定义、一个 .dsi 的父级——因此当前资产会显示为 最新，而重新构建总会使过期的资产变为最新。1.x 从文本中解析 Name= / Root= 并剥离导入，并在内联它们的情况下对源进行哈希；该方案对 .dss 无法给出任何答案，已被移除。

然后叠加桥接的诊断信息，从其存储中实时读取：该文件的任何 error 记录都会使其变为 compile error，并以第一条错误记录作为详情 （L{line}:{col} {message}）。所有记录都保留在条目上供检查器使用。

[!NOTE] 步骤 2 不会加载，因此磁盘上存在但本会话尚未加载的材质会 报告为 未编译，直到有东西加载它。

资产模式

引擎的资产选择器基于 UMaterial 和 UMaterialInstanceConstant（递归地，其中 包括 UDreamShaderMaterialInstance），范围限定为导航树的内容路径。有意保留为引擎控件：缩略图、拖拽到视口、列视图以及选择器自身的 设置都随之而来。

共享过滤器在这里同样适用，并且不加载任何内容即可得到答案：已扫描源的资产由其条目判定，而 Ephemeral 则从注册表的包标志中读取。DreamShader 从未生成过的 手工制作材质，除 Ephemeral 外不通过任何状态过滤器。

双击打开该资产。右键单击会给出相同的上下文菜单。

检查器

两种模式共用一个面板。它显示选择中存在的任何一半——源一半 （一个已扫描文件）和资产一半（项目中的一个材质）——通过资产的 DreamShader.SourceFile 标记连接起来。因此，在资产模式中选中的材质会显示其源的 编译状态和诊断信息；在源模式中选中的源会显示其资产的来源和 继承关系。

对于 .dsp （自 2.1.0 起），检查器没有预览，也没有创建实例。打开会在其详细信息面板中打开管线，信息行以管线——{N} pass(es), {N} buffer(s), {N} parameter(s); order {N}——开头，取代基础、域和混合模式。来源部分提供与材质相同的三个选项：在详细信息面板中编辑的管线会被逐值纳入其 .dsp 中。

来源行和部分所说明的摘要状态：

状态栏的手动编辑计数仅指 Diverged：被调整的实例没有问题，也不需要查找。

状态栏

{N} sources · 正常（最新，或已编译，Ephemeral）、陈旧、错误、手动编辑和 Ephemeral 的计数，每个都是一键筛选器 · 未管理，可跳转到该节点 · 桥接的状态：bridge: idle、编译时的 bridge: {action}、同一项目上的第二个编辑器持有写锁时的 bridge: idle (another editor owns writes)，或 bridge: off。工具提示是桥接的最后一次结果。

上下文菜单

在任一列表中右键单击。命令作用于所选内容；大多数取第一个选中的条目。

跟随编辑器

此处不做任何轮询。选项卡监听：

反应会合并为每个时钟周期一次刷新，因此一个头文件重新编译其十二个依赖项时，选项卡只重绘一次。刷新仍适用于这些情况之外的任何场景——例如在会话中途挂载的插件。

新建源文件

新建 ▾ 会从插件模板在 Resources/Templates 下写入文件，桥接的监视器会像对待任何保存一样列出并编译它。菜单有三个部分：

管线会指定其通道所绘制的材质，因此每个管线模板也会写入这些材质，紧挨着 .dsp，并且 .dsp 一经落盘即构建；着色器则直接写在 .dsp 本身中。<Base> 是去掉其 CP_ 前缀后的名称（CP_Outline 得到 Outline）；没有前缀的名称则按原样使用。

伴生文件会先写入，因此监视器在编译管线时能找到 .dsp 所指定的材质；所有文件要么全部写入，要么全部不写——一旦某次写入失败，会收回在此之前写入的文件。管线只有在被某物激活时才会运行：Project Settings ▸ DreamPlugin ▸ DreamShader Custom Pass 中的全局管线、Dream Pass Volume、某个组件，或 API——参见 Custom Pass 运行时。

对话框：

对于管线，对话框还会说明该模板除 .dsp 之外会写入哪些文件。

无论哪种情况，资产都会落在其邻居的旁边——在 DShader/Materials/ 中创建的文件会编译到 /Game/Materials/…。1.x 块自己会说明这一点：其 Name= 是文件夹相对于其根目录的路径 加上名称。.dss 什么也不说明：名称来自其 export，而文件夹就是文件所在的位置。 .dss 是一种产品——一个材质，或任意数量的导出函数，每个函数都是自己的 资产——旁边还有未导出的辅助项；这两个条目启动这两种类型。

这些模板由自动化测试 DreamShader.Browser.NewSource.TemplatesRenderAndCompile 编译，因此不会腐坏。管线模板 不在其所覆盖的模板之列。

创建材质实例

可从检查器、上下文菜单以及内容浏览器条目 Create DreamShader instance 打开。

创建步骤及其错误：

成功时提示为 Created {Name}——资产名称来自 Name 框，而非对象 路径——并且窗口关闭。失败时错误会以提示显示，并且 窗口保持打开，以便更正 名称或文件夹。

对仅存在于内存中的父材质进行实例化会先实体化父材质，因此子实例永远不会引用 瞬态对象。从未编译过的源会先被编译；如果它仍未产生 材质，提示为 Compile {File} first.

实体化

将仅存在于内存中的材质及其包装的隐藏基础写入磁盘。

单击按钮时会按对象路径重新解析材质，而不是保留自面板构建时的引用，因此期间发生的删除或垃圾回收不会使其崩溃。

键盘

示例

一个源树以及 Sources 模式为其显示的内容：

<Project>/DShader/
    Materials/M_Emissive.dsm        ● up to date          /Game/Materials
    Materials/M_Toon.dss            ● up to date          /Game/Materials
    Materials/M_Broken.dsm          ▲ compile error       L12:9 'Tin' is not declared in this scope.
    Materials/M_New.dsm             ○ not compiled        No generated asset at /Game/Materials/M_New.M_New
    Lib/Noise.dsf                   ◆ function · used by 2 material(s)
    Lib/Common.dsh                  ◆ function · used by 3 material(s)
    Packages/Sample/Demo.dsm        (not listed — under DShader/Packages)

另请参阅

• 编辑器集成 — 打开此选项卡的菜单条目，以及管线打开所在的细节面板
• Custom Pass 管线 — .dsp — 管线模板使用的编写语言
• 预览 — 检查器预览背后的渲染器
• 分歧 — Revert、Adopt、Detach
• 反编译器 — 导出 .dss / .dsi
• 瞬态材质 — 仅内存生成、隐藏基础、实体化
• 缓存 — up to date 和 stale 背后的源哈希
• 资产路径 — Name= 和 Root= 如何解析为对象路径
• 项目设置 — Material Instance Subfolder 和 Ephemeral 可见性开关
• 桥接 — 此选项卡读取的诊断存储及其跟随的事件
• 材质实例 API — C++ 中的 UDreamShaderMaterialInstance
• 诊断索引 — 按阶段列出的每条消息