顶层声明

Shader、ShaderFunction、ShaderLayer、VirtualFunction、Function、GraphFunction 和 Namespace 的完整结构。

顶层声明决定当前文件生成什么、暴露什么、复用什么。

`Shader`

Shader 生成 UMaterial。

Shader(Name="DreamMaterials/M_Sample", Root="Game")
{
    Properties = {
        float Strength = 1.0;
    }

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

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

    Graph = {
        Color = vec3(Strength, Strength, Strength);
    }
}

规则：

项目	规则
`Name`	必填，解析为 `Root` 下的相对资产路径。
`Root`	可选，默认 `Game`。支持 `Game`、`Plugin.PluginName`，也可追加子目录，例如 `Game/Generated`；`Plugin.PluginName` 指向 `[Project]/Plugins/PluginName/Content`，`Plugins.PluginName` 作为兼容写法同样支持。
`Graph`	必填。没有 `Graph` 会报错。
`Outputs`	强烈建议显式提供；没有输出绑定时无法得到有效材质输出。
`Code`	不再作为 `Shader` section 使用，必须改为 `Graph`。

`ShaderFunction`

ShaderFunction 生成 UMaterialFunction。

ShaderFunction(Name="Functions/F_Tint", Root="Plugin.MyPlugin")
{
    Properties = {
        const Texture2D PreviewTex;
    }

    Inputs = {
        vec3 InColor;
        opt vec3 InTint = vec3(1.0, 1.0, 1.0) [
            Description="Preview tint";
        ];
        opt Texture2D BaseColorTex = PreviewTex;
    }

    Outputs = {
        vec3 OutColor;
    }

    Settings = {
        Description = "Tint helper";
        ExposeToLibrary = true;
        LibraryCategories = "DreamShader,Color";
    }

    Graph = {
        OutColor = InColor * InTint;
    }
}

规则：

项目	规则
`Name`	必填，生成 `UMaterialFunction` 的资产路径。
`Root`	可选，规则同 `Shader`。
`Properties`	可选，声明材质函数内部的 parameter/helper 节点。
`Inputs`	输入 pin 声明。
`Outputs`	输出 pin 声明。
`Graph`	材质函数内部图。
`Settings`	支持材质函数元数据，例如说明和库分类。

输入声明前可加 opt，表示该输入可以使用 Unreal FunctionInput 的预览默认值。调用时可以传 default 或省略尾部可选输入。

`ShaderLayer` 与 `ShaderLayerBlend`

ShaderLayer 生成 Unreal 原生 UMaterialFunctionMaterialLayer，ShaderLayerBlend 生成 UMaterialFunctionMaterialLayerBlend。两者复用 ShaderFunction 的 Properties、Inputs、Outputs、Settings 和 Graph sections。

ShaderLayer(Name="Layers/L_SimpleSurface", Root="Game")
{
    Outputs = {
        MaterialAttributes Attrs;
    }

    Graph = {
        Attrs.BaseColor = vec3(0.8, 0.2, 0.1);
        Attrs.Roughness = 0.5;
    }
}

ShaderLayerBlend 示例：

ShaderLayerBlend(Name="Layers/L_BlendByMask")
{
    Inputs = {
        MaterialAttributes BaseLayer;
        MaterialAttributes TopLayer;
        float Mask;
    }

    Outputs = {
        MaterialAttributes Result;
    }

    Graph = {
        Result.BaseColor = lerp(BaseLayer.BaseColor, TopLayer.BaseColor, Mask);
        Result.Roughness = lerp(BaseLayer.Roughness, TopLayer.Roughness, Mask);
    }
}

规则：

项目	规则
`Name`	必填，生成 Layer Function 资产路径。
`Root`	可选，规则同 `Shader`。
`Outputs`	必须声明且只声明一个 `MaterialAttributes` 输出。
`ShaderLayerBlend.Inputs`	至少声明两个 `MaterialAttributes` 输入。
`MaterialLayer` / `MaterialLayerBlend`	旧兼容写法，仍可解析但会产生废弃警告；新源码应使用 `ShaderLayer` / `ShaderLayerBlend`。

`VirtualFunction`

