Material Content Browser

DreamShader » Tools » Material Content Browser

A dockable editor tab over every DreamShader source and every material in the project: what each source compiles to, whether that asset is current, whether somebody has edited it by hand, what it imports and what inherits from it — and the actions that follow from each of those answers.

Opening it

The tab is registered only when the editor bridge starts. Launching the editor with -NoDreamShaderEditorBridge removes every route — see Editor integration.

Layout

┌────────────────────────────────────────────────────────────────────────────┐
│ [⟳ Refresh] [▶ Compile ▾] [+ New ▾] │ search…          │ [View ▾] [VSCode] [⚙] │
├──────────────┬──────────────────────────────────┬──────────────────────────┤
│ NAVIGATION   │ LIST                              │ INSPECTOR                │
│ ▾ Sources    │ Sources mode: columns or tiles    │ live preview · mesh      │
│   ▾ Project  │ Assets mode: the asset picker     │ name · status · storage  │
│     Materials│                                   │ actions                  │
│   ▸ PluginA  │                                   │ Root / Source / Asset /  │
│ ▾ Content    │                                   │   Domain / Blend / …     │
│   ▸ /Game    │                                   │ Diagnostics (N)          │
│ ──────────── │                                   │ Provenance               │
│ Quick filters│                                   │ Imports / Used by        │
│ ☐ Errors …   │                                   │ Inheritance · Children   │
├──────────────┴──────────────────────────────────┴──────────────────────────┤
│ 14 sources · 9 ok · 3 stale · 1 errors · 1 edited by hand · 5 Ephemeral │ bridge: idle │
└────────────────────────────────────────────────────────────────────────────┘

Three panes in a horizontal splitter, a toolbar above, a status bar below. The pane fractions, the mode, the navigation scope, the filters, the sort, the list/tile choice, the preview mesh and the last selection are all saved per user and per project (UDreamShaderBrowserUserSettings, EditorPerProjectUserSettings) and restored when the tab is next opened.

Toolbar

Every compile started from this tab goes through the editor bridge, so its result reaches the diagnostics store, diagnostics.json and the VSCode extension exactly as a compile-on-save does, and a success clears the file's previous error.

Navigation

A tree of two groups. Selecting a node scopes the list and switches the mode.

Quick filters

Check boxes under the tree. The four status filters are OR-ed: ticking Errors and Stale shows entries that are either.

The status-bar counts are the same filters: clicking a count turns it on alone, clicking it again turns it off, and clicking the ok count clears all four.

Sources mode

Every scanned source that passes the scope, the filters and the search, as a list with sortable columns or — View ▸ Tiles — a grid of thumbnails. Multi-selection; right-click for the context menu; double-click opens the material when there is one, else the source.

Listed files

.dss, .dsi, .dsp, .dsm, .dsf and .dsh found recursively under every source root, excluding each root's Packages folder — plus, under the Sources header and the Not managed by DreamShader node, the unmanaged materials. Selection survives a Refresh: entries are re-selected by path.

Pipelines

(since 2.1.0) A .dsp is listed like a material source — its status is its pipeline's, resolved and judged by the same rules — but its asset is a UDreamPassPipeline, the one kind of product in this tab that is not a material, and the rows say so:

A pipeline is listed through its .dsp alone: a UDreamPassPipeline that no scanned source builds is not an unmanaged row, and neither are the render targets of its exported buffers.

Unmanaged materials

Every UMaterial and UMaterialInstanceConstant under the content roots (/Game and the mount point of each plugin that ships DreamShader sources) that no scanned source resolves to, so the tab covers the whole project rather than DreamShader's corner of it. They are found through the asset registry and never loaded for listing — a project with a thousand hand-made materials costs a registry query, not a thousand loads; a row is loaded only when selected, at which point the inspector reads its real provenance (an orphan generated asset turns out Unstamped or Generated, a hand-made one stays Foreign) and folds it back into the row.

The status-bar count not managed jumps to the node rather than toggling a filter. The thin backend's hidden MB_DreamThinBase_* base is never listed. Export .dss on one of these (a .dsi for a plain material instance) is how it comes under DreamShader's management.

Status values

Status computation for every source but a .dsf / .dsh (since 2.0.0):

The build key covers what a compile stamps — the preprocessed file and every header it includes, the defines they read, a .dsi's parent — so a current asset reads up to date and a rebuild always makes a stale one current. 1.x resolved Name= / Root= from text with the imports stripped and hashed the source with them inlined; that recipe answered nothing for a .dss and is gone.

Then the bridge's diagnostics are overlaid, read live from its store: any error record for the file makes it compile error, with the first error record as the detail (L{line}:{col} {message}). All records stay on the entry for the inspector.

[!NOTE] Step 2 does not load, so a material that exists on disk but has not been loaded this session reports not compiled until something loads it.

Assets mode

The engine's asset picker over UMaterial and UMaterialInstanceConstant (recursively, which includes UDreamShaderMaterialInstance), scoped to the navigation tree's content path. Kept as the engine widget on purpose: thumbnails, drag-to-viewport, the column view and the picker's own settings all come with it.

