编译器行为
诊断与排错
DreamShaderLang 常见错误、定位来源和处理方法。
DreamShaderLang 的错误大致分为四层：本地编辑诊断、解析错误、生成错误、Unreal 材质编译错误。
| 来源 | 说明 |
|---|
| VSCode 本地诊断 | 编辑时发现语法、引用和简单语义问题。 |
| Unreal Parser | 保存或重编时解析 .dsm / .dsh。 |
| Material Generator | 创建节点、连接输出、应用设置时产生。 |
| Unreal Material Compiler | Unreal 自身材质编译报错。 |
当 .dsm import 了 .dsh，DreamShader 会尽量把错误映射回真实源文件行列：
DShader/Shared/Common.dsh:12:5
这对共享 helper 很重要。否则所有错误都会落到展开后的合并文本里，难以定位。
| 错误 | 原因 | 处理 |
|---|
Shader(Name="...") is required | Shader 缺少 Name。 | 补上资产路径。 |
Only one top-level Shader block is currently supported | 一个文件里写了多个 Shader。 | 拆成多个 .dsm。 |
Shader must provide a Graph block | Shader 没有 Graph。 | 添加 Graph = { ... }。 |
Unknown shader section | Shader 中写了不支持的 section。 | 使用 Properties / Settings / Outputs / Graph。 |
Shader graph sections now use Graph | 还在 Shader 里使用 Code。 | 改为 Graph。 |
Namespace may only contain Function or GraphFunction blocks | namespace 里放了其他顶层块。 | 只保留 Function / GraphFunction。 |
| 错误 | 原因 | 处理 |
|---|
Unknown Graph function | 函数未定义或未 import。 | 检查 import 和 namespace。 |
Graph variable is declared more than once | 重复声明局部变量。 | 改名或复用已有变量。 |
Arithmetic operators cannot be applied to Texture2D values | 对纹理对象做算术。 | 先采样，或只对采样结果运算。 |
String literals can only be used in named UE builtin arguments | 字符串作为普通值使用。 | 只在 UE.* 命名参数里使用字符串。 |
Graph if condition ... must evaluate to a scalar value | 条件不是标量。 | 使用 .r、.x 或 ComponentMask。 |
Graph if statement cannot select Texture2D value | 分支选择纹理对象。 | 分支选择采样后的数值。 |
input ... is not optional and cannot use default | 非 opt 的 ShaderFunction / VirtualFunction 输入使用了 default。 | 给输入加 opt，或传入真实表达式。 |
StaticSwitchParameter ... requires True=... and False=... | 静态开关调用缺少分支。 | 同时提供 True 和 False 命名参数。 |
StaticSwitchParameter ... cannot switch Texture object values | 静态开关直接选择纹理对象。 | 改为选择采样后的数值。 |
Graph #Region must include a name | region 缺少名称。 | 写成 #Region "Surface"。 |
Graph #EndRegion has no matching #Region | 多写或错放 #EndRegion。 | 检查 region 配对。 |
| 错误 | 原因 | 正确写法 |
|---|
must be called with explicit out variables | 多输出 Function / GraphFunction 被当作单值表达式。 | ApplyTint(a, b, result); |
currently uses positional arguments only | 使用了命名参数。 | Fn(a, b, outValue); |
out argument must be a plain variable name | out 位置传了表达式。 | 先声明变量再传入。 |
expects N arguments | 输入和输出目标数量不对。 | 参数数量必须等于 in 加 out。 |
UE.* calls are not allowed in Function | 普通 Function 体内调用了图节点入口。 | 改用 GraphFunction。 |
| 错误 | 原因 | 处理 |
|---|
Unsupported UE builtin call | 调用了未注册的 UE.*，又没写 OutputType。 | 使用 UE.Expression(..., OutputType="...")。 |
Generic UE.* calls require named arguments | 泛型调用用了位置参数。 | 改成命名参数。 |
Class must be a literal value | Class 不是字符串或字面量。 | 写 Class="Sine"。 |
OutputType is not supported | 输出类型不在支持范围。 | 使用 float1/2/3/4 或纹理类型。 |
OutputIndex is out of range | 输出索引不存在。 | 检查 MaterialExpression 输出。 |
UE.CollectionParam requires Collection=Path(...) | MPC 读取缺少 Collection。 | 写 Collection=Path(Game, "Collections/MPC_Name")。 |
UE.CollectionParam collection ... does not contain parameter ... | 指定的 MPC 中没有该参数。 | 检查 Material Parameter Collection 里的参数名。 |
VSCode 扩展 1.2.26 起，UE.CollectionParam(Collection=Path(...), ...) 中的 Path(...) 会被当作 DreamShader helper 处理，不再误报 Unknown function 'Path'。扩展 1.4.x 起，本地诊断改由新的 parser-based language core 提供，并陆续覆盖 .dsf、Layout、Graph region、VolumeTexture / Texture3D 和 Function builtin，能更稳定地区分 Inputs、Graph、Function、Settings、Outputs 和 metadata context。
| 错误 | 原因 | 处理 |
|---|
Layout statement is missing a trailing ';' | Node(...) 或 Comment(...) 后缺少分号。 | 补上 ;。 |
Layout statement should be Node(...) or Comment(...) | Layout 中写了其他调用。 | 只使用 Node 和 Comment。 |
Layout argument ... must use Key=Value syntax | 参数使用了位置写法。 | 改为 X=0、Var="Name"。 |
Layout argument 'X' must be an integer | 坐标或尺寸不是整数。 | 使用整数坐标。 |
Layout Comment Color must be a float4 literal | Color 不是 float4(...) 字面量。 | 写成 Color=float4(0.10, 0.16, 0.22, 0.35)。 |
| 错误 | 原因 | 处理 |
|---|
ShaderLayer must output exactly one MaterialAttributes value | ShaderLayer 输出缺失、过多或类型不是 MaterialAttributes。 | 只声明一个 MaterialAttributes 输出。 |
ShaderLayerBlend must declare at least two MaterialAttributes inputs | Layer Blend 输入不满足原生 Layer Blend 形状。 | 至少声明两个 MaterialAttributes 输入。 |
MaterialLayer is deprecated | 使用了旧兼容关键字。 | 改为 ShaderLayer / ShaderLayerBlend。 |
| 错误 | 原因 | 处理 |
|---|
Unsupported material output | Base.* 名称不支持。 | 查 输出绑定。 |
bound material property expects a different type | 输出变量类型与目标不匹配。 | 修改声明类型或绑定目标。 |
Expression output target must use .Pin[index] | 辅助输出节点格式错误。 | 使用 Expression(Class="...").Pin[0]。 |
- 先看 VSCode 红线，修掉明显语法和 import 问题。
- 执行
DreamShaderLang: Recompile Current Source。
- 看 Unreal Output Log 或 VSCode 桥接诊断。
- 如果是材质编译器错误，定位到生成的 Custom 节点代码。
- 对复杂逻辑，先缩小到最小
.dsm，再逐步恢复 import 和 helper。