编译器行为
当前限制
DreamShaderLang 当前版本的边界、兼容性和推荐替代写法。
DreamShaderLang 的当前目标是稳定生成 Unreal 材质图，而不是成为完整通用编程语言。理解边界能避免把逻辑写到不合适的层级。
Graph 限制
| 限制 | 替代 |
|---|---|
不支持 for / while | 放进 Function / GraphFunction。 |
| 不支持任意 HLSL 语句 | 放进 Function / GraphFunction。 |
| 多输出 helper 不能作为单值表达式 | 使用显式 out 参数。 |
Function 调用只支持位置参数 | 按签名顺序传参。 |
| 条件两侧必须是标量 | 使用 swizzle 或 ComponentMask。 |
if 不能选择纹理对象 | 分支选择采样结果或数值。 |
MaterialAttributes 不能参与算术 | 读写具体成员，例如 Attrs.BaseColor。 |
字符串只用于 UE.* 命名参数 | 不要作为普通变量值。 |
类型限制
| 区域 | 支持重点 |
|---|---|
Properties | 标量、向量、纹理、const helper、显式 Parameter 节点、StaticSwitchParameter、UE.CollectionParam 和 UE.*。 |
Graph | 标量、向量、纹理对象引用、MaterialAttributes 聚合值。 |
ShaderFunction / VirtualFunction pin | 标量、向量、纹理、MaterialAttributes，可用 opt 表达预览默认值。 |
Function HLSL | 更自由，可写 HLSL 风格逻辑，但不能直接调用 UE.*。 |
GraphFunction HLSL | 可写 HLSL 风格逻辑，也可调用 UE.* 并把图节点结果接入 Custom。 |
mat2 / mat3 / mat4 这类别名更适合 helper 代码，不应作为 Graph 变量或材质输出 pin 的主要类型。
Import 与 Package 限制
| 限制 | 说明 |
|---|---|
.dsh 不直接生成资产 | 必须由 .dsm / .dsf 引用或作为共享库。 |
.dsf 不用于材质或 Layer 资产 | .dsf 面向 ShaderFunction 和相关 helper，材质入口仍放 .dsm。 |
| 循环 import 不允许 | 需要拆分公共依赖。 |
| Package 示例不会自动编译 | 示例 .dsm 需要复制到项目源码目录。 |
| Package 更新依赖 git | VSCode 安装和更新需要本机可用 git。 |
诊断边界
VSCode 诊断是开发辅助，不等同于完整编译器语义系统。最终结果仍以 Unreal 侧解析、生成和材质编译为准。
可能出现：
| 情况 | 说明 |
|---|---|
| VSCode 没报错，但 Unreal 报错 | 生成器或材质编译阶段发现更深层问题。 |
| Unreal 材质编译错误行列不精确 | Custom 节点内部错误可能来自 Unreal 原始信息。 |
泛型 UE.Expression 报错较晚 | 需要创建具体 MaterialExpression 后才知道属性是否存在。 |
版本迁移提示
| 旧写法 | 新写法 |
|---|---|
Shader 中 Code = { ... } | Graph = { ... } |
ShaderFunction 中 Code = { ... } | Graph = { ... } |
Scalar | float |
Vector | float2 / float3 / float4 |
Color | vec3 / vec4 或 float3 / float4 |
| 多输出 helper 返回值风格调用 | 显式 out 参数 |
MaterialLayer / MaterialLayerBlend | ShaderLayer / ShaderLayerBlend |
直接调用未声明的现有 UMaterialFunction | 使用 VirtualFunction 声明签名和 Options.Asset |
设计原则
| 想做的事 | 放在哪里 |
|---|---|
| 连材质节点 | Graph |
| 写复用公式 | Function / GraphFunction |
| 写复杂流程或循环 | Function / GraphFunction |
在 helper 里调用 UE.* | GraphFunction |
| 管理材质属性 | Properties / Settings |
| 管理输出 | Outputs |
| 调用已有材质函数资产 | VirtualFunction |
| 生成 Material Layer 函数资产 | ShaderLayer / ShaderLayerBlend |
| 共享一组 helper | .dsh + Namespace |
| 分发共享库 | Package |