VirtualFunction 声明一个已经存在的 Unreal UMaterialFunction，让 Graph 可以像调用 ShaderFunction 一样调用它。它只描述签名和资产引用，不生成、不保存、不覆盖对应资产。

VirtualFunction(Name="BufferWriter")
{
    Options = {
        Asset = Path(Plugins.MoonToon, "MaterialFunctions/Buffer/Writer");
        Description = "Existing MoonToon material function";
    }

    Inputs = {
        float3 Color;
        opt float Alpha = 1.0 [
            Description="Preview alpha";
        ];
    }

    Outputs = {
        float3 Result;
    }
}

规则：

项目	规则
`Name`	必填，作为 `Graph` 中的调用名。
`Options.Asset`	必填，指向已有 `UMaterialFunction`。支持 `Path(Game, "...")`、`Path(Engine, "...")`、`Path(Plugin.PluginName, "...")` / `Path(Plugins.PluginName, "...")` 和完整 Unreal object path。
`Inputs`	输入 pin 声明，需要与已有材质函数资产对应。
`Outputs`	输出 pin 声明，至少一个。
`Graph` / `Code`	不支持，`VirtualFunction` 不拥有实现。

调用：

Graph = {
    float3 result = BufferWriter(Color, 1.0, Output="Result");
}

Material Function 资产右键菜单和 Material Function 编辑器工具栏中的 DreamShader 下拉菜单可以复制定义、创建 .dsh 定义文件，并复制 Graph 调用示例。

`Function`

Function 定义可复用 HLSL helper。它不会生成 Unreal 资产，而是供 Graph 创建 Custom 节点调用。

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

参数规则：

参数限定符	含义
`in`	输入参数。
`out`	输出参数，调用时必须传变量名。

至少需要一个 out 参数：

Function GetPair(in float x, out float a, out float b) {
    a = x;
    b = x * x;
}

调用：

Graph = {
    float a;
    float b;
    GetPair(2.0, a, b);
}

单输出 Function 可以作为 Graph 值表达式使用：

Graph = {
    float value = Remap01(2.0);
}

多输出 Function 仍必须使用显式 out 变量调用。

`GraphFunction`

GraphFunction 定义可复用 Custom 节点 helper。它的函数体仍按 HLSL 风格书写，但允许调用 UE.* 图节点。DreamShader 会先创建对应 Unreal 材质节点，再把节点输出作为自动输入 pin 接入 Custom 节点。

GraphFunction BuildPulse(in float scale, out float result) {
    float t = UE.Time();
    result = sin(t * scale);
}

调用规则与 Function 相同：

Graph = {
    float pulse = BuildPulse(2.0);
}

项目	规则
参数	使用 `in` / `out`。
单输出	可以作为值表达式使用。
多输出	必须传显式 `out` 变量。
`UE.*`	允许在 `GraphFunction` 体内使用，不允许在普通 `Function` 体内使用。
递归	会进行递归调用检测。

`SelfContained` 与 `Inline`

普通 Function / GraphFunction 会生成 .ush include，并由 Custom 节点引用。

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

自包含 helper 会把依赖代码嵌入 Custom 节点：

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

Inline 是 SelfContained 的别名：

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

适合场景：

模式	适合
普通 `Function` / `GraphFunction`	项目内持续使用 DreamShader，代码集中生成到 `.ush`。
`SelfContained` / `Inline`	需要把生成资产交给未安装 DreamShader 的项目使用。

`Namespace`

Namespace 用来组织一组 Function 或 GraphFunction。

Namespace(Name="Texture")
{
    Function Sample2DRGB(in Texture2D texture, in float2 uv, out float3 color) {
        color = Texture2DSample(texture, textureSampler, uv).rgb;
    }
}

调用：

Graph = {
    vec2 uv = UE.TexCoord(Index=0);
    vec3 sampled;
    Texture::Sample2DRGB(MainTex, uv, sampled);
}

规则：

项目	规则
`Name`	必填，必须是合法标识符。
内容	可以包含 `Function` 和 `GraphFunction`。
调用	使用 `NamespaceName::FunctionName(...)`。
生成	内部会映射为安全的 HLSL 符号名，避免原生 `::` 问题。

本页目录