生成流程

DreamShaderLang 的编译目标不是字节码，也不是可执行文件，而是 Unreal 资产：一个 UMaterial 或 UDreamShaderMaterialInstance、若干材质函数资产，以及一个生成的 HLSL include。本页跟着一个源文件走完全程。

没有运行时路径。打包后的游戏里不存在从 DreamShaderLang 构建材质的代码，那时资产早已存在。

阶段

一次编译一个文件会走完下面这串流程。每一步都是一道闸门：第一个失败会中止编译，它的消息就是这次编译返回的结果。

本节中的 {Placeholder} 表示编译器在运行时替换的值。

上表里有两点值得单独拎出来：

• 解析单元是 import 闭包，不是单个文件。 import 在解析 之前 就被内联，所以"一个文件一个 Shader" 实际上是"一个闭包一个 Shader"—— 第 6 步的 source hash 也因此覆盖了每一个被导入的字节。见 import 与命名空间。
• 材质函数先于材质生成。 所以同一个文件里的 Shader 可以调用写在它旁边的 ShaderFunction。

import 行会被替换成空行，每个被内联的文件用 // Begin DreamShader source: <path> / // End DreamShader source: <path> 标记包裹，因此报告出来的行列号仍然指向你真正编辑的那个文件。

第 9 步和第 10 步共用同一个图构建器。只请求生成材质时（编辑器的 compile material 入口），会执行 1–7 和 10，跳过 9。

第 10 步内部 —— 材质

图构建内部

两种 backend 共用。在 ThinCustom 下，它作用于隐藏的 base 材质，而不是发出的那个实例。

1. 清空现有表达式，然后把每一个材质属性重置为引擎默认值。
2. 应用 Settings。
3. 绑定了 Base.FrontMaterial 时，强制切到 Substrate 着色。
4. 拒绝重名的 Properties —— 比较时忽略大小写。
5. 为每个未初始化的 MaterialAttributes 输出声明各生成一个 MakeMaterialAttributes 节点。
6. 构建主体 —— 要么是 Graph 块，要么在既无 Graph 又无已初始化输出时，用一个整表面 Custom 节点。
7. 连接每一条 Outputs 绑定。
8. 布局。纯内存模式下跳过；表达式数量达到 1200 及以上且没有 Layout section 时同样跳过。
9. 重新编译材质。

第 1 步就是"手改生成出来的资产没有意义"的原因 —— 见 重新生成。

什么会触发编译

保存时自动编译由两个项目设置控制：Auto Compile On Save（默认开）与 Save Debounce Seconds （默认 0.25，钳制在 [0.05, 10.0]）。关掉前者，源目录监视器会完全忽略文件变化。见 项目设置。

不产出资产的结果

一个源文件可以编译成功，却没有任何东西能放进 Content Browser。

要留意的是最后一行：一个什么可生成物都没声明的文件是错误，而只声明 helper 的文件没有问题。

成功消息

解析警告永远不会让编译失败。它们会被追加到上面对应的消息后面，放在一个 Warnings: 标题下。

进度反馈

生成过程通过 Unreal 的 slow task 系统汇报。对话框有延迟，所以一次快速编译不会闪出窗口；在 IsRunningCommandlet() 下则完全不弹。

完整示例

// DShader/Materials/M_Emissive.dsm
import "Common.dsh";

ShaderFunction(Name="Functions/F_Tint")
{
    Inputs  { vec3 InColor; vec3 InTint; }
    Outputs { vec3 OutColor; }
    Graph   { OutColor = InColor * InTint; }
}

Shader(Name="Materials/M_Emissive")
{
    Properties { vec3 Tint = vec3(1.0, 0.4, 0.1); }
    Settings   { ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }
    Graph      { Color = F_Tint(vec3(1.0, 1.0, 1.0), Tint); }
}

编译这个文件一次会产出：

Intermediate/DreamShader/GeneratedShaders/M_Emissive_9f2c41ab.ush   (only if Common.dsh declares Function blocks)
/Game/Functions/F_Tint                                             UMaterialFunction
/Game/Materials/M_Emissive                                         UDreamShaderMaterialInstance + hidden UMaterial base

并报告：

Generated ShaderFunction /Game/Functions/F_Tint from I:/.../M_Emissive.dsm.
Generated DreamShader thin-custom material /Game/Materials/M_Emissive from I:/.../M_Emissive.dsm.

这个 .ush include 位于 Generated Shader Directory 项目设置指向的目录（默认 Intermediate/DreamShader/GeneratedShaders），并映射到虚拟着色器路径 /DreamShaderGenerated/。它的文件名里嵌的是 源文件路径 的哈希，不是源码文本的哈希，所以改动 Function 体只会重写同一个文件，不会越积越多。

继续阅读