DreamShader 参考
DreamShader 参考
DreamShader 参考
如需教程和面向任务的阅读，请从文档概览开始。
DreamShader 将 DreamShaderLang 源文件——.dsm、.dsf、.dsh，以及在 2.0 系列上的
.dss——编译为标准 Unreal Engine 材质资产：UMaterial、UMaterialFunction、
UMaterialFunctionMaterialLayer 和 UMaterialFunctionMaterialLayerBlend——并且在 Unreal Engine 5.8 上，将
.dsp Custom Pass 管线编译为 UDreamPassPipeline 资产，从而添加你自己的渲染 pass。
源文件是创作表面；资产是构建产物，随时可以重新生成。
| 版本 | 2.2.0 |
| 引擎 | Unreal Engine 5.3 – 5.8（Win64 已验证）；Custom Pass 需要 5.8 |
| 模块 | DreamShaderLang (Runtime)、DreamShader (Runtime)、DreamShaderPass (Runtime)、DreamShaderCompiler (Editor)、DreamShaderEditor (Editor) |
| 源文件扩展名 | .dsm 材质 · .dsf 函数 · .dsh 头文件 · .dss 2.0 编译单元 · .dsi 材质实例 · .dsp Custom Pass 管线 |
| 项目设置 | Project Settings ▸ DreamPlugin ▸ Dream Shader |
| 许可证 | MIT |
DreamShaderLang
[!NOTE] 两套语法，一个编译器。下面记录的 1.x 语法（
.dsm/.dsf/.dsh）是 已发布的语法。2.0 语法——.dss，用声明代替 Section 块的 HLSL—— 在2.0系列上通过新的 binder/IR/emitter 管线编译，并有自己的页面： DreamShaderLang 2.0。
语言参考
声明语法：源文件、块和 Section。
| 源文件 | .dsm / .dsf / .dsh 以及各自可包含的内容 |
| 词法元素 | 注释、标识符、大小写敏感性、字面量、后缀 |
| 关键字索引 | 每个保留字和别名，附链接 |
import | 引入头文件、函数和包 |
| 预处理器 | #if 和 define 表——条件编译 |
| 类型 | 类型标记、GLSL 别名、各上下文有效性 |
顶层块
Shader | 生成一个 UMaterial |
ShaderFunction | 生成一个 UMaterialFunction |
ShaderLayer / ShaderLayerBlend | 生成原生材质层函数 |
VirtualFunction | 声明一个已有的 UMaterialFunction |
Function | 可复用的 HLSL 辅助函数 |
GraphFunction | 可将 UE.* 节点引入其输入的 HLSL 辅助函数 |
Namespace | 将辅助函数归组到 Ns::Name 下 |
Section
Properties | 参数声明和组作用域 |
Inputs / Outputs | 函数签名和材质输出 |
| 输出绑定 | Base.<Target> = <value>; |
Settings | 材质和函数设置 |
Options | VirtualFunction 资产绑定 |
Layout | 节点放置、注释框、#Region |
Graph 语言
Graph = { ... } 内部的语句和表达式语言，用于具现化材质节点。
| 语句 | 每种语句形式 |
| 声明 | 变量、初始化器、作用域 |
| 表达式和运算符 | 优先级、操作数规则、整数除法 |
| 字面量 | 数值、布尔值、后缀 |
| 构造函数 | float3(...)、vec4(...)、整数构造函数 |
| Swizzle | 通道掩码、重排、重复 |
| 类型转换 | 拓宽、收窄、分量数量规则 |
if / else | 条件、真值性、分支选择 |
MaterialAttributes | 类结构体成员写入 |
| 调用 | 调用函数和参数引脚 |
| 名称解析 | 查找顺序和遮蔽 |
| 节点复用 | 公共子表达式去重 |
| 不支持的写法 | 循环、return、%、索引——以及取而代之的行为 |
节点库
内置节点
UE.* 目录 | 每个具名材质节点内置 |
UE.Expression | 通用反射节点逃生舱 |
OutputType 值 | 每个可接受的输出类型标记 |
| 数学内置 | lerp、saturate、frac…… |
| 变换内置 | UE.TransformVector / UE.TransformPosition 坐标基 |
Substrate.* | Substrate 节点（UE 5.4+） |
| Custom Pass 节点 | UE.DreamPassOutput、UE.DreamPassBuffer（UE 5.8） |
DreamShaderBuiltins.ush | 随附的 HLSL 辅助头文件 |
参数
| 紧凑类型 | float、float3、Texture2D…… |
| 参数节点 | ScalarParameter、StaticSwitchParameter…… |
| 元数据块 | Group、SortPriority、Slider、反射属性 |
SamplerType | 纹理采样器配置 |
在 Graph 中使用参数 | 值读取和引脚调用形式 |
Path(...) | 资产引用 |
Custom Pass
在 Unreal Engine 5.8 上添加你自己的渲染 pass，无需修改引擎：遮罩和自定义缓冲区、 屏幕空间效果、写入数据纹理的 compute shader。
管线——.dsp | 缓冲区、pass、注入点、绑定、网格选择、编译器检查的内容 |
| 运行时 | 什么使管线生效、pass 何时运行、内置和导出的缓冲区、视图、调试、限制 |
| HLSL pass | 固定参数、槽位、快照和预检查 |
| 材质节点 | 用于网格 pass 的 UE.DreamPassOutput，用于读取导出缓冲区的 UE.DreamPassBuffer |
| 示例 | 高亮描边、UI 毛玻璃、透视、风场 |
DreamShaderPass | 该模块的 C++ 和蓝图 API |
构建与输出
设置
| 材质设置 | 特殊键加上反射的 UMaterial 属性 |
| 枚举取值 | 每一个 ShadingModel、BlendMode、Domain |
Backend | ThinCustom 对比 Graph |
| 函数设置 | 材质函数支持的键 |
| 项目设置 | DreamPlugin ▸ Dream Shader |
生成
| 资产路径 | Name= 和 Root= 到包路径与磁盘路径 |
| 瞬时材质 | 薄实例、隐藏基础、烹饪行为 |
| 缓存 | 源哈希与跳过的重建 |
| 图表布局 | 自动放置及其限制 |
| 重新生成 | 重建后什么保留、什么不保留 |
| 分歧 | 手改过的资产：检测，以及三种出路 |
| NoGeneration | 只有指名它们的那次编译才会构建的源文件 |
| 生成的 HLSL | 生成的 .ush include |
工具链
编辑器工具
| 编辑器集成 | 菜单、工具栏、上下文菜单 |
| 材质 Content Browser | 浏览、筛选、实例化、实体化 |
| 预览 | 缩略图和流式预览 |
| 反编译器 | 把已有的材质、实例和 Custom Pass 管线导出为源文件 |
| VirtualFunction 工具 | 声明并同步已有的函数 |
| 工作区与编辑器扩展 | VSCode 工作区、VSCode 与 Rider 插件 |
| Package | DShader/Packages 共享库 |
| Commandlet | 无头编译与反编译 |
| 编辑器 bridge | 请求文件、WebSocket 协议、产物 |
C++ API
DreamShaderModule.h | 模块、日志类别、导出的函数 |
DreamShaderTypes.h | 解析后的源数据模型 |
DreamShaderParser.h | 2.0 中已退役 —— 取代 1.x 解析器入口点的是什么 |
DreamShaderSettings.h | UDreamShaderSettings |
DreamShaderMaterialInstance.h | 生成的实例类 |
DreamShaderVersionCompat.h | 引擎版本宏 |
DreamShaderCompiler | 编译器接口与服务 |
DreamShaderPass | Custom Pass：管线资产、设置、子系统、体积与组件 |
参考
| 诊断索引 | 每一个错误和警告，附原因与修复方法 |
| 禁用诊断 | disable_warning / disable_error，针对一个文件或一行 |
| 示例 | 完整、可直接复制粘贴的源文件 |
| 贡献 | 构建插件 |
| 测试 | 自动化测试套件与固定样本集 |
| 发布 | 打标签与打包 |