Commandlet

-run=DreamShader is the headless entry point. It compiles DreamShader sources into persistent assets and decompiles existing material assets back into source files, with no editor UI and no bridge running.

Synopsis

UnrealEditor-Cmd.exe <project>.uproject -run=DreamShader <command> [<option>…]

<command> ::= { compile | generate | decompile | export }

-run=DreamShader { compile | generate } { -Source=<path> | -File=<path> | -All } [-Force]
-run=DreamShader { decompile | export } -Asset=<object-path> [{ -Out | -Output }=<path>]

Commands

The command name is the first bare (non--) argument. If there is no bare argument, a Command=<name> parameter is consulted instead. Matching is case-insensitive and surrounding whitespace is trimmed.

Anything else fails with Unknown DreamShader command '{Command}'. followed by the usage banner, and exits 1.

compile / generate

Precedence: -Source is looked up first, then -File; -All is consulted only when neither yielded a value. -Source and -All together silently compiles only the one file. With none of the three, the usage banner is logged at Error and the run exits 1.

-Force bypasses the source-hash skip only. It deletes nothing.

-Source path resolution

Tried in this order; the first that applies wins.

<SourceDirectory> is the Source Directory project setting, default <Project>/DShader. A relative value therefore resolves against the DreamShader source tree first and the project directory second.

-All discovery and ordering

Step 4 is a guarantee, not an accident: function assets referenced by a material must exist before that material is generated, and the two-rank sort provides that within a single run. Step 2 has a sharp edge for .dsf files that live inside packages — see Packages.

Per-file guard

Each file in the compile list is checked before compiling. A path that is not a DreamShader source, or that is a .dsh header, logs DreamShader compile requires a .dsm or .dsf file: {Path}, marks the whole run failed, and the loop continues with the remaining files. One bad file therefore does not prevent the rest from compiling — but the process still exits 1.

Result messages

Each file's compile result is logged verbatim: Display on success, Error on failure. When one file produces several assets, the messages are joined with newlines.

A message ending in (virtual) indicates a transient asset; the commandlet never produces those.

decompile / export

Asset path normalization

The normalized path is loaded first. If that fails and normalization actually changed the string, the raw (quote-stripped) input is retried unchanged.

Supported asset classes

Path segments are sanitized: control characters and < > : " / \ \| ? * become _; an empty folder segment becomes Folder<N> and an empty asset segment becomes Asset<N>. Output is UTF-8 without BOM. -Out bypasses the computed destination entirely, creating the directory if needed. The full exporter behaviour is on Decompiler.

Argument syntax

Shared by every command, and pinned by the automation test DreamShader.Commandlet.Args.SplitAndGet.

Boolean flags

A flag may be written bare or with a value. The value is lowercased before matching.

Exit codes

What does not run

• The editor bridge never starts inside a commandlet. The editor module returns from startup as soon as it detects a commandlet process, so there is no source-directory watcher, no auto-compile-on-save, no WebSocket server on port 17864, no diagnostics.json writer, no bridge.db, and no menu registration.
• The only exception is the cook commandlet, which installs a post-engine-init hook. On the cook director only — a process whose -run= contains Cook and that does not carry -cookworker — DreamShader materializes every project source as a persistent asset before the cook proper. A generation failure there is Fatal and aborts the cook.
• Adding -NoDreamShaderEditorBridge to a non-commandlet automation run (for example -ExecCmds="Automation RunTests …") suppresses the bridge there too — see Editor Tools.

Diagnostics

All messages go to LogDreamShader. Runtime substitutions are written {Placeholder}.

The usage banner, verbatim:

Usage:
  -run=DreamShader compile -Source="C:/Project/DShader/File.dsm" [-Force]
  -run=DreamShader compile -All [-Force]
  -run=DreamShader decompile -Asset="/Game/Path/Asset.Asset" [-Out="C:/Project/DShader/Decompiled/File.dsm"]
Supported asset types: Material -> .dsm, MaterialFunction -> .dsf.

Examples

Compile a single source, bypassing the hash skip:

& "C:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "C:\Projects\MyGame\MyGame.uproject" `
  -run=DreamShader compile -Source="C:/Projects/MyGame/DShader/Materials/M_Sample.dsm" -Force `
  -unattended -nopause -nosplash -stdout -log

Compile every project source — .dsf first, then .dsm — as a CI gate:

& "C:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "C:\Projects\MyGame\MyGame.uproject" `
  -run=DreamShader compile -All -Force `
  -unattended -nopause -nosplash -stdout -log

Decompile an existing material to a chosen path:

& "C:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "C:\Projects\MyGame\MyGame.uproject" `
  -run=DreamShader decompile -Asset="/Game/Materials/M_Existing" `
  -Out="C:/Projects/MyGame/DShader/Decompiled/Materials/M_Existing.dsm" `
  -unattended -nopause -nosplash -stdout -log

A relative -Source resolves against DShader/ first:

-run=DreamShader compile -Source="Materials/M_Sample.dsm"

Console output of a successful two-file -All run:

LogDreamShader: Display: Generated ShaderFunction /Game/Functions/MF_Noise from C:/Projects/MyGame/DShader/Functions/MF_Noise.dsf.
LogDreamShader: Display: Generated DreamShader thin-custom material /Game/Materials/M_Sample from C:/Projects/MyGame/DShader/Materials/M_Sample.dsm.

Where next