Regeneration

A generated asset is source-derived output, not a document. When a source file is compiled again, the generated graph is torn down and rebuilt from the .dsm or .dsf. Every hand edit inside the asset is destroyed, with exactly one exception.

Internalize that sentence and most of this page follows from it.

What survives

Sequence

0. Refuse if the asset is open in an asset editor, then refuse if it has diverged — both before anything below runs, and before any of it is reversible. since 1.8.0
1. Modify() the target object.
2. Clear the generated comments — every UMaterialExpressionComment whose text starts with the literal DreamShader: .
3. Null every material property input, from the first to the last material-property slot.
4. Delete every expression in the graph.
5. Reset the material to defaults — see Reset properties. Material functions skip this step.
6. Apply Settings.
7. Rebuild: Properties nodes, the Graph body or the whole-surface Custom node, the Outputs bindings.
8. Lay out — runs in memory-only mode too since 1.6.0, see Project Settings.
9. Recompile.

Step 4 now has one strategy: the graph leaves as a unit. The node-by-node path existed to break inbound links, which is O(n^2) across a graph and pointless when the whole collection is detached at once, so the former 1200-expression threshold is gone in 1.8.0 and every rebuild takes the fast path. The material path also resets the material's editor parameter cache; the material-function path does not.

A rebuild is atomic

Steps 1–9 either all take effect or none of them do. The old graph is detached rather than destroyed, and destroyed only once the rebuild has fully succeeded; a failure at any point puts it back — nodes, connections, render state, material-function usage and pin GUIDs alike — before the compile returns. The asset a failed compile leaves behind is the asset it started with.

That matters because not every failure is caught up front. The whole-file parse, the Settings validation and the Outputs validation are gates that run before the asset is touched at all, but a Graph block is compiled one statement at a time by the graph builder, which runs at step 7 — after the teardown. Until 1.8.0 such a failure left the asset emptied, which was bad for a material and much worse for a material function, whose call sites read their pins from the live asset: one bad .dsf took every material that called it down with it, with no undo (generated assets are deliberately not RF_Transactional).

Two details make the rollback work. The snapshot is taken with delta serialization off — a property equal to the class default is otherwise skipped, and the restore would leave whatever the failed build had set it to — and it covers the asset's editor-only data object as well as the asset, since UE 5.1 moved the expression collection and the material property inputs onto a separate UMaterialEditorOnlyData / UMaterialFunctionEditorOnlyData UObject; snapshotting the material alone captures nothing but a pointer to it.

The one hand edit that survives

A comment box whose text does not carry the DreamShader prefix.

dreamshader: Notes, DREAMSHADER: Notes and DreamShader:Notes (no space) all fail the prefix test and therefore survive. This is the supported way to annotate a generated material by hand.

Preserved identities

Two identities are deliberately preserved so that existing call sites do not break.

• Material function pins. Before the graph is cleared, the Id GUID of every UMaterialExpressionFunctionInput and UMaterialExpressionFunctionOutput is cached by name and restored onto the newly created pin with the same name. A MaterialFunctionCall node elsewhere in the project keeps its wiring across a regeneration of the function. since 1.3.2
• Named reroutes. A declaration's variable GUID is regenerated only when the existing one is invalid.

Renaming an input or output in the source is therefore a breaking change for its call sites: the old name's GUID has nothing to restore onto.

Parameter overrides on a generated instance

Divergence

The source hash fingerprints the source a compile reads. It says nothing about the asset that compile produced. So an asset you edited by hand still looked untouched: the next time its .dsm moved, regeneration tore the graph down and rebuilt it, and the edit was gone with no diagnostic and no undo.

The output digest is the other half: a fingerprint of what the asset actually holds, written to DreamShader.OutputDigest at the end of every successful generation. Comparing it against the asset before a rebuild answers the question the source hash cannot — has somebody been working in here?

DreamShader.SourceFile decides ownership; the digest decides whether the contents are still ours.

Unstamped covers two cases, both benign: an asset generated before digests existed, and one whose stamp carries a different schema tag. The tag is the digest format version plus the engine version (DSD1-5.8), because the property set the digest walks is the engine's — without it, upgrading the engine would re-fingerprint every asset in the project at once and report the whole library as hand-edited.

What counts as a hand edit

The rule is the digest covers exactly what a rebuild would destroy. A property a rebuild never touches survives it untouched, so blocking on that property would refuse a rebuild in order to protect something that was never in danger.

What a refusal looks like

