DreamShaderVersionCompat.h

DreamShader » C++ API » DreamShaderVersionCompat.h

Thirteen preprocessor macros that gate every engine-version-dependent behaviour in the plugin — and, outside the header, one module definition: the Custom Pass gate, DREAMSHADER_WITH_CUSTOM_PASS. This page is the source of truth for every (since UE 5.x) marker in the manual.

Defined in header DreamShaderVersionCompat.h.

Synopsis

The version arithmetic every other macro is built on. The feature gates that use it are in Macros below.

#include "Misc/CoreDelegates.h"
#include "Runtime/Launch/Resources/Version.h"

#ifndef DREAMSHADER_UE_MAJOR
#define DREAMSHADER_UE_MAJOR ENGINE_MAJOR_VERSION
#endif

#ifndef DREAMSHADER_UE_MINOR
#define DREAMSHADER_UE_MINOR ENGINE_MINOR_VERSION
#endif

#ifndef DREAMSHADER_UE_PATCH
#define DREAMSHADER_UE_PATCH ENGINE_PATCH_VERSION
#endif

#ifndef DREAMSHADER_WITH_SUBSTRATE_BUILTINS
#define DREAMSHADER_WITH_SUBSTRATE_BUILTINS (DREAMSHADER_UE_MAJOR > 5 || (DREAMSHADER_UE_MAJOR == 5 && DREAMSHADER_UE_MINOR >= 4))
#endif

#define DREAMSHADER_UE_VERSION_AT_LEAST(MajorVersion, MinorVersion) \
    (DREAMSHADER_UE_MAJOR > (MajorVersion) || (DREAMSHADER_UE_MAJOR == (MajorVersion) && DREAMSHADER_UE_MINOR >= (MinorVersion)))

#if DREAMSHADER_UE_VERSION_AT_LEAST(5, 4)
#define DREAMSHADER_ALLOW_SHRINKING_NO EAllowShrinking::No
#else
#define DREAMSHADER_ALLOW_SHRINKING_NO false
#endif

Macros

The six #ifndef-guarded ones may be pre-defined by a build target — for example to compile the Substrate paths out on a 5.4+ engine by defining DREAMSHADER_WITH_SUBSTRATE_BUILTINS=0, or to force a version branch when testing. DreamShader.Build.cs uses that to set DREAMSHADER_WITH_MOON_ENGINE and DREAMSHADER_WITH_PARAMETER_COLLECTION_PARAMETERS from their header probes. The plugin's only other definitions are DREAMSHADER_WITH_CUSTOM_PASS, a PublicDefinitions entry of DreamShaderPass.Build.cs that this header does not define (below), and MOON_ENGINE=1, a PrivateDefinitions entry that DreamShaderEditor.Build.cs adds when the engine's SceneTypes.h declares MP_MoonEncodedAttribute0 and that no source file reads.

[!NOTE] DREAMSHADER_ALLOW_SHRINKING_NO carries no behavioural difference. It exists solely because UE 5.4 changed the trailing bool bAllowShrinking parameter of TArray::RemoveAt, TArray::Pop, FString::RightChopInline and FString::LeftChopInline into an EAllowShrinking enum. Both spellings mean "do not shrink the allocation". It is used throughout the plugin and is not a tuning knob.

[!NOTE] There are no raw #if ENGINE_MAJOR_VERSION, ENGINE_MINOR_VERSION or UE_VERSION_NEWER_THAN tests anywhere in the plugin outside this header. The one version test outside it is not C++: DreamShaderPass.Build.cs reads Target.Version to set DREAMSHADER_WITH_CUSTOM_PASS. Every version-dependent behaviour goes through these macros or that definition, which is what makes the table below exhaustive.

[!NOTE] (since 2.0.0) Where a member is younger than the oldest supported engine and nobody can say in which release it arrived, the code asks the type instead of a version: if constexpr (requires { … }) inside a small template, with a static_assert of the same question on the engine where the member is known to exist, so a misspelling cannot read as "this engine does not have it". Those sites are listed under Asked of the type.

