文件模型

DreamShaderLang 使用三类源文件：.dsm 负责材质和资产入口，.dsf 负责可复用生成函数，.dsh 负责共享 helper 和声明。解析器会把入口文件和它 import 的 .dsf / .dsh 合并成一次编译上下文。

`.dsm`

.dsm 是 Dream Shader Material 文件。它可以包含：

import "Shared/Common.dsh";

Function Helper(in float x, out float result) {
    result = x * x;
}

Shader(Name="DreamMaterials/M_Example")
{
    Properties = {}
    Outputs = {
        float Value;
        Base.EmissiveColor = float3(Value, Value, Value);
    }
    Graph = {
        Helper(1.0, Value);
    }
}

常见用途：

顶层块	是否推荐放在 `.dsm`
`Shader`	推荐。
`ShaderFunction`	可以；更推荐放在独立 `.dsf`。
`ShaderLayer`	推荐，可放在独立 `.dsm`。
`ShaderLayerBlend`	推荐，可放在独立 `.dsm`。
`VirtualFunction`	可以，用于声明已有材质函数资产。
`Function`	可以，但复用逻辑更推荐放 `.dsh`。
`GraphFunction`	可以，但复用逻辑更推荐放 `.dsh`。
`Namespace`	可以，但共享 namespace 更推荐放 `.dsh`。
`import`	推荐，用于引入 `.dsf`、`.dsh` 或 Package。

当前一个 .dsm 中只建议放一个主要生成资产声明，例如一个 Shader、ShaderLayer 或 ShaderLayerBlend。ShaderFunction 更推荐拆到 .dsf。同一个文件可以同时声明共享 helper，但从维护性看，建议按资产拆文件。

`.dsf`

.dsf 是 Dream Shader Function 文件。它适合放可复用的生成函数资产，以及这个函数需要的局部 helper：

ShaderFunction(Name="Functions/F_PulseTint")
{
    Inputs = {
        vec3 Color;
        vec3 Tint;
        float Pulse;
        opt float Strength = 1.0;
    }

    Outputs = {
        vec3 OutColor;
        float OutMask;
    }

    Graph = {
        OutMask = saturate(Pulse * Strength);
        OutColor = Color * Tint * OutMask;
    }
}

推荐只放：

顶层块	用途
`ShaderFunction`	生成可复用 `UMaterialFunction`。
`Function`	该函数文件内或被导入后可用的 HLSL helper。
`GraphFunction`	可复用 Custom 节点 helper。
`Namespace`	一组 helper。
`VirtualFunction`	声明已有 `UMaterialFunction` 签名。
`import`	引入 `.dsh`、其他 `.dsf` 或 Package。

.dsf 不应包含 Shader、ShaderLayer 或 ShaderLayerBlend。从 .dsm 导入 .dsf 后，可以在 Graph 中调用其中生成的 ShaderFunction：

import "Functions/F_PulseTint.dsf";

Graph = {
    F_PulseTint(BaseColor.rgb, Tint, Pulse, Strength, Color, Mask);
}

`.dsh`

.dsh 是 Dream Shader Header 文件。它通常包含：

import "Shared/Math.dsh";

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

推荐只放：

顶层块	用途
`import`	复用其他 header 或 Package。
`Function`	无 namespace 的共享 helper。
`GraphFunction`	可复用 Custom 节点 helper，函数体中可使用 `UE.*` 图节点。
`Namespace`	一组 helper。
`VirtualFunction`	只声明已有 `UMaterialFunction` 签名，不直接生成资产。

.dsh 不直接生成 Shader / ShaderFunction 资产。保存 .dsh 后，DreamShader 会根据 import graph 找到依赖它的 .dsm / .dsf 并重编。

顶层块

一个源文件由若干顶层块组成：

import "..."
Shader(Name="...") { ... }
ShaderFunction(Name="...") { ... }
ShaderLayer(Name="...") { ... }
ShaderLayerBlend(Name="...") { ... }
VirtualFunction(Name="...") { ... }
Function [SelfContained|Inline] Name(...) { ... }
GraphFunction [SelfContained|Inline] Name(...) { ... }
Namespace(Name="...") { Function ... }

Shader、ShaderFunction、ShaderLayer 和 ShaderLayerBlend 使用属性列表：

Shader(Name="DreamMaterials/M_Name")
{
    ...
}

Function 使用 C/HLSL 风格签名：

Function Remap01(in float value, out float result) {
    result = saturate(value * 0.5 + 0.5);
}

注释

语言在 section 与 Graph 解析中支持常见注释：

// 行注释

/*
   块注释
*/

注释不会进入声明解析，但 Function 的函数体本身会作为 HLSL 风格代码保留。

大小写

大多数内置关键字、类型名、设置名和 Unreal 输出绑定以大小写不敏感方式解析。但建议保持文档中的大小写风格：

Shader
ShaderFunction
ShaderLayer
ShaderLayerBlend
VirtualFunction
Function
GraphFunction
Namespace
Properties
Settings
Outputs
Graph

.dsm

.dsf

.dsh

顶层块

注释

大小写

本页目录

`.dsm`

`.dsf`

`.dsh`