Source files

DreamShader » DreamShaderLang » Source files

The three DreamShaderLang file kinds — .dsm, .dsf and .dsh — and the rule that decides which top-level blocks each may contain.

Synopsis

// <name>.dsm — Dream Shader Material
[ import "<header>.dsh" ; ]…
[ Shader( Name = "…" [, Root = "…"] ) { … } ]          // at most one per file
[ { VirtualFunction | Namespace | Function | GraphFunction } … ]…

// <name>.dsf — Dream Shader Function
[ import "<header>.dsh" ; ]…
[ { ShaderFunction | ShaderLayer | ShaderLayerBlend }( Name = "…" [, Root = "…"] ) { … } ]…
[ { VirtualFunction | Namespace | Function | GraphFunction } … ]…

// <name>.dsh — Dream Shader Header
[ import "<header>.dsh" ; ]…
[ { VirtualFunction | Namespace | Function | GraphFunction } … ]…     // and 2.0 declarations, side by side

What each kind may contain

A .dsm builds its Shader and every ShaderFunction or layer block beside it, each into its own asset, as 1.x did; the material may call such a function by name (2.0.0 – 2.1.0 refused it with DSH6201). A .dss makes a material or function assets, not both (DSH6201), so dsc migrate cannot rewrite such a file as one .dss: give each function a .dsf of its own first.

How the restriction is enforced

(since 2.0.0) By the parser, one declaration at a time, and by the binder over the declarations of one file.

A .dsh may hold 1.x blocks and 2.0 declarations side by side, so a project can migrate one file at a time. A comment or a string that mentions Shader( is just a comment or a string.

[!NOTE] Through 1.9.x the rule was a case-insensitive substring scan of each file's text, after its import lines were removed: a .dsh was refused for containing Shader(, ShaderFunction(, … — in a comment or a string too — and a .dsf for containing Shader(, while Shader ( with a space slipped past. Nothing scans text any more: the front end reads the block word, so a .dsf with a Shader block is DSH2259 however it is spaced (2.0.0 – 2.1.0 did not refuse it, and the file built a material like a .dsm). See the retired parser page.

Source roots

Discovery runs over a list of source roots, not a single directory.

Each root owns a Packages folder of its own at <Root>/Packages. A root is the unit of import resolution: an import specifier is resolved against the bases of the root that owns the importing file and never against another root's — see import.

Only the project root is writable. Plugin roots are discovered, parsed and compiled like any other source, but the editor never rewrites a file under one: VirtualFunction sync skips them, and every editor action that writes a source file targets the project root.

[!NOTE] A plugin DShader folder that overlaps an existing root is ignored, with a warning naming both. This happens when Source Directory is pointed at a plugin folder, or at a directory containing one; without the check the same file would belong to two roots and its imports would resolve by scan order.

The source-directory watcher registers one watch per root, so Auto Compile On Save fires for a plugin's sources exactly as it does for the project's.

[!NOTE] The root list is cached. A DShader folder created while the editor is open appears when Refresh (F5) is pressed in the Material Content Browser; its watch, registered once at startup, attaches on the next editor start, so that root's Auto Compile On Save begins working then.

A file under a plugin root that declares no Root= defaults to that plugin's mount point rather than to /Game — a .dsm in Plugins/MoonToon/DShader generates into /MoonToon with no attribute at all. Write Root="/" to opt back into /Game. See Asset paths.

File discovery

Files are found by recursive scans of every source root. Directories are not returned, and every result is normalized to a full path.

[!NOTE] The two exclusions are not symmetric. The all-sources scan drops every file under a packages directory; the generatable scan drops only package .dsm files. A .dsf shipped inside DShader/Packages is therefore still picked up as a generatable file and will produce function assets on a generate-all — and on the 2.0 line so is a .dss, a .dsi or a .dsp there.

(since 2.0.0) The command-line verbs that name their files with -All use scans of their own:

The 2.0 kinds are described under DreamShaderLang 2.0: .dsi material instances and (UE 5.8) .dsp Custom Pass pipelines.

A configured path that is relative is resolved against the project directory. The project's source, packages and generated-shader directories are created at module startup; a plugin's DShader folder is never created, only discovered. See Project settings and Packages.

What each kind generates

A .dsm with no Shader block is still compilable — it produces whatever function assets it does declare. A compile builds what its own file declares, and never what a header it imports declares: a header holds no asset block.

Notes

• Extensions are compared case-insensitively. M_Water.DSM is a material file.
• At most one Shader per file (DSH2250). Through 1.9.x imports were inlined into one text before parsing, so the limit spanned the whole import closure; since 2.0.0 a header is read on its own and cannot hold a Shader at all, so an import never adds one.
• A .dsh is the natural home for VirtualFunction declarations; the editor's Create Virtual Function action writes one under DShader/VirtualFunctions. See VirtualFunction tools.
• Only a .dsh can be imported (since 2.0.0). An import of a .dsf or a .dsm is DSH2252: a material or function file is compiled on its own, and its assets are reached from another file through a VirtualFunction.

Diagnostics

The codes of an import that cannot be resolved, read or parsed, and of a cycle, are on import. Every code: diagnostics.

Example

<Project>/DShader/
├── Materials/
│   └── M_Water.dsm
├── Functions/
│   └── F_Tint.dsf
├── Shared/
│   └── Common.dsh
└── Packages/
    └── @typedreammoon/
        └── dream-noise/
            └── Library/
                └── Noise.dsh

// DShader/Shared/Common.dsh — header: helpers only
Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

// DShader/Functions/F_Tint.dsf — function file: declares ShaderFunction blocks
import "Shared/Common.dsh";

ShaderFunction(Name="Functions/F_Tint")
{
    Inputs = {
        vec3 InColor;
        opt float Strength = 1.0;
    }

    Outputs = {
        vec3 OutColor;
    }

    Graph = {
        OutColor = Common::ApplyTint(InColor, vec3(1.0, 0.9, 0.8)) * Strength;
    }
}

// DShader/Materials/M_Water.dsm — material file: one Shader block
import "Shared/Common.dsh";

Shader(Name="Materials/M_Water")
{
    Outputs = {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph = {
        Color = Common::ApplyTint(vec3(0.1, 0.3, 0.6), vec3(1.0, 0.9, 0.8));
    }
}

Each source builds its own asset; the header builds nothing and is read by both:

M_Water.dsm   ->  /Game/Materials/M_Water        UMaterial
F_Tint.dsf    ->  /Game/Functions/F_Tint         UMaterialFunction
Common.dsh    ->  (nothing)

See also

• import — how a header is found, read and declared into the file that imports it
• Shader — the .dsm-only top-level block
• ShaderFunction — the block a .dsf normally holds
• VirtualFunction — declaring an existing asset from a .dsh
• Lexical elements — comments and strings
• Packages — DShader/Packages and the @scope/name layout
• Project settings — Source Directory and Generated Shader Directory
• Commandlet — compiling files headlessly
• Testing — the Tests/Corpus fixture format