DreamShaderLang

一句话来说，DreamShaderLang 是为了代替虚幻引擎材质“连连看”而生的语言。

DreamShaderLang 是 DreamShader 插件的源语言。它用 .dsm、.dsf 和 .dsh 文件描述 Unreal 材质、材质函数、Material Layer、共享 helper、包依赖和材质图连接关系，然后由插件生成标准 UMaterial、UMaterialFunction、UMaterialFunctionMaterialLayer 与 UMaterialFunctionMaterialLayerBlend 资产。

这套文档以语言为中心组织，目标是让 DreamShaderLang 像常见编程语言一样可学习、可查询、可引用。

教程路线

阶段	阅读内容	目标
入门	安装与准备、第一个材质	能在 Unreal 项目里保存 `.dsm` 并生成材质。
语言基础	文件模型、顶层声明、Section	知道 `.dsm`、`.dsf`、`.dsh` 分别放什么。
图与 helper	Graph 语言、Function 与 Namespace、布局与 Region	能把节点连接、Custom helper 和图布局写成文本。
工具链	插件概览、编辑器支持、资产生成	理解生成、反编译、诊断和 Package 工作流。

核心模型

概念	作用
`.dsm`	Dream Shader Material。通常生成材质、Material Layer 或项目级资产入口。
`.dsf`	Dream Shader Function。用于生成可复用 `ShaderFunction` 资产，并可被 `.dsm` 或其他 `.dsf` 导入。
`.dsh`	Dream Shader Header。存放共享 `Function`、`Namespace` 与 import。
`Shader`	顶层材质声明，生成 Unreal `UMaterial`。
`ShaderFunction`	顶层材质函数声明，生成 Unreal `UMaterialFunction`。
`ShaderLayer`	顶层 Material Layer 声明，生成 `UMaterialFunctionMaterialLayer`。
`ShaderLayerBlend`	顶层 Material Layer Blend 声明，生成 `UMaterialFunctionMaterialLayerBlend`。
`VirtualFunction`	声明已有 Unreal `UMaterialFunction`，供 `Graph` 调用但不生成或覆盖资产。
`Graph`	生成 Unreal 材质节点的图 DSL。
`Function`	HLSL 风格 helper，供 `Graph` 调用。
`GraphFunction`	可复用 Custom 节点 helper，可在函数体中使用 `UE.*` 图节点。
`Layout`	可选图布局 metadata，用 `Node(...)` 固定变量节点位置，用 `Comment(...)` 创建注释框。
`#Region`	`Graph` 内的命名区域，用于分组生成节点并配合布局注释。
`Namespace`	组织共享 helper，调用形式为 `Namespace::Function(...)`。
`Package`	可分发的 `.dsh` 共享库，安装到 `DShader/Packages`。

公开仓库

项目	链接
DreamShader 插件	TypeDreamMoon/DreamShader
VSCode 扩展	TypeDreamMoon/dreamshader-language-support
Rider 插件	tsdaer/dreamshader-language-support
Package Store Index	TypeDreamMoon/dreamshader-package-index

语言分层

DreamShaderLang 不是把 HLSL 直接塞进材质文件。它分成三层：

层级	写在哪里	适合表达
资产层	`Shader` / `ShaderFunction` / `ShaderLayer` / `ShaderLayerBlend` / `VirtualFunction`	Unreal 资产名称、属性、设置、输出绑定，或现有材质函数签名。
图层	`Graph = { ... }`	变量、节点、表达式、`UE.*`、材质函数调用、helper 调用、基础 `if` / `else`。
Helper 层	`Function` / `GraphFunction` / `Namespace`	可复用 HLSL 计算、循环、复杂流程、自包含 Custom 节点代码。

最小材质

Shader(Name="DreamMaterials/M_Minimal")
{
    Properties = {
        vec3 Tint = vec3(1.0, 0.2, 0.2);
    }

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

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

    Graph = {
        Color = Tint;
    }
}

目标	页面
第一次写材质	安装与准备、第一个材质
理解项目结构	项目布局、文件模型
学语言核心	顶层声明、Section、类型和值
写共享逻辑	Function 与 Namespace、Import 与 Namespace
写材质图	Graph 语言、UE 节点入口参考
查资产输出	材质设置、输出绑定、Package 参考
看示例	常用模式、配方示例
排错与生成	资产生成、诊断、限制
了解插件和工具	DreamShader 插件、编辑器支持、Package 作者工作流
追踪版本变化	ChangeLog、插件更新、VSCode 更新、网站更新
补充着色语言背景	HLSL 简介、GLSL 简介、关键字速查

