Editor integration

DreamShader » Tools » Editor integration

Every place DreamShader attaches itself to the Unreal editor UI: the Tools menu, the Level Editor toolbar, the Content Browser asset context menus, the Material Editor toolbar, the Window menu, the details panel of a Custom Pass pipeline, and the notifications it raises on its own.

Menu registration is idempotent — a second registration pass adds nothing — and is skipped while the editor is shutting down.

Tools menu

Tools ▸ DreamShader, extending LevelEditor.MainMenu.Tools, section DreamShader.

[!NOTE] The first five entries and the sixth are registered by two different startup callbacks into the same DreamShader section. Their relative order within the section is registration-order dependent and is not guaranteed between editor runs.

Level Editor toolbar

One Dream combo button, shared by the Dream-family plugins (DreamShader, DreamFX, DreamGUI): each plugin adds it if it is not there yet, so it appears once whichever of them loads first, and belongs to the owner DreamToolsShared, which no plugin unregisters.

DreamShader's section there, titled DreamShader:

Window menu

The Material Content Browser registers a nomad tab, which also lists it under Window ▸ Tools.

Content Browser context menus

All entries are added into the stock GetAssetActions section of the per-class asset context menu.

[!WARNING] Every DreamShader context-menu entry requires exactly one selected asset. With two or more assets selected the section is empty and nothing indicates why. Right-click a single asset.

Menu names in Unreal are keyed on the exact class, so an entry meant for both instance classes is registered twice — once for the stock class and once for the DreamShader subclass.

A UDreamPassPipeline (since 2.1.0) gets no DreamShader entry here. Its Open Source, Revert to Source and Adopt Into Source are on its details panel, its source is in the Material Content Browser, and it decompiles with dsc decompile.

Material submenu

DreamShader.MaterialActions — label DreamShader, tooltip "DreamShader actions for this Material.", icon Icons.Settings. Built only when the single selected asset is a UMaterial.

Section 1, DreamShader.ProvenanceActions, titled Generated Asset — the Generated Asset section below; empty for an asset DreamShader did not generate.

Section 2, DreamShader.DecompileActions, titled Decompiler:

Material Function submenu

DreamShader.MaterialFunctionActions — label DreamShader, tooltip "DreamShader actions for this Material Function.", icon Icons.Settings. The same submenu serves a material layer and a layer blend.

Section 1, DreamShader.ProvenanceActions, titled Generated Asset — the Generated Asset section below.

Section 2, DreamShader.DecompileActions, titled Decompiler:

Section 3, DreamShader.VirtualFunctionActions, titled VirtualFunction (since 1.2.1). Its contents depend on whether a VirtualFunction declaration already references this asset — the full table is on VirtualFunction tools.

The two extern Prototype entries (since 2.0.0) are the .dss counterpart of a VirtualFunction block: the function's extern prototype with its /// @asset line, copied to the clipboard or written to a new .dsh for .dss sources to #include.

Material instance submenus

A UDreamShaderMaterialInstance — the product of a ThinCustom Shader — gets submenu DreamShader.MaterialInstanceActions, label DreamShader, tooltip "DreamShader actions for this generated material.", with the Generated Asset section alone.

Any other UMaterialInstanceConstant — what a .dsi builds, or a hand-made instance — gets submenu DreamShader.MaterialInstanceConstantActions, label DreamShader, tooltip "DreamShader actions for this material instance.", icon Icons.Settings:

Generated Asset section

Section DreamShader.ProvenanceActions of every submenu above. It is empty unless the asset carries DreamShader's source metadata, so a hand-authored asset shows none of it.

Material Editor toolbar

DreamShader.MaterialEditorToolbarActions, a dynamic entry in section DreamShader of AssetEditor.MaterialEditor.ToolBar (since 1.2.1).

Pass pipeline details panel

