Asset paths

DreamShader » Generation » Asset paths

The rule that turns a block's Name and Root header attributes into an Unreal package path, an object path, and a file on disk.

Synopsis

Shader        (Name = "<name-path>" [, Root = "<root>"]) { … }
ShaderFunction(Name = "<name-path>" [, Root = "<root>"]) { … }

<name-path> := [<folder> /] … <leaf>
<root>      := "" | Game | Plugin.<PluginName> | Plugins.<PluginName>
             | Plugin / <PluginName> | Plugins / <PluginName>
             | / <MountRoot> [/ <folder>] …
             | <folder> [/ <folder>] …

Name is required: a block without one, or with one that is empty, is DSH2242. Root is optional and defaults to the empty string. Attribute keys are matched case-insensitively, so name= and ROOT= both resolve.

(since 2.0.0) A 1.x block keeps exactly this destination (legacy rule L10): its Name= is never placed under the source file's folder, as the name of a .dss product is. A destination that does not resolve fails the product with DSH8200, whose message quotes the asset layer's code and text — see Diagnostics.

Resolution order

1. Root → root package path. Trim; \ → /; remember whether the string began with /; strip leading and trailing /; split on /. An empty result at any point yields /Game.
2. Name → folders + leaf. Trim; \ → /; strip all leading and trailing /; split on /. The last segment is the asset name; every preceding segment is a folder appended to the root.
3. Every segment passes through ObjectTools::SanitizeObjectName. Empty segments are skipped silently.
4. PackageName = <root>/<folders…>/<Leaf> and ObjectPath = <PackageName>.<Leaf>.
5. PackageName is validated with FPackageName::IsValidObjectPath.

Root= dispatch

Dispatch is on the first segment, compared case-insensitively.

Branch — omitted or empty

The plugin source root default

The table above is the project root's answer. A source file that lives under a plugin source root — <Plugin>/DShader, see Source files — defaults instead to that plugin's mount point, exactly as if it had written Root="Plugin.<PluginName>".

Only an absent or whitespace-only Root is defaulted, so Root="/" (or any explicit spelling) is how a plugin-root file opts back into /Game. The default is applied per block: a file may leave its Shader block to the default and pin one ShaderFunction to /Game.

[!NOTE] The default is skipped, and the block falls back to /Game, when the owning plugin cannot host generated content — it is not a project plugin under <Project>/Plugins, is disabled, declares no CanContainContent, has no Content directory, or is unmounted. (since 2.0.0) The fallback is silent: nothing is logged. An unresolvable inferred Root is never emitted as an error, because the author never wrote one.

The package asset root

(after 2.1.2) A source a package builds — one under its Assets folder, or an asset header — defaults to the package's asset root, whichever source root holds the package, and the plugin default above does not apply to it:

A 2.0 source adds its folder under Assets, as a project source adds its folder under the source root; a 1.x Name= says every folder it wants. An explicit Root still wins. See Packages ▸ Package assets.

The default is applied in the one place a product becomes an asset path, so the compile, product resolution (the Material Content Browser, dsc list-generated) and the preview renderer all name the same asset.

Branch — Game

The comparison is case-insensitive, but the emitted root is always the literal /Game.

Branch — Plugin.<Name> / Plugins.<Name>

The dotted form names the plugin in a single segment; everything after it is folders.

Branch — Plugin/<Name> / Plugins/<Name>

The slash form spends two segments on the plugin reference.

[!WARNING] Root="Plugin" and Root="Plugins" with no second segment do not name a plugin. They fall through to the last dispatch row and are treated as ordinary folder names, producing /Game/Plugin and /Game/Plugins. No diagnostic is emitted.

Branch — explicit mount root

A Root that begins with / and is not one of the forms above is taken verbatim as a mount point.

The first segment must survive SanitizeObjectName unchanged, otherwise the destination fails with DSH8097. The mount point itself is not checked for existence here — an unmounted root fails later, at the IsValidObjectPath gate.

Branch — bare relative path

Any other Root without a leading / becomes folders under /Game.

The difference between this branch and the previous one is exactly the leading slash: Root="Foo/Bar" is /Game/Foo/Bar, Root="/Foo/Bar" is /Foo/Bar.

Plugin-root requirements

Both plugin forms resolve through the same validator. Every gate below must pass, in this order; each has its own code, which the product's DSH8200 quotes.