DREAMSHADER_WITH_CUSTOM_PASS

(since 2.1.0) The Custom Pass gate is not in this header. DreamShaderPass.Build.cs computes it from the engine being built against and adds it to the module's PublicDefinitions:

bool bForcedOff = Target.ProjectDefinitions.Any(Definition =>
    Definition == "DREAMSHADER_FORCE_NO_CUSTOM_PASS" || Definition == "DREAMSHADER_FORCE_NO_CUSTOM_PASS=1");
bool bWithCustomPass = !bForcedOff
    && (Target.Version.MajorVersion > 5 || (Target.Version.MajorVersion == 5 && Target.Version.MinorVersion >= 8));
PublicDefinitions.Add("DREAMSHADER_WITH_CUSTOM_PASS=" + (bWithCustomPass ? "1" : "0"));

The module builds on every engine. Every reflected type in it is plain data, so pipelines, the settings, the components and the volume load and save on any supported engine; below 5.8 nothing renders them. What 0 compiles out, module by module, is under UE ≥ 5.8 — DREAMSHADER_WITH_CUSTOM_PASS.

Complete version-gated behaviour

Every site in the plugin guarded by one of these macros, grouped by the version it requires. Diagnostics are cited by code; the strings still quoted below are log lines, material-compile errors and UI text, which carry no code.

Decided by the node catalog

(since 2.0.0) Most of what the 1.x generator gated by engine version is no longer a DreamShader gate at all. The UE.* and Substrate.* nodes, their pins and properties, the values of their enumerated properties and the material attributes a source can write come from the builtin catalog, which is reflected from the running engine (every non-abstract UMaterialExpression class it has loaded). What an engine does not have, the catalog does not list, and the binder says so:

A catalog exported with dsc export-catalog from an older engine gives the same answers. The version gates that remain in C++ are the ones below.

UE ≥ 5.4 — DREAMSHADER_UE_VERSION_AT_LEAST(5, 4)

UE ≥ 5.4 — DREAMSHADER_WITH_SUBSTRATE_BUILTINS

The Substrate gate is a separate macro so it can be overridden independently, but its default threshold is the same 5.4.

UE ≥ 5.5

The periodicworld basis and the PeriodicWorldTileSize argument are no longer gated here (since 2.0.0): see Decided by the node catalog.

UE ≥ 5.6

The firstperson bases and the FirstPersonInterpolationAlpha argument are no longer gated here (since 2.0.0): see Decided by the node catalog.

[!NOTE] DREAMSHADER_ENGINE_EXPRESSION_CLASS is a link-time gate, not a compile-time one. UE 5.6 changed UHT to emit DECLARE_CLASS2 with an exported Z_Construct_<Class>_NoRegister, so StaticClass() resolves from a plugin even for a UCLASS() that carries neither MinimalAPI nor ENGINE_API. UE 5.5 and earlier emit DECLARE_CLASS(..., NO_API): GetPrivateStaticClass never leaves Engine.dll, and naming StaticClass() compiles on every engine and then fails with LNK2019. Only a full RunUAT BuildPlugin sees it — an editor build against one engine never will.

Asked of the type

(since 2.0.0) No version number here: each row is decided by whether the engine's own type has the member -- or, (since 2.0.1), whether the engine has the node's header at all (__has_include).

DREAMSHADER_WITH_PARAMETER_COLLECTION_PARAMETERS

(since 2.0.0)

UE ≥ 5.7

UE ≥ 5.8

UE ≥ 5.8 — DREAMSHADER_WITH_CUSTOM_PASS

(since 2.1.0) Custom Pass as a whole. The language does not change: a .dsp parses and binds on every engine, and so does a .dss — what changes is what the engine side can build and run.

"Since UE 5.x" summary

Nodes, pins, enumerators and material attributes that only newer engines have are not in this table: the running engine's catalog decides them (above). Everything else works identically on every engine from 5.3 to 5.8. A .dsp is the one source that parses and binds everywhere and builds on 5.8 only.

