Implement StaticSwitchParameter and CollectionParameter support in DreamShader

- Added functionality to parse and evaluate StaticSwitchParameter calls, including handling of True and False inputs.
- Introduced CollectionParameter support, allowing for dynamic parameter retrieval from MaterialParameterCollections.
- Enhanced error handling for missing required inputs and default arguments in shader functions.
- Updated metadata application for material expressions to include descriptions, groups, and sort priorities.
- Improved asset reference extraction for parameters and added validation for parameter names and types.
- Refactored code for better readability and maintainability, including the introduction of helper functions for expression metadata and parameter handling.

Author: TypeDreamMoon

CHANGELOG.md

@@ -1,5 +1,21 @@
 # DreamShader ChangeLog
 
+## 1.2.3 - 2026-04-29
+
+### Parameters
+
+- Added declaration metadata `[Group="...", SortPriority=32, Description="..."]` for material `Properties` and function input/output declarations.
+- Added explicit Parameter node declarations including `ScalarParameter`, `VectorParameter`, `TextureObjectParameter`, texture sample parameter nodes, `StaticBoolParameter`, and `StaticSwitchParameter`.
+- Added `StaticSwitchParameter` graph calls, for example `UseDetail(True=detailColor, False=baseColor)`.
+- Added `UE.CollectionParam(Collection=Path(...), Parameter="...")` for Material Parameter Collection reads.
+
+### Function Defaults
+
+- Added `opt` inputs for `ShaderFunction` and `VirtualFunction`.
+- Added `default` call arguments for optional material function inputs, preserving Unreal FunctionInput preview defaults.
+- Generated `ShaderFunction` assets now write input/output descriptions and sort priorities to FunctionInput / FunctionOutput nodes.
+- VirtualFunction copy/create/sync now emits optional inputs, preview defaults, and pin metadata when available.
+
 ## 1.2.2 - 2026-04-29
 
 ### VirtualFunction Workflow

Docs/LanguageReference.md

@@ -4,7 +4,7 @@ DreamShaderLang 是 DreamShader 插件使用的文本语言。它用 `.dsm` / `.
 
 | 项目 | 内容 |
 | --- | --- |
-| 插件版本 | `1.2.2` |
+| 插件版本 | `1.2.3` |
 | 源文件 | `.dsm` / `.dsh` |
 | 主要产物 | `UMaterial` / `UMaterialFunction` |
 | 开发者 | TypeDreamMoon |
@@ -210,6 +210,23 @@ Properties = {
     float Strength = 1.0;
     vec3 Tint = vec3(1.0, 1.0, 1.0);
     Texture2D MainTex = Path(Game, "/Textures/T_Main");
+    StaticSwitchParameter UseDetail = true [Group="Switches", SortPriority=30, Description="Use detail branch"];
+}
+```
+
+除 `float` / `vec3` / `Texture2D` 简写外，`Properties` 也支持常见显式 Parameter 节点类型，例如 `ScalarParameter`、`VectorParameter`、`DoubleVectorParameter`、`TextureObjectParameter`、`TextureSampleParameter2D`、`StaticBoolParameter`、`StaticSwitchParameter` 等。
+
+声明尾部可以加元数据：
+
+```c
+ScalarParameter Roughness = 0.35 [Group="Surface", SortPriority=10, Description="Material roughness"];
+```
+
+`StaticSwitchParameter` 在 `Graph` 中以同名函数形式使用：
+
+```c
+Graph = {
+    float3 finalColor = UseDetail(True=detailColor, False=baseColor);
 }
 ```
 
