Decompiler

DreamShader » Tools » Decompiler

The exporter that walks an existing UMaterial or UMaterialFunction node graph and writes an equivalent DreamShaderLang source file.

[!IMPORTANT] There are two decompilers. This page describes the 1.x one, which writes .dsm / .dsf and is kept behind -Format=Legacy. The 2.0 decompiler is the default: it reads the asset's graph into the compiler's own IR and prints a .dss — or a .dsi for a material instance — and its output is proved: the text is compiled again and the two IRs are compared. A Custom Pass pipeline, which has no graph, comes back as a .dsp, read back and compared with the asset (since 2.1.0). See The 2.0 decompiler at the end of this page.

[!NOTE] Treat the 1.x decompiler as a migration starting point, not a round-trip guarantee. It reproduces the graph's structure and the parts of the node state it can express, then leaves a // Warning: comment for everything it could not. The known round-trip gaps below are the ones worth checking by hand before deleting the original asset.

Invoking it

Without -Format=Legacy (or a .dsm / .dsf -Out), the commandlet runs the 2.0 decompiler (since 2.0.0); the Export .dss entry beside each legacy one does the same from the editor.

Both editor routes require exactly one selected asset, write the file, and then open it in your preferred editor. See Editor integration and Commandlet.

A progress dialog appears after a 0.25 s delay, titled Decompiling Material '{Asset}'... or Decompiling Material Function '{Asset}'..., with one progress frame per visited node. The dialog is suppressed in commandlet runs.

Output paths

<SourceDirectory> is the Source Directory project setting, DShader by default. The layer and layer-blend directories are separate from Functions, and the class test is ordered blend-first, so a layer blend never lands in Layers.

Inside the category directory the asset's package path becomes the relative file path, one directory per package segment:

/Game/Materials/Metal/M_Steel
  →  <Project>/DShader/Decompiled/Materials/Game/Materials/Metal/M_Steel.dsm

Passing -Out= to the commandlet overrides the whole computation and writes exactly where told (after path normalization). The editor routes never take an override.

The generated asset name

The Name= written inside the file is not the file path. It is Decompiled/<Category>/<package segments> with \ / . : replaced by _ in each segment:

/Game/Materials/Metal/M_Steel
  →  Shader(Name="Decompiled/Materials/Game/Materials/Metal/M_Steel")

Recompiling the exported file therefore creates a new asset under /Game/Decompiled/Materials/…, leaving the original untouched. Edit Name= and Root= when you are ready to take over the original path. See Asset paths.

File layout

