Editor Tools

Everything DreamShader adds to the Unreal editor lives in one editor-only module. This page is the map: what appears where, what each command actually does, and how the Material Content Browser tab works.

None of it exists in a packaged game — the module is editor-only, and the runtime DreamShader module carries no UI at all. Menu registration is idempotent, so a second registration pass adds nothing, and it is skipped entirely while the editor is shutting down.

What starts, and in what order

The bridge's own startup then resets bridge.db, exports the three manifests, runs the VirtualFunction sync, queues a full scan, opens the preview WebSocket server on port 17864, registers the source-directory watcher, and installs the menus.

Tools menu

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

Level Editor toolbar

Extending LevelEditor.LevelEditorToolBar.AssetsToolBar, section DreamShader. Two buttons, both duplicates of Tools-menu entries.

Window menu

The Material Content Browser registers a nomad tab, which puts it under Window ▸ Tools as well.

Content Browser context menus

Every entry is added into the stock GetAssetActions section of the per-class asset context menu.

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

Material submenu

Label DreamShader, tooltip "DreamShader actions for this Material.", icon Icons.Settings. Built only when the single selected asset is a UMaterial. One section, Decompiler:

Material Function submenu

Label DreamShader, tooltip "DreamShader actions for this Material Function.", icon Icons.Settings. Two sections.

Decompiler:

VirtualFunction since 1.2.1 — its contents depend on whether a VirtualFunction declaration already names this asset. See VirtualFunction tools.

Material Editor toolbar

A dynamic entry in section DreamShader of AssetEditor.MaterialEditor.ToolBar since 1.2.1.

What each command does

Runtime substitutions in quoted messages are written {Placeholder}.

Recompile DSM

Rebuilds the material dependency graph, then stamps every project .dsm and .dsf into the pending queue with the current time. .dsm files under DShader/Packages are excluded; .dsf files there are not — see Packages. The queued files are then compiled by the debounce ticker exactly as if you had saved them.

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

Clean Generated Shaders

Deletes the generated .ush includes and queues a full scan.

Clean Persisted Generated Assets

Finds and deletes DreamShader-generated assets that exist on disk, because a saved asset shadows the memory-only material 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.

Show In-Memory Materials

Flips bShowInMemoryMaterialsInContentBrowser 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 removal, so tiles appear or disappear immediately rather than at the next re-enumeration.

The Project page of the Material Content Browser carries a checkbox for the same global setting. The checkbox early-outs when the value is unchanged and shows no toast; the menu entry always toasts. The menu entry's check mark is read live from the settings object, so changing the value in Project Settings updates it.

Open Dream Shader Workspace (VSCode)

Re-exports material-expressions.json, settings.json and substrate-builtins.json, rewrites DShader/DreamShader.code-workspace, and then launches it through a three-step fallback chain — VSCode, the OS default editor, Notepad. The discovery order, the exact file contents and the "this file is rewritten from scratch" warning are on VSCode and Rider.

Material Content Browser

A dockable tab with two pages: one for browsing the project's materials and instancing them, one for the DreamShader source files and their generated assets.

Opening it

The tab is registered only when the editor bridge starts, so -NoDreamShaderEditorBridge removes both routes.

The root widget is a header bar of two radio-style check boxes over a widget switcher. Only the checked transition is honoured, so re-clicking the page you are already on does nothing. The two pages keep independent state, and switching refreshes neither.

Project page

A horizontal splitter: the asset picker takes 0.62 of the width, the details panel 0.38.

Asset picker

Header controls

Details panel

Empty state: "Select a material to see its inheritance and settings." The thumbnail is 96×96, drawn from a 16-entry pool refreshed by a 0.05 s timer.

Dream Shader Gen page

A horizontal splitter: the source list takes 0.6 of the width, the preview pane 0.4. Thumbnails come from an 8-entry pool refreshed by a 0.05 s timer.

Header controls and filters

The page lists .dsm, .dsh and .dsf sources found recursively under the configured source directory. Everything under DShader/Packages is excluded — including package headers and function files, which therefore never appear here.

Status values

Each row draws the status glyph — whose tooltip is the status detail — then the file name, then a subdued sub-label. For .dsf and .dsh items the sub-label reads function · used by {N} material(s).

Refresh pipeline

Status per item:

Step 2 reads the file and strips every import line before parsing — import lines carry no top-level block and would confuse block detection — then resolves the asset destination as described on Asset Paths.

Error overlay