(since 2.1.0) The details panel of a UDreamPassPipeline — the asset a .dsp compiles to — with three categories above the pipeline's own properties that read the asset the way a frame runs it. The properties stay, and stay editable: the panel is where a pipeline is tuned, and Adopt Into Source writes the tuning back into its .dsp.

Pipeline Overview

Passes in Frame Order

One group per injection point the pipeline uses, in the order a frame reaches them, titled <injection point> (<number of passes>), with its passes in declaration order — the order they run in. Another pipeline's passes at the same point run before or after these by Order. Each pass:

Buffers

One row per declared buffer, its tooltip the buffer's /// @desc: the format and the keys as the .dsp spells them (R8 Resolution = Render Scale = 0.5 Clear = 0 Export = true). An exported buffer adds a link, exported to <render target>, that shows the render target in the Content Browser — or, before the first compile, exported, but its render target does not exist yet: compile the source.

Edits

The rows read the asset live, so a value edited in the properties below shows above at once. Adding, removing or renaming a pass or a buffer, moving a pass to another injection point, and changing a slot, a shader path or an export rebuild the panel. An edit takes effect on the next frame and makes the pipeline diverge from what its .dsp built: until it is reverted or adopted, a rebuild of the changed .dsp refuses to overwrite it.

Notifications

The one surface on this page that DreamShader raises by itself rather than registering and waiting to be clicked. Notifications are suppressed wherever there is no Slate application or nobody to read one — a commandlet, a cook, a dedicated server, and any run with -unattended.

The two divergence notifications do not time out, because they ask a question; every other notification on this page is a four-second toast reporting something already done. Closing the editor retires any divergence notification still waiting for an answer.

Command semantics

Runtime substitutions in every quoted message on this page are shown as {Placeholder}.

Recompile DSM

Asks first — a Yes/No dialog, "Recompile every DreamShader .dsm and .dsf source file? This rebuilds all generated materials and can take a while on a large tree." On Yes, rebuilds the material dependency graph, then stamps every .dsm, .dsf, .dss, .dsi and .dsp of every source root into the pending queue with the current time, forced. A .dsm under a root's Packages folder is excluded; .dsh headers are never queued, because they build nothing. The files are then compiled by the debounce ticker exactly as if they had been saved.

Log: DreamShader queued a full .dsm/.dsf recompile scan.

Clean Generated Shaders

Deletes generated .ush includes and queues a full scan.

Make Ephemeral

Finds and deletes the Materialized ThinCustom products — the ones with a package on disk — because a saved product shadows the Ephemeral one generated from the same source.

Because the filter is provenance-based, hand-authored materials are never touched, while orphans whose source file was deleted or renamed still qualify.

Log: DreamShader made {Deleted} of {Total} Materialized product(s) Ephemeral.

Show Ephemeral Materials

Flips bShowEphemeralMaterials and writes it straight to the project's DefaultEngine.ini. It then walks every live UDreamShaderMaterialInstance whose package is newly created and broadcasts asset creation or asset removal, so tiles appear or disappear immediately rather than at the next re-enumeration.

[!WARNING] While Ephemeral materials are shown, they also appear in save pickers, and an explicit Save Materializes one. The saved copy then shadows the Ephemeral product. Recover with Make Ephemeral.

View ▾ ▸ Show Ephemeral materials in the Material Content Browser runs the same command on the same global setting, toast included.

Open Dream Shader Workspace (VSCode)

Runs in this order: re-export material-expressions.json, settings.json, substrate-builtins.json, preprocessor-defines.json and the builtin node catalog (dreamshader-builtin-catalog.json); rewrite DShader/DreamShader.code-workspace; then launch it through a three-step fallback chain — VSCode, the OS default editor, Notepad. See Workspace for the discovery order and the exact file contents.

Disabling the integration

UnrealEditor.exe "<Project>.uproject" -NoDreamShaderEditorBridge

The switch is parsed as a bare command-line parameter, so -NoDreamShaderEditorBridge is the only accepted spelling. When present, StartupModule returns before creating anything.

