DreamShader 插件

DreamShader 的版本更新记录按插件版本整理。这里主要记录会影响使用者的语言、生成器、工作流和兼容性变化。

Current source - 2026-06-10

Automation Baseline

• 新增 DreamShader automation 测试基线，覆盖最小材质解析、最小材质生成、.dsf + import 生成、Substrate 材质生成、source-hash skip 和 commandlet 单源编译 smoke。
• 测试会在 DShader/Tests/Automation 下写入临时 .dsm / .dsf / .dsh，并在 /Game/DreamShaderTests/Automation/... 下生成临时资产，运行后清理。
• source hash is unchanged 是未变更源文件跳过重复生成的稳定断言文本。
• 针对 automation 运行新增显式桥接关闭开关 -NoDreamShaderEditorBridge，用于避免 Bridge 启动扫描噪声干扰测试日志。

1.4.0 - 2026-06-06

Compatibility

• 新增 Unreal Engine 5.3 到 5.7 的兼容覆盖说明。
• 已在 Windows 上通过单插件 RunUAT BuildPlugin 验证 UE 5.3、5.4、5.5、5.6 和 5.7。
• 仍以 UE 5.7 作为主要开发版本；UE 5.3 / 5.4 在 Windows 上可能需要 MSVC 14.38 工具链。

Substrate

• 补齐 UE 5.7 Substrate 生成链路，支持 Substrate 图值、Base.FrontMaterial 输出绑定和 Substrate.* wrapper。
• 生成器、反编译、类型传播和编辑器 manifest 会识别 Substrate 类型与相关 wrapper。

Material Preview

