Project settings

DreamShader » Settings » Project settings

The project-wide configuration object: seventeen properties under Project Settings ▸ DreamPlugin ▸ Dream Shader, persisted to the project's DefaultEngine.ini.

Location

The panel is at Project Settings ▸ DreamPlugin ▸ Dream Shader — not under Plugins. Edits made in the panel, and the toggles the editor exposes elsewhere, are written straight back to DefaultEngine.ini.

Settings

Every configurable property, grouped by the category it appears under in the panel.

Rows in bold carry an explicit DisplayName; the others show the name Unreal derives from the property identifier, which drops a leading b from booleans.

Enumerators of EDreamShaderDefaultBackend

Full behaviour, including how a per-file Backend setting overrides this, is on Backend.

Verbatim tooltips

Scan Plugin Source Directories:

When enabled, every enabled plugin that ships a DShader folder contributes its own source root, so a plugin can carry the .dsm/.dsf/.dsh files that build its materials. Plugin roots are discovered and compiled but never rewritten by the editor -- only the project's own source directory is writable. Imports never cross roots: a file resolves its imports against its own root and that root's Packages folder.

Default Compiler Backend:

How DreamShader materializes a source file that does not specify Settings = { Backend = "..." }. ThinCustom (the default) builds the material graph on a hidden per-material base and emits a lightweight, Ephemeral material instance of it -- full feature surface, no visible per-material asset. Graph builds a visible UMaterial node graph. Instance is a deprecated alias for ThinCustom.

Show Ephemeral Materials:

Applies to the ThinCustom/Instance backend only -- it is the only one with an Ephemeral state, which it hides via UDreamShaderMaterialInstance::IsAsset. When enabled, Ephemeral materials appear in the Content Browser like unsaved assets. Disabled by default: the source files are the intended authoring surface, and hiding the materials also prevents accidental Save actions from materializing them to disk. Graph-backend materials are plain UMaterials with no way to opt out of asset enumeration, so they are always visible and this setting does not affect them.

Material Instance Subfolder:

Subfolder, relative to the parent material's folder, where the Material Content Browser creates new material instances. Leave empty to create them alongside the parent.

Sync Source References On Asset Rename:

When enabled, renaming or moving an asset in the editor rewrites the .dsm/.dsf/.dsh files that reference it, so a source keeps naming the asset rather than the path it used to have. Only files under the project source directory are rewritten -- plugin source roots are never touched -- and each file is copied to a .bak next to it before it is written. Batched renames such as Fix Up Redirectors are coalesced into a single pass. Deleting an asset is not covered: a deletion has no new path to write, and the compile error it produces is the correct outcome. Turn this off if you would rather the plugin never edited your source files on its own.

Preprocessor Defines:

Preprocessor defines every .dsm/.dsf/.dsh source compiles with -- what its #if / #elif conditions read. The name answers defined(); a value that parses as an integer compares as a number, anything else as a string; an empty value still counts as defined; a name absent from this table evaluates to 0, as in C. Conditions are evaluated at GENERATION time and the losing branch is cut before the parser sees it, so a condition can select a Domain, a ShadingModel or a whole Outputs block -- none of which a StaticSwitch can reach, because they describe what the material IS rather than what it computes. Editing this table rebuilds only the generated assets whose sources actually read a name that changed. Names are case-sensitive and must match [A-Za-z_][A-Za-z0-9_]*. The DS_ prefix is reserved for the read-only builtins; an entry using it is dropped with a log warning rather than failing the compile, since a settings mistake has no source line to report against.

The builtin names this tooltip alludes to are DS_ENGINE_MAJOR, DS_ENGINE_MINOR, DS_ENGINE_PATCH, DS_PLATFORM, DS_PLUGIN_VERSION and DS_SUBSTRATE; they are listed out in the preprocessor page. The tooltip names them only by their prefix because UHT caps a metadata string at 1024 characters, and spelling all six out went over it.

The mapping maps

