Packages

A package is a reusable DreamShaderLang library: .dsh headers, .dsf function files, examples, a README. Packages are installed under DShader/Packages and reached by import.

Layout

The directory name is hard-coded: the package root is always the literal subdirectory Packages of the configured source directory. Changing Source Directory moves it; there is no separate package directory setting.

Division of labour

Everything marked extension is defined and enforced by the editor extensions in their own repositories, and cannot be observed from the plugin at all.

Import resolution

An import specifier is normalized, then tried against three candidate roots in order. The first candidate that both stays inside its own root and exists on disk wins. This resolver is shared by the compiler's import inliner and the editor's dependency scanner, so both agree.

Specifier normalization

Step 4 means import "@scope/pkg/Library/Noise" and import "@scope/pkg/Library/Noise.dsh" are the same import. An extensionless specifier can therefore never resolve to a .dsf.

Candidate roots

Because candidate 1 is rooted at Packages for a file that lives inside a package, a .dsh inside a package can reach its siblings with a relative specifier but cannot climb out of the package tree with ../: the escape guard rejects that candidate, and resolution falls through to roots 2 and 3.

A specifier that resolves under no root produces DreamShader import '{Specifier}' referenced from '{File}' could not be resolved. The full grammar, cycle handling and line-number mapping are on Imports and Namespaces.

Source-file enumeration

The plugin has two enumerators. They exclude different things, and that asymmetry decides which package files are compiled.

The exclusion test is a case-insensitive path-prefix comparison against the package directory, and it matches the package directory itself as well as anything beneath it at any depth.

Package .dsh headers are fully importable but are never scanned for VirtualFunction declarations, so a VirtualFunction block shipped inside a package is never validated or refreshed against its UMaterialFunction asset. See Editor Tools.

dreamshader.package.json

Placed at the root of a package. Not read by the plugin. The fields below are the convention the extension's installer and store use; the extension repository is authoritative.

{
  "name": "@typedreammoon/dream-noise",
  "version": "1.0.0",
  "displayName": "Dream Noise",
  "description": "Reusable noise functions for DreamShaderLang.",
  "author": "TypeDreamMoon",
  "repository": "https://github.com/TypeDreamMoon/dream-noise",
  "license": "MIT",
  "dreamshader": {
    "language": "DreamShaderLang",
    "version": ">=1.0.0",
    "entry": "Library/Noise.dsh"
  },
  "keywords": ["noise", "fbm", "voronoi"]
}

A package repository becomes discoverable in the store by carrying the GitHub topic dreamshader-package.

dreamshader.lock.json

Neither read nor written by the plugin. Deleting it changes nothing about compilation; it exists so a team can see which package revisions are checked in. Commit it if your team installs packages.

Extension commands

Command-palette entries provided by the VSCode extension. Install and update require a working git on PATH — the plugin never downloads anything.

DreamShaderLang: Install Package from GitHub
DreamShaderLang: Browse Package Store
DreamShaderLang: Update Installed Packages
DreamShaderLang: Remove Installed Package
DreamShaderLang: Open Packages Folder
DreamShaderLang: Add Package Store Index Source
DreamShaderLang: Remove Package Store Index Source
DreamShaderLang: Create Package Step by Step

Install accepts either an owner/repo shorthand or a full https://github.com/owner/repo URL. The store reads one or more index JSON files, configured through dreamshader.packageStoreIndexUrls, plus an optional GitHub topic search — see VSCode and Rider.

Authoring a package

A library header:

Namespace(Name = "DreamNoise")
{
    Function float Remap01(float x)
    {
        return saturate(x * 0.5 + 0.5);
    }
}

And a project material consuming it:

import "@typedreammoon/dream-noise/Library/Noise.dsh";

Shader(Name="Materials/M_Noise")
{
    Properties = {
        float Scale = 4.0 [Slider(0.1, 32)];
    }

    Outputs = {
        vec3 Color;
        Base.EmissiveColor = Color;
    }

    Graph = {
        vec2  UV = UE.TexCoord(Index = 0);
        float N  = DreamNoise::Remap01(UV.x * Scale);
        Color = vec3(N, N, N);
    }
}

Versioning

Design guidance

Notes

• The package directory is created at module startup even when it is empty, and even in a commandlet process, alongside the source directory and the generated-shader directory.
• Package files are ordinary files. Nothing prevents editing a package .dsh in place — but the extension's update command overwrites it.
• Because the exclusion is a path test, a symbolic link or junction that points a non-package path at package content is treated as whatever its resolved path is.

Example

A package installed at DShader/Packages/@typedreammoon/dream-noise/, and how its specifier resolves:

specifier   @typedreammoon/dream-noise/Library/Noise.dsh
candidate 1 <Project>/DShader/Materials/@typedreammoon/dream-noise/Library/Noise.dsh   missing
candidate 2 <Project>/DShader/@typedreammoon/dream-noise/Library/Noise.dsh             missing
candidate 3 <Project>/DShader/Packages/@typedreammoon/dream-noise/Library/Noise.dsh    resolved

Dropping the extension resolves identically:

import "@typedreammoon/dream-noise/Library/Noise";

Where next