Installation

DreamShaderLang is compiled by the DreamShader Unreal plugin. Everything on this page is done once per project.

Install

Copy the plugin into the project

Download DreamShader-<version>.zip from a GitHub release — its single top-level folder is DreamShader — or clone the repository. Put it at:

MyProject/
└─ Plugins/
   └─ DreamShader/
      └─ DreamShader.uplugin

Keep the folder name DreamShader; the module names, the log category and every path in these docs assume it.

What the release archive holds:

Note:

The archives from 1.6.0 to 2.1.1 did not carry Content/, so an archive install showed the editor UI in English only. To get the translation on an older version, copy Content/Localization/ in from the matching tag. Tests/, Tools/ and Config/ are not in the archive.

Enable it and restart

Enable DreamShader in Edit ▸ Plugins and restart the editor. The plugin descriptor enables WebSocketNetworking and SQLiteCore automatically — the first serves the live-preview WebSocket, the second backs the editor bridge's bridge.db. Only DreamShaderEditor uses either.

There are five modules: DreamShaderLang, DreamShader and DreamShaderPass (Runtime, loaded at PostConfigInit), and DreamShaderCompiler and DreamShaderEditor (Editor, at Default). Only the two Editor modules generate assets; DreamShaderPass is the Custom Pass runtime, built on every engine, running passes on 5.8 only. See About DreamShader.

Confirm the settings page

Open Project Settings and find:

Project Settings ▸ DreamPlugin ▸ Dream Shader

Warning:

The settings live under the DreamPlugin category, not Plugins. If the page is missing, the plugin did not load — check the Output Log for LogDreamShader. The Custom Pass settings are a separate page in the same category, DreamShader Custom Pass.

Let the plugin create its directories

On the first editor start, the runtime modules create the working directories whether or not you have written a single source file:

<Project>/DShader/                                        source root
<Project>/DShader/Packages/                               installed shared libraries
<Project>/Intermediate/DreamShader/GeneratedShaders/      mapped to /DreamShaderGenerated

DShader comes from the Source Directory setting; Packages is always the literal subfolder Packages under it and cannot be configured on its own. GeneratedShaders is still created and mapped, but (since 2.0.0) no compile writes there — a Function's HLSL goes straight into its Custom node. On UE 5.8, DreamShaderPass also keeps .dreampass/ under the source root — the snapshots of Custom Pass HLSL, which belong in version control next to the sources.

Write a source file and save it

Write new sources as .dss:

// <Project>/DShader/Materials/M_InstallCheck.dss
#pragma material(Domain = UI, ShadingModel = Unlit)

export void M_InstallCheck(inout material m)
{
    m.EmissiveColor = float3(0.2, 0.6, 1.0);
}

Or in 1.x syntax, which builds the same asset — keep one of the two files:

// <Project>/DShader/Materials/M_InstallCheck.dsm
Shader(Name="Materials/M_InstallCheck")
{
    Settings = {
        Domain = "UI";
        ShadingModel = "Unlit";
    }

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

    Graph = {
        Color = vec3(0.2, 0.6, 1.0);
    }
}

With Auto Compile On Save on (the default), the file watcher picks up the save and generates the material after the debounce. The Output Log shows:

Generated Material /Game/Materials/M_InstallCheck from .../M_InstallCheck.dss.

Or skip the typing: Tools ▸ DreamShader ▸ Material Content Browser ▸ New ▾ ▸ Material (.dss) writes the same shape from a template.

Verify the installation

Warning:

Do not expect the new material in the Content Browser. Under the default ThinCustom backend it is Ephemeral — in memory only — and hides itself from the Content Browser, asset pickers and save dialogs. See Your first material.

The settings you will touch first

The full panel has 17 properties; these are the ones you meet on day one. Note that the config identifiers keep their b prefix while the display names drop it.

The values go to the project's Config/DefaultEngine.ini, section [/Script/DreamShader.DreamShaderSettings], so everyone who pulls the project shares them. All 17 settings are on Project settings.

Warning:

GeneratedShaderDirectory is read only while the /DreamShaderGenerated virtual shader mount is not yet registered. Changing it mid-session does not move the output — restart the editor.

Where the asset lands

A .dss asset lands under /Game at the file's folder relative to the source root, named after its export function: DShader/Materials/M_Minimal.dss builds /Game/Materials/M_Minimal. A /// @name above the entry names it otherwise.

In 1.x syntax the block header decides: Shader(Name="Materials/M_Minimal") resolves to /Game/Materials/M_Minimal. Name is the package path relative to the root, without a /Game prefix of its own. Root is optional and defaults to Game:

Shader(Name="Materials/M_Minimal", Root="Plugin.MyPlugin")

This generates /MyPlugin/Materials/M_Minimal, physically <Project>/Plugins/MyPlugin/Content/Materials/M_Minimal.uasset. Only project plugins under <Project>/Plugins are accepted; engine and marketplace plugins are refused (DSH8090). The full dispatch rules are on Asset Paths.

Engine compatibility

DreamShader 2.2.0 is developed against Unreal Engine 5.8 and verified on Win64 with a single-plugin RunUAT BuildPlugin:

To check that the plugin builds against an engine without building a full project target:

& "<EngineDir>\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin `
  -Plugin="<ProjectDir>\Plugins\DreamShader\DreamShader.uplugin" `
  -Package="<OutputDir>\DreamShader" `
  -TargetPlatforms=Win64 `
  -Rocket

-Package must point outside the source tree — UAT stages a clean copy there.

Warning:

UE 5.3 and 5.4 do not build under a recent MSVC toolchain, whatever plugin you point at them. The engine's ConcurrentLinearAllocator.h writes #elif __has_feature(address_sanitizer) without a defined() guard, which raises C4668 on a toolchain that ships the ASan headers, and UBT compiles engine code with /we4668. The failure is in engine code, and Source/DreamShader* is named nowhere in it — Epic's own ExampleDeviceProfileSelector fails the same way on the same machine, which confirms the cause. Installing MSVC 14.38 does not by itself help (it ships the ASan headers too); it takes a toolchain without them, or a one-line patch to the engine header. UE 5.5 fixed the header.

Feature availability varies by engine: Substrate needs (since UE 5.4), a few transform bases and parameters need 5.5 or 5.6, and Custom Pass needs (since UE 5.8). The plugin binary is built per engine, so moving a project to a newer engine means rebuilding the plugin. The full list is on About DreamShader ▸ Engine support.

Editor extensions

The language service is not in the plugin. For highlighting, completion, diagnostics and previews, install one of:

Tools ▸ DreamShader ▸ Open Dream Shader Workspace (VSCode) writes DShader/DreamShader.code-workspace, refreshes the bridge manifests and opens it in VSCode. See VSCode and Rider.

Next

• Your first material — write one, then find it
• Project layout — how DShader/ is organized
• Daily workflow — the save, debounce, generate loop
• About DreamShader — what the plugin is made of