@@ -220,10 +237,18 @@ Properties = {
 ```c
 Inputs = {
     vec3 InColor;
-    float Strength = 1.0;
+    opt float Strength = 1.0 [Description="Preview default strength"];
 }
 ```
 
+`opt` 表示该输入可选，并使用 Unreal Function Input 的预览值作为默认值。调用 `ShaderFunction` / `VirtualFunction` 时可以传 `default`，也可以省略尾部可选参数：
+
+```c
+float3 color = MyFunction(InColor, default, Output="Result");
+```
+
+`ShaderFunction` / `VirtualFunction` 的 `Inputs` / `Outputs` 同样支持 `[SortPriority=..., Description="..."]` 元数据；`Group` 会被解析并保留在语法层，但 Unreal Function Input / Output 本身没有分组字段。
+
 ### 3.3 `Outputs`
 
 `Shader` 中既能声明输出变量，也能绑定 Unreal 材质属性。
@@ -285,6 +310,8 @@ Options = {
 - 标量、向量构造。
 - Brace initializer。
 - `UE.*` builtin 调用。
+- `UE.CollectionParam(Collection=Path(...), Parameter="Name")` 读取 Material Parameter Collection。
+- `UE.StaticSwitchParameter(...)` 或 `StaticSwitchParameter` 属性调用。
 - `Function(...)` / `Namespace::Function(...)` 独立调用。
 - `ShaderFunction(...)` / `VirtualFunction(...)` 值调用。
 - 基础 `if` / `else` 图分支。
@@ -375,7 +402,7 @@ Properties = {
 规则：
 
 - 单参数形式必须使用 `/Game/...` 或 `/Engine/...`。
-- 双参数形式的根名支持 `Game` / `Engine`。
+- 双参数形式的根名支持 `Game` / `Engine` / `Plugin.PluginName` / `Plugins.PluginName`。
 - 如果未显式写 `.AssetName`，会自动补成合法 Unreal object path。
 - 会校验声明类型和实际资产类型是否一致。
 

DreamShader.uplugin

@@ -1,7 +1,7 @@
 {
 	"FileVersion": 3,
-	"Version": 122,
-	"VersionName": "1.2.2",
+	"Version": 123,
+	"VersionName": "1.2.3",
 	"FriendlyName": "DreamShader",
 	"Description": "Author Unreal materials and material functions with DreamShaderLang .dsm/.dsh source files that auto-generate standard UMaterial and UMaterialFunction assets.",
 	"Category": "DreamPlugin",

README.md

@@ -2,13 +2,15 @@
 
 DreamShader 是一个 Unreal Engine 材质生成插件。它提供 `DreamShaderLang` 文本语言，让你用 `.dsm` / `.dsh` 源文件描述材质图、共享函数和材质函数，并自动生成标准 Unreal `UMaterial` / `UMaterialFunction` 资产。
 
-> 当前版本：`1.2.2`。插件仍在持续开发中，核心工作流已经可用，建议在项目中逐步接入并保留源文件版本管理。
+> 当前版本：`1.2.3`。插件仍在持续开发中，核心工作流已经可用，建议在项目中逐步接入并保留源文件版本管理。
 
 ## 核心能力
 
 - 使用文本源文件维护材质逻辑，减少手动连材质节点的重复工作。
 - 从 `Shader(Name="...", Root="Game")` 生成 `UMaterial`，从 `ShaderFunction(Name="...", Root="Game")` 生成 `UMaterialFunction`。
 - 使用 `VirtualFunction(Name="...")` 声明现有 Unreal `UMaterialFunction` 资产，并在 `Graph` 中直接调用，不会生成或覆盖资产。
+- `Properties` 支持显式 Parameter 节点、`StaticSwitchParameter`、`UE.CollectionParam(...)` 和 `[Group="...", SortPriority=32, Description="..."]` 元数据。
+- `ShaderFunction` / `VirtualFunction` 输入支持 `opt` 和调用侧 `default`，用于复用 Unreal FunctionInput 的预览默认值。
 - 在 `Graph = { ... }` 中声明变量、调用 UE 材质节点、调用共享函数，并绑定材质输出。
 - 在 `Function` / `Namespace` 中编写可复用 HLSL 风格 helper。
 - 支持 `Inline` / `SelfContained` 函数，把依赖代码嵌入材质 Custom 节点，便于在未安装 DreamShader 的项目中继续使用生成资产。
@@ -98,6 +100,52 @@ Shader(Name="DreamMaterials/M_Minimal", Root="Plugin.MyPlugin")
 这会使用 `/MyPlugin/DreamMaterials/M_Minimal.M_Minimal` 作为 Unreal object path，并物理保存到 `[Project]/Plugins/MyPlugin/Content/DreamMaterials/M_Minimal.uasset`。
 `Plugins.MyPlugin` / `Plugins/MyPlugin` 也作为兼容写法支持。
 
+## Parameter 与默认输入
+
+`Properties` 可以继续使用 `float` / `float3` / `Texture2D` 简写，也可以显式声明 Unreal Parameter 节点，并在声明尾部加元数据：
+
+```c
+Properties = {
+    ScalarParameter Roughness = 0.35 [Group="Surface", SortPriority=10, Description="Material roughness"];
+    VectorParameter Tint = float4(1.0, 0.9, 0.8, 1.0) [Group="Surface", SortPriority=20];
+    StaticSwitchParameter UseDetail = true [Group="Switches", SortPriority=30];
+}
+
+Graph = {
+    float3 baseCol = Tint.rgb;
+    float3 detailCol = baseCol * 2.0;
+    float3 finalCol = UseDetail(True=detailCol, False=baseCol);
+}
+```
+
+Material Parameter Collection 可以在 Graph 中直接读取：
+
+```c
+float wind = UE.CollectionParam(
+    Collection=Path(Game, "MaterialParameterCollections/MPC_Global"),
+    Parameter="WindStrength");
+```
+
+`ShaderFunction` / `VirtualFunction` 的输入可以标记 `opt`。调用时传 `default` 或省略尾部可选参数，会使用 Unreal FunctionInput 的预览默认值：
+
+```c
+ShaderFunction(Name="Functions/DebugValue")
+{
+    Inputs = {
+        float2 UV;
+        opt float4 ColorA = float4(0.3, 0.3, 0.7, 0.7) [Description="Debug color A"];
+    }
+
+    Outputs = {
+        float4 Result;
+    }
+
+    Graph = {
+        Result = ColorA;
+    }
+}
+```
+
 ## 共享函数示例
 
 `.dsh` 文件适合放共享函数：

Source/DreamShader/Private/DreamShaderParserScanner.cpp

@@ -389,6 +389,7 @@ namespace UE::DreamShader::Private
 		TArray<FString> Statements;
 		FString Current;
 		int32 ParenthesisDepth = 0;
+		int32 BracketDepth = 0;
 		bool bInString = false;
 
 		for (int32 Index = 0; Index < BlockContent.Len(); ++Index)
@@ -430,7 +431,21 @@ namespace UE::DreamShader::Private
 				continue;
 			}
 
-			if (Char == TCHAR(';') && ParenthesisDepth == 0)
+			if (Char == TCHAR('['))
+			{
+				++BracketDepth;
+				Current.AppendChar(Char);
+				continue;
+			}
+
+			if (Char == TCHAR(']'))
+			{
+				BracketDepth = FMath::Max(0, BracketDepth - 1);
+				Current.AppendChar(Char);
+				continue;
+			}
+
+			if (Char == TCHAR(';') && ParenthesisDepth == 0 && BracketDepth == 0)
 			{
 				Current.TrimStartAndEndInline();
 				if (!Current.IsEmpty())
@@ -458,6 +473,7 @@ namespace UE::DreamShader::Private
 		TArray<FString> Parts;
 		FString Current;
 		int32 ParenthesisDepth = 0;
+		int32 BracketDepth = 0;
 		bool bInString = false;
 
 		for (int32 Index = 0; Index < Input.Len(); ++Index)
@@ -499,7 +515,21 @@ namespace UE::DreamShader::Private
 				continue;
 			}
 
-			if (Char == Delimiter && ParenthesisDepth == 0)
+			if (Char == TCHAR('['))
+			{
+				++BracketDepth;
+				Current.AppendChar(Char);
+				continue;
+			}
+
+			if (Char == TCHAR(']'))
+			{
+				BracketDepth = FMath::Max(0, BracketDepth - 1);
+				Current.AppendChar(Char);
+				continue;
+			}
+
+			if (Char == Delimiter && ParenthesisDepth == 0 && BracketDepth == 0)
 			{
 				Current.TrimStartAndEndInline();
 				if (!Current.IsEmpty())
@@ -525,6 +555,7 @@ namespace UE::DreamShader::Private
 	bool SplitTopLevelAssignment(const FString& InText, FString& OutLeft, FString& OutRight)
 	{
 		int32 ParenthesisDepth = 0;
+		int32 BracketDepth = 0;
 		bool bInString = false;
 
 		for (int32 Index = 0; Index < InText.Len(); ++Index)
@@ -562,7 +593,19 @@ namespace UE::DreamShader::Private
 				continue;
 			}
 
-			if (Char == TCHAR('=') && ParenthesisDepth == 0)
+			if (Char == TCHAR('['))
+			{
+				++BracketDepth;
+				continue;
+			}
+
+			if (Char == TCHAR(']'))
+			{
+				BracketDepth = FMath::Max(0, BracketDepth - 1);
+				continue;
+			}
+
+			if (Char == TCHAR('=') && ParenthesisDepth == 0 && BracketDepth == 0)
 			{
 				OutLeft = InText.Left(Index).TrimStartAndEnd();
 				OutRight = InText.Mid(Index + 1).TrimStartAndEnd();
@@ -577,6 +620,7 @@ namespace UE::DreamShader::Private
 	{
 		const FString Trimmed = InText.TrimStartAndEnd();
 		int32 ParenthesisDepth = 0;
+		int32 BracketDepth = 0;
 		bool bInString = false;
 		int32 LastWhitespaceIndex = INDEX_NONE;
 
@@ -615,7 +659,19 @@ namespace UE::DreamShader::Private
 				continue;
 			}
 
-			if (ParenthesisDepth == 0 && FChar::IsWhitespace(Char))
+			if (Char == TCHAR('['))
+			{
+				++BracketDepth;
+				continue;
+			}
+
+			if (Char == TCHAR(']'))
+			{
+				BracketDepth = FMath::Max(0, BracketDepth - 1);
+				continue;
+			}
+
+			if (ParenthesisDepth == 0 && BracketDepth == 0 && FChar::IsWhitespace(Char))
 			{
 				LastWhitespaceIndex = Index;
 			}