插件概览

DreamShader 是一个 Unreal Engine 材质生成插件。它提供 DreamShaderLang 源语言，让材质、材质函数、Material Layer、Substrate 图值和共享 helper 可以像代码一样维护，并生成标准 Unreal UMaterial、UMaterialFunction、UMaterialFunctionMaterialLayer 与 UMaterialFunctionMaterialLayerBlend 资产。

当前插件版本：1.4.0。插件目前基于 Unreal Engine 5.7 持续开发，并已通过单插件 RunUAT BuildPlugin 构建验证 Unreal Engine 5.3、5.4、5.5、5.6 和 5.7。

插件仓库：

https://github.com/TypeDreamMoon/DreamShader

解决什么问题

传统 Unreal 材质图在复杂项目里容易出现这些问题：

问题	DreamShader 的处理方式
节点图难以版本管理	使用 `.dsm` / `.dsh` 文本源文件。
重复连接节点	用 `Function`、`Namespace` 和 Package 复用逻辑。
材质函数分发麻烦	用 `ShaderFunction` 生成 `UMaterialFunction`，或用 `VirtualFunction` 声明已有函数资产。
Material Layer 资产难以文本化维护	用 `ShaderLayer` / `ShaderLayerBlend` 生成 Unreal 原生 Layer Function 资产。
UE 5.7 Substrate 节点难以稳定复用	用 `Substrate` 类型、`Base.FrontMaterial` 和 `Substrate.*` wrapper 把 Substrate 图生成纳入语言层。
共享函数修改后难以追踪影响	通过 import graph 刷新依赖 `.dsf` / `.dsh` 的源文件。
生成资产难以追溯来源	在资产 metadata 中记录源文件和 hash。
现有材质迁移成本高	从 Content Browser 导出 `.dsm` / `.dsf` 初稿，再逐步整理。
大型生成图难以阅读	用 `Layout` 和 Graph `#Region` 保存节点位置与注释框。
编辑器里调材质缺少快速反馈	通过 VSCode 材质预览请求和 Unreal Bridge 预览输出查看当前 `.dsm` 生成材质。

核心能力

能力	说明
`.dsm` / `.dsf` / `.dsh` 文件模型	材质入口、可复用函数文件和共享头文件分离。
`Shader`	生成或更新 `UMaterial`。
`ShaderFunction`	生成或更新 `UMaterialFunction`。
`ShaderLayer`	生成或更新 Unreal 原生 `UMaterialFunctionMaterialLayer`。
`ShaderLayerBlend`	生成或更新 Unreal 原生 `UMaterialFunctionMaterialLayerBlend`。
`VirtualFunction`	声明已有 `UMaterialFunction`，供 Graph 调用但不覆盖资产。
`Graph`	用文本描述 Unreal 材质节点和连接关系。
参数生成	`Properties` 可生成 Scalar / Vector / Texture / Static Switch 等参数节点，并支持分组、排序和说明。
外部参数	通过 `UE.CollectionParam(...)` 读取 Material Parameter Collection。
函数默认输入	`ShaderFunction` / `VirtualFunction` 可用 `opt` 输入复用 Unreal FunctionInput 的预览默认值。
Substrate	`Substrate` 可作为 Graph 值、函数输入输出和 `Base.FrontMaterial` 绑定，常用 UE 5.7 Substrate 节点通过 `Substrate.*` 调用。
`Function`	编写 HLSL 风格 Custom 节点 helper。
`GraphFunction`	编写可复用 Custom 节点 helper，并允许函数体内的 `UE.*` 调用先生成图节点再传入 Custom。
`Namespace`	组织共享 helper，降低命名冲突。
`SelfContained` / `Inline`	把 helper 依赖嵌入 Custom 节点。
`Layout` / `#Region`	显式材质图布局 metadata 和命名节点区域。
反编译导出	将已有 `Material` / `Material Function` 导出为 `.dsm` / `.dsf` 初稿。
材质预览桥接	Unreal 侧响应 VSCode 的 preview 请求，输出 `preview.json`、预览 PNG，或通过本机 WebSocket 推送预览帧。
VolumeTexture	支持 `VolumeTexture` / `Texture3D` 属性、函数输入和默认资源。
Package	通过 GitHub 分发 `.dsh` 共享库。
编辑器支持	VSCode 和 Rider 语言插件提供高亮、补全、跳转、诊断和 Package 工具。

语言与插件的分工

部分	负责
DreamShaderLang	描述材质资产、Material Layer、Graph、helper、导入关系和 Package 依赖。
DreamShader 插件	解析源文件、生成 Unreal 节点、写入资产、保存 metadata，并导出 Bridge 诊断、MaterialExpression manifest 和材质预览结果。
VSCode 扩展	提供编辑器语言服务、动态 MaterialExpression 补全、Bridge 诊断、材质预览和 Package 工作流入口。
Rider 插件	提供 `.dsm` / `.dsf` / `.dsh` 文件类型、PSI 解析、高亮、补全、导航、诊断、Unreal Bridge、semantic token、inlay hints 和 Package 工具。
Package Store Index	提供可发现的社区 Package 列表。

产物

源声明	Unreal 产物
`Shader(Name="...")`	`UMaterial`
`ShaderFunction(Name="...")`	`UMaterialFunction`
`ShaderLayer(Name="...")`	`UMaterialFunctionMaterialLayer`
`ShaderLayerBlend(Name="...")`	`UMaterialFunctionMaterialLayerBlend`
`VirtualFunction(Name="...")`	已有 `UMaterialFunction` 的调用签名
`Function` / `GraphFunction`	Custom 节点代码和生成 helper include。
`.dsf`	生成可复用 `ShaderFunction` 资产，也可作为依赖被 import。
`.dsh`	不直接生成资产，作为共享依赖参与 `.dsm` / `.dsf` 编译。

Shader、ShaderFunction、ShaderLayer 和 ShaderLayerBlend 可用 Root="Game" 或 Root="Plugin.PluginName" 指定生成资产根路径；省略时默认生成到 /Game。Plugin.PluginName 指向 [Project]/Plugins/PluginName/Content。

生成材质参数时，可以用普通类型保持简洁，也可以用显式 Parameter 类型控制 Unreal 参数节点：

Properties = {
    ScalarParameter Roughness = 0.35 [
        Group="Surface";
        SortPriority=10;
    ];
    StaticSwitchParameter UseDetail = true [
        Group="Switches";
        Description="Use detail branch";
    ];
}

适合场景

场景	是否适合
大量风格一致的 UI / Surface 材质	适合。
需要版本管理材质逻辑	适合。
团队共享材质函数库	适合。
原生 Material Layer / Layer Blend 函数资产	适合。
临时做一个简单节点图	可以，但手动材质编辑器也足够。
完整替代所有 HLSL shader pipeline	不适合，DreamShader 目标是 Unreal 材质资产生成。

解决什么问题

核心能力

语言与插件的分工

产物

适合场景

本页目录