Project Layout

DreamShaderLang sources live in one directory under the project root — DShader by default, set by Project Settings ▸ DreamPlugin ▸ Dream Shader ▸ Paths ▸ Source Directory. A relative path resolves against the project directory.

The source directory, its Packages subfolder and the generated-shader directory are created by the plugin at module startup — the first time the editor starts, whether or not you have written any source.

(since 1.6.0) It is no longer the only root: every enabled plugin with a DShader folder contributes a source root of its own — see Plugin source roots below.

Six kinds of source file

The folders are yours to choose; the extension is what matters.

Write new sources as .dss; a .dsm / .dsf is the 1.x syntax, which still builds through the same compiler, so a project can migrate one file at a time with dsc migrate. What each kind may contain is on File model.

The tree

MyProject/
├─ DShader/
│  ├─ Materials/
│  │  ├─ M_Sample.dss
│  │  └─ M_Legacy.dsm
│  ├─ Functions/
│  │  ├─ F_Tint.dss
│  │  └─ F_Old.dsf
│  ├─ Instances/
│  │  └─ MI_Sample_Red.dsi
│  ├─ Passes/
│  │  ├─ P_Outline.dsp
│  │  └─ M_OutlineComposite.dss
│  ├─ Shared/
│  │  ├─ Common.dsh
│  │  └─ Color.dsh
│  ├─ VirtualFunctions/
│  │  └─ Engine.dsh
│  ├─ Decompiled/
│  │  ├─ Materials/
│  │  └─ Functions/
│  ├─ Packages/
│  │  └─ @typedreammoon/
│  │     └─ dream-noise/
│  │        ├─ dreamshader.package.json
│  │        └─ Library/
│  │           └─ Noise.dsh
│  ├─ .dreampass/
│  ├─ DreamShader.code-workspace
│  └─ dreamshader.lock.json
├─ Intermediate/
│  └─ DreamShader/
│     └─ GeneratedShaders/
└─ Plugins/
   └─ DreamShader/

Plugin source roots

(since 1.6.0)

A plugin can ship the sources that build its materials instead of parking them in the project's tree.

Plugins/
└─ MoonToon/
   ├─ DShader/
   │  ├─ Materials/
   │  │  └─ M_Toon.dss
   │  ├─ Shared/
   │  │  └─ Toon.dsh
   │  └─ Packages/
   └─ MoonToon.uplugin

Warning:

A plugin DShader folder that overlaps an existing root is ignored with a warning rather than giving one file two owners. That happens when Source Directory points into a plugin folder, or at a folder that contains one.

Note:

The root list is cached and rebuilt only when Source Directory or the scan switch changes, or on a refresh in the Material Content Browser — which is how to pick up a DShader folder you just created or a plugin mounted mid-session. But watchers are registered once, at startup, so Auto Compile On Save for a root that appeared mid-session starts working on the next editor start.

Directory roles

Warning:

DreamShader.code-workspace is serialized from a fixed object on every invocation — never read, merged or preserved. Hand-added launch, tasks, extensions or extra settings are destroyed. Keep personal configuration in DShader/.vscode/settings.json, which the command never touches.

Naming conventions

A .dss asset is named after its export function, so keeping the file name and the export name the same saves surprises. Extension matching is case-insensitive, so M_Water.DSM is a material file too. Identifiers are another matter: the plugin replaces non-ASCII characters when it sanitizes namespace and function names into HLSL and asset identifiers, so keep those names ASCII.

Imports and includes

Keep each material's imports to a few stable entry points:

// 1.x
import "Shared/Common.dsh";
import "@typedreammoon/dream-noise/Library/Noise.dsh";

// .dss
#include "Shared/Common.dsh"
#include "@typedreammoon/dream-noise/Library/Noise.dsh"

A specifier is tried against three candidates: the importing file's directory, the owning root's source directory, and that root's Packages directory. The first that exists and stays inside its containment root wins — a file in a package cannot ../ its way out. A specifier without an extension gets .dsh appended; only a header can be brought in (importing a .dsf / .dsm is DSH2252). One that resolves nowhere is DSH8292. The full rules are on Imports and namespaces.

Shallow imports pay off in another way: the build key covers every header a file brings in, so editing one header invalidates every file that includes it.

What is compiled, and what is not

Every build path takes the same files (after 2.1.2) — the startup sweep, a save and the dependents it queues, Recompile All, the commandlet's compile -All, the cook and the Material Content Browser:

To use an example, copy it from DShader/Packages to somewhere under DShader/. Through 2.1.2 a package's .dsf, .dss, .dsi or .dsp outside Assets was compiled by the file watcher and Recompile DSM but by none of compile -All, the cook and the Material Content Browser; move such sources under Assets. See Packages ▸ Package assets.

Note:

A source marked NoGeneration (#pragma nogeneration, /// @nogeneration, a 1.x NoGeneration = true) is enumerated like any other, but only a compile that names it builds its assets — see NoGeneration.

A package .dsh header can be imported, but it never takes part in the VirtualFunction declaration scan — a VirtualFunction shipped in a package is never checked against its asset.

Source control

Agree on one Source Directory across the team so imports resolve the same on every machine. The build key records sources by their project-relative path (since 2.1.1), so a second checkout does not rebuild every asset. A plugin's DShader folder is committed with the plugin — it is part of the same deliverable as the plugin's Content/.

Next

• File model — what each 1.x extension may contain
• DreamShaderLang 2.0 — .dss, .dsi and .dsp
• Imports and namespaces — specifier syntax and cycle handling
• Packages — the install root, and the half the plugin does not implement
• Daily workflow — what one save actually triggers