A commandlet run reaches the same state by a different route: the module returns early whenever IsRunningCommandlet() is true, installing only the cook-time asset materialization hook, and only when -run= contains Cook and -cookworker is absent.

Example

Launch the editor with the integration off, then do the same work headlessly:

# No menus, no watcher, no bridge.
& "$Engine\Binaries\Win64\UnrealEditor.exe" "I:\Project\Project.uproject" -NoDreamShaderEditorBridge

# The commandlet is unaffected by the switch.
& "$Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "I:\Project\Project.uproject" `
    -run=DreamShader compile -All -Force -unattended -nopause -nosplash -stdout -log

Notes

• Four of the VirtualFunction entry labels are CamelCase with no spaces — OpenVirtualFunction, CopyVirtualFunction, CreateVirtualFunction, CopyVirtualFunctionCall — while the fifth reads Copy Virtual Function Reference. The inconsistency is in the shipped labels.
• Deciding between the two VirtualFunction entry sets re-reads and re-lexes every project source file from disk, on every right-click of a Material Function asset. On projects with many sources the menu takes measurably longer to open. See VirtualFunction tools.
• The Show Ephemeral Materials toggle's checked state is read live from the settings object, so changing the value in Project Settings updates the menu check mark.
• Changing Default Compiler Backend, one of the three enum mapping tables or Preprocessor Defines in Project Settings regenerates every source file — not forced: each of them is part of the build key, so exactly the sources it affects fail the skip check — and raises a failure-state toast when Materialized ThinCustom products would shadow the result: {Count} previously generated asset(s) are still saved on disk and shadow the Ephemeral materials. Run Tools > DreamShader > Make Ephemeral to remove them. No other settings property triggers a reaction.

Material Editor node context menu

(since 2.0.0) Right-clicking a node in the Material Editor graph that DreamShader generated adds a DreamShader submenu, in a DreamShader section of the node's own context menu.

[!NOTE] A node with no recorded source position gets no menu at all — not a disabled one. Every node of every hand-authored material in the project is in that state, and a greyed-out entry on all of them would be noise. The same is true of an asset last built before 2.0.0, by the 1.x generator, which wrote no span table; every source, .dsm and .dsf included, is built by the 2.0 pipeline now, so a forced rebuild (compile -Force) gives its nodes the entries.

A failure is a four-second failure toast plus a LogDreamShader error carrying DSH9058 — either the source file is gone, or no launcher would start.

reveal-node — the reverse direction

(since 2.0.0) The bridge request that goes the other way: from a line of source to the node in the Material Editor. It is what the VSCode extension's Reveal in Material Editor command sends.

Served synchronously: it finds the assets stamped with that source file, picks the expressions whose span falls on the line, opens the Material Editor for the asset that owns them and selects the first. A node that starts on the line wins over one that was merely inlined from a call there.

The response is the ordinary Responses/<requestId>.json envelope with four fields added:

Failures come back as ok: false with the reason in diagnostics (stage: "navigate"), coded DSH9050–DSH9057. The two worth knowing: DSH9051 means no asset from that source is loaded in this editor — compile the file first — and DSH9052 means the assets exist but were built before node navigation, so they carry no span table and need a -Force rebuild.

See also

• Tools — the editor tooling hub
• Material Content Browser — the tab the Tools menu opens
• Decompiler — what Export .dss, Export .dsi and the two Export Legacy entries produce
• VirtualFunction tools — the conditional VirtualFunction section
• Workspace — the workspace file, VSCode discovery and the launch fallback chain
• Bridge — the file and WebSocket surfaces the switch disables
• Commandlet — the headless entry point
• Project settings — every setting these commands read or write
• Ephemeral materials — why persisted assets shadow generated ones
• Generated HLSL — what Clean Generated Shaders deletes
• Divergence — Revert and Adopt for a pipeline edited in its details panel