Generation fails with the asset exactly as you left it — not cleared, not half-built:

Asset '/Game/Materials/M_Emissive.M_Emissive' has been edited by hand since DreamShader generated it
from 'DShader/Materials/M_Emissive.dsm', so it was NOT rebuilt (rebuilding would destroy those
edits). Right-click the asset > DreamShader and choose one: 'Revert to Source' discards the edits and
rebuilds, 'Adopt Into Source' rewrites 'DShader/Materials/M_Emissive.dsm' from the edited asset,
'Detach From DreamShader' hands the asset over to you and stops managing it.

The check runs before anything mutates the asset. For a material function that ordering is the whole point: the gate fires before the usage is restamped, not merely before the graph teardown.

This gate and the atomic rebuild above answer two different questions, and you want both. The gate stops a rebuild that would have succeeded from overwriting work you did by hand; atomicity stops a rebuild that fails from leaving the asset in pieces. Neither covers the other's case.

A rebuild is only ever attempted when the source moved. An unchanged source is skipped by the source hash long before the gate, so hand-editing an asset and leaving its source alone reports nothing at all — nothing is in danger.

The three ways out

All three live on the asset's right-click menu, under DreamShader, for materials, material functions, layers, layer blends, and generated ThinCustom instances alike.

Three things to know about Adopt Into Source: the previous source is copied to <source>.bak before anything is written; it is refused when the source file declares more than one asset; and the file's own form — hand-written comments, import directives, formatting — becomes the decompiler's output.

That multi-asset refusal matters: the decompiler emits one block, not a translation unit, so adopting one asset out of a file that declares several would silently delete the others. Use Export DSM and merge by hand in that case.

Open in an asset editor

A rebuild is refused outright while the asset is open in an asset editor:

Asset '{ObjectPath}' is open in an asset editor, so it was NOT rebuilt. An open editor works on its
own copy of the asset and writes that copy back when you press Apply or Save, which would silently
undo this rebuild. Close the editor and compile again.

The reason is that an asset editor does not edit the asset. FMaterialEditor duplicates it into a transient UPreviewMaterial and copies that duplicate back over the original on Apply or Save (UpdateOriginalMaterial); the material instance editor writes back through a UMaterialEditorInstanceConstant wrapper. An editor that stayed open across a rebuild is therefore holding a pre-rebuild copy of the asset, and the next Apply reverts everything the rebuild did — which then shows up as a divergence on the compile after that, a long way from the cause.

The provenance actions are the exception. Revert to Source and Adopt Into Source close the editor themselves, do the work, and reopen it — because you just clicked them, quite possibly from that editor's own toolbar, and a menu item that is permanently dead where it is most useful is not a guard, it is a bug. The engine's save prompt may appear as part of that close; for Adopt it is load-bearing rather than noise, since unapplied editor changes are not part of "this asset's current contents" until the prompt is answered. Cancelling it cancels the whole action.

The ownership guard

DreamShader refuses to overwrite an asset it did not generate.

The guard is inert for packages that are not on disk: a memory-only asset has no saved package to protect, so the check does not run. That gap is covered from the other side — divergence applies in memory too, because the source path is stamped there as well.

A wrong-class asset at the target path is refused by a class check instead, before the ownership question is asked at all:

Asset '{ObjectPath}' already exists and is not a DreamShader instance material. Delete it (or remove
Backend="Instance") before switching backends.

Reset properties

Before the graph is rebuilt, a material's render state is restored to these values, in this order. Settings is applied afterwards, so any key you declare wins; anything you do not declare returns to the value below, regardless of what the material editor last held.

bUsedWithVolumetricCloud is the one entry above that is not a constant: the domain decides it. A Volume-domain material is a volumetric material, and the volumetric cloud renderer refuses one that is not flagged for it — so you never have to write the flag by hand. Write it explicitly to override the domain's choice; a Volume material that only ever feeds volumetric fog can turn the flag back off with bUsedWithVolumetricCloud = "false"; and save the cloud shader permutations.

Material functions have no render state; their asset-level fields are reapplied instead:

The material-function usage is also re-stamped from the block kind on every regeneration.

The build key (source hash)

Regeneration is expensive, so an unchanged source skips it entirely.

prepared text  ->  CRC32  ->  "%08x"  ->  DreamShader.SourceHash   e.g. "9f2c41ab"
source path    ->  project-relative, forward slashes  ->  DreamShader.SourceFile

What is hashed

The hash covers the text the parser actually sees, after import inlining — not the bytes of the file on disk. That is the single most surprising property of the cache.

