重新生成

生成出来的资产是源码的产物，不是文档。 当源文件被再次编译时，生成的图会被拆掉，然后从 .dsm 或 .dsf 重建。 资产内部的每一处手改都会被毁掉，只有一个例外。

把这句话记住，本页剩下的内容基本都能顺推出来。

什么能留下来

执行顺序

0. 资产开着编辑器就拒绝，然后指纹对不上就拒绝 —— 两者都在下面任何一步之前，也在任何一步变得 不可逆之前。since 1.8.0
1. 对目标对象调用 Modify()。
2. 清除生成的注释 —— 每一个文本以字面量 DreamShader: 开头的 UMaterialExpressionComment。
3. 清空每一个材质属性输入，从第一个材质属性槽到最后一个。
4. 删除图中的每一个表达式。
5. 把材质重置为默认值 —— 见下面的"重置属性"。材质函数跳过这一步。
6. 应用 Settings。
7. 重建：Properties 节点、Graph 主体或整表面 Custom 节点、Outputs 绑定。
8. 布局 —— 纯内存模式下也会运行 since 1.6.0，见项目设置。
9. 重新编译。

第 4 步现在只有一套策略：整张图作为一个整体被摘下来。逐节点删除原本是为了断开入边，而当图整体离开时这件事 没有意义，还是 O(n^2) 的，所以原来 1200 个表达式的阈值在 1.8.0 里消失了，每次重建都走快路径。 材质路径还会重置材质的编辑器参数缓存；材质函数路径不会。

重建是原子的

第 1–9 步要么全部生效、要么一条都不生效。旧图是被摘下来而不是被销毁的，只有在重建完整成功之后才真正销毁； 中途任何一点失败，都会在编译返回之前把它放回去 —— 节点、连线、渲染状态、材质函数 usage 和 pin GUID 一并回来。 一次失败的编译留下的资产，就是它开始时的那个资产。

这件事非做不可，是因为不是所有失败都能提前拦住：整文件解析、Settings 校验和 Outputs 校验确实都是在 资产被碰之前跑的闸门，但 Graph 块是由图构建器一句一句编的，跑在第 7 步 —— 也就是拆除之后。 在 1.8.0 之前，这类失败会留下一个被清空的资产：材质如此已经很糟，材质函数更糟 —— 它的调用点是从活着的 资产上读 pin 的，一个坏掉的 .dsf 会把每一个调用它的材质一起带走，而且没有 undo（生成资产刻意不是 RF_Transactional 的）。

回滚有两个细节让它真的成立：快照是关掉 delta 序列化取的（否则等于类默认值的属性会被跳过，恢复时就会留下失败的 那次构建设进去的值），而且它覆盖资产的编辑器专用数据对象 —— UE 5.1 起，表达式集合和材质属性输入住在一个独立的 UMaterialEditorOnlyData / UMaterialFunctionEditorOnlyData 对象上，只给材质本身做快照，抓到的不过是一个指向它的指针。

唯一能留下来的手改

文本不带 DreamShader 前缀的注释框。

dreamshader: Notes、DREAMSHADER: Notes 和 DreamShader:Notes（没有空格）都通不过前缀检测，因此都会 留下来。 这是官方支持的、手工标注生成材质的方式。

被刻意保留的身份

有两种身份被刻意保留下来，好让已有的调用点不被打断。

• 材质函数 pin。 在图被清空之前，每个 UMaterialExpressionFunctionInput 和 UMaterialExpressionFunctionOutput 的 Id GUID 会按名字缓存起来，然后恢复到同名的新建 pin 上。项目里别处的 MaterialFunctionCall 节点因此能在该函数重新生成后保住连线。since 1.3.2
• 命名 reroute。 声明的变量 GUID 只有在现有的那个无效时才重新生成。

因此在源码里重命名一个输入或输出，对它的调用点来说是 破坏性变更：旧名字的 GUID 没有可以恢复的目标了。

生成实例上的参数覆盖

手改检测

source hash 给编译读的源码打指纹，它对那次编译产出的资产一无所知。所以一个被你手动改过的资产 看上去仍然是干净的：下一次它的 .dsm 一动，重建就把图拆了、重建了，手改没了，没有诊断，也没有 undo。

输出指纹是缺的另一半：每次成功生成的末尾，把资产实际持有的内容写成 DreamShader.OutputDigest； 下一次重建在清空资产之前拿它比一次，回答 source hash 回答不了的那个问题 —— 有人在这里面动过手吗？

DreamShader.SourceFile 决定归属，指纹决定内容是否还是我们的：

「未打标」覆盖两种无害情况：指纹机制存在之前生成的资产，以及指纹带着不同 schema 标签的资产。标签是指纹格式版本 加引擎版本（DSD1-5.8），因为指纹遍历的属性集合本来就是引擎的 —— 没有它，升一次引擎会把整个工程的资产一次性 重新指纹化，然后把整个材质库报成「被手改过」。

什么算手改

规则是指纹恰好覆盖一次重建会摧毁的东西。重建本来就不碰的属性，能原样活过重建，因此拿它挡住一次重建， 等于为了保护一个从来没有危险的东西而白白拒掉一次编译。

