贡献

DreamShader » 贡献

构建插件本身、其五个 C++ 模块的布局，以及各子系统的代码所在位置。

概要

独立验证插件，无需构建完整的项目目标：

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

<PluginDir> 是存放 DreamShader.uplugin 的目录。-Package 必须指向一个不与源码树重叠的目录——UAT 会在那里暂存一份干净的副本。

仅一个引擎无法证明其他引擎的情况，因此请使用 .skill/build-plugin.ps1 运行整个矩阵。

仓库布局

模块

该顺序即描述符中的顺序。DreamShaderPass 在 PostConfigInit 加载，因为它映射了一个着色器源目录，且其全局着色器类型会在其 DLL 加载时注册，这两者都必须在引擎确定着色器类型列表之前发生。

描述符声明了两个已启用的插件依赖：WebSocketNetworking（预览 WebSocket 服务器）和 SQLiteCore（桥接数据库）。两者都是引擎插件。

构建规则

所有五个模块均设置 PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs。其中三个模块添加了定义，每个都来自对所针对构建的引擎的探测：

DreamShaderPass 是 DreamShaderCompiler 和 DreamShaderEditor 的私有依赖。两者都读取其公共定义 DREAMSHADER_WITH_CUSTOM_PASS，而不是再次测试引擎版本。DreamShaderPass 本身依赖 DreamShader——因为项目源码根目录所在的 .dreampass/ 文件夹——而不依赖任何编辑器模块。

DreamShader 是 DreamShaderCompiler 的公共依赖，因此任何链接 DreamShaderCompiler 的目标都会传递性地获得运行时头文件。

运行时模块为何需要其各项依赖：DeveloperSettings 用于 UDeveloperSettings；Engine 用于 EngineTypes.h、MaterialDomain.h 和 UMaterialInstanceConstant；RenderCore 用于 AllShaderSourceDirectoryMappings / AddShaderSourceDirectoryMapping；Projects 用于 IPluginManager。

源码树

Source/DreamShader — 运行时

(自 2.0.0 起) 位于 Private/Parser/ 的 1.x 解析器已被移除。.dsm / .dsf / .dsh 由 DreamShaderLang 的旧版前端读取 — 参见 DreamShaderLang。

Source/DreamShaderPass — 运行时

(自 2.1.0 起) Custom Pass 运行时：.dsp 编译成的资产、决定哪些管线应用于某个视图的子系统，以及运行其通道的场景视图扩展。该模块在所有引擎上构建；需要渲染器的部分仅在 DREAMSHADER_WITH_CUSTOM_PASS 为 1 的地方编译。参见 DreamShaderPass 和 Custom Pass 运行时。

这些通道编译的着色器位于插件的 Shaders/Pass/ 中，挂载在 /Plugin/DreamShader。

Source/DreamShaderCompiler — 编辑器

编译器本身 — 编译管线、IR 发射器和资产层 — 在 2.0 中移入此模块，替换了 1.x 生成器（DreamShaderEditor/Private/MaterialAssetGeneration/）；参见编译模块。

Source/DreamShaderLang — 运行时，仅 Core

参见 DreamShaderLang 和 2.0 语言。

Source/DreamShaderEditor — 编辑器

所有内容都在 Private/ 下；没有导出任何内容。

MaterialAssetGeneration/ 内部

(在 2.0.0 中移除) 1.x 生成器——带文本 import 内联的源加载、Graph 语句遍历器、各关注点降低单元以及生成的 .ush 写入器——已被删除。其各项任务 现在由谁完成：

构建

BuildPlugin 针对目标引擎编译全部五个模块，并在第一个 UBT 或 UHT 错误时失败。在添加引擎版本门控时，这是至关重要的检查，因为项目构建只会针对一个引擎版本进行。它也是唯一能看到链接错误的检查：一个在所有地方都能编译、仅从 UE 5.6 起才能解析的引擎类，对每个编译时门控都是不可见的。参见 UE ≥ 5.6 下有关版本兼容性的说明。

引擎矩阵

.skill/build-plugin.ps1 为每个引擎根运行一次 BuildPlugin，各自进入自己的 -Package 目录，并为每个引擎打印一行 PASS / FAIL，加上失败引擎的编译器诊断。插件自身的 Binaries/ 和 Intermediate/ 从不被触碰。其退出代码是失败的引擎数量，因此 0 表示矩阵全绿。