Errors on this page are read straight out of <Project>/Saved/DreamShader/Bridge/diagnostics.json, not from the bridge's in-memory store — the page is deliberately decoupled from the bridge internals.

Compile actions

Both actions generate in memory and force a rebuild, ignoring the source-hash cache.

Headers are skipped by Compile all because their dependents are already in the target set. A failed single compile also logs Material Content Browser compile failed: {Message} at Error level and pins the message onto the item, so the preview pane shows why.

Preview pane

Empty state: "Select a source file to preview its material."

The placeholder tile reads "function library" for .dsf / .dsh items and "not compiled yet" otherwise. The material is resolved by loading the object path, and only for non-function items.

Below the buttons: the file name in large text, the status glyph and label, the absolute source path in small text, used by {N} material(s) for functions and headers, and — only for compile error and unresolved — the error detail in red.

Create instance on an item that was never compiled first force-compiles it and re-resolves the object. If it is still missing, the toast reads Compile {File} first.

Create material instance

Reached from the Project page button, the details panel, the Gen page preview pane, and the Content Browser entry Create DreamShader instance.

On success the toast reads Created {Name} — the asset name from the Name box, not the object path — and the window closes. On failure the error is toasted and the window stays open, so the name or folder can be corrected.

Instancing a memory-only parent materializes the parent first, so a child instance never references a transient object.

Materialize

Materialize writes a memory-only material, and the hidden base it wraps, to disk.

The Gen page's Materialize button deliberately re-resolves the material by object path when clicked, rather than holding the pointer captured when the pane was built, so a delete or a garbage collection between build and click cannot crash it. The whole memory-only model is on In-memory Materials.

Previews

Two different renderers exist, and they are easy to confuse.

Only .dsm can be previewed; a .dsf or .dsh is rejected with DreamShader preview only supports .dsm material files: '{File}'. The material is always compiled transiently — a preview never writes an asset.

There is no pitch clamp on the plugin side — the editor extension clamps to roughly ±89° before sending, and a client that does not will flip the camera over. Motion blur, anti-aliasing and dynamic screen percentage are off, alpha is forced opaque, and a UI-domain material is always drawn on a plane. The client half of this protocol is on VSCode and Rider.

VirtualFunction tools

The actions that generate, open and refresh a VirtualFunction block for an existing UMaterialFunction asset.

The section is built fresh on every right-click. Before building it, the editor searches every project source file for a VirtualFunction declaration whose resolved asset matches the selection — and the entries you get depend on the answer.

The file name is <sanitized MaterialFunction name>.dsh, or <sanitized name>_<crc32 of the object path>.dsh on collision, with the CRC in eight lowercase hex digits. A .dsh written here is picked up by the source-directory watcher like any other header, so the materials importing it recompile automatically. The generated declaration carries Options.Asset = Path(Game|Engine|Plugins.<Name>, "…") — see Asset References — one Inputs entry per function input, and one Outputs entry per output. Copied call examples always end with OutputIndex=0, even for a single-output function.

The startup sync service

Once per editor session, at bridge startup, DreamShader re-reads every VirtualFunction declaration in the project, rebuilds it from the live asset, and writes the file back when the text changed.

Sync problems are published as diagnostics with stage virtualFunctionSync, code virtual-function-sync and severity error; the full list is in the diagnostics index. Reporting logs: DreamShader refreshed {Count} VirtualFunction definition(s) in '{File}'. and DreamShader scanned {Scanned} VirtualFunction definition(s), refreshed {Refreshed}, reported {Issues} issue(s).

Bridge artifacts

The editor writes a set of files under <Project>/Saved/DreamShader/Bridge/ for external tooling to read. Three of them are catalogues exported at bridge startup and again on every Open Dream Shader Workspace; the rest are produced as work happens.

Every manifest carries a generatedAt ISO-8601 UTC timestamp. Only diagnostics.json is ever read back by the plugin — the Gen page reads it. The schemas and the request protocol are covered from the consumer's side on VSCode and Rider.

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 it detects a commandlet process, installing only the cook-time materialization hook, and only when -run= contains Cook and -cookworker is absent.

Notes

• Four 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.
• Toasts raised by the bridge expire after 4 seconds; toasts raised from the Dream Shader Gen page after 3.5 seconds.
• The editor never writes a per-material .uasset on its own. Persisting happens at cook, through the commandlet, or through an explicit Materialize.
• Changing Default Compiler Backend in Project Settings regenerates every source file in memory and raises a toast when persisted assets would shadow the result. No other settings property triggers a reaction.

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

Where next