当前版本

项目	内容
DreamShader 插件	`1.4.0`
VSCode 扩展	`1.5.3`
Rider 插件	`tsdaer/dreamshader-language-support`
文档站	`lang.64hz.cn`
语言	`DreamShaderLang`
文件扩展名	`.dsm` / `.dsf` / `.dsh`
作者	TypeDreamMoon
主要产物	`UMaterial` / `UMaterialFunction` / Material Layer 函数资产

1.4.0 / 1.5.3 重点

能力	说明
UE 5.3-5.7 兼容	DreamShader 插件 `1.4.0` 基于 UE `5.7` 持续开发，并已通过单插件 `RunUAT BuildPlugin` 验证 UE `5.3` 到 `5.7`。
Substrate 生成	插件支持 UE 5.7 `Substrate` 图值、`Base.FrontMaterial` 输出绑定和 `Substrate.*` wrapper，并向编辑器导出 Substrate builtin metadata。
材质预览	VSCode 扩展 `1.5.3` 新增 `.dsm` 材质预览面板，优先通过本机 WebSocket 直播预览帧，并在不可用时回退到 `Saved/DreamShader/Bridge/preview.json` 文件桥。
Callable Hover	VSCode 扩展 `1.5.2` 在 Hover 中显示 DreamShader 函数、UE builtin 和 Substrate helper 的返回值与输出 pin 信息。
Template / Bridge / Package	VSCode 扩展 `1.5.1` 补齐 `Template` 块语言支持、Bridge 命令、状态栏、诊断面板、Package 工具和常用创作模板。
`.dsf` 函数文件	新增 Dream Shader Function 文件，用于生成可复用 `ShaderFunction` 资产，并支持 `.dsm` / `.dsf` 之间 import。
反编译导出	Content Browser 可将已有 `Material` / `Material Function` 导出为 `.dsm` / `.dsf` 初稿，常见节点转成 Graph 文本，少见节点回退到 `UE.Expression(...)`。
Layout 与 Region	`Layout = { Node(...); Comment(...); }` 和 Graph `#Region` / `#EndRegion` 可保留或约束生成图布局。
VolumeTexture	插件和 VSCode 扩展支持 `VolumeTexture` / `Texture3D` 类型、默认纹理、补全和诊断。
Function 内置函数	VSCode 扩展统一 HLSL intrinsic、GLSL 别名和 Unreal 纹理采样 helper metadata，用于补全、Hover、Signature Help、Inlay Hint、诊断和语义高亮。
动态 MaterialExpression	插件导出 `Saved/DreamShader/Bridge/material-expressions.json`，VSCode 可读取 reflected `UMaterialExpression` 元数据用于补全、Hover 和 Signature Help，并带内置 fallback manifest。
Material Layer	新增推荐顶层块 `ShaderLayer` / `ShaderLayerBlend`，生成 Unreal 原生 Material Layer / Layer Blend 函数资产。
GraphFunction	新增 `GraphFunction` helper，可在 Custom 节点 body 中写 `UE.*` 调用，生成器会把这些图节点作为自动输入接入 Custom。
helper 值表达式	单输出 `Function` / `GraphFunction` 调用可作为 Graph 值表达式；多输出调用仍使用显式 `out` 变量。
Material Function 稳定性	重新生成 `ShaderFunction` 时保留输入输出 ID，减少普通 Unreal 材质中 `MaterialFunctionCall` 断线风险。
生成图布局	生成节点布局更稳定，避免对 DreamShader 生成图执行 Unreal 全量自动布局。
VSCode 语言核心	扩展使用 scanner / parser / context / symbol / provider 模块组织语言服务。
作用域诊断	补全、诊断、语义高亮、折叠和文档符号改走新语言核心，减少 `Inputs`、`Graph`、`Function`、`Settings`、`Outputs`、metadata 之间的作用域串漏。
Substrate / Strata	VSCode 扩展增加 Substrate / Strata 类型、语法、补全和诊断提示。