Path(…) asset references

DreamShader » Parameters » Path(…)

The asset-reference form: a package root plus a relative path, resolved to a full Unreal object path at generation time.

Synopsis

Path( <root> , "<relative-path>" )
Path( "<absolute-path>" )
"<absolute-path>"
<Class>'<absolute-path>'

<root> and the path may each be written quoted or bare.

Texture2D A = Path(Game, "Textures/T_X");
Texture2D B = Path("Plugin.MyPlugin", "Textures/T_X");
Texture2D C = Path("/Game/Textures/T_X");
Texture2D D = "/Game/Textures/T_X";
Texture2D E = Texture2D'/Game/Textures/T_X.T_X';

The front end keeps a reference as the text it was written as; it is resolved when the asset is built, because only the editor knows which plugins are mounted.

Content Browser references

(since 1.9.0)

Right-clicking an asset and choosing Copy Reference puts Unreal's export form on the clipboard:

/Script/Engine.Texture2D'/Game/Cloud/Texture/T_VolumeCloud_03.T_VolumeCloud_03'

Paste it in as it stands. The resolver strips the <Class>'…' shell before anything else and uses the object path inside the quotes; the class in front of the quotes is used only for the check below. Three spellings of the shell are recognized:

The shell may be pasted bare, wrapped in quotes, or handed to Path(…) — all four of these name the same asset:

Texture2D A = Texture2D'/Game/Textures/T_X.T_X';
Texture2D B = "Texture2D'/Game/Textures/T_X.T_X'";
Texture2D C = Path("Texture2D'/Game/Textures/T_X.T_X'");
Texture2D D = Path(Game, "Texture2D'/Game/Textures/T_X.T_X'");   // the root is ignored

The path inside the quotes is absolute, so a root written beside it is ignored, exactly as it is for any other absolute path. See Roots and absolute paths.

A shell is only recognized when it is well formed: the text must end in ', there must be an earlier ', and what lies between them must be non-empty and contain no further '. Anything else is left alone and reaches the resolver's ordinary grammar — and its ordinary diagnostics — unchanged.

Class checking

The class named by the shell is checked against the slot it is being assigned to, before the asset is loaded:

DSH1043 and DSH1044 are raised right after the file is parsed; DSH1045 when the asset is built.

[!NOTE] An unrecognized class is never an error. Unreal itself ignores the class when it resolves an export path, and a project is free to name classes DreamShader has never heard of, so a prefix that cannot be placed is dropped rather than refused.

TextureObjectParameter, which declares no dimension of its own, and TextureSampleParameterCubeArray are only checked against the "is this a texture at all" half of the table; TextureObjectParameter takes its real dimension from the asset that loads.

Roots

The root argument is unquoted, \ is folded to /, and leading and trailing / are stripped; the result is then split on /. The first segment names the root.

All spellings are matched case-insensitively. Any other first segment is DSH8126.

Segments after the root are appended as folders. Path("Game/Textures", "T_X") resolves to /Game/Textures/T_X, and Path("Plugin/MyPlugin/Materials", "MF_X") to /MyPlugin/Materials/MF_X.

A plugin root resolves through the plugin's own mounted asset path, normalized the same way (backslashes folded, trailing / stripped, a leading / added). If that path is empty or just /, /<PluginName> is used instead. The plugin has to be known, enabled, able to contain content, have a Content folder on disk and — on UE 5.6 and newer — be mounted (DSH8118 … DSH8122).

Roots and absolute paths

(changed in 1.9.0)

A root is only consulted when the asset path is relative. Written beside an absolute path — one that begins with /, including the path inside a Class'…' shell — the root is ignored, and it is not validated either: Path(Plugin.NotInstalled, "/Game/Textures/T_X") resolves to /Game/Textures/T_X.T_X without complaining about the plugin.

Before 1.9.0 the texture-default resolver prepended the root anyway, so Texture2D T = Path(Game, "/Game/Textures/T_X"); resolved to /Game/Game/Textures/T_X.T_X and then failed to load. Since 1.9.0 the root is dropped.

[!NOTE] If a source relied on the old prepending — a relative path deliberately written with a leading /, as in Path(Game, "/Textures/T_X") — it now resolves to /Textures/T_X.T_X and fails to load. Drop the leading /: Path(Game, "Textures/T_X").

