重新生成

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

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

什么能留下来

执行顺序

1. 对目标对象调用 Modify()。
2. 清除生成的注释 —— 每一个文本以字面量 DreamShader: 开头的 UMaterialExpressionComment。
3. 清空每一个材质属性输入，从第一个材质属性槽到最后一个。
4. 删除图中的每一个表达式。
5. 把材质重置为默认值 —— 见下面的"重置属性"。材质函数跳过这一步。
6. 应用 Settings。
7. 重建：Properties 节点、Graph 主体或整表面 Custom 节点、Outputs 绑定。
8. 布局 —— 纯内存模式下跳过。
9. 重新编译。

第 4 步有两套策略。表达式少于 1200 个时，通过材质编辑库逐个删除节点，最多 64 轮外层遍历，并报告 Deleting old Material node '{Name}'...。达到 1200 及以上时，整个表达式集合会被一次性解除根引用并标记为垃圾。 材质路径还会重置材质的编辑器参数缓存；材质函数路径不会。

唯一能留下来的手改

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

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

被刻意保留的身份

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

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

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

生成实例上的参数覆盖

归属守卫

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

对不在磁盘上的 package，这个守卫是不生效的：纯内存资产没有已保存的 package 需要保护，所以检查不会执行。

重置属性

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

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

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

source hash 缓存

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

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

哈希覆盖什么

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

元数据存在哪

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

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

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

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

什么时候会跳过重新生成

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

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

强制重建

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

说明

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

诊断

完整示例

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：

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

继续阅读