Overview
DreamShaderLang is a text language for Unreal Engine materials, compiled by the DreamShader plugin into ordinary material assets; on UE 5.8, .dsp sources add render passes of your own.
DreamShader reference
For tutorials and task-oriented reading, start at the documentation overview.
DreamShader compiles DreamShaderLang source files — .dsm, .dsf, .dsh and, on the 2.0 line,
.dss — into standard Unreal Engine material assets: UMaterial, UMaterialFunction,
UMaterialFunctionMaterialLayer, and UMaterialFunctionMaterialLayerBlend — and, on Unreal Engine 5.8,
.dsp Custom Pass pipelines into UDreamPassPipeline assets that add render passes of
your own. Source files are the authoring surface; the assets are build output and can always be
regenerated.
| Version | 2.2.0 |
| Engines | Unreal Engine 5.3 – 5.8 (Win64 verified); Custom Pass needs 5.8 |
| Modules | DreamShaderLang (Runtime), DreamShader (Runtime), DreamShaderPass (Runtime), DreamShaderCompiler (Editor), DreamShaderEditor (Editor) |
| Source extensions | .dsm material · .dsf function · .dsh header · .dss 2.0 compilation unit · .dsi material instance · .dsp Custom Pass pipeline |
| Project settings | Project Settings ▸ DreamPlugin ▸ Dream Shader |
| License | MIT |
New here? Start with Getting started, then Examples.
DreamShaderLang
[!NOTE] Two syntaxes, one compiler. The 1.x syntax documented below (
.dsm/.dsf/.dsh) is the one that ships. The 2.0 syntax —.dss, HLSL with declarations instead of section blocks — compiles through the new binder/IR/emitter pipeline on the2.0line and has its own page: DreamShaderLang 2.0.
Language reference
The declaration grammar: source files, blocks, and sections.
| Source files | .dsm / .dsf / .dsh and what each may contain |
| Lexical elements | Comments, identifiers, case sensitivity, literals, suffixes |
| Keyword index | Every reserved word and alias, with links |
import | Including headers, functions, and packages |
| Preprocessor | #if and the define table — conditional compilation |
| Types | Type tokens, GLSL aliases, per-context validity |
Top-level blocks
Shader | Generates a UMaterial |
ShaderFunction | Generates a UMaterialFunction |
ShaderLayer / ShaderLayerBlend | Generates native material layer functions |
VirtualFunction | Declares an existing UMaterialFunction |
Function | Reusable HLSL helper |
GraphFunction | HLSL helper that may pull UE.* nodes into its inputs |
Namespace | Groups helpers under Ns::Name |
Sections
Properties | Parameter declarations and group scopes |
Inputs / Outputs | Function signatures and material outputs |
| Output bindings | Base.<Target> = <value>; |
Settings | Material and function settings |
Options | VirtualFunction asset binding |
Layout | Node placement, comment boxes, #Region |
Graph language
The statement and expression language inside Graph = { ... }, which materialises material nodes.
| Statements | Every statement form |
| Declarations | Variables, initialisers, scope |
| Expressions and operators | Precedence, operand rules, integer division |
| Literals | Numeric, boolean, suffixes |
| Constructors | float3(...), vec4(...), integer constructors |
| Swizzles | Channel masks, reorder, repeat |
| Conversions | Widening, narrowing, component-count rules |
if / else | Conditions, truthiness, branch selection |
MaterialAttributes | Struct-like member writes |
| Calls | Calling functions and parameter pins |
| Name resolution | Lookup order and shadowing |
| Node reuse | Common-subexpression deduplication |
| Unsupported constructs | Loops, return, %, indexing — and what happens instead |
Node library
Builtins
UE.* catalogue | Every named material-node builtin |
UE.Expression | The generic reflected-node escape hatch |
OutputType values | Every accepted output-type token |
| Math builtins | lerp, saturate, frac, … |
| Transform builtins | UE.TransformVector / UE.TransformPosition bases |
Substrate.* | Substrate nodes (UE 5.4+) |
| Custom Pass nodes | UE.DreamPassOutput, UE.DreamPassBuffer (UE 5.8) |
DreamShaderBuiltins.ush | Shipped HLSL helper header |
Parameters
| Compact types | float, float3, Texture2D, … |
| Parameter nodes | ScalarParameter, StaticSwitchParameter, … |
| Metadata block | Group, SortPriority, Slider, reflected properties |
SamplerType | Texture sampler configuration |
Using parameters in Graph | Value reads and pin call forms |
Path(...) | Asset references |
Custom Pass
Render passes of your own on Unreal Engine 5.8, without changing the engine: masks and custom buffers, screen-space effects, compute shaders writing data textures.
Pipelines — .dsp | Buffers, passes, injection points, bindings, mesh selection, what the compiler checks |
| Runtime | What makes a pipeline apply, when passes run, built-in and exported buffers, views, debugging, limits |
| HLSL passes | The fixed parameters, slots, snapshots and the pre-check |
| Material nodes | UE.DreamPassOutput for mesh passes, UE.DreamPassBuffer to read an exported buffer |
| Examples | Highlight outline, UI frosted glass, X-ray, wind field |
DreamShaderPass | The module's C++ and Blueprint API |
Build and output
Settings
| Material settings | Special keys plus reflected UMaterial properties |
| Enum values | Every ShadingModel, BlendMode, Domain |
Backend | ThinCustom vs Graph |
| Function settings | Keys honoured by material functions |
| Project settings | DreamPlugin ▸ Dream Shader |
Generation
| Asset paths | Name= and Root= to package and disk paths |
| Ephemeral materials | The thin instance, hidden base, cook behaviour |
| Caching | Source hashing and skipped rebuilds |
| Graph layout | Automatic placement and its limits |
| Regeneration | What survives a rebuild and what does not |
| Divergence | Hand-edited assets: detection, and the three ways out |
| NoGeneration | Sources only a compile that names them builds |
| Generated HLSL | The emitted .ush include |
Tooling
Editor tools
| Editor integration | Menus, toolbar, context menus |
| Material Content Browser | Browse, filter, instance, materialize |
| Preview | Thumbnail and streaming preview |
| Decompiler | Export existing materials, instances and Custom Pass pipelines to source |
| VirtualFunction tools | Declare and sync existing functions |
| Workspace and editor extensions | VSCode workspace, VSCode and Rider plugins |
| Packages | DShader/Packages shared libraries |
| Commandlet | Headless compile and decompile |
| Editor bridge | Request files, WebSocket protocol, artifacts |
C++ API
DreamShaderModule.h | Module, log category, exported functions |
DreamShaderTypes.h | The parsed-source data model |
DreamShaderParser.h | Retired in 2.0 — what replaced the 1.x parser entry point |
DreamShaderSettings.h | UDreamShaderSettings |
DreamShaderMaterialInstance.h | The generated instance class |
DreamShaderVersionCompat.h | Engine-version macros |
DreamShaderCompiler | Compiler interfaces and service |
DreamShaderPass | Custom Pass: the pipeline asset, settings, subsystem, volume and components |
Reference
| Diagnostics index | Every error and warning, with cause and fix |
| Disabling diagnostics | disable_warning / disable_error, for a file or a line |
| Examples | Complete, copy-pasteable sources |
| Contributing | Building the plugin |
| Testing | Automation suite and the fixture corpus |
| Release | Tagging and packaging |
External links
| Repository | https://github.com/TypeDreamMoon/DreamShader |
| Issues | https://github.com/TypeDreamMoon/DreamShader/issues |
| Documentation site | https://shader.toolchain.64hz.cn/ |
| VSCode extension | https://github.com/TypeDreamMoon/dreamshader-language-support |
| Rider plugin | https://github.com/tsdaer/dreamshader-language-support |
| Changelog | ../CHANGELOG.md |