Gate 7 does not exist on UE 5.3 – 5.5; on those engines an unmounted plugin is caught later by the object-path validation instead.

The root package path is the plugin's own mounted asset path — normalized to \ → /, no trailing slash, a forced leading slash. If that degenerates to empty or /, /<PluginName> is used.

[!NOTE] Engine plugins and marketplace plugins installed under the engine directory are rejected by gate 3 even when they are enabled and mounted. Only plugins physically under <Project>/Plugins are accepted. To write into an engine-side mount, use the explicit mount-root branch (Root="/SomeMount"), which skips the plugin validator entirely.

A cook does not abort over such a source. Its products are the plugin's own — the plugin ships the assets its sources describe — and no host project can generate into that mount or even edit the file (plugin roots are read-only), so a generation failure there is logged and the cook goes on. Only the project's own sources, and those of its own plugins under <Project>/Plugins, can fail a cook. See Cook behaviour.

Per asset kind

The path resolution is identical for all four block kinds. What differs is the class created and, for the function kinds, the material-function usage stamped on it.

When an asset already exists at the resolved path, the class must match:

Custom Pass pipelines

(since 2.1.0) A .dsp has no Name=, no Root= and no /// @name. Its one product, a UDreamPassPipeline, is named after the file and placed by the 2.0 default: the file's folder relative to its source root, under /Game — or under the plugin's mount point for a file under a plugin's source root, by the same plugin source root default and with the same fallback to /Game. The render target of every exported buffer lands in the pipeline's folder, named <Pipeline>_<Buffer> through SanitizeObjectName.

The only way to choose where a pipeline lands is where the .dsp lives, which is also why a decompiled .dsp cannot keep its asset's path from elsewhere (DSH9224). Moving or renaming the file builds a new pipeline at the new path; the old one, and its render targets, are left where they are, and its HLSL slots stay taken until dsc pass-registry -Gc collects them.

On-disk mapping

The file is <directory>/<Leaf>.uasset. A Graph-backend material and every function, layer and blend asset are saved by every build that may write; a ThinCustom product only once it is Materialized — see Ephemeral materials.

Notes

• Name may contain folders; Root is only a prefix. Name="A/B/C" under Root="Game" yields /Game/A/B/C, and the asset is named C.
• A duplicate attribute key overwrites the earlier one. Shader(Name="A", Name="B") resolves to B, with the warning DSH2244 (since 2.0.0; silent through 1.x).
• Every segment is sanitized independently. Characters SanitizeObjectName rejects are replaced, so Name="My Mat" resolves to a leaf named My_Mat without a diagnostic.
• Empty segments are dropped: Name="A//B" is A/B, and Root="Game//Sub" is /Game/Sub.
• The resolver is also what the Content Browser status column and the Materialize action use, so a path that fails here also shows as unresolvable in the Material Content Browser.

Diagnostics

The asset layer's codes reach the compile result inside the emitter's: a destination that does not resolve is DSH8200, an asset that cannot be created or reused is DSH8201 (Graph material), DSH8203 (ThinCustom instance) or DSH8202 (function, layer, blend), and each message quotes the code below.

Example

Shader(Name="Mat/Test", Root="Plugin.MoonToon")
{
    Properties { vec3 Tint = vec3(1.0, 0.2, 0.2); }
    Settings   { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }
    Graph      { Color = Tint; }
}

Resolved destination:

Root      "Plugin.MoonToon"  ->  /MoonToon                       (plugin mount point)
Name      "Mat/Test"         ->  folders "Mat", leaf "Test"
package                          /MoonToon/Mat/Test
object path                      /MoonToon/Mat/Test.Test
on disk                          <Project>/Plugins/MoonToon/Content/Mat/Test.uasset

See also

• Shader — the header attributes as part of the block grammar
• ShaderFunction — the same attributes on a function block
• ShaderLayer / ShaderLayerBlend — the layer asset kinds
• Ephemeral materials — when the .uasset is actually written
• Regeneration — the ownership guard and where it does not apply
• Caching — the provenance metadata that marks an asset as DreamShader-generated
• Path(Root, "…") — the other path grammar, for referencing existing assets
• Backend — which class a Shader produces
• Custom Pass pipelines — .dsp — a source whose asset is named after its file
• Diagnostics index — every message, by stage