DreamShaderLang

https://shader.toolchain.64hz.cn/docs
Admin
DreamShaderLang is a textual shader language for Unreal Engine that compiles source files into...
Tokens:524,562
Snippets:2,186
Trust Score:2.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### dreamshader.package.json manifest example

Source: https://shader.toolchain.64hz.cn/docs/tools/packages

Example manifest for a DreamShader package. The plugin does not read this file; it is used by the installer and store. Fields include name, version, displayName, description, author, repository, license, dreamshader.language, dreamshader.version, dreamshader.entry, and keywords.

```json
{
  "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"]
}
```

--------------------------------

### 编写 .dss 源文件

Source: https://shader.toolchain.64hz.cn/docs/start/installation

新源文件使用 .dss 扩展名，此示例创建 M_InstallCheck 材质，设置 Domain 为 UI、ShadingModel 为 Unlit，并输出蓝色。

```hlsl
// <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);
}
```

--------------------------------

### Complete DreamShader Material Example

Source: https://shader.toolchain.64hz.cn/docs/generation/pipeline

A sample .dsm file defining a ShaderFunction and a Shader, demonstrating the use of imports and graph-based logic.

```dsm
// DShader/Materials/M_Emissive.dsm
import "Common.dsh";

ShaderFunction(Name="Functions/F_Tint")
{
    Inputs  { vec3 InColor; vec3 InTint; }
    Outputs { vec3 OutColor; }
    Graph   { OutColor = InColor * InTint; }
}

Shader(Name="Materials/M_Emissive")
{
    Properties { vec3 Tint = vec3(1.0, 0.4, 0.1); }
    Settings   { ShadingModel = "Unlit"; }
    Outputs    { vec3 Color; Base.EmissiveColor = Color; }
    Graph      { Color = F_Tint(vec3(1.0, 1.0, 1.0), Tint); }
}
```

--------------------------------

### Group scope and SortPriority counter example

Source: https://shader.toolchain.64hz.cn/docs/parameters/metadata

Shows how Group scopes and SortPriority counters behave in a Properties block: members without explicit Group/Category inherit the enclosing scope, explicit values take precedence, nested scopes combine with '|', and the counter starts at 0 with step 10 shared across all scopes. Members with explicit SortPriority do not consume a counter slot, and declarations outside any scope get no group and SortPriority 32.

```hlsl
Properties {
    Group("Surface") {
        ScalarParameter A = 0.5;                   // SortPriority = 0
        VectorParameter B = float4(1, 1, 1, 1);    // SortPriority = 10
    }
    Group("Detail") {
        ScalarParameter C = 1.0 [SortPriority=99]; // 99 —— 不消耗槽位
        ScalarParameter D = 2.0;                   // SortPriority = 20
    }
    ScalarParameter Loose = 3.0;                   // 无分组，SortPriority = 32
}
```

--------------------------------

### Const Declaration Examples

Source: https://shader.toolchain.64hz.cn/docs/parameters/properties

Examples of using the const keyword to generate constant nodes for floats, vectors, and textures.

```text
const float Gamma = 2.2;                       // Constant
const vec3  Sky   = vec3(0.2, 0.4, 0.9);       // Constant3Vector
const Texture2D Lut = Path(Game, "T_Lut");     // TextureObject
```

--------------------------------

### Substrate.UI

Source: https://shader.toolchain.64hz.cn/docs/builtins/substrate

域输出节点，用于 UI 材质。

```APIDOC
## Substrate.UI

### Description
域输出节点，用于 UI 材质。

### Parameters
| 参数 | 值类型 | 补全 |
|------|--------|------|
| `Color` | 数值 | 是 |
| `Opacity` | 数值 | 是 |
```

--------------------------------

### 关闭编辑器集成：-NoDreamShaderEditorBridge

Source: https://shader.toolchain.64hz.cn/docs/tools/editor

使用 -NoDreamShaderEditorBridge 参数启动 UnrealEditor.exe 以关闭编辑器集成。该参数必须作为裸命令行参数传递，且是唯一被接受的写法。存在时，StartupModule 在创建任何东西之前就返回。

```powershell
UnrealEditor.exe "<Project>.uproject" -NoDreamShaderEditorBridge
```

--------------------------------

### Shader Definition Example

Source: https://shader.toolchain.64hz.cn/docs/builtins/ue-nodes

Example shader definition using UE built-in nodes, showing property declarations, settings, outputs, and graph construction.

