The Pipeline

DreamShaderLang does not compile to bytecode or to an executable. It compiles to Unreal assets: a UMaterial or a UDreamShaderMaterialInstance, any number of material-function assets, and one generated HLSL include. This page follows one source file all the way through.

There is no runtime path. Nothing builds a material from DreamShaderLang in a packaged game; by then the assets already exist.

Stages

One compile of one file runs this sequence. Every step is a gate: the first failure aborts the compile, and its message is what comes back as the compile result.

Throughout this section, {Placeholder} marks a value the compiler substitutes at runtime.

Two consequences are worth pulling out of that table:

• The parse unit is the import closure, not the file. import directives are inlined before parsing, so "one Shader per file" is really "one Shader per closure" — and the source hash in step 6 covers every imported byte. See Imports and Namespaces.
• Material functions are generated before the material. A Shader can therefore call a ShaderFunction declared beside it in the same file.

Import lines are replaced by blank lines, and each inlined file is bracketed by // Begin DreamShader source: <path> / // End DreamShader source: <path> markers, so reported line and column numbers still point into the file you actually edited.

Steps 9 and 10 share the same graph builder. Requesting only the material — what the editor's compile material entry point does — runs steps 1–7 and 10, skipping 9.

Inside step 10 — the material

Inside the graph build

Shared by both backends. Under ThinCustom it runs against the hidden base material, not the emitted instance.

1. Clear the existing expressions, then reset every material property to its engine default.
2. Apply Settings.
3. Force Substrate shading when Base.FrontMaterial is bound.
4. Reject duplicate Properties names — compared ignoring case.
5. Seed one MakeMaterialAttributes node per uninitialized MaterialAttributes output declaration.
6. Build the body — either the Graph block, or, when the unit has no Graph and no initialized output, one whole-surface Custom node.
7. Connect each Outputs binding.
8. Lay the graph out. Skipped in memory-only mode, and skipped for graphs of 1200 or more expressions unless a Layout section is present.
9. Recompile the material.

Step 1 is why editing a generated asset by hand is futile — see Regeneration.

What triggers a build

Auto-compile is governed by two project settings: Auto Compile On Save (default on) and Save Debounce Seconds (default 0.25, clamped to [0.05, 10.0]). Turning the first off makes the source-directory watcher ignore file changes entirely. See Project Settings.

Outcomes that are not assets

A source file can compile successfully and still produce nothing you can place in the Content Browser.

The last row is the one to watch: a file that declares nothing generatable is an error, while a file that declares only helpers is fine.

Success messages

Parser warnings never fail a compile. They are appended to whichever message above applies, under a Warnings: header.

Progress reporting

Generation reports through Unreal's slow-task system. Dialogs are delayed so a fast compile never flashes one, and are suppressed entirely under IsRunningCommandlet().

Worked example

// DShader/Materials/M_Emissive.dsm
import "Common.dsh";

ShaderFunction(Name="Functions/F_Tint")
{
    Inputs  { vec3 InColor; vec3 InTint; }
    Outputs { vec3 OutColor; }
    Graph   { OutColor = InColor * InTint; }
}

Shader(Name="Materials/M_Emissive")
{
    Properties { vec3 Tint = vec3(1.0, 0.4, 0.1); }
    Settings   { ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }
    Graph      { Color = F_Tint(vec3(1.0, 1.0, 1.0), Tint); }
}

One compile of that file produces:

Intermediate/DreamShader/GeneratedShaders/M_Emissive_9f2c41ab.ush   (only if Common.dsh declares Function blocks)
/Game/Functions/F_Tint                                             UMaterialFunction
/Game/Materials/M_Emissive                                         UDreamShaderMaterialInstance + hidden UMaterial base

and reports:

Generated ShaderFunction /Game/Functions/F_Tint from I:/.../M_Emissive.dsm.
Generated DreamShader thin-custom material /Game/Materials/M_Emissive from I:/.../M_Emissive.dsm.

The .ush include lives under the Generated Shader Directory project setting (default Intermediate/DreamShader/GeneratedShaders) and is mapped to the virtual shader path /DreamShaderGenerated/. Its file name embeds a hash of the source path, not of the source text, so editing a Function body rewrites the same file instead of accumulating variants.

Where next