拒绝长什么样

生成失败，资产保持你离开时的样子 —— 没有清空，也没有半成品：

Asset '/Game/Materials/M_Emissive.M_Emissive' has been edited by hand since DreamShader generated it
from 'DShader/Materials/M_Emissive.dsm', so it was NOT rebuilt (rebuilding would destroy those
edits). Right-click the asset > DreamShader and choose one: 'Revert to Source' discards the edits and
rebuilds, 'Adopt Into Source' rewrites 'DShader/Materials/M_Emissive.dsm' from the edited asset,
'Detach From DreamShader' hands the asset over to you and stops managing it.

检查跑在任何东西改动资产之前。对材质函数来说这个顺序就是全部意义所在：闸门在 usage 被重新打标之前就开火， 而不只是在拆图之前。

这道闸门和上面的原子重建回答的是两个不同的问题，而且两个你都想要：闸门拦住一次本来会成功的重建覆盖掉你手写的 东西；原子性拦住一次失败的重建把资产留成碎片。谁也盖不住谁的场景。

只有源码动过时才会尝试重建。没动过的源码早在闸门之前就被 source hash 跳过了，所以「手改了资产但没动它的源码」 这件事根本不会报任何东西 —— 因为没有任何东西处于危险中。

三个出口

三个都在资产右键菜单的 DreamShader 下，材质、材质函数、layer、layer blend 和生成的 ThinCustom 实例一视同仁。

Adopt Into Source 的三个细节：写任何东西之前，旧源码先被复制成 <source>.bak；源文件声明了不止一个资产时 拒绝执行；文件自身的形态 —— 手写注释、import 指令、排版 —— 会被替换成反编译器的输出。

拒绝多资产文件是必要的：反编译器发射的是一个块而不是一个翻译单元， 所以从一个声明了好几个资产的文件里 adopt 其中一个，会静默删掉其余的。这种情况请用 Export DSM 然后手工合并。

资产开着编辑器时拒绝重建

资产开在某个资产编辑器里时，重建被直接拒绝：

Asset '{ObjectPath}' is open in an asset editor, so it was NOT rebuilt. An open editor works on its
own copy of the asset and writes that copy back when you press Apply or Save, which would silently
undo this rebuild. Close the editor and compile again.

原因是资产编辑器并不编辑资产本身。FMaterialEditor 把资产复制成一个临时的 UPreviewMaterial， 在 Apply 或 Save 时用 UpdateOriginalMaterial 把副本盖回原件；材质实例编辑器则通过 UMaterialEditorInstanceConstant 包装写回。一个跨越了重建仍然开着的编辑器，手里握的是重建之前的副本， 下一次 Apply 会把重建做的一切还原 —— 然后以一次手改检测的形式出现在再下一次编译里，离病因已经很远。

两个来历动作是例外。 Revert to Source 和 Adopt Into Source 自己关掉编辑器、动手、再打开 —— 因为你刚刚点了它们，很可能就是从那个编辑器自己的工具栏上点的，而一个在最有用的地方永远是灰的菜单项不是保护， 是 bug。关闭过程中可能出现引擎的保存提示；对 Adopt 来说它是承重的而不是噪音，因为未 Apply 的编辑器改动 在这个提示被回答之前，不算「这个资产当前的内容」。取消它就取消整个动作。

归属守卫

DreamShader 拒绝覆盖不是自己生成的资产。

对不在磁盘上的 package，这个守卫是不生效的：纯内存资产没有已保存的 package 需要保护，所以检查不会执行。 这个缺口由另一侧补上 —— 手改检测在内存里同样生效，因为源码路径在那边也会被打上。

目标路径上放着类不对的资产，是在问归属之前就被一次类检查挡掉的：

Asset '{ObjectPath}' already exists and is not a DreamShader instance material. Delete it (or remove
Backend="Instance") before switching backends.

重置属性

在图被重建之前，材质的渲染状态会按下表顺序恢复成这些值。Settings 在之后才应用，所以你声明的键会赢； 你 没有 声明的项则一律回到下表的值，不管材质编辑器里之前是什么。

bUsedWithVolumetricCloud 是上表里唯一不是常量的一项：由 domain 决定。Volume domain 的材质就是体积 材质，而体积云渲染器会拒绝一个没打这个标志的材质 —— 所以你永远不需要手写它。显式写出来可以覆盖 domain 的选择： 一个只喂体积雾的 Volume 材质可以用 bUsedWithVolumetricCloud = "false"; 把标志关掉，省下云的 shader 排列。

材质函数没有渲染状态；重新应用的是它们的资产级字段：

每次重新生成还会按块类型重新打上 material function usage。

构建键（source hash）

重新生成的开销不小，所以未改动的源文件会被完全跳过。

prepared text  ->  CRC32  ->  "%08x"  ->  DreamShader.SourceHash   e.g. "9f2c41ab"
source path    ->  project-relative, forward slashes  ->  DreamShader.SourceFile

哈希覆盖什么

