编译器行为
当前限制
DreamShaderLang 1.1.1 的边界、兼容性和推荐替代写法。
DreamShaderLang 的当前目标是稳定生成 Unreal 材质图，而不是成为完整通用编程语言。理解边界能避免把逻辑写到不合适的层级。
Graph 限制
| 限制 | 替代 |
|---|---|
不支持 for / while | 放进 Function。 |
| 不支持任意 HLSL 语句 | 放进 Function。 |
Function 不能作为返回值表达式 | 使用显式 out 参数。 |
Function 调用只支持位置参数 | 按签名顺序传参。 |
| 条件两侧必须是标量 | 使用 swizzle 或 ComponentMask。 |
if 不能选择纹理对象 | 分支选择采样结果或数值。 |
字符串只用于 UE.* 命名参数 | 不要作为普通变量值。 |
类型限制
| 区域 | 支持重点 |
|---|---|
Properties | 标量、向量、纹理和 UE.*。 |
Graph | 标量、向量、纹理对象引用。 |
ShaderFunction pin | 标量、向量、纹理。 |
Function HLSL | 更自由，可写 HLSL 风格逻辑。 |
mat2 / mat3 / mat4 这类别名更适合 helper 代码，不应作为 Graph 变量或材质输出 pin 的主要类型。
Import 与 Package 限制
| 限制 | 说明 |
|---|---|
.dsh 不直接生成资产 | 必须由 .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 |
返回值风格 Function | 显式 out 参数 |
设计原则
| 想做的事 | 放在哪里 |
|---|---|
| 连材质节点 | Graph |
| 写复用公式 | Function |
| 写复杂流程或循环 | Function |
| 管理材质属性 | Properties / Settings |
| 管理输出 | Outputs |
| 共享一组 helper | .dsh + Namespace |
| 分发共享库 | Package |