Dream Shader Optimize

dream-shader-optimize <file>

A decompiled or migrated source builds the right graph, but it reads like a machine wrote it. This skill turns it into the file a person would have written — and proves, node for node, that the graph did not change.

Paths below are relative to the plugin root, Plugins/DreamShader/.

The rule

Behaviour must not change. Renaming a local, inlining a value read once, naming a value read twice, moving repeated logic into a helper, swapping a class-exact node call for the HLSL that builds the same node — safe. Reordering lerp arguments, folding pow(x, 2) into x * x, dropping a saturate, renaming a parameter — not: those are changes, and they belong in a separate, explicitly requested edit.

Do this

1 — Read the file, its header warnings and the language. Every // Warning: DSHnnnn: … line under // Decompiled by DreamShader from … names something the text cannot state the way the asset has it; they are the work list (Docs/diagnostics/DSH9xxx.md). Read reference/dss.md.

A .dsm / .dsf from -Format Legacy? Do not clean 1.x text by hand. Decompile the asset again as 2.0 (the default) — or dsc migrate the file (dream-shader-migrate) — and optimize the .dss. The 2.0 text starts far cleaner: a value read once is already inline, one read twice already has one local, literals are exact.

2 — Capture the graph before touching anything. dump-graph generates the source in memory and writes a canonical JSON of each asset's graph — node classes, properties, connections, pin order; no coordinates, no GUIDs. It writes no asset:

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 dump-graph DShader/Decompiled/Materials/Game/M_Steel.dss -Out Saved/Optimize/before

If an asset of that path already exists on disk, dump-graph reads it as it stands instead of generating it (the run says so). A fresh decompile under Decompiled/ has none.

3 — Apply the passes below. Then check it.

4 — Prove nothing changed.

pwsh -File Plugins/DreamShader/.skill/dsc.ps1 dump-graph DShader/Decompiled/Materials/Game/M_Steel.dss -Out Saved/Optimize/after
git diff --no-index -- Saved/Optimize/before Saved/Optimize/after

Every hunk is a behavioural difference. The only acceptable ones are those the user asked for, and the Constant nodes a -Readable decompile adds (the shader is the same). Anything else: undo that pass.

5 — Retarget, last. Move the file to the place that names the original asset, or give its export a /// @name /Game/Materials/Metal/M_Steel — the step that makes this source authoritative. Then compile -Force -CleanNew once; delete nothing until the rebuilt asset has been looked at in the editor.

6 — Report what changed, the dump diff verdict, and — separately — every header warning you could not resolve from the source alone. That list is for the human; it needs the original asset open.

The passes

Resolve the header warnings

Each // Warning: is something the asset has and the text could not say. Some are fixed in the source (a function asset that moved: correct the /// @asset path); some only in the original asset (re-assign it, decompile again); some are accepted with the user (a node property the language cannot state). Delete a warning line only once it is resolved or accepted.

Rename what deserves a name

Locals named after their node (Multiply_2, Sample, Combined) become what the value is: scanline, bandPhase, edgeFalloff.

• A renamed local must be renamed in its #pragma layout(Node, Var = …) line too, or that position is orphaned.
• A uniform's name is the parameter's name. Renaming it renames the parameter, and every material instance that overrides it silently loses the override. Keep the name — or rename with /// @name <the old name> above it, which keeps the parameter.
• An export function's name is the asset's name: renaming it moves the asset unless /// @name keeps it.

Prefer HLSL to class-exact node calls

UE.Multiply(A = x, B = y) is x * y; UE.LinearInterpolate(A = a, B = b, Alpha = t) is lerp(a, b, t). Write the HLSL where it builds the same node, and keep UE.<Class>(…) where the language has no spelling for it. Or decompile again with -Readable, which does this throughout (the graph may gain Constant nodes; the shader does not change).