```APIDOC
## Shader Definition Example

### Description
An example shader definition using UE built-in nodes, demonstrating property declarations, settings, outputs, and graph construction.

### Syntax
```
Shader(Name="Docs/M_UEBuiltins")
{
    Properties { ... }
    Settings { ... }
    Outputs { ... }
    Graph { ... }
}
```

### Properties
- **Tint** (vec3) - Required - Default: vec3(1.0, 0.6, 0.2)
- **UV0** (UE.TexCoord) - Required - Texture coordinate with Index = 0

### Settings
- **Domain** (string) - Required - Set to "UI"
- **ShadingModel** (string) - Required - Set to "Unlit"

### Outputs
- **Color** (vec3) - Required - Assigned to Base.EmissiveColor

### Graph Nodes
- **UE.Panner** - Parameters: Coordinate, Time, SpeedX, SpeedY
- **UE.Time** - No parameters
- **UE.TranslatedWorldPosition** - No parameters
- **UE.TransformVector** - Parameters: Source, Destination
- **UE.VertexNormalWS** - No parameters
- **UE.PerInstanceFadeAmount** - No parameters
- **UE.VertexColor** - No parameters

### Example
```
Shader(Name="Docs/M_UEBuiltins")
{
    Properties {
        vec3 Tint = vec3(1.0, 0.6, 0.2);
        UE.TexCoord(Index = 0) UV0;
    }

    Settings {
        Domain       = "UI";
        ShadingModel = "Unlit";
    }

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

    Graph {
        float2 uv   = UE.Panner(Coordinate = UV0, Time = UE.Time(), SpeedX = 0.1, SpeedY = 0.0);
        float3 wp   = UE.TranslatedWorldPosition();
        float3 nrm  = UE.TransformVector(UE.VertexNormalWS(), Source = "World", Destination = "Tangent");
        float  fade = UE.PerInstanceFadeAmount();
        float4 vcol = UE.VertexColor();

        Color = (vec3(uv.x, uv.y, wp.z) + nrm) * Tint * vcol.rgb * fade;
    }
}
```

### Generated Nodes
- **TextureCoordinate** (CoordinateIndex 0) <- UV0
- **Panner** (Coordinate, Time, SpeedX) <- uv
- **Time** <- Panner.Time
- **WorldPosition** (camera-relative) <- wp
- **VertexNormalWS** -> Transform
- **Transform** (World -> Tangent) <- nrm
- **PerInstanceFadeAmount** <- fade
- **VertexColor** <- vcol
```

--------------------------------

### GraphFunction example: WindPulse

Source: https://shader.toolchain.64hz.cn/docs/language/blocks

Example GraphFunction that uses UE.Time() to create a pulsing sine wave. The UE.Time() call is extracted into a material node and connected as an input pin.

```hlsl
GraphFunction WindPulse(in float2 uv, out float pulse)
{
    float t = UE.Time();
    pulse = sin(uv.x * 8.0 + t);
}
```

--------------------------------

### Substrate.Add

Source: https://shader.toolchain.64hz.cn/docs/builtins/substrate

Substrate 加法节点，用于将两个材质相加。

```APIDOC
## Substrate.Add

### Description
Substrate 加法节点，用于将两个材质相加。

### Class
UMaterialExpressionSubstrateAdd

### Output
Substrate 输出
```

--------------------------------

### Namespace example: Common.ApplyTint

Source: https://shader.toolchain.64hz.cn/docs/language/blocks

Example Namespace named Common containing a Function ApplyTint. The member name is flattened to Common_ApplyTint (since 2.0.0); Common::ApplyTint and Common_ApplyTint are the same name. Empty namespaces are allowed.

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

--------------------------------

### Substrate.Select

Source: https://shader.toolchain.64hz.cn/docs/builtins/substrate

Substrate 选择节点，用于根据条件选择材质。

```APIDOC
## Substrate.Select

### Description
Substrate 选择节点，用于根据条件选择材质。

### Class
UMaterialExpressionSubstrateSelect

### Output
Substrate 输出
```

--------------------------------

### Example of block form with multiple pins

Source: https://shader.toolchain.64hz.cn/docs/generation/outputs

A concrete example of the block form binding three pins to a single Expression node with class 'VolumetricAdvancedMaterialOutput' and several parameters. All pins share the same header, so the node is created only once.

```shader
Outputs = {
    float _PhaseG_Out;
    float _PhaseG2_Out;
    float _PhaseBlend_Out;

    Expression(Class="VolumetricAdvancedMaterialOutput",
        PerSamplePhaseEvaluation="false",
        MultiScatteringApproximationOctaveCount=0,
        bGroundContribution="false")
    {
        Pin[0] = _PhaseG_Out;
        Pin[1] = _PhaseG2_Out;
        Pin[2] = _PhaseBlend_Out;
    }
}
```