Notes

• The gate is compile-time, not run-time. The plugin binary built against UE 5.3 does not contain the Substrate code paths at all. Moving a project to a newer engine requires rebuilding the plugin to gain the newer behaviours.
• GetInputsView() survives in exactly one place. Epic deprecated it in favour of FExpressionInputIterator and UMaterialExpression::GetInput(), and naming it produces C4996 on UE 5.8 — a warning today, a compile error in whichever release removes it. The remaining call is the UE 5.3 – 5.4 branch of GetDreamShaderExpressionInputCount, where CountInputs() does not exist yet and the deprecation is not in force; every other site asks for a pin by index.
• (since 2.0.0) A node, pin, enumerator or attribute the engine lacks is missing from its catalog, so a source that uses one is an error when it is bound; 1.x dropped some of them (an unread argument) without a word. Only a few of those errors name a version — DSH5294 (a Substrate node from a later engine), DSH5300 (UE.UserSceneTexture, the Custom Pass nodes), DSH7128 (ShadingModel="Substrate" on 5.3) and DSH8300 (a .dsp below 5.8); the rest say that the node, pin, value or attribute does not exist (DSH5210, DSH5213, DSH5215, DSH5200). The substrate-builtins.json manifest on 5.3 still carries an unsupportedReason. To build one source on several engines, guard the newer code with #if DS_ENGINE_MINOR >= ….
• DREAMSHADER_WITH_SUBSTRATE_BUILTINS is evaluated as a value, so it must be written #if DREAMSHADER_WITH_SUBSTRATE_BUILTINS, not #ifdef. It is always defined.
• DREAMSHADER_UE_VERSION_AT_LEAST is defined unconditionally, so pre-defining it in a build target produces a macro redefinition. Override the three version-number macros instead.
• Because DreamShaderModule.h includes this header, any translation unit that uses the plugin's path helpers also has the macros available.

Example

Guarding project code that consumes a version-gated DreamShader behaviour:

#include "DreamShaderVersionCompat.h"

void ConfigureShadingModel(FString& OutSettingValue)
{
#if DREAMSHADER_WITH_SUBSTRATE_BUILTINS
    OutSettingValue = TEXT("Substrate");
#else
    OutSettingValue = TEXT("DefaultLit");
#endif
}

void TrimTrailing(TArray<int32>& InOut)
{
    if (InOut.Num() > 0)
    {
        InOut.RemoveAt(InOut.Num() - 1, 1, DREAMSHADER_ALLOW_SHRINKING_NO);
    }
}

#if DREAMSHADER_UE_VERSION_AT_LEAST(5, 6)
// Plugin-rooted asset paths are mount-validated here; a packaged-but-unmounted plugin is an error.
#endif

The corresponding DreamShaderLang source, written so it compiles on 5.3 as well:

Shader(Name="Materials/M_Portable")
{
    Settings { ShadingModel = "DefaultLit"; }   // "Substrate" would require UE 5.4+
    Outputs  { vec3 Color; Base.BaseColor = Color; }
    Graph    { Color = UE.TransformVector(Input = UE.VertexNormalWS(), Source = "World", Destination = "Tangent"); }
}

See also

• C++ API — modules, headers, and linkage
• DreamShaderModule.h — the header that includes this one everywhere
• DreamShaderSettings.h — the Strata alias gate in the shading-model catalogue
• Substrate.* — the builtin family behind DREAMSHADER_WITH_SUBSTRATE_BUILTINS
• Transform builtins — the version-gated basis names
• UE.* catalogue — the nodes the reflected catalog offers
• Material enums — where Substrate appears as a shading model
• Path(...) — plugin roots and the 5.6 mount check
• Asset paths — Root="Plugin.X" and the 5.6 mount check
• Decompiler — the version-gated round-trip properties
• DreamShaderPass — the module whose rules file defines DREAMSHADER_WITH_CUSTOM_PASS
• Custom Pass runtime — what runs on 5.8
• Diagnostics index — every code, including the version-requirement ones