Backend

DreamShader » Settings » Backend

Shader 设置，用于选择源文件如何被物化：一个可见的 UMaterial 节点图， 还是隐藏基础材质之上的一个轻量材质实例。

概要

Shader(Name = "<asset-path>")
{
    Settings [=] {
        Backend = { "Graph" | "ThinCustom" | "Instance" };
    }
}

该值在去除首尾空白并去除引号后以大小写不敏感方式匹配；引号可选。 Backend 是一个特殊键：它在源文件绑定时被读取，永远不会到达材质或 反射解析器。2.0 的写法是 #pragma material(Backend = ThinCustom)。

可接受的取值

[!WARNING] Backend = "Instance" 自 1.5.0 起已弃用。它是 ThinCustom 的别名；旧的无图实例后端已退役， 运行时不再存在 Instance 后端。该拼写仍然能编译，并且自 2.0.0 起会以 DSH7204 警告说明这一点。 请将其替换为 Backend = "ThinCustom"; —— 或删除该键，让项目默认值生效。

[!NOTE] Backend = ""; 是一个错误 （自 2.0.0 起）。1.x 将其读作 Graph，这等于用一个没人写的值 悄悄覆盖了项目默认值。只有不写该键才会回落到 Default Compiler Backend；如果你想要的就是它，请写 Graph。

优先级

显式写的 Backend 永远压过项目设置。项目设置见 项目设置。

Backend 在源文件绑定时解析，早于任何材质对象存在，也早于 Settings 的其余部分被应用。 无法识别的值是一个绑定错误，因此编译会在那里停止，该文件不会再报告构建期的设置诊断。

每种后端产出什么

Graph

ThinCustom （自 1.5.0 起）

UDreamShaderMaterialInstance 覆盖了两个 UObject/UMaterialInterface 行为：

构建时发现本该是 Ephemeral 的资产却已保存，会记一条警告： '{Asset}' exists as a saved asset, so it is rebuilt and saved on disk rather than in memory. Run Tools > DreamShader > Make Ephemeral to make it Ephemeral again. 见 内存材质。

修改项目默认值

在编辑器运行时修改 Default Compiler Backend 会重建工程的源文件，并记录 DreamShader setting '{Setting}' changed; regenerating all source files.。构建键不受这次修改影响的源文件会被跳过。如果磁盘上还有持久化的生成资产，会弹出提示 指向清理操作：{Count} 个先前生成的资产仍保存在磁盘上并遮蔽 Ephemeral 材质。运行 Tools > DreamShader > Make Ephemeral 将其删除。

单独给某个材质切换后端会把之前的资产留在原地。接下来你就会撞上上面的复用冲突错误；删掉旧资产再重新生成。

备注

• 后端不改变语言层面的能力。两种后端构建相同的节点图，接受完全相同的功能集；它们的区别仅在于由哪个对象承载图、哪个对象可被寻址。
• 在 ThinCustom 下，从生成的实例上读取 BlendMode 或着色模型，显示的是从隐藏基础材质继承来的值——设置正是写在那里的。
• ThinCustom 产物在日常编辑器工作中是 Ephemeral 的：它在 cook 时通过命令行，或通过显式的 物化 操作写入磁盘。而 Graph 材质在构建时即被保存。参见临时材质。
• Backend 仅在 Shader 块中生效。在 ShaderFunction 的 Settings 块中，它是一条 DSH3263 警告并会被忽略——参见函数设置。

诊断

信息性输出：

示例

Shader(Name="Docs/M_ThinCustom", Root="Game")
{
    Properties {
        VectorParameter Tint = float4(0.2, 0.6, 1.0, 1.0) [Group="Look"];
    }

    Settings {
        Backend      = "ThinCustom";
        Domain       = "Surface";
        ShadingModel = "DefaultLit";
        BlendMode    = "Opaque";
        TwoSided     = true;
    }

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

    Graph {
        Color = Tint.rgb;
    }
}

生成的资产：

package     /Game/Docs/M_ThinCustom
asset       /Game/Docs/M_ThinCustom.M_ThinCustom      UDreamShaderMaterialInstance
subobject   MB_DreamThinBase_M_ThinCustom             UMaterial  (hidden base, same package)

Settings applied to:  MB_DreamThinBase_M_ThinCustom
  BlendMode    = BLEND_Opaque
  ShadingModel = MSM_DefaultLit
  TwoSided     = true

该列表对应的是持久化模式。在编辑器日常的纯内存模式下，实例是同一个对象，但基础材质是 transient 包中一个单独的对象，名为 MB_DreamThinBase__Game_Docs_M_ThinCustom——使用的是净化后的包路径，而非叶子名。

同一个文件改用 Backend = "Graph"; 后，会在 /Game/Docs/M_ThinCustom 处生成单个 UMaterial，由它自身承载图和设置。

另请参阅

• 设置——每种块类型共用的块语法
• 着色器设置——其他特殊键与反射解析器
• 项目设置——默认编译器后端与临时材质可见性开关
• 临时材质——纯内存生成、隐藏基础材质、物化到磁盘
• 生成管线——后端解析在管线中的位置
• 资产路径——Name 与 Root 如何变成包路径
• 缓存——源哈希跳过
• 材质实例 API——C++ 中的 UDreamShaderMaterialInstance
• 着色器——外层块
• 材质内容浏览器——物化并检查生成的资产
• 诊断索引——所有代码