--------------------------------

### CP_Highlight.dsp 完整示例：mesh、compute、fullscreen pass 组合

Source: https://shader.toolchain.64hz.cn/docs/language-v2/passes

一个完整的 .dsp 文件，定义了一个 UDreamPassPipeline，包含三个 pass：mesh pass 绘制遮罩，compute pass 进行模糊，fullscreen pass 合成轮廓。展示了缓冲区声明、参数定义、pass 配置和 HLSL 代码。需要 UE 5.8 及以上版本。

```dsp
// DShader/Passes/CP_Highlight.dsp —— 选中的物体描一圈橙色轮廓，隔着墙也看得见
#pragma pipeline(Order = 100)

/// @group Look
uniform float4 OutlineColor = float4(1.0, 0.6, 0.0, 1.0);
/// @group Look   @slider 1 8
uniform float  OutlineWidth = 3.0;

buffer Mask    : R8(Clear = 0);
/// @desc 模糊后的遮罩；地面材质也读它。
buffer Blurred : R8(Scale = 0.5, Export = true);

pass DrawMask : mesh
{
    Injection = AfterOpaque;
    Filter    = Layer(Highlight);
    Material  = "M_HighlightMask";
    Depth     = None;
    write Output0 = Mask;
}

pass Blur : compute
{
    Injection = AfterOpaque;
    Dispatch  = Blurred;
    read  Source = Mask;
    write Result = Blurred;
    param Radius = OutlineWidth;

    hlsl
    {
        // 入口的语句：Id 是本线程的纹素，超出 dispatch 的线程已经提前返回。
        const float2 UV = (Id.xy + 0.5) * ResultSize.zw;
        const int R = (int)Radius;
        float Sum = 0;
        for (int y = -R; y <= R; ++y)
        {
            for (int x = -R; x <= R; ++x)
            {
                Sum += Source.SampleLevel(DP_LinearClamp, UV + float2(x, y) * SourceSize.zw, 0).r;
            }
        }
        Result[DP_ViewRect.xy + Id.xy] = Sum / ((2 * R + 1) * (2 * R + 1));
    }
}

pass Composite : fullscreen
{
    Injection = BeforePostProcess;
    Material  = "PP_OutlineComposite";
    read  Mask;
    read  Blurred;
    write SceneColor;
    param Color = OutlineColor;
}

```

--------------------------------

### DefaultEngine.ini DreamShader settings example

Source: https://shader.toolchain.64hz.cn/docs/settings/project

Example configuration for DreamShader settings in DefaultEngine.ini, listing all scalar property defaults. Note that container properties like mapping tables and Preprocessor Defines should be edited in the Project Settings panel, not manually.

```ini
[/Script/DreamShader.DreamShaderSettings]
SourceDirectory=(Path="DShader")
GeneratedShaderDirectory=(Path="Intermediate/DreamShader/GeneratedShaders")
DefaultBackend=ThinCustom
GraphLayoutStyle=Blocks
bScanPluginSourceDirectories=True
bShowEphemeralMaterials=False
bAutoCompileOnSave=True
SaveDebounceSeconds=0.250000
bVerboseLogs=False
bExportDecompiledLayout=True
bOpenInNewWindow=True
InstanceSubfolder=Instances
bSyncSourceReferencesOnAssetRename=True
```

--------------------------------

### Substrate.Select

Source: https://shader.toolchain.64hz.cn/docs/builtins/substrate

Selects between two Substrate materials. Available since UE 5.6.

```APIDOC
## Substrate.Select

### Description
Selects between two Substrate materials. Available since UE 5.6.

### Parameters
- **A** (Substrate) - Required - The first material.
- **B** (Substrate) - Required - The second material.
- **SelectValue** (Numeric) - Required - The selection value.

```

--------------------------------

### 工作区操作文件列表

Source: https://shader.toolchain.64hz.cn/docs/tools/vscode

执行 Open Dream Shader Workspace (VSCode) 后会被重写或替换的文件列表。

```text
<Project>/DShader/DreamShader.code-workspace                    重写
<Project>/Saved/DreamShader/Bridge/material-expressions.json    重写
<Project>/Saved/DreamShader/Bridge/settings.json                重写
<Project>/Saved/DreamShader/Bridge/pass-keys.json               重写（2.1.0 起）
<Project>/Saved/DreamShader/Bridge/substrate-builtins.json      重写
<Project>/Saved/DreamShader/Bridge/bridge.db                    整表替换
```
Tokens:
Raw