DreamShaderMaterialInstance.h

DreamShader » C++ API » DreamShaderMaterialInstance.h

UDreamShaderMaterialInstance — the addressable asset the ThinCustom backend produces: a constant material instance whose parent is a hidden per-material base UMaterial carrying the real node graph.

Defined in header DreamShaderMaterialInstance.h.

Synopsis

UCLASS(ClassGroup = DreamShader)
class DREAMSHADER_API UDreamShaderMaterialInstance : public UMaterialInstanceConstant
{
    GENERATED_BODY()

public:
    /** DreamShader source file this instance was generated from. */
    UPROPERTY(VisibleAnywhere, Category = "DreamShader")
    FString SourceFilePath;

    /** Hash of the source text (the regeneration skip check compares against it). */
    UPROPERTY(VisibleAnywhere, Category = "DreamShader")
    FString SourceHash;

    //~ Begin UMaterialInstance interface
    virtual bool HasOverridenBaseProperties() const override;
    //~ End UMaterialInstance interface

    //~ Begin UObject interface
    virtual bool IsAsset() const override;
    //~ End UObject interface
};

The class adds no methods beyond the two overrides, no constructor, and no PostLoad. Everything else — parameters, settings, domain, scene reads — lives on the hidden base as ordinary expressions and material properties, enumerated natively by the engine.

Properties

Both are read-only in the details panel — VisibleAnywhere, not EditAnywhere — and neither is Config or Transient.

[!WARNING] The header comment on SourceHash says "the regeneration skip check compares against it". That is imprecise. The skip check reads the package metadata keys DreamShader.SourceFile and DreamShader.SourceHash, not these UPROPERTYs. The values coincide, but the two paths differ: the metadata stores a project-relative source path while SourceFilePath stores the absolute one. Do not implement your own skip logic against these properties. See Caching.

HasOverridenBaseProperties

virtual bool HasOverridenBaseProperties() const override;

The engine recomputes bHasStaticPermutationResource from this on every load, inside InitStaticPermutation, so the test must be durable state rather than a transient flag — hence the parent-class test rather than a stored boolean. The pattern mirrors ULandscapeMaterialInstanceConstant.

That is the point of the override: any number of colour and parameter variants created off one DreamShader material reuse a single compiled shader map instead of each compiling its own, which bounds the shader-map count for a project that instances heavily. See Material Content Browser for the instance-creation action.

IsAsset

virtual bool IsAsset() const override;

Returning false removes the object from the Content Browser, from the asset registry's live-object-iterator discovery path, and from save pickers — which also prevents an accidental explicit Save from materializing a memory-only material to disk. Object-path references still resolve normally; only enumeration is affected. A persisted instance has no PKG_NewlyCreated flag and behaves like any other asset.

[!NOTE] The setting is read on every call, through GetDefault<UDreamShaderSettings>(). Toggling Show Ephemeral Materials changes the answer immediately, with no reload; the editor re-broadcasts asset creation and removal for every memory-only instance so the browser refreshes. See Project settings.

Role in the ThinCustom result

A Materialized ThinCustom compile produces one package containing:

/Game/Materials/M_Emissive                      UDreamShaderMaterialInstance   (the addressable asset)
  └─ MB_DreamThinBase_M_Emissive                UMaterial                      (subobject, hidden base)
       └─ the generated node graph, parameters, settings, output bindings

An Ephemeral one keeps the hidden base out of that package: it is a transient UMaterial in the transient package, named MB_DreamThinBase_ plus the instance's package path run through SanitizeIdentifier (MB_DreamThinBase__Game_Materials_M_Emissive), so two instances with the same leaf name in different folders never share a base. See Ephemeral materials.

[!WARNING] Regeneration under the ThinCustom backend rebuilds the hidden base's graph and clears the instance's parameter values; the overrides are captured first and restored afterwards by name. An override whose parameter was renamed or removed in the source is dropped, and reported once as DSH8155. Create a child instance for values a rebuild must never touch. See Regeneration.

The instance is created with NewObject<UDreamShaderMaterialInstance>(InstancePackage, FName(*AssetName), RF_Public | RF_Standalone), or reused in place when an instance of this class already occupies the target path. Any other object at that path is refused rather than replaced (DSH8106), and so is a saved instance of this class that carries no DreamShader source metadata (DSH8107).

Notes

• ClassGroup = DreamShader places the class in its own group in class pickers. There is no BlueprintType, no Blueprintable, and no factory registered for manual creation — the class is only ever instantiated by the compiler's asset factory.
• The class ships in the Runtime module, not the editor module, because a cooked build must be able to load the instances that cooking materialized.
• Neither override consults the source properties. SourceFilePath and SourceHash are inert with respect to engine behaviour; they exist for tooling and for the details panel.
• Under the Graph backend no instance is produced at all — the asset at the target path is a plain UMaterial. See Backend.

Example

Finding the source file behind a selected asset:

#include "DreamShaderMaterialInstance.h"

FString GetDreamShaderSource(const UMaterialInterface* Material)
{
    if (const UDreamShaderMaterialInstance* Instance = Cast<UDreamShaderMaterialInstance>(Material))
    {
        return Instance->SourceFilePath;   // absolute, '/' separators
    }
    return FString();
}

Details-panel view of a generated instance:

Parent                 MB_DreamThinBase_M_Emissive
DreamShader
  Source File Path     I:/Project/DShader/Materials/M_Emissive.dsm
  Source Hash          9f2c41ab

See also

• Ephemeral materials — the hidden base, visibility, and materializing
• Backend — ThinCustom versus Graph, and the deprecated Instance alias
• Regeneration — what a rebuild destroys on the instance
• Caching — the package metadata keys the skip check actually uses
• Project settings — the visibility toggle behind IsAsset()
• DreamShaderSettings.h — bShowEphemeralMaterials in C++
• Material Content Browser — creating child instances and materializing
• Shader — the block that generates this asset
• Asset paths — where the package lands