It is a build key, not just a source hash

The stamp fingerprints the source in the context that compiles it. Anything that changes what a given source produces is folded in, because leaving it out makes the skip check answer "still current" about an asset that is not:

A batch compiles in dependency order

When a batch contains both a function and something that calls it, the batch is ordered so that dependencies compile first. This is not a nicety: a .dsm that calls a ShaderFunction binds its call node against the live UMaterialFunction asset — SetMaterialFunction reads the pins off the object, not off the source — so compiling the caller first binds it against the previous version of that function's interface. Rename a function input and save both files, and which one won used to depend on the iteration order of the pending file map.

Both drain points — the watcher's pending-file batch and the whole-project sweep — topologically sort by the import graph. Only edges inside the batch are honoured; a cycle is left for the import loader to reject with DreamShader import cycle detected at '{File}'.

Where the metadata lives

Two keys are written into the generated asset's package metadata, keyed by the asset object. These are the only two keys DreamShader ever sets — nothing writes a generation timestamp.

Storing the project-relative path is deliberate: a checkout on another machine, or a moved project directory, still recognizes its own generated assets instead of regenerating everything. DreamShader.SourceFile doubles as the ownership marker — its presence is what the guard above tests, and what Clean Persisted Generated Assets filters on.

Which assets get stamped, and when:

A ThinCustom instance additionally carries the source path and the hash as read-only UPROPERTYs — SourceFilePath and SourceHash, category DreamShader — so they are visible in the details panel without inspecting package metadata. SourceFilePath holds the full normalized source path, not the project-relative form the metadata stores.

When regeneration is skipped

The short circuit fires only when all of the following hold:

Placing the ThinCustom check before the base is created is what makes a skip cheap: no base material, no ownership check, no graph teardown. A material function whose usage does not match — a ShaderLayer block whose asset is still marked Default, for instance — is regenerated even when the hash matches, and the usage is corrected.

Forcing a rebuild

There is no way to clear the stored hash from the source language. To force a rebuild without a force-capable entry point, either change the source text — any change, including whitespace — or delete the generated asset.

Notes

• Regeneration is not undoable, but it is atomic since 1.8.0: a failure puts the asset back the way it was before the rebuild. Generated material instances are deliberately not RF_Transactional, because undo/redo desynchronizes the shader map — which is why the rollback is a snapshot rather than a transaction.
• The safest mental model: treat the .dsm / .dsf as the asset. Anything you want to persist belongs in the source.
• A regeneration that is skipped by the source hash does none of the above — the asset is not touched at all.
• Deleting the generated asset and recompiling is always equivalent to a forced regeneration, except that a material function's pin GUIDs are lost and its call sites break.
• The hash is a CRC32, not a cryptographic digest. It detects edits; it is not an integrity mechanism.
• The generated .ush helper include is not covered by this short circuit. It is rewritten on every compile of a unit that declares Function blocks.
• The decompiler is the way to capture hand edits: export the edited material back to .dsm / .dsf, then make that the source of truth. Since 1.8.0, Adopt Into Source is exactly that as a right-click action, with the old source backed up to <source>.bak first.

Diagnostics

Worked example

Shader(Name="Docs/M_Regen")
{
    Properties {
        ScalarParameter Intensity = 2.0 [Group="Look"; SortPriority=10];
        VectorParameter Tint      = float4(1.0, 0.4, 0.1, 1.0) [Group="Look"];
    }
    Settings { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs  { vec3 Color; Base.EmissiveColor = Color; }
    Graph    { Color = Tint.rgb * Intensity; }
    Layout   { Node(Var="Color", X=-400, Y=0); }
}

Hand-edit the generated asset, then save the .dsm again. Since 1.8.0 that is stopped by the divergence gate first; the table below is what happens once you pick Revert to Source:

before regeneration                              after regeneration
-----------------------------------------------  --------------------------------------------
comment "DreamShader: Output: EmissiveColor"     recreated
comment "Reviewed 2026-07-30"                    KEPT — no DreamShader: prefix
extra Multiply node wired in by hand             deleted
Two Sided ticked in the material editor          reset to false (not declared in Settings)
Intensity override = 5.0 on the instance         cleared, back to the source default 2.0
Color node dragged to (900, 400)                 back to (-400, 0), pinned by Layout

And the metadata on the generated instance:

DreamShader.SourceFile   DShader/Docs/M_Regen.dsm
DreamShader.SourceHash   9f2c41ab

Where next