./.skill/build-plugin.ps1 -Engine C:\UE\UE_5.5, C:\UE\UE_5.6, C:\UE\UE_5.7

每个引擎的完整 UAT 日志都保留在 <Package>\Logs\<Engine>.log 下，无论通过还是失败。

每个引擎都会构建到 <Package>\<Engine>（UE_5.8，来自 Build.version），该目录在构建前会被删除，由 BuildPlugin 自身清空，并在构建后再次删除，除非设置了 -KeepOutput。因此，在构建或写入任何内容之前，脚本会检查每个引擎的输出 目录，并在以下情况停止：该目录是驱动器根目录、是或包含或位于某个引擎根目录或 插件树内（-Engine C:\UE\UE_5.8 -Package C:\UE 否则会指向引擎本身），或者 已存在其中包含并非由脚本放入的文件。它自己的输出目录携带有 .build-plugin-output 标记，因此 -KeepOutput 之后的运行会回收它们。

引擎版本

[!WARNING] Unreal Engine 5.3 和 5.4 无论你将哪个插件指向它们，都无法在较新的 MSVC 工具链下构建。 ConcurrentLinearAllocator.h 写入 #elif __has_feature(address_sanitizer) 时没有 defined() 保护，位于 #if PLATFORM_HAS_ASAN_INCLUDE 内——而它是 __has_include(<sanitizer/asan_interface.h>)，对于每个附带 ASan 头文件的工具链都为真。MSVC 没有 __has_feature，因此该行会引发 C4668，而 UBT 编译引擎代码 时使用 /we4668。UE 5.5 通过拆分该测试修复了该头文件。

该失败发生在引擎代码中，在任何插件源码被触及之前，且 Source/DreamShader* 在其中未被提及。Epic 自己的 ExampleDeviceProfileSelector 在同一 引擎上会以相同方式失败，这是在特定机器上确认原因的最省事方法。请注意，安装 MSVC 14.38 本身并不能解决问题——它也附带 sanitizer/asan_interface.h。需要 一个没有那些头文件的工具链，或对引擎头文件打一行补丁。

插件中的每个引擎版本测试都通过 DreamShaderVersionCompat.h 中的宏进行； 在 Source/ 中任何地方都没有原始的 ENGINE_MAJOR_VERSION 或 UE_VERSION_NEWER_THAN 用法。当你 添加依赖版本的代码时，将它加到那里并使用 DREAMSHADER_UE_VERSION_AT_LEAST(Major, Minor) 或 DREAMSHADER_WITH_SUBSTRATE_BUILTINS。唯一的例外是 Custom Pass：DreamShaderPass.Build.cs 测试 Target.Version 并定义 DREAMSHADER_WITH_CUSTOM_PASS，而依赖 DreamShaderPass 的代码使用 #if 测试该定义，而不是测试版本。两侧都能在 5.8 机器上编译和 测试：见 Custom Pass 门控的两侧。 当前受门控行为的完整列表见 版本兼容性。

本地化

