Backend

DreamShader » Settings » Backend

The Shader setting that selects how a source file is materialized: a visible UMaterial node graph, or a thin material instance over a hidden base material.

Synopsis

Shader(Name = "<asset-path>")
{
    Settings [=] {
        Backend = { "Graph" | "ThinCustom" | "Instance" };
    }
}

The value is matched case-insensitively after trimming and quote-stripping; quotes are optional. Backend is a special key: it is read when the source is bound and never reaches the material or the reflection resolver. The 2.0 spelling is #pragma material(Backend = ThinCustom).

Accepted values

[!WARNING] Backend = "Instance" is deprecated since 1.5.0. It is an alias for ThinCustom; the legacy graphless instance backend is retired and there is no runtime Instance backend left. The spelling still compiles, and since 2.0.0 it says so with a DSH7204 warning. Replace it with Backend = "ThinCustom"; — or delete the key and let the project default apply.

[!NOTE] Backend = ""; is an error (since 2.0.0). 1.x read it as Graph, which silently overrode the project default with a value nobody wrote. Only omitting the key falls back to Default Compiler Backend; write Graph if that is what you mean.

Precedence

An explicit Backend always wins over the project setting. The project setting is described in Project settings.

Backend is resolved when the source is bound, before any material object exists and before the rest of Settings is applied. An unrecognized value is a binding error, so the compile stops there and no settings diagnostic of the build is reported for that file.

What each backend produces

Graph

ThinCustom (since 1.5.0)

UDreamShaderMaterialInstance overrides two UObject/UMaterialInterface behaviours:

A build that finds a saved asset where an Ephemeral one was asked for logs a warning: '{Asset}' exists as a saved asset, so it is rebuilt and saved on disk rather than in memory. Run Tools > DreamShader > Make Ephemeral to make it Ephemeral again. See Ephemeral materials.

Changing the project default

Changing Default Compiler Backend while the editor is running rebuilds the project's sources and logs DreamShader setting '{Setting}' changed; regenerating all source files. A source the change does not affect is skipped by its build key. If persisted generated assets exist, a notification points at the cleanup action: {Count} previously generated asset(s) are still saved on disk and shadow the Ephemeral materials. Run Tools > DreamShader > Make Ephemeral to remove them.

Switching an individual material between backends leaves the previous asset behind. The reuse-conflict errors above are what you hit next; delete the stale asset and regenerate.

Notes

• The backend does not change the language surface. Both backends build the same node graph and accept the identical feature set; they differ only in which object carries the graph and which object is addressable.
• Under ThinCustom, reading BlendMode or the shading model off the generated instance shows the value inherited from the hidden base — that is where the settings were written.
• A ThinCustom product is Ephemeral during ordinary editor work: it reaches disk at cook time, through the commandlet, or through an explicit Materialize action. A Graph material is saved when it is built. See Ephemeral materials.
• Backend is honoured only in a Shader block. In a ShaderFunction Settings block it is a DSH3263 warning and is ignored — see Function settings.

Diagnostics

Informational output:

Example

Shader(Name="Docs/M_ThinCustom", Root="Game")
{
    Properties {
        VectorParameter Tint = float4(0.2, 0.6, 1.0, 1.0) [Group="Look"];
    }

    Settings {
        Backend      = "ThinCustom";
        Domain       = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode    = "Opaque";
        TwoSided     = true;
    }

    Outputs {
        vec3 Color;
        Base.BaseColor = Color;
    }

    Graph {
        Color = Tint.rgb;
    }
}

Generated assets:

package     /Game/Docs/M_ThinCustom
asset       /Game/Docs/M_ThinCustom.M_ThinCustom      UDreamShaderMaterialInstance
subobject   MB_DreamThinBase_M_ThinCustom             UMaterial  (hidden base, same package)

Settings applied to:  MB_DreamThinBase_M_ThinCustom
  BlendMode    = BLEND_Opaque
  ShadingModel = MSM_DefaultLit
  TwoSided     = true

That listing is persist mode. In the editor's ordinary memory-only mode the instance is the same object, but the base is a separate transient-package object named MB_DreamThinBase__Game_Docs_M_ThinCustom — the sanitized package path, not the leaf.

The same file with Backend = "Graph"; instead produces a single UMaterial at /Game/Docs/M_ThinCustom carrying the graph and the settings itself.

See also

• Settings — the block grammar shared by every block kind
• Shader settings — the other special keys and the reflection resolver
• Project settings — Default Compiler Backend and the Ephemeral visibility toggle
• Ephemeral materials — memory-only generation, the hidden base, materializing to disk
• Generation pipeline — where backend resolution sits in the pipeline
• Asset paths — how Name and Root become a package path
• Caching — the source-hash skip
• Material instance API — UDreamShaderMaterialInstance in C++
• Shader — the enclosing block
• Material Content Browser — materializing and inspecting generated assets
• Diagnostics index — every code