哈希覆盖的是解析器真正看到的那份文本，也就是 import 内联 之后 的文本，而不是磁盘上文件的字节。这是这套缓存里最容易让人意外的一点。

它是一把构建键，不只是源码哈希

这个 stamp 给源码在编译它的上下文里打指纹。任何会改变某份源码产出的东西都被折进来， 因为把它漏掉，就意味着跳过检查会对一个其实已经不是最新的资产回答「还是最新的」：

一批文件按依赖顺序编译

一批里同时有函数和调用它的东西时，批次会被排成依赖先编。这不是锦上添花：一个调用 ShaderFunction 的 .dsm 会把调用节点绑到活着的 UMaterialFunction 资产上（SetMaterialFunction 是从对象而不是从源码上读 pin 的）， 所以先编调用方，就绑到了那个函数上一版的接口。改一个函数输入的名字、两个文件一起保存就能撞上， 而谁赢取决于待编译文件表的遍历顺序。

两个入口 —— watcher 的待编译批次和全工程扫描 —— 都按 import 图做拓扑排序；只有批次内部的边被考虑， 成环则留给 import 加载器用 DreamShader import cycle detected at '{File}'. 拒绝。

元数据存在哪

有两个键写进生成资产的 package 元数据，以资产对象为键。这也是 DreamShader 唯二会写的键 —— 没有任何地方写生成时间戳。

存 项目相对 路径是刻意的：换台机器检出、或者把项目目录挪个地方，它仍然认得出自己生成的资产，而不会把一切重新生成一遍。 DreamShader.SourceFile 同时充当 归属标记 —— 上面那个守卫检查的就是它，Clean Persisted Generated Assets 过滤的也是它。

哪些资产会被打标记，以及什么时候打：

ThinCustom 实例还额外把源码路径和哈希作为只读 UPROPERTY 携带 —— SourceFilePath 和 SourceHash，分类 DreamShader —— 所以不用翻 package 元数据就能在详情面板里看到。SourceFilePath 存的是 完整规范化 的源码路径， 而不是元数据里那种项目相对形式。

什么时候会跳过重新生成

短路只在 全部 条件成立时才触发：

把 ThinCustom 的检查放在 base 创建之前，正是跳过之所以便宜的原因：不建 base、不做归属检查、不拆图。 而 usage 不匹配的材质函数 —— 比如一个 ShaderLayer 块对应的资产还标着 Default —— 即使哈希相同也会重新生成，并顺手纠正 usage。

强制重建

源语言里没有清除已存哈希的办法。要在没有强制入口的情况下强制重建，要么改动源码文本（任何改动，包括空白），要么删掉生成的资产。

说明

• 重新生成不可撤销，但它是原子的 since 1.8.0：失败会把资产放回重建之前的样子。 生成的材质实例刻意不是 RF_Transactional，因为撤销/重做会让 shader map 失步 —— 所以回滚不能靠事务， 只能靠快照。
• 最稳妥的心智模型：把 .dsm / .dsf 当成资产本身。任何你想保留的东西都应该写在源码里。
• 被 source hash 跳过的那次重新生成，上面这些一件都不做 —— 资产完全没有被碰。
• 删掉生成的资产再重新编译，效果永远等价于一次强制重新生成，唯一的差别是材质函数的 pin GUID 会丢失，它的调用点会断。
• 这个哈希是 CRC32，不是密码学摘要。它用来检测改动，不是完整性机制。
• 生成的 .ush helper include 不 受这个短路保护。只要该单元声明了 Function 块，每次编译都会重写它。
• 反编译导出是把手改捞回来的正道：把改过的材质导出回 .dsm / .dsf，然后以那份源码为准。 自 1.8.0 起，Adopt Into Source 就是把这件事做成一个右键动作，并且会先把旧源码备份成 <source>.bak。

诊断

完整示例

Shader(Name="Docs/M_Regen")
{
    Properties {
        ScalarParameter Intensity = 2.0 [Group="Look"; SortPriority=10];
        VectorParameter Tint      = float4(1.0, 0.4, 0.1, 1.0) [Group="Look"];
    }
    Settings { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs  { vec3 Color; Base.EmissiveColor = Color; }
    Graph    { Color = Tint.rgb * Intensity; }
    Layout   { Node(Var="Color", X=-400, Y=0); }
}

手改生成出来的资产，然后再保存一次 .dsm —— 自 1.8.0 起这会先被手改检测拦下来， 下面这张表是你选了 Revert to Source 之后发生的事：

before regeneration                              after regeneration
-----------------------------------------------  --------------------------------------------
comment "DreamShader: Output: EmissiveColor"     recreated
comment "Reviewed 2026-07-30"                    KEPT — no DreamShader: prefix
extra Multiply node wired in by hand             deleted
Two Sided ticked in the material editor          reset to false (not declared in Settings)
Intensity override = 5.0 on the instance         cleared, back to the source default 2.0
Color node dragged to (900, 400)                 back to (-400, 0), pinned by Layout

生成实例上的元数据：

DreamShader.SourceFile   DShader/Docs/M_Regen.dsm
DreamShader.SourceHash   9f2c41ab

继续阅读