The shared filters apply here too, and are answered without loading anything: a scanned source's asset is judged by its entry, and Ephemeral is read off the registry's package flags. A hand-authored material that DreamShader never generated passes no status filter except Ephemeral.

Double-click opens the asset. Right-click gives the same context menu.

Inspector

One panel for both modes. It shows whichever halves of the selection exist — the source half (a scanned file) and the asset half (a material in the project) — joined through the asset's DreamShader.SourceFile stamp. A material picked in Assets mode therefore shows its source's compile status and diagnostics; a source picked in Sources mode shows its asset's provenance and inheritance.

For a .dsp (since 2.1.0) the inspector has no preview and no Create instance. Open opens the pipeline in its details panel, and the info rows begin with Pipeline — {N} pass(es), {N} buffer(s), {N} parameter(s); order {N} — in place of Base, Domain and Blend mode. The Provenance section offers the same three answers as for a material: a pipeline edited in its details panel is adopted into its .dsp value by value.

The digest states the Provenance row and section spell out:

The status bar's edited by hand count is Diverged alone: a tweaked instance is not in trouble and does not need finding.

Status bar

{N} sources · the counts of ok (up to date, or compiled, Ephemeral), stale, errors, edited by hand and Ephemeral, each a one-click filter · not managed, which jumps to that node · the bridge's state: bridge: idle, bridge: {action} while it compiles, bridge: idle (another editor owns writes) when a second editor on the same project holds the write lock, or bridge: off. The tooltip is the bridge's last result.

Context menu

Right-click in either list. Commands act on the selection; most take the first selected entry.

Following the editor

Nothing here polls. The tab listens to:

Reactions are coalesced into one refresh per tick, so a header that recompiles its twelve dependents repaints the tab once. Refresh remains for anything outside these — a plugin mounted mid-session, say.

New source

New ▾ writes a file from the plugin's templates under Resources/Templates and the bridge's watcher lists and compiles it as it would any save. The menu has three sections:

A pipeline names the materials its passes draw, so each pipeline template writes those too, next to the .dsp, and the .dsp builds as soon as it lands; a shader is written in the .dsp itself. <Base> is the name without its CP_ prefix (CP_Outline gives Outline); a name without the prefix is used as it is.

The companions are written first, so the watcher finds the materials the .dsp names when it compiles the pipeline; and all of them or none — a write that fails takes back the files written before it. A pipeline runs only where something activates it: the global pipelines of Project Settings ▸ DreamPlugin ▸ DreamShader Custom Pass, a Dream Pass Volume, a component, or the API — see Custom Pass runtime.

The dialog:

For a pipeline the dialog also says which files the template writes besides the .dsp.

Either way the asset lands beside its neighbours' — a file created in DShader/Materials/ compiles to /Game/Materials/…. A 1.x block says so itself: its Name= is the folder's path relative to its root plus the name. A .dss says nothing: the name is its export's, and the folder is where the file is. A .dss is one kind of product -- one material, or any number of exported functions, each an asset of its own -- with helpers that are not exported beside either; the two entries start the two kinds.

The templates are compiled by the automation test DreamShader.Browser.NewSource.TemplatesRenderAndCompile, so they cannot rot. The pipeline templates are not among the ones it covers.

Create material instance

Reached from the inspector, the context menu, and the Content Browser entry Create DreamShader instance.

Creation steps and their errors:

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. A source that has never been compiled is compiled first; if it still yields no material the toast reads Compile {File} first.

Materialize

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

The material is re-resolved by object path when the button is clicked, rather than held from when the panel was built, so a delete or garbage collection in between cannot crash it.

Keyboard

Example

A source tree and what Sources mode shows for it:

<Project>/DShader/
    Materials/M_Emissive.dsm        ● up to date          /Game/Materials
    Materials/M_Toon.dss            ● up to date          /Game/Materials
    Materials/M_Broken.dsm          ▲ compile error       L12:9 'Tin' is not declared in this scope.
    Materials/M_New.dsm             ○ not compiled        No generated asset at /Game/Materials/M_New.M_New
    Lib/Noise.dsf                   ◆ function · used by 2 material(s)
    Lib/Common.dsh                  ◆ function · used by 3 material(s)
    Packages/Sample/Demo.dsm        (not listed — under DShader/Packages)

See also

• Editor integration — the menu entries that open this tab, and the details panel a pipeline opens in
• Custom Pass pipelines — .dsp — what the pipeline templates are written in
• Preview — the renderer behind the inspector's preview
• Divergence — Revert, Adopt, Detach
• Decompiler — Export .dss / .dsi
• Ephemeral materials — memory-only generation, the hidden base, materializing
• Caching — the source hash behind up to date and stale
• Asset paths — how Name= and Root= resolve to the object path
• Project settings — Material Instance Subfolder and the Ephemeral visibility toggle
• Bridge — the diagnostics store this tab reads and the events it follows
• Material instance API — UDreamShaderMaterialInstance in C++
• Diagnostics index — every message, by stage