插件工作流

DreamShader 的推荐工作流是：文本源文件作为真实来源，Unreal 资产作为生成结果。这样材质逻辑可以被搜索、审查、复用和版本管理。

日常流程

1. 在 DShader 中创建或修改 .dsm / .dsf / .dsh。
2. 在 .dsh 中维护共享 Function 和 Namespace，在 .dsf 中维护可复用 ShaderFunction。
3. 在 .dsm 中通过 import 引入共享文件、函数文件或 Package。
4. 在 Shader / ShaderFunction / ShaderLayer / ShaderLayerBlend 的 Graph 中描述节点连接。
5. 保存源文件，或通过 VSCode 扩展执行重编命令。
6. 在 Unreal Editor 中查看生成的材质或材质函数。
7. 对 .dsm 材质，可以在 VSCode 中打开 DreamShaderLang: Show Material Preview，快速查看当前生成材质的预览结果。

.dsm 工作流

.dsm 是资产入口：

Shader(Name="DreamMaterials/M_Tinted")
{
    Properties = {
        vec3 Tint = vec3(1.0, 0.5, 0.25);
    }

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

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

    Graph = {
        Color = Tint;
    }
}

.dsh 工作流

.dsh 适合放共享 helper：

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

.dsm 引入：

import "Shared/Color.dsh";

保存 .dsh 后，插件会刷新依赖它的 .dsm / .dsf。

.dsf 工作流

.dsf 适合放可复用的 ShaderFunction 资产：

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;
    }
}

其他 .dsm 或 .dsf 可以 import 并调用它：

import "Functions/F_PulseTint.dsf";

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

如果 helper 需要在 Custom 节点中复用 UE.* 图节点，可以使用 GraphFunction：

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

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

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

多输出 helper 仍然使用显式 out 变量调用。

Material Layer 工作流

ShaderLayer 和 ShaderLayerBlend 适合把 Unreal Material Layer 函数资产纳入文本化流程：

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

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

ShaderLayer 必须输出且只输出一个 MaterialAttributes。ShaderLayerBlend 必须至少有两个 MaterialAttributes 输入，并输出一个 MaterialAttributes。旧的 MaterialLayer / MaterialLayerBlend 写法仍可解析，但新源码建议使用 ShaderLayer / ShaderLayerBlend。

生成和缓存

DreamShader 会在生成资产时记录：

DreamShader.SourceFile
DreamShader.SourceHash
DreamShader.GeneratedAtUtc

如果源内容没有变化，可以跳过重复生成。这个机制适合全量扫描或自动保存场景。

从 1.3.2 起，生成 ShaderFunction 时会尽量保留输入输出 ID，减少普通 Unreal 材质中已有 MaterialFunctionCall 节点在函数重生成后断线的风险。

材质预览

VSCode 扩展的 Show Material Preview 命令会向 Unreal Bridge 请求当前 .dsm 材质预览。Unreal 侧会先解析并生成对应材质，再输出预览状态和图片：

Saved/DreamShader/Bridge/preview.json
Saved/DreamShader/Bridge/Preview/*.png

如果 Unreal Bridge 的本机 WebSocket 正常监听，扩展会通过 127.0.0.1:17864 接收预览结果和连续帧；否则会回退到文件桥。预览只面向 .dsm 材质源文件，不用于 .dsf 函数文件或 .dsh 共享头文件。

可用场景：

反编译迁移

已有 Unreal 材质可以从 Content Browser 右键导出：

反编译会尽量保留常见参数、常量、算术、swizzle、纹理采样、Custom 节点、MaterialFunctionCall 和部分布局信息。少见节点会用 UE.Expression(...) 保留结构。导出结果适合作为迁移初稿，建议再手动整理命名、helper 分层和 Package 依赖。

团队协作建议