面向编辑器的文本是 LOCTEXT/NSLOCTEXT。但线格式不是：diagnostics.json、 diagnostics/*.json、bridge.db、preview.json 以及预览 WebSocket 由 VSCode 和 Rider 扩展解析，并且在每种编辑器区域性中都必须读取相同内容。

使两者都成立的原则：

• 到达线格式的文本一路保持为 FText，且写入通过 ToInvariantWireString()（Diagnostics/DreamShaderTextWireUtils.h）进行。该函数在固定区域性中重放 FText 的历史格式数据——模式、参数、嵌套格式。 仅靠 FTextInspector::GetSourceString 是不够的：对于 FText::Format 结果，它会返回 已本地化的替换后显示内容。
• 绝不要在此过程中用 ToString() 折叠这样的 FText。 ToString() 是本地化后的 显示内容，而将结果重新包装为 FText::FromString 无法恢复英文。因此，错误通道为 FString 类型的 API——FDreamShaderPreviewRenderContext、资产层的 FDreamShaderError——保留字面量 FString::Printf 消息，并标记为 I18N-EXEMPT。
• 仅到达 Slate 的文本没有此类约束；按常规对其进行本地化。

pwsh -File Tools/Localization/localization_lint.ps1

检查 LOCTEXT_NAMESPACE 的定义/取消定义配对，拒绝在头文件中定义，并标记 gather 无法看到的字面量（FText::FromString(TEXT(...))、FString::Printf(TEXT(...))）。有意为之的 非显示字面量通过在与调用同一行上的 I18N-EXEMPT 注释被豁免——该 检查读取一行，而不是一段范围。-IncludeDeferred 扩大这些字面量规则所运行的文件范围。

-EmitBaseline 会重新生成 Tools/Localization/BASELINE.md，其 gather 计数就是回归 检查；它涵盖每个源文件，因为 GatherText 也如此。若计数发生变动却没有对应的 .locres 更新，则意味着翻译落后了。

目前还没有 Config/Localization/DreamShader.ini，因此 Dashboard 无法重新 gather 目标， 而检入的 zh-Hans .locres 是手工制作的快照。新的 LOCTEXT 会回退到英文， 直到它被重新生成。

注意事项

• DreamShaderEditor 不导出任何内容。 它没有 Public/ 文件夹，并且 DREAMSHADEREDITOR_API 从不出现在源码中，因此第三方 C++ 无法链接到桥接或反编译器。受支持的 C++ 扩展点是 IDreamShaderCompiler —— 声明于 DreamShader，实现于 DreamShaderCompiler，通过 GetDreamShaderCompiler() 访问；其他一切只能通过编辑器 UI、commandlet 或 桥接 访问。
• 没有模块单例。 没有模块类具有 Get() / IsAvailable() 访问器。请使用 FModuleManager::LoadModuleChecked<FDreamShaderModule>(TEXT("DreamShader"))。公开委托包括 OnDreamShaderSourceGenerated（编译完成，位于 DreamShaderCompiler）、DreamShaderDefineResolution.h 的 define-provider 委托，以及 DreamShaderPass 中的 FOnDreamPassPipelineChanged。
• 编译器是游戏线程的、仅限编辑器的。 编译管线会打开一个 FScopedSlowTask， 创建并修改 UPackage 和 UMaterial，并调用 PostEditChange()。
• 存在三个不同的 "normalize" 辅助函数，容易混淆：NormalizeSettingKey （去空白 + 转小写）、UDreamShaderSettings::NormalizeMappingKey（去空白 + 转小写 + 去除空格， _ 和 -），以及 NormalizeSourceFilePath（使用 / 分隔符的绝对路径）。SanitizeIdentifier 是标识符清理器，不是键规范化器。
• 生成的文档站点由 Docs/ 构建；描述符中的 DocsURL 指向 https://shader.toolchain.64hz.cn/。

示例

针对 5.7 引擎的完整独立插件构建：

& "C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin `
  -Plugin="D:\Work\MyProject\Plugins\DreamShader\DreamShader.uplugin" `
  -Package="D:\Work\Out\DreamShader" `
  -TargetPlatforms=Win64 `
  -Rocket

暂存输出：

D:\Work\Out\DreamShader\
  Binaries\Win64\UnrealEditor-DreamShaderLang.dll
  Binaries\Win64\UnrealEditor-DreamShader.dll
  Binaries\Win64\UnrealEditor-DreamShaderPass.dll
  Binaries\Win64\UnrealEditor-DreamShaderCompiler.dll
  Binaries\Win64\UnrealEditor-DreamShaderEditor.dll
  Binaries\Win64\UnrealEditor.modules
  Intermediate\              UBT and UHT working files
  Source\                    copied from the plugin tree
  Shaders\                   copied from the plugin tree
  Resources\                 copied from the plugin tree
  Docs\                      copied from the plugin tree
  DreamShader.uplugin

相同的五个模块名称会出现在 <Plugin>/Binaries/Win64/ 下的普通项目构建中， 并伴随其 .pdb 文件。

另请参阅

• 测试 —— 自动化测试套件、fixture 语料库，以及如何无头运行两者
• 发布 —— 标签约定、发布工作流，以及归档包含的内容
• C++ API —— 导出的头文件，逐个类
• 编译器模块 —— IDreamShaderCompiler，受支持的扩展点
• 版本兼容性 —— 兼容宏与所有受门控行为
• Commandlet —— -run=DreamShader，无头入口点
• 编辑器桥接 —— 请求文件、bridge.db、预览 WebSocket
• 生成管线 —— 一次编译从端到端做了什么
• 项目设置 —— UDreamShaderSettings，包括源目录