Contributing

DreamShader » Contributing

Building the plugin itself, the layout of its five C++ modules, and where each subsystem's code lives.

Synopsis

Validate the plugin standalone, without building a full project target:

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

<PluginDir> is the directory holding DreamShader.uplugin. -Package must point at a directory that does not overlap the source tree — UAT stages a clean copy there.

One engine proves nothing about the others, so run the whole matrix with .skill/build-plugin.ps1.

Repository layout

Modules

The order is the descriptor's. DreamShaderPass loads at PostConfigInit because it maps a shader source directory and its global shader types register when its DLL loads, both of which have to happen before the engine commits the shader type list.

The descriptor declares two enabled plugin dependencies: WebSocketNetworking (the preview WebSocket server) and SQLiteCore (the bridge database). Both are engine plugins.

Build rules

All five modules set PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs. Three of them add definitions, each from a probe of the engine being built against:

DreamShaderPass is a private dependency of DreamShaderCompiler and DreamShaderEditor. Both read its public definition DREAMSHADER_WITH_CUSTOM_PASS instead of testing the engine version again. DreamShaderPass itself depends on DreamShader — for the project source root its .dreampass/ folder lives in — and on no editor module.

DreamShader is a public dependency of DreamShaderCompiler, so anything that links DreamShaderCompiler transitively gets the runtime headers.

Why the runtime module needs each of its dependencies: DeveloperSettings for UDeveloperSettings; Engine for EngineTypes.h, MaterialDomain.h and UMaterialInstanceConstant; RenderCore for AllShaderSourceDirectoryMappings / AddShaderSourceDirectoryMapping; Projects for IPluginManager.

Source tree

Source/DreamShader — Runtime

(since 2.0.0) The 1.x parser that lived in Private/Parser/ is gone. A .dsm / .dsf / .dsh is read by the legacy front end of DreamShaderLang — see DreamShaderLang.

Source/DreamShaderPass — Runtime

(since 2.1.0) The Custom Pass runtime: the asset a .dsp compiles to, the subsystem that decides which pipelines apply to a view, and the scene view extension that runs their passes. The module builds on every engine; what needs the renderer is compiled only where DREAMSHADER_WITH_CUSTOM_PASS is 1. See DreamShaderPass and Custom Pass runtime.

The shaders these passes compile live in the plugin's Shaders/Pass/, mounted at /Plugin/DreamShader.

Source/DreamShaderCompiler — Editor

The compiler itself — the compile pipeline, the IR emitter and the asset layer — moved into this module in 2.0, replacing the 1.x generator (DreamShaderEditor/Private/MaterialAssetGeneration/); see Compiler module.

Source/DreamShaderLang — Runtime, Core only

See DreamShaderLang and The 2.0 language.

Source/DreamShaderEditor — Editor

Everything is under Private/; nothing is exported.

Inside MaterialAssetGeneration/

(removed in 2.0.0) The 1.x generator — source loading with textual import inlining, the Graph statement walker, the per-concern lowering units and the generated .ush writer — was deleted. Where each of its jobs is done now:

Building

BuildPlugin compiles all five modules against the target engine and fails on the first UBT or UHT error. It is the check that matters when adding an engine-version gate, because the project build only ever exercises one engine version. It is also the only check that sees a link error: an engine class that compiles everywhere and only resolves from UE 5.6 on is invisible to every compile-time gate. See the note under UE ≥ 5.6 on version compatibility.

The engine matrix

.skill/build-plugin.ps1 runs BuildPlugin once per engine root, each into its own -Package directory, and prints one PASS / FAIL line per engine plus the compiler diagnostics of the ones that failed. The plugin's own Binaries/ and Intermediate/ are never touched. Its exit code is the number of engines that failed, so 0 means the matrix is green.

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

The full UAT log of every engine is kept under <Package>\Logs\<Engine>.log, pass or fail.

Each engine builds into <Package>\<Engine> (UE_5.8, from Build.version), and that directory is deleted before the build, emptied by BuildPlugin itself, and deleted again after it unless -KeepOutput. So before anything is built or written, the script checks every engine's output directory and stops when one is a drive root, is or contains or sits inside an engine root or the plugin tree (-Engine C:\UE\UE_5.8 -Package C:\UE would otherwise name the engine itself), or already exists with files in it that the script did not put there. Its own output directories carry a .build-plugin-output marker, so a run after -KeepOutput reclaims them.

Engine versions

[!WARNING] Unreal Engine 5.3 and 5.4 do not build under a recent MSVC toolchain, whatever plugin you point at them. ConcurrentLinearAllocator.h writes #elif __has_feature(address_sanitizer) without a defined() guard, inside #if PLATFORM_HAS_ASAN_INCLUDE — which is __has_include(<sanitizer/asan_interface.h>), true for every toolchain that ships the ASan headers. MSVC has no __has_feature, so the line raises C4668, and UBT compiles engine code with /we4668. UE 5.5 fixed the header by splitting the test.