// Decompiled from <full object path>
[// Warning: <text>]…

[<VirtualFunction declaration>]…

{ Shader | ShaderFunction | ShaderLayer | ShaderLayerBlend }(Name="<generated name>")
{
    [Properties = { … }]
    [Inputs     = { … }]   // function kinds only
    [Settings   = { … }]   // Shader only
    [Outputs    = { … }]
    [Graph      = { … }]
    [Layout     = { … }]
}

The Settings block of a decompiled Shader always begins with Domain, ShadingModel and BlendMode, emitted unconditionally. Every other setting is emitted only when it differs from the UMaterial class default; the round-trip set is listed on Shader settings. When a Base.FrontMaterial binding was decompiled the shading model is forced to Substrate, because a Substrate material's own shading-model enum does not describe its surface.

Outputs declares one variable per connected material property and binds it, in the fixed order EmissiveColor, BaseColor, Metallic, Specular, Roughness, Anisotropy, Opacity, OpacityMask, Normal, Tangent, WorldPositionOffset, SubsurfaceColor, CustomData0, CustomData1, AmbientOcclusion, Refraction, PixelDepthOffset, MaterialAttributes, and — on UE 5.4 and newer — FrontMaterial. Unconnected properties are skipped entirely.

Terminal output nodes

A UMaterialExpressionCustomOutput (ThinTranslucentMaterialOutput, ClearCoatNormalCustomOutput, VolumetricAdvancedMaterialOutput, VertexInterpolator, …) has no output pins, so the material root cannot reach it — it is exported from the node list instead, as an Expression( … ) output binding. One Outputs variable is declared per connected input pin, named after the pin, and the pin's whole input subtree lands in Graph. Which spelling is written depends on how many pins are connected:

Both spellings regenerate the same single node; the block form is chosen for multi-pin nodes because it states that intent in the syntax instead of leaving it to N repeated argument lists. A file that decompiled to the statement form before 1.9.0 still decompiles to it byte for byte.

Class= carries the reflected class name (MaterialExpressionThinTranslucentMaterialOutput, no U prefix), which is a spelling Expression(Class=…) resolves.

[!WARNING] Output-target nodes are de-duplicated by class plus argument list, so a material holding two nodes of the same class cannot round-trip. The decompiler exports the first and records the warning Material has more than one '{Class}' node; output targets are de-duplicated by class, so only the first was exported.

What is exported faithfully

The node walker has a curated case for each class below. Everything else falls through to the generic fallback.

Emitted as DreamShaderLang syntax

Unconnected operand pins fall back to the node's own constant property when it has one — Min, Max, LinearInterpolate, Power and Clamp all read their Const* values — otherwise to a literal 0.0.

Emitted as a property declaration

These become entries in the Properties section and are referenced by name in the Graph. Names are uniquified, and a ParameterName= metadata entry is added whenever the DreamShaderLang identifier had to differ from the asset's parameter name.

A TextureSampleParameter2D with any connected input pin is emitted as a curated UE.Expression instead, carrying its parameter arguments and its sampler arguments together (since 1.3.7). Its RGBA output is emitted once into a named temporary; every other pin becomes a swizzle of it.

Emitted as a curated UE.Expression

These keep a hand-written argument list rather than a reflection dump, so only the properties that actually differ from the node default appear.

The UE.Expression fallback

Any class without a case above is exported as a generic UE.Expression call, and the decompiler records a warning.

The argument list is built in two passes:

1. Every connected input pin, named after the pin, in pin order.
2. Every reflected literal property whose value differs from the class default (since 1.3.7).

A property is exported in pass 2 only when all of these hold:

Names are compared after normalization, so bTwoSided and Two Sided collide.

[!WARNING] Struct, array, map, set and delegate properties are dropped silently. They are not one of the supported property types, so a node whose state lives in a struct exports with that state at its class default and no warning names the specific property. Re-set those by hand after the first compile, or keep the node as UE.Expression and add the missing arguments yourself.

OutputType is always emitted, resolved from the real output index. When a named output selector (Output= / OutputName=) is present, OutputIndex is suppressed, because a call that carries both is DSH5252. Calls with more than three arguments, or longer than 120 characters, are emitted across multiple lines.

Layout export

Controlled by the Export Decompiled Layout project setting, default on. When on, the file gets a Layout section:

Comment boxes whose text begins with DreamShader: are skipped — those are generated markers, not authored comments.

Independently of the setting, each expression is also assigned to the smallest comment box that encloses it, and those assignments become #Region / #EndRegion directives around the corresponding Graph statements. Turning layout export off removes the Layout block but not the regions.

See Layout.

Diagnostics

Runtime substitutions are shown as {Placeholder}.

Warnings written into the file

Each is emitted once, as a // Warning: … comment under the // Decompiled from … header line. They do not fail the export.

Export failures

Editor toasts

The same toasts for every Export entry, the 2.0 ones included (since 2.0.0):

Logs: Exported '{Asset}' to '{File}'. at Display, and Failed to export '{Asset}' to a DreamShader source: {Reason} at Warning.

Known round-trip gaps

Verified behaviour of 1.5.0. Each row is something the exported file will not reproduce.

Example

Export /Game/Materials/M_Steel headlessly, then inspect the result:

& "$Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "I:\Project\Project.uproject" `
    -run=DreamShader decompile -Asset="/Game/Materials/M_Steel" -Format=Legacy `
    -unattended -nopause -nosplash -stdout -log

DreamShader decompiled '/Game/Materials/M_Steel.M_Steel' to
'I:/Project/DShader/Decompiled/Materials/Game/Materials/M_Steel.dsm' (legacy).

The written file:

// Decompiled from /Game/Materials/M_Steel.M_Steel
Shader(Name="Decompiled/Materials/Game/Materials/M_Steel")
{
    Properties = {
        ScalarParameter Roughness_0 = 0.35 [ParameterName="Roughness"];
        VectorParameter Tint = float4(0.8, 0.8, 0.82, 1.0);
    }
    Settings = {
        Domain = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode = "Opaque";
    }

    Outputs = {
        float3 BaseColor;
        float Metallic;
        float Roughness;

        Base.BaseColor = BaseColor;
        Base.Metallic  = Metallic;
        Base.Roughness = Roughness;
    }

    Graph = {
        BaseColor = Tint.rgb;
        Metallic  = 1.0;
        Roughness = saturate(Roughness_0);
    }

    Layout = {
        Node(Var="Tint", X=-640, Y=-208);
        Node(Var="Roughness_0", X=-640, Y=48);
    }
}

The 2.0 decompiler

./dsc.ps1 decompile /Game/Materials/M_Steel                  # writes DShader/Decompiled/.../M_Steel.dss
./dsc.ps1 decompile /Game/Materials/MI_Steel_Worn            # a material instance: MI_Steel_Worn.dsi
./dsc.ps1 decompile -SourceFile DShader/Functions/Lib.dss    # every asset that source builds, in one file
./dsc.ps1 decompile /Game/Materials/M_Steel -Format Legacy   # the 1.x text described above

It is the compiler run backwards: graph → IR → AST → printer.

1. Import. Each expression is read back as the IR op the emitter writes for it; anything else is a reflected UE.<Class>(...) node over the builtin catalog. Inline pin masks become swizzles by the emitter's own rule, comment boxes become #pragma regions, node positions become #pragma layout hints. Two classes keep their pins in arrays no call can name, and are read back as what they compute instead: a Convert node (Make / Break FloatN) as the channels each output is put together from (DXY.xy, float3(Gain, 0.25, 0.75)), a Switch as the branches the engine makes of it (0.0 == floor(s) ? a : 1.0 == floor(s) ? b : default, or the one input the number picks when nothing is wired to SwitchValue) -- where a case has no name. A Switch whose wired cases are all named is the Switch itself, as the Landscape nodes below are: UE.Switch(SwitchValue = s, Dry = a, Wet = b, Inputs = "((InputName=\"Dry\"),(InputName=\"Wet\"))"). A VertexInterpolator, a custom output that also hands a value on, is that value wherever something reads it. A class that keeps its pins in an array of structs and names each after its entry -- LandscapeLayerBlend, LandscapeGrassOutput, LandscapePhysicalMaterialOutput, RenderTrace's PhysicalMaterialOutput of the same shape -- is called with the array as the text the details panel pastes, pins left out, and each pin by the name the node shows in identifier form: UE.LandscapeLayerBlend(Layer_Grass = g, Height_Rock = h, Layers = "((LayerName=\"Grass\"),...)").
2. Raise. Nodes nothing reads are pruned, and the shapes the emitter lowers by hand are read back (a StaticSwitch over a static bool is an if / ?:, a Set-attributes chain is m.X = ...). A Substrate node stays the call it is -- Substrate.Weight(...), SSSMFP = Substrate.TransmittanceToMFP(...).MFP -- so the text names every node the graph shows. Only the readable form reads the Substrate sugar back, wherever that is graph-exact: SubstrateAdd / SubstrateWeight / SubstrateHorizontalMixing with nothing set on them are A + B, A * w and lerp(A, B, t), and a conversion node that feeds one BSDF and nothing else becomes BaseColor = ... / Haziness = ... / Transmittance = ... on that BSDF.
3. Write. Uniforms in display order (@sort only where a priority is not the uniform's place), a local for a value that is read twice or that a statement named, custom functions recovered from their node's code with their helpers, layers and blends in their own signatures, an extern prototype for every function asset the graph calls.
4. Prove. The printed text is parsed again (DSH9089 if it does not), and the round-trip tests compile it and compare IRs.

What the language cannot say is named, never dropped silently: DSH9060–DSH9074 from the import (a missing function asset, a class outside the catalog, a Preview-pin default expression, additional defines on a Custom node) and DSH9075–DSH9084 from the writer (a renamed identifier, positions of values written inline, an extern inferred from its calls).

These engine classes still keep pins or outputs in arrays the text has no spelling for; a node of one of them comes back as a reflected call without those wires (DSH9070) or that state (DSH9068), and has to be finished by hand:

A Substrate node is written under the name sources use — Substrate.Slab(...), the first alias the catalog lists for the class — rather than the reflected SubstrateSlabBSDF; both resolve to the same class.

A plain UMaterialInstanceConstant is written as a .dsi: the parent, the #pragma instance keys it overrides, and the parameters that differ from the parent.

Pipelines (.dsp)

(since 2.1.0) A UDreamPassPipeline has no graph to import. Its fields are read back into the payload a .dsp binds to — the mapping the emitter applies, run the other way — and the printer writes that payload as a .dsp: #pragma pipeline, the uniforms, the buffers and the passes, in the asset's order, with every key left out that would read back as the default.

./dsc.ps1 decompile /Game/Passes/CP_Highlight                # DShader/Decompiled/Pipelines/Game/Passes/CP_Highlight.dsp
./dsc.ps1 decompile -SourceFile DShader/Passes/CP_Highlight.dsp
./dsc.ps1 decompile /Game/Passes/CP_Highlight -Out I:/Work/CP_Highlight.dsp

There is no Content Browser or Material Content Browser entry that decompiles a pipeline.

What the text cannot say the way the asset has it is a warning, written at the head of the file as a // Warning: DSHnnnn: … line in English, and raised as a diagnostic:

A fixed-size buffer's Scale, which the asset may still hold, is not written: Size excludes it.

The re-parse check. Before the text is handed back it is parsed again and bound without the engine — the references taken as written, and every check that needs the project skipped — and the payload it binds to is compared with the asset's, the facts only the engine knows (what a reference resolves to, a .usf's [numthreads]) taken from the asset where the text spells the reference the same way. A text that does not parse is DSH9221; one that does not bind into a pipeline is DSH9222 — the asset breaks a rule a .dsp is checked against, which a hand edit can do, or the decompiler is at fault; one that reads back as a different pipeline is DSH9223, naming the first difference. All three are warnings: the file is written as it is, and they are not copied into its head.

See also

• Editor integration — the Export .dss and Export Legacy .dsm / .dsf menu entries
• Commandlet — -run=DreamShader decompile, -Asset and -Out
• UE.Expression — the generic call the fallback emits
• Layout — Node and Comment directives, and #Region
• Shader settings — the settings the exporter can and cannot emit
• Function settings — the keys a decompiled .dsf will be missing
• VirtualFunction — the declaration emitted for each called function
• VirtualFunction tools — the same declaration builder, driven from the asset menu
• Asset paths — what the emitted Name= resolves to
• Graph layout — what happens when no Layout block is present
• Project settings — Export Decompiled Layout and Source Directory
• Substrate builtins — the UE 5.4 gate behind Base.FrontMaterial
• Custom Pass pipelines — .dsp — the text a pipeline decompiles to
• Divergence — Adopt Into Source for a pipeline edited in its details panel