Object-path completion

After the root and the relative path are joined, the result is completed to a full object path: if the text after the last / contains no ., the asset name is appended after a ..

The completed path is finally validated by Unreal's own object-path validator, whose message is reported, without a code of its own, inside the diagnostic of the slot.

The resolver

(since 2.0.0) There is one resolver. 1.x had two — one for texture defaults, one for metadata and the rest — with different accepted forms and different messages; every reference site now goes through the shared one, and the diagnostic of the slot quotes its code.

What the resolver accepts

A texture declaration's default that is no reference at all — Texture2D T = Foo; — is not refused as a spelling any more; it is simply not found when the material is built (DSH8218).

String escapes

Quoted paths are string literals, read by the lexer (since 2.0.0): \\, \", \n, \r, \t and \0 are recognized, and any other \X is DSH2104 — 1.x read it as the literal X. A backslash in a path is therefore written \\, and the resolver then folds it to /. See Lexical elements.

Load behaviour

Resolving a path produces text. Whether the asset then loads is a separate step, and the outcome depends on the slot:

[!WARNING] The silent-null case is the one to watch: [Texture = Path(Game, "Typo")] — and since 2.0.0 TextureSampleParameter2D T = Path(Game, "Typo"); — generates without any diagnostic and leaves the sampler on a texture nobody chose. A path that resolves is not a path that exists.

Diagnostics

Each of these reaches you inside the diagnostic of its slot — see The resolver. The complete list lives in the diagnostics index.

Example

Shader(Name="Docs/M_Paths")
{
    Properties = {
        // Root + relative path — the canonical form.
        Texture2D A = Path(Game, "Textures/T_White");

        // Quoted root, and extra folder segments carried by the root.
        Texture2D B = Path("Game/Textures", "T_Noise");

        // Engine content.
        TextureCube C = Path(Engine, "EngineResources/DefaultTextureCube");

        // Plugin content: both spellings resolve identically.
        Texture2D D = Path(Plugin.DreamShader, "Textures/T_Probe");
        Texture2D E = Path("Plugins/DreamShader", "Textures/T_Probe");

        // Single-argument and bare quoted forms — both must be absolute.
        Texture2D F = Path("/Game/Textures/T_White");
        Texture2D G = "/Game/Textures/T_White";

        // Pasted straight from the Content Browser's "Copy Reference".
        Texture2D H = /Script/Engine.Texture2D'/Game/Textures/T_White.T_White';
        Texture2D I = "Texture2D'/Game/Textures/T_White.T_White'";

        // An object-valued metadata entry.
        TextureSampleParameter2D Mask [Texture = Path(Game, "Textures/T_Mask")];

        // A UE builtin argument.
        UE.CollectionParam(Collection = Path(Game, "Collections/MPC_World"),
                           Parameter  = "WindStrength") Wind;
    }

    Settings = { Domain = "Surface"; ShadingModel = "Unlit"; BlendMode = "Opaque"; }
    Outputs  = { vec3 Color; Base.EmissiveColor = Color; }

    Graph = {
        Color = vec3(Wind, Wind, Wind);
    }
}

Resolved object paths:

A  /Game/Textures/T_White.T_White
B  /Game/Textures/T_Noise.T_Noise
C  /Engine/EngineResources/DefaultTextureCube.DefaultTextureCube
D  /DreamShader/Textures/T_Probe.T_Probe          (plugin mounted asset path)
E  /DreamShader/Textures/T_Probe.T_Probe
F  /Game/Textures/T_White.T_White
G  /Game/Textures/T_White.T_White
H  /Game/Textures/T_White.T_White
I  /Game/Textures/T_White.T_White

A reference is resolved when the property it belongs to is built. This Graph reads only Wind, so the textures are dropped as unread (DSH4390, info) and only the collection is resolved; read them and each resolves as listed.

See also

• Parameters — the hub and the decision table
• Compact type tokens — the texture tokens whose defaults use this form
• Parameter node tokens — which tokens accept = Path(…) and which do not
• Metadata block — object-valued metadata entries and the silent-null texture case
• UE builtins — UE.CollectionParam and its Collection argument
• VirtualFunction — Options = { Asset = Path(…); }
• Lexical elements — string literals and escape sequences
• Asset paths — the output side: Name= + Root= → package path
• Diagnostics index — every code