The failure is in engine code, before any plugin source is reached, and Source/DreamShader* is named nowhere in it. Epic's own ExampleDeviceProfileSelector fails identically on the same engine, which is the cheapest way to confirm the cause on a given machine. Note that installing MSVC 14.38 does not by itself help — it ships sanitizer/asan_interface.h too. It takes a toolchain without those headers, or a one-line patch to the engine header.

Every engine-version test in the plugin goes through the macros in DreamShaderVersionCompat.h; there are no raw ENGINE_MAJOR_VERSION or UE_VERSION_NEWER_THAN uses anywhere in Source/. When you add version-dependent code, add it there and use DREAMSHADER_UE_VERSION_AT_LEAST(Major, Minor) or DREAMSHADER_WITH_SUBSTRATE_BUILTINS. The one exception is Custom Pass: DreamShaderPass.Build.cs tests Target.Version and defines DREAMSHADER_WITH_CUSTOM_PASS, and code that depends on DreamShaderPass tests that definition with #if instead of the version. Both sides compile and test on a 5.8 machine: see Both sides of the Custom Pass gate. The complete list of currently gated behaviour is on Version compatibility.

Localization

Editor-facing text is LOCTEXT/NSLOCTEXT. The wire format is not: diagnostics.json, diagnostics/*.json, bridge.db, preview.json and the preview WebSocket are parsed by the VSCode and Rider extensions and must read the same in every editor culture.

The rule that keeps both true:

• Text that reaches the wire stays an FText all the way there, and the write goes through ToInvariantWireString() (Diagnostics/DreamShaderTextWireUtils.h). That function replays the FText's historic format data — pattern, arguments, nested formats — in the invariant culture. FTextInspector::GetSourceString alone is not enough: for an FText::Format result it returns the localized substituted display.
• Never collapse such an FText with ToString() on the way. ToString() is the localized display, and re-wrapping the result in FText::FromString cannot recover the English. An API whose error channel is FString-typed — FDreamShaderPreviewRenderContext, the asset layer's FDreamShaderError — therefore keeps literal FString::Printf messages, marked I18N-EXEMPT.
• Text that only ever reaches Slate has no such constraint; localize it normally.

pwsh -File Tools/Localization/localization_lint.ps1

Checks LOCTEXT_NAMESPACE define/undef pairing, rejects the define in headers, and flags literals gather cannot see (FText::FromString(TEXT(...)), FString::Printf(TEXT(...))). A deliberate non-display literal is exempted with an I18N-EXEMPT comment on the same line as the call — the check reads one line, not a span. -IncludeDeferred widens which files those literal rules run on.

-EmitBaseline regenerates Tools/Localization/BASELINE.md, whose gather count is the regression check; it covers every source file, because GatherText does. A count that moves without a matching .locres update means the translations are behind.

There is no Config/Localization/DreamShader.ini yet, so the Dashboard cannot re-gather the target and the checked-in zh-Hans .locres is a hand-made snapshot. New LOCTEXT falls back to English until it is regenerated.

Notes

• DreamShaderEditor exports nothing. It has no Public/ folder, and DREAMSHADEREDITOR_API never appears in source, so third-party C++ cannot link against the bridge or the decompiler. The supported C++ extension point is IDreamShaderCompiler — declared in DreamShader, implemented in DreamShaderCompiler, reached through GetDreamShaderCompiler(); everything else is reachable only through the editor UI, the commandlet or the bridge.
• No module singletons. No module class has Get() / IsAvailable() accessors. Use FModuleManager::LoadModuleChecked<FDreamShaderModule>(TEXT("DreamShader")). The public delegates are OnDreamShaderSourceGenerated (a compile finished, in DreamShaderCompiler), the define-provider delegate of DreamShaderDefineResolution.h, and FOnDreamPassPipelineChanged in DreamShaderPass.
• The compiler is game-thread, editor-only. The compile pipeline opens an FScopedSlowTask, creates and modifies UPackages and UMaterials, and calls PostEditChange().
• Three different "normalize" helpers exist and are easy to confuse: NormalizeSettingKey (trim + lowercase), UDreamShaderSettings::NormalizeMappingKey (trim + lowercase + strip spaces, _ and -), and NormalizeSourceFilePath (absolute path with / separators). SanitizeIdentifier is an identifier sanitizer, not a key normalizer.
• The generated documentation site is built from Docs/; DocsURL in the descriptor points at https://shader.toolchain.64hz.cn/.

Example

A complete standalone build of the plugin against a 5.7 engine:

& "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

Staged output:

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

The same five module names appear in a normal project build under <Plugin>/Binaries/Win64/, alongside their .pdb files.

See also

• Testing — the automation suite, the fixture corpus, and how to run both headlessly
• Release — tag conventions, the release workflow, and what the archive contains
• C++ API — the exported headers, class by class
• Compiler module — IDreamShaderCompiler, the supported extension point
• Version compatibility — the compat macros and every gated behaviour
• Commandlet — -run=DreamShader, the headless entry point
• Editor bridge — request files, bridge.db, the preview WebSocket
• Generation pipeline — what a compile does, end to end
• Project settings — UDreamShaderSettings, including the source directory