Imports and Namespaces

import inlines another DreamShaderLang source file into the current translation unit. It belongs to neither grammar: the editor source loader strips it line by line, before the declaration parser is ever called, so the parser does not know it as a keyword.

<file>.dsm
  │
  ├─ editor source loader   strip `import` lines, inline targets depth-first,
  │                         enforce the .dsh / .dsf content rules
  │
  ├─ declaration parser     blocks, sections, statements  ->  definition tree
  │
  └─ material generator     Graph expression grammar  ->  material nodes  ->  asset

Syntax

import "<specifier>" [;] [// <comment>]
import '<specifier>' [;] [// <comment>]

<specifier>      := [ <root-qualifier> ":" ] <path>
<root-qualifier> := Project | Plugin.<PluginName> | Plugins.<PluginName>

The directive must be the first thing on its line — leading whitespace is allowed, anything else is not. After the closing quote only an optional ; since 1.2.2 and an optional // comment may follow. import itself is matched case-insensitively.

import "Shared/Common";                                   // -> Shared/Common.dsh in this file's own root
import '@typedreammoon/dream-noise/Library/Noise.dsh';    // -> <root>/Packages/@typedreammoon/…
import "../Functions/F_Tint.dsf"                          // -> relative to the importing file
import "Plugin.MoonToon:Shared/Toon.dsh";                 // -> another root, see below <Since v="1.6.0" />

A bare <path> resolves inside the importing file's own source root. The <root-qualifier> prefix since 1.6.0 is the one thing that lets an import reach a different root.

Recognition

Each physical line is tested against these rules in order. A line failing any of them is not an import and is passed to the parser unchanged.

Specifier normalisation

So import "Shared/Common" and import "Shared/Common.dsh" are the same directive. Importing a .dsf or a .dsm therefore requires the explicit extension (.dsf since 1.3.5).

Resolution

Three candidate paths are tried in order. Each is paired with a containment root; a candidate resolving outside its root is skipped rather than reported, and the first candidate that exists on disk wins.

Source roots

Candidates 2 and 3 belong to the owning root of the importing file — the source root the file sits under.

A file under no root — a test fixture, a commandlet -Source pointing outside the tree — takes the project's source and packages directories for candidates 2 and 3, which is what every file did before roots existed.

Crossing a root deliberately

Prefix the specifier with a root qualifier and a :.

The vocabulary is the one Root= already uses, minus the package-only spellings, and the qualifier is matched case-insensitively. Project names the project root whatever Source Directory points at.

A qualified specifier is rooted by construction, so only two candidates are tried — the target root's source directory and its packages directory, in that order — and both are containment-checked the same way. There is no relative-to-the-importing-file candidate, and the importing file's own root is not consulted.

The containment comparison is case-insensitive on every platform; whether a candidate is then found still follows the file system's own case behaviour.

Containment is what stops a specifier climbing out of the tree. .. segments are resolved before the check, so:

• from a file directly under DShader, import "../Secret.dsh" resolves above the source directory and candidate 1 is skipped; candidates 2 and 3 collapse the same .. and land outside their own roots, so they are skipped too;
• from a file under DShader/Packages/@scope/pkg/, .. may traverse anywhere inside DShader/Packages, because that is the containment root chosen for it;
• for a source file under neither directory the containment root is its own directory, so no .. specifier can resolve at all.

Package-style paths

@scope/name/… is not a distinct path syntax. @ is an ordinary directory-name character, and a specifier such as "@typedreammoon/dream-noise/Library/Noise.dsh" resolves through candidate 3 simply because DShader/Packages/@typedreammoon/dream-noise/Library/Noise.dsh exists on disk. There is no scope registry, no version resolution and no special-cased root.

See Packages for the layout this convention assumes.

Inlining, cycles and ordering

The loader walks the import graph depth-first and produces one flat text for the parser.

Each file's contribution is wrapped in marker comments, and every import line is replaced by an empty line so the lines below it keep their original numbers:

// Begin DreamShader source: <Project>/DShader/Shared/Common.dsh
Namespace(Name="Common")
…
// End DreamShader source: <Project>/DShader/Shared/Common.dsh

// Begin DreamShader source: <Project>/DShader/Materials/M_Water.dsm
                                     <- blank lines where the imports were
Shader(Name="Materials/M_Water")
…
// End DreamShader source: <Project>/DShader/Materials/M_Water.dsm

Namespaces across files

A Namespace is not a module and has nothing to do with import. Because the closure is one flat text, namespaces from imported headers are visible with no further declaration — and they collide across files exactly as they would within one.

// DShader/Lib/Common.dsh
Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

import "Lib/Common.dsh";

Graph = {
    vec3 Tinted;
    Common::ApplyTint(Base, Tint, Tinted);
}

The declaration rules, :: resolution and the body-normalisation trap are on Functions.

Source-line mapping

Diagnostics are mapped back from the assembled text to the file you actually wrote.

• The mapper scans the error text for the literal near index and reads the integer that follows. That is the only channel by which a parse error carries a position — which is why so many messages end in near index {Index}.
• It then walks the assembled text, tracking the current // Begin DreamShader source: file and a per-file line counter that resets at each marker. Marker lines do not advance the counter.
• A located message is formatted <file>(<line>,<column>): <message>; when mapping fails the form is <file>: <message>.
• Graph errors are anchored separately: the parser records where each Graph body starts, and a graph-relative line and column are offset onto that origin. The column offset applies only to the body's first line.

Organising a project

A single stable entry header per project keeps that graph shallow:

// DShader/Shared/Common.dsh
import "Shared/Color.dsh";
import "Shared/Texture.dsh";

Namespace(Name="Project")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

// every material imports one file
import "Shared/Common.dsh";

Diagnostics

Where to next