• 编辑器 Bridge 新增材质预览能力，可根据 .dsm 源文件生成预览材质并写入 Saved/DreamShader/Bridge/preview.json 与 Preview/*.png。
• 新增本机 WebSocket 预览服务，默认监听 127.0.0.1:17864，用于 VSCode 预览面板接收结果和连续帧。

1.3.9 - 2026-05-29

Maintenance

• 插件版本元数据更新到 1.3.9。
• README、发布说明和文档引用同步到当前语言能力。

1.3.8 - 2026-05-25

Texture Support

• 新增 VolumeTexture property 解析、代码生成和默认纹理处理。
• 生成 HLSL / Custom 节点输入时保留纹理对象子类型，Texture2D、Texture2DArray 和 VolumeTexture 会以正确 Unreal 纹理类型传入。

Plugin Cleanup

• 移除项目设置和文档中的内置 shader library path 支持。

1.3.7 - 2026-05-18

Decompiler

• 泛型 UE.Expression(...) 反编译会导出更多 reflected literal property，减少少见 MaterialExpression 节点的状态丢失。
• 连接了 UV 等 graph 输入的 TextureSampleParameter2D 会导出为 graph 表达式，而不是简单 Properties 声明。
• 修复带动态命名输入和自定义输出类型 metadata 的 MaterialExpressionCustom 反编译。

Performance

• 优化大型反编译材质的 import 性能，减少逐节点 package dirty、降低进度文本刷新频率，并在大型生成图上跳过自动布局。

1.3.6 - 2026-05-12

Build Fixes

• DreamShaderSettings.h 显式包含 MaterialDomain.h，让直接包含设置头的项目能稳定解析 EMaterialDomain。

1.3.5 - 2026-05-11

ShaderFunction Calls

• Graph 支持 statement-style 多输出 ShaderFunction 和 VirtualFunction 调用：位置输入参数在前，输出目标变量在后。

Dream Shader Function Files

• 新增 .dsf Dream Shader Function 文件，用于可复用生成 ShaderFunction 资产。
• .dsm 和 .dsf 可以 import .dsf，便于在不同 DreamShader 源文件间复用生成函数。
• 增加 .dsf 源文件发现、依赖追踪和 VSCode workspace 文件关联。

Decompiler

• Content Browser 增加 UMaterial 导出 .dsm、UMaterialFunction 导出 .dsf 的入口。
• 反编译文件会写入 DShader/Decompiled/Materials 或 DShader/Decompiled/Functions，并使用唯一文件名。
• 常见常量、参数、算术节点、swizzle、纹理采样、Custom 节点和 MaterialFunction call 会尽量导出为 DreamShader graph 文本；少见 reflected 节点回退为 UE.Expression(...)。

1.3.4 - 2026-05-11

Output Initializers

• Outputs 支持初始化声明，例如 vec3 Color = Tint;。
• Shader 可以使用已初始化 output declaration 配合空 Graph = {}。

1.3.3 - 2026-05-11

Graph Swizzles

• 修复 vector property 分量数，声明为 vec2 / vec3 时生成 RG / RGB，不再总是按 RGBA 绑定。
• 修复 .gbr 这类非顺序 swizzle，通过显式 ComponentMask 和 AppendVector 节点生成。

1.3.2 - 2026-05-11

Material Function Generation

• 插件版本更新到 1.3.2。
• 重新生成 ShaderFunction 时保留生成输入和输出 ID，普通 Unreal 材质中的既有 MaterialFunctionCall 节点会尽量保持连接。
• Graph 和 Custom/HLSL 生成路径会跳过未使用的生成 property 节点。
• 改进生成节点摆放，并避免对 DreamShader 生成的材质图执行 Unreal 全量自动布局。
• 修复重新生成已打开 Material Function 资产时，编辑器仍持有 expression root 导致的崩溃。

1.3.1 - 2026-05-09

Function Calls

• 单输出 Function 和 GraphFunction 调用现在可以作为值表达式使用，例如 Color = Texture::Sample2DRGB(BaseTex, UV0);。
• 多输出 Function 和 GraphFunction 仍然需要显式 out 变量，例如 Texture::Sample2D(BaseTex, UV0, Color, Alpha);。

Graph Functions

• 新增顶层和 namespaced GraphFunction block，用于复用 HLSL Custom 节点逻辑。
• GraphFunction 仍按 HLSL 风格书写，但 body 中的 UE.* 调用会转换成材质节点，并作为生成输入传入 Custom 节点。
• 新增 GraphFunction 参数验证、递归调用检测和显式 out 变量写回。

1.3.0 - 2026-05-08

Shader Layer Functions

• 新增顶层 ShaderLayer(Name="...", Root="...") 和 ShaderLayerBlend(Name="...", Root="...")。
• 生成的 layer 资产使用 Unreal 原生 UMaterialFunctionMaterialLayer / UMaterialFunctionMaterialLayerBlend 类。
• MaterialLayer / MaterialLayerBlend 保留为兼容别名并产生警告；新源码应使用 ShaderLayer / ShaderLayerBlend。
• ShaderLayer / ShaderLayerBlend 复用现有 Properties、Inputs、Outputs、Settings 和 Graph sections。
• 新增验证：Shader Layer block 必须输出且只输出一个 MaterialAttributes，Shader Layer Blend block 必须声明至少两个 MaterialAttributes 输入。
• Vector parameter property 在 Graph 中保留 RGBA 输出，.a / .w 可读取 alpha，低分量赋值会自动取前置通道。

1.2.10 - 2026-05-08

VSCode MaterialExpression Manifest

• 新增编辑器侧 reflected UMaterialExpression metadata 导出，路径为 Saved/DreamShader/Bridge/material-expressions.json。
• manifest 会在编辑器 bridge 启动和打开 DreamShader VSCode workspace 时刷新。
• 导出内容包含 expression class 名称、可编辑反射属性、expression inputs、output pins 和推断的 DreamShader OutputType 提示。
• Release workflow 会下载最新 dreamshader-language-support GitHub Release 资产并附加到 DreamShader release。

1.2.8 - 2026-05-05

项目设置与编辑器入口

• 插件版本更新到 1.2.8。
• DreamShader.uplugin 的文档链接改为 https://lang.64hz.cn/，支持链接改为 GitHub 主页。
• Unreal Project Settings 中的插件分类从 Plugins 调整到 DreamPlugin，section 显示名为 Dream Shader，说明文本为 Dream Shader Settings。
• 新增 Editor 分类下的 OpenInNewWindow 配置。默认开启时，从 Unreal 打开 DreamShader VSCode workspace 会新开窗口；关闭时会追加 --reuse-window，复用已有 VSCode 窗口。

1.2.7 - 2026-05-05

Unreal 5.7 兼容性

• 插件版本更新到 1.2.7。
• 生成器补齐 UMaterialExpressionFunctionInput / UMaterialExpressionFunctionOutput 相关头文件依赖，适配新版 Unreal 材质函数输入输出节点的编译环境。
• Moon Engine 专属的 MooaEncodedAttribute0 到 MooaEncodedAttribute4 输出现在包在 MOON_ENGINE 条件编译内，普通引擎构建不会再依赖这些自定义材质属性。
• 该版本不改变 .dsm / .dsh 语法；主要是输出目标和引擎兼容性修正。

1.2.6 - 2026-04-30

ShaderFunction Properties

• ShaderFunction 新增 Properties section，用于声明只属于生成材质函数内部的 property/helper 节点。
• Properties 支持 const 标记，可生成不可外部调参的标量、向量或 Texture Object helper 节点。
• ShaderFunction 的 Inputs 预览默认值可以引用同一函数的 Properties，例如 opt Texture2D BaseColorTex = PreviewTex;。

1.2.5 - 2026-04-30

MaterialAttributes

• 新增 MaterialAttributes 图值类型，可用于 Shader 输出声明、ShaderFunction 输出和 VirtualFunction 输出签名。
• Graph 支持 Attrs.BaseColor = Color;、Attrs.Roughness = Roughness; 这类成员写入，生成器会创建 Material Attributes 相关节点。
• Shader 可以将聚合值绑定到 Base.MaterialAttributes，生成材质会自动启用 Unreal 的 Use Material Attributes。
• MaterialAttributes 值可以从生成的或已有的 Material Function 返回，并继续在 Graph 中传递、分支或读取成员。

1.2.4 - 2026-04-30

Parameter Reflection

• 声明尾部的 metadata 文档写法切换为分号式 [...] 反射属性块。
• Properties 中的显式 Parameter 节点现在可以通过属性块写入任意可反射的 UMaterialExpression 属性。
• float / 向量 / 纹理简写生成的 Scalar / Vector / Texture Object Parameter 也使用同一套反射属性块。
• TextureSampleParameter2D 等纹理采样参数可以配置 SamplerType、SamplerSource、MipValueMode、AutomaticViewMipBias、ConstCoordinate、ConstMipValue 等字段。

1.2.3 - 2026-04-29

Parameters

• Properties 和函数输入输出声明支持 [Group="...", SortPriority=32, Description="..."] 元数据。
• Properties 支持显式 Parameter 节点类型，包括 ScalarParameter、VectorParameter、TextureObjectParameter、纹理采样参数节点、StaticBoolParameter 和 StaticSwitchParameter。
• StaticSwitchParameter 可以在 Graph 中用同名函数调用，例如 UseDetail(True=detailColor, False=baseColor)。
• 新增 UE.CollectionParam(Collection=Path(...), Parameter="...")，用于读取 Material Parameter Collection。

Function Defaults

• ShaderFunction 和 VirtualFunction 的输入支持 opt，用于表示该输入可使用 Unreal FunctionInput 的预览默认值。
• 调用 ShaderFunction / VirtualFunction 时支持 default 参数，显式跳过可选输入并沿用预览默认值。
• 生成 ShaderFunction 资产时会把输入输出的 description 和 sort priority 写入 FunctionInput / FunctionOutput 节点。
• VirtualFunction 的复制、创建和启动同步现在会尽量带上可选输入、预览默认值和 pin 元数据。

1.2.2 - 2026-04-29

VirtualFunction 编辑器工作流

• CreateVirtualFunction 会先查找 DShader 中已有的同资产声明，不再重复创建多个相同定义文件。
• 如果当前 Material Function 已经有对应 VirtualFunction 定义，菜单只显示 OpenVirtualFunction 和 Copy Virtual Function Reference。
• OpenVirtualFunction 会优先用 VSCode 打开并跳转到定义位置。
• Copy Virtual Function Reference 会复制可直接粘贴到 Shader / ShaderFunction 的 Graph 块中的调用表达式。
• 插件启动时会扫描 DShader 下的 VirtualFunction 声明，检查对应 UMaterialFunction 是否存在，并在签名变化时刷新定义。

import 兼容性

• Unreal 生成器现在支持无分号 import，例如 import "VirtualFunctions/MF_Test.dsh"。
• 带分号写法 import "VirtualFunctions/MF_Test.dsh"; 仍然兼容。

1.2.1 - 2026-04-29

Material Function 编辑器

• Material Function 编辑器工具栏和资产右键菜单中的 VirtualFunction 相关操作统一收进 DreamShader 下拉菜单。
• 新增 CopyVirtualFunction，用于复制完整 VirtualFunction 声明。
• 新增 CreateVirtualFunction，用于在 DShader/VirtualFunctions 下创建 .dsh 定义文件，并打开到默认外部编辑器。
• 新增 CopyVirtualFunctionCall，用于复制可直接粘贴到 Graph 的调用示例。

1.2.0 - 2026-04-28

VirtualFunction

• 新增 VirtualFunction(Name="...")，用于声明项目、引擎或插件中已经存在的 UMaterialFunction 资产。
• VirtualFunction 可在 Graph 中像 ShaderFunction 一样作为值函数调用，但不会生成、保存或覆盖对应资产。
• Options.Asset 支持 Path(Game, "...")、Path(Engine, "...")、Path(Plugin.PluginName, "...") / Path(Plugins.PluginName, "...")，也支持完整 Unreal object path。
• Material Function 资产右键菜单和 Material Function 编辑器工具栏新增 VirtualFunction 定义复制能力，可自动生成包含 Inputs、Outputs 和 Options 的声明。

工具链

• VSCode 扩展同步支持 VirtualFunction 高亮、补全、Hover、Snippet、签名提示和诊断。
• Path(Plugins.) 内的项目内容插件名也会参与自动补全。

1.1.4 - 2026-04-28

资产生成

• Root="Plugins.PluginName" / Root="Plugins/PluginName" 现在作为兼容写法支持，解析结果与 Root="Plugin.PluginName" 相同。
• 这避免 Plugins.MoonToon 被当作普通 /Game/Plugins_MoonToon 子目录保存。

1.1.3 - 2026-04-28

资产生成

• 明确 Root="Plugin.PluginName" 只指向已启用的项目内容插件。
• Plugin.MoonToon 会解析到 UE package 根 /MoonToon，物理保存位置是 [Project]/Plugins/MoonToon/Content。
• 生成器会校验目标插件位于项目 Plugins 目录、已启用、可包含内容且存在 Content 目录。

1.1.2 - 2026-04-28

语言与生成

• Shader 和 ShaderFunction 顶层属性新增 Root，用于指定生成资产根路径。
• Root 默认是 Game，也支持 Plugin.PluginName，用于把生成的 UMaterial 或 UMaterialFunction 保存到已启用的项目内容插件根。
• ShaderFunction 在 Graph 中被调用时，会按该函数自己的 Root 解析并加载生成的 UMaterialFunction 资产。

文档

• 更新插件 README、语言参考和网站文档中的资产生成说明。

1.1.1 - 2026-04-26

修复

• 修复 Graph 中调用带多个 out 参数的 Function 时，Custom 节点后续输出 pin 没有收到值的问题。
• 多输出 Function 的第一个 out 仍通过 Custom 节点主 return 输出；第二个及后续 out 现在会生成显式赋值，把 __ds_*_outN 临时变量写回对应 Additional Output 参数，例如 Output_ToonA = __ds_xxx_out1;。

兼容性

• 这是一个 patch 版本，不需要修改 .dsm / .dsh 写法。

1.1.0 - 2026-04-22

语言与 Graph

• 将材质和材质函数中的 Code = { ... } 区块重命名为 Graph = { ... }，让图 DSL 与 HLSL helper 层更容易区分。
• Graph 增加基础 if / else 支持，可以在图层表达简单条件分支。
• 改进输出表达式处理：输出绑定从只记录变量名改为记录 source text，可用于更灵活地解析 Graph 输出。
• 增强类型转换和 UE.* 通用 MaterialExpression 参数处理，减少手动补节点时的摩擦。

Function 与生成

• 新增 Function SelfContained / Function Inline，可以把 helper 依赖嵌入 Custom 节点，便于把生成材质交给未安装 DreamShader 插件的项目使用。
• 普通 Function 继续生成 .ush helper include，并通过 Custom 节点引用。
• 增加清理生成 shader 文件的工作流，减少历史 include 残留。

Package 与工作流

• 新增 Package 系统，用 GitHub 分发和安装可复用 .dsh 共享库。
• 增加 import dependency graph，保存共享 .dsh 后可以找到受影响的 .dsm 并增量刷新；后续版本也覆盖 .dsf 依赖。
• 缓存配置目录，减少重复解析项目设置带来的开销。

诊断与兼容性

• 诊断信息增加 stage、platform、quality 等上下文，便于区分解析、生成和材质编译阶段的问题。
• 移除 Toon shading model 的默认映射，避免生成结果意外依赖项目自定义 shading model。
• 配套更新 README、语言参考和示例文档。

1.0.0 - 2026-04-21

初始版本

• 提供 .dsm / .dsh 文件模型，用文本源文件描述 Unreal 材质和共享 helper。
• 支持 Shader(Name="...") 生成 UMaterial，支持 ShaderFunction(Name="...") 生成 UMaterialFunction。
• 支持 Properties、Settings、Outputs 和早期图构建语法。
• 支持 HLSL 风格 Function helper，并生成 Custom 节点代码。
• 支持基础文档和示例，作为 DreamShaderLang 的第一版公开基线。