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

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 — skipped in memory-only mode.
9. Recompile.

Step 4 has two strategies. Below 1200 expressions each node is deleted individually through the material editing library, in up to 64 outer passes, reporting Deleting old Material node '{Name}'.... At 1200 or more the whole expression collection is un-rooted and marked as garbage in one pass. The material path also resets the material's editor parameter cache; the material-function path does not.

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

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.

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.

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 source-hash cache

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.

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. Generated material instances are deliberately not RF_Transactional, because undo/redo desynchronizes the shader map.
• 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.

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:

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