The three Mappings entries extend the value spellings accepted by the three enum settings. They are empty by default: the built-in alias tables are rebuilt on demand during resolution and are never materialized into these maps, so an empty panel does not mean "no aliases".

The complete built-in tables are on Material enums.

Other places these settings are surfaced

Notes

• The class is Config=Engine, DefaultConfig, so values live in the project's Config/DefaultEngine.ini, not in a per-user file. They are shared by everyone who checks the project out.
• There is no persistence on/off toggle. A ThinCustom product is Ephemeral — source files are the authoring surface — and materialization to disk happens at cook, through the commandlet, or through an explicit action. Default Compiler Backend replaced the old In-Memory toggle in 1.5.0. Removed in 2.0.0: Lay Out In-Memory Graphs (bLayoutInMemoryGraphs). Graph layout now always runs; only the large-graph performance guard can skip it. The Show Ephemeral Materials key was bShowInMemoryMaterialsInContentBrowser before 2.0.0 and is migrated on load.
• GeneratedShaderDirectory is only consulted while the virtual shader directory is unmapped. If a mapping already exists for this project, the existing mapping wins over the setting until the editor restarts.
• The built-in shader library path setting was removed in 1.3.8; no replacement exists.
• The C++ surface of this object — the three TryResolve* methods, NormalizeMappingKey and the three BuildDefault*Mappings helpers — is documented in Settings API.

Example

<Project>/Config/DefaultEngine.ini, showing every scalar property at its default value:

[/Script/DreamShader.DreamShaderSettings]
SourceDirectory=(Path="DShader")
GeneratedShaderDirectory=(Path="Intermediate/DreamShader/GeneratedShaders")
DefaultBackend=ThinCustom
bShowEphemeralMaterials=False
bAutoCompileOnSave=True
SaveDebounceSeconds=0.250000
bVerboseLogs=False
bExportDecompiledLayout=True
bOpenInNewWindow=True
InstanceSubfolder=Instances
bSyncSourceReferencesOnAssetRename=True

The ini keys are the raw C++ identifiers, including the b prefix on booleans — bAutoCompileOnSave, not AutoCompileOnSave. The three mapping maps and Preprocessor Defines are container properties; edit them in the Project Settings panel and let the editor write them back. A hand-written entry uses the +Key=((…)) form:

+PreprocessorDefines=(("MOONTOON_LEGACY_TOON", "1"))

DreamShader Custom Pass

A second settings object sits beside this one: UDreamPassSettings, in the DreamShaderPass runtime module, at Project Settings ▸ DreamPlugin ▸ DreamShader Custom Pass. It is saved to the same DefaultEngine.ini, section [/Script/DreamShaderPass.DreamPassSettings], and configures the Custom Pass runtime. It exists on every engine; below UE 5.8 nothing reads it.

[/Script/DreamShaderPass.DreamPassSettings]
bEnabled=True
+GlobalPipelines=(Pipeline="/Game/Effects/CP_Wind.CP_Wind",bEnabled=True,Priority=0.000000)
+LayerNames=Highlight
+LayerNames=XRay

See also

• Custom Pass runtime — what GlobalPipelines and the layers feed
• Settings — the per-file Settings section this page's defaults interact with
• Preprocessor — what Preprocessor Defines feeds, and the four other tiers
• Backend — how Default Compiler Backend is overridden per file
• Material enums — the built-in tables the mapping maps extend
• Shader settings — the reflected UMaterial property surface
• Settings API — UDreamShaderSettings in C++
• Material instance API — the IsAsset() behaviour driven by the visibility toggle
• Ephemeral materials — what "memory-only" means in practice
• Generated HLSL — what GeneratedShaderDirectory receives
• Material Content Browser — the Project page and the instance factory
• Decompiler — the layout-export toggle
• Workspace — VSCode launch and the exported settings manifest
• Asset rename sync — what Sync Source References On Asset Rename switches on
• Editor integration — the Tools menu entries