Plugin Overview
The purpose and capabilities of the DreamShader plugin, and how it relates to DreamShaderLang.
DreamShader is the Unreal plugin that compiles DreamShaderLang source files into Unreal material assets. DreamShaderLang is the source language; the plugin handles parsing, generation, diagnostics, cache tracking, decompilation, and editor integration.
Current plugin version: 1.4.0. It is actively developed against Unreal Engine 5.7
and has been verified with single-plugin RunUAT BuildPlugin builds on Unreal Engine
5.3, 5.4, 5.5, 5.6, and 5.7.
Problem It Solves
Unreal material graphs become hard to review, diff, reuse, and migrate as they grow. DreamShader moves the repeatable parts into text:
| Pain point | DreamShader answer |
|---|---|
| Large graphs are hard to review | Store graph structure in .dsm / .dsf files. |
| Shared logic is duplicated | Put helpers in .dsh, .dsf, Function, GraphFunction, or packages. |
| Material functions are easy to break on regeneration | Preserve stable inputs and outputs for ShaderFunction assets. |
| UE 5.7 Substrate graphs need text authoring | Use the Substrate type, Base.FrontMaterial, and Substrate.* wrappers. |
| Existing graphs need migration | Export Material and Material Function assets as .dsm / .dsf starting points. |
| Material iteration needs faster feedback | Request a .dsm material preview from VSCode through the Unreal bridge. |
Core Capabilities
| Capability | Description |
|---|---|
| Source scanning | Watches the configured DShader source directory. |
| Asset generation | Generates UMaterial, UMaterialFunction, Material Layer, and Layer Blend assets. |
| Graph generation | Converts Graph DSL statements into Unreal MaterialExpression nodes. |
| Substrate generation | Supports Substrate graph values, Base.FrontMaterial, and current UE 5.7 Substrate wrappers. |
| Diagnostics | Reports parse, semantic, generation, and bridge diagnostics back to the editor. |
| MaterialExpression metadata | Exports reflected node metadata for editor completion and hover. |
| Material preview bridge | Writes preview results under Saved/DreamShader/Bridge and can stream local WebSocket preview frames to VSCode. |
| Decompile export | Creates initial .dsm / .dsf sources from existing Unreal assets. |
| Package workflow | Resolves package imports from DShader/Packages. |
Language vs Plugin
| Part | Responsibility |
|---|---|
| DreamShaderLang | Syntax, declarations, Graph expressions, helper functions, imports, and package references. |
| DreamShader plugin | Finds files, parses sources, resolves imports, creates Unreal assets, writes metadata, reports diagnostics, and serves preview results. |
| Editor extensions | Provide syntax highlighting, completion, hover, navigation, diagnostics, material preview, package commands, and templates. |
Outputs
| Declaration | Unreal asset |
|---|---|
Shader | UMaterial |
ShaderFunction | UMaterialFunction |
ShaderLayer | UMaterialFunctionMaterialLayer |
ShaderLayerBlend | UMaterialFunctionMaterialLayerBlend |
VirtualFunction | No generated asset; references an existing material function. |
.dsh | No direct asset; contributes imports and shared helpers. |
Best Fit
DreamShaderLang works best for:
| Scenario | Why it fits |
|---|---|
| Parameterized UI / Unlit materials | These graphs are often formulaic and easy to describe as text. |
| Shared material helper libraries | .dsh, .dsf, and package imports make reuse explicit. |
| Team-reviewed material changes | Text diffs are easier to review than graph screenshots. |
| Generated or migrated materials | Decompile export and source regeneration reduce manual graph work. |
Very visual one-off graphs can still be authored directly in Unreal, then exported later if they become stable or need to be reused.