安装插件

DreamShader 作为 Unreal 项目插件使用。安装后，项目可以识别 .dsm / .dsf / .dsh 源文件，并在保存或手动重编时生成材质、材质函数和 Material Layer 函数资产。

获取插件

公开仓库：

https://github.com/TypeDreamMoon/DreamShader

可以通过 Git 克隆或下载源码包，再放入 Unreal 项目的插件目录。目录名建议保持为 DreamShader，便于团队成员和文档统一。

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

在 Windows 上，UE 5.3 和 5.4 可能需要 MSVC 14.38 工具链。较新的编译器可能会先在旧版引擎头文件处失败，还没有进入 DreamShader 插件代码编译。

启用流程

将插件加入 Unreal 项目。
在 Unreal Editor 的插件面板中启用 DreamShader。
重启 Unreal Editor。
创建 DreamShaderLang 源目录，默认名称为 DShader。
创建 .dsm 或 .dsh 源文件。
保存源文件或使用 VSCode 扩展命令触发重编。

项目设置

打开 Project Settings > DreamPlugin > Dream Shader 可以看到插件配置。

设置	说明
`SourceDirectory`	DreamShaderLang 源文件根目录，默认使用 `DShader`。
`GeneratedShaderDirectory`	普通 `Function` / `GraphFunction` 生成 helper include 的目录，可按项目需要配置。
`AutoCompileOnSave`	保存源文件时是否自动刷新资产。
`SaveDebounceSeconds`	保存防抖时间，避免连续保存触发过多编译。
`VerboseLogs`	输出更详细日志，适合排错。
`OpenInNewWindow`	从 Unreal 打开 DreamShader VSCode workspace 时是否新开窗口；关闭后会复用已有 VSCode 窗口。

引擎兼容验证

如果只想验证插件能否在某个 Unreal 版本下编译，不需要构建完整项目目标，可以使用单插件打包命令：

& "<EngineDir>\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin `
  -Plugin="<ProjectDir>\Plugins\DreamShader\DreamShader.uplugin" `
  -Package="<OutputDir>\DreamShader" `
  -TargetPlatforms=Win64 `
  -Rocket

当前 1.4.0 版本在 Windows 上已按上述方式验证：

Unreal Engine	状态
`5.7`	已验证
`5.6`	已验证
`5.5`	已验证
`5.4`	已验证
`5.3`	已验证

验证安装

创建一个最小 .dsm：

Shader(Name="DreamMaterials/M_InstallCheck")
{
    Settings = {
        Domain = "UI";
        ShadingModel = "Unlit";
    }

    Outputs = {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph = {
        Color = vec3(0.2, 0.6, 1.0);
    }
}

保存后，如果项目中生成了对应 UMaterial，说明插件编译链路正常。

如果同时使用 VSCode 扩展，DreamShader 会在项目 Saved/DreamShader/Bridge 下写入诊断、material-expressions.json 和材质预览结果。扩展会读取这些文件，用于 Bridge 面板、编辑器诊断、动态 UMaterialExpression 补全和 .dsm 材质预览。

注意事项

项目	建议
源文件	把 `.dsm` / `.dsf` / `.dsh` 纳入版本管理。
生成资产	视项目策略决定是否提交。
共享库	推荐通过 Package 或项目共享 `.dsh` 管理。
错误定位	先看 VSCode 诊断，再看 Unreal Output Log。