init

Plugins/Dialog/UPresentationJsonLibrary.md

@@ -0,0 +1,70 @@
+# UPresentationJsonLibrary
+
+## 基本信息
+- **类型**: UCLASS（BlueprintFunctionLibrary）
+- **父类**: UBlueprintFunctionLibrary
+- **源文件**: Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h
+- **模块**: Dialog
+
+## 功能概述
+用于对话脚本 JSON 解析和序列化的静态函数库。解析 Choices JSON 数组和 PresentationScript JSON 命令数组。提供获取命令数量、指定索引处的命令名称、参数数量、指定索引处的参数的函数。同时支持将命令序列化回 JSON。所有方法均为静态 UFUNCTION。
+
+## 设计用意
+蓝图与 JSON 对话数据之间的桥梁。FDialogPresentationScriptData 将命令存储为原始 JSON 字符串；本库负责解析它们。BlueprintFunctionLibrary 使所有方法无需实例即可从蓝图中调用。私有辅助函数处理带正确转义的递归 JSON 值序列化。
+
+## 职责范围
+对话脚本的 JSON 与结构体之间的转换。将 FDialogPresentationScriptData 字段解析为类型化的访问接口。将 TArray<FDialogPresentationScriptCommand> 序列化回 JSON。不执行命令。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| FDialogPresentationScriptData | 参数类型 | Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h |
+| FDialogPresentationScriptCommand | 参数/返回类型 | Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h |
+| FDialogPresentationScriptParam | 内部创建/解析 | Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h |
+| FDialogTextData | 参数类型 | Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h |
+
+## 对外接口
+BlueprintFunctionLibrary，所有方法均为静态 UFUNCTION(BlueprintCallable)，可从 C++ 和蓝图调用。提供两大类功能：脚本数据解析和文本数据访问。
+
+脚本数据解析（参数均为 FDialogPresentationScriptData）：
+- **GetPresentationScriptComment**: 返回 Data.Comment（设计者注释）。
+- **GetPresentationScriptChoicesNum**: 解析 Data.Choices JSON 数组，返回选项数量；解析失败返回 -1。
+- **GetPresentationScriptChoiceAt**: 解析 Data.Choices，返回指定索引处的选项名称 (FName)；越界或失败返回空 FName。
+- **GetPresentationScriptCommandsNum**: 解析 Data.Choices JSON 数组，返回元素数量（注意：此函数存在已知 bug，应解析 Data.PresentationScript 而非 Data.Choices，参见 `DialogPresentationScript.cpp:53`）。
+- **GetPresentationScriptCommandName**: 解析 Data.PresentationScript，返回第 Index 条命令的名称 (FName)。
+- **GetPresentationScriptCommandParaNum**: 解析 Data.PresentationScript，返回第 Index 条命令的参数数量（总元素数减 1）。
+- **GetPresentationScriptCommandParaAt**: 解析 Data.PresentationScript，返回第 CommandIndex 条命令的第 ParaIndex 个参数 (FDialogPresentationScriptParam)。
+- **BuildPresentationScriptCommandParaFromStr**: 从单字符串解析 JSON 值并构建 FDialogPresentationScriptParam。
+- **GetPresentationScriptCommandParams**: 解析 Data.PresentationScript，返回第 CommandIndex 条命令的所有参数 (TArray<FDialogPresentationScriptParam>)。
+- **PresentationScriptToJson**: 将命令数组反向序列化为 JSON 字符串（编辑器导出用）。
+
+文本数据访问：
+- **GetDialogText**: 返回 FDialogTextData 的 DialogText 字段。
+- **GetChoicesText**: 遍历 TArray<FDialogTextData>，提取每个元素的 ChoiceText 字段组成 TArray<FText>。
+
+已知 bug：`GetPresentationScriptChoicesNum` 和 `GetPresentationScriptCommandsNum` 的实现都解析了 `Data.Choices` 而非分别解析 Choices 和 PresentationScript（参见 `DialogPresentationScript.cpp:14` 与 `DialogPresentationScript.cpp:53`）。调用时需注意此行为。
+
+## 使用方法
+在 C++ 中解析脚本命令：
+```cpp
+int NumCommands = UPresentationJsonLibrary::GetPresentationScriptCommandsNum(ScriptData);
+for (int i = 0; i < NumCommands; i++)
+{
+    FName CmdName = UPresentationJsonLibrary::GetPresentationScriptCommandName(ScriptData, i);
+    TArray<FDialogPresentationScriptParam> Params = UPresentationJsonLibrary::GetPresentationScriptCommandParams(ScriptData, i);
+    // 根据 CmdName 分发处理...
+}
+```
+
+在编辑器中序列化命令数组为 JSON：
+```cpp
+// Plugins/Dialog/Source/DialogEditor/Private/DialogGraphDataAsset.cpp:478
+auto ScriptString = UPresentationJsonLibrary::PresentationScriptToJson(DialogNode->PresentationScriptCommands);
+```
+
+## 用例
+| 文件 | 行号 | 用途 |
+|------|------|------|
+| Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h | 101-145 | 类声明，包含所有公共静态方法签名 |
+| Plugins/Dialog/Source/Dialog/Private/DialogPresentationScript.cpp | 6-402 | 全部方法实现：JSON 解析、参数构建、反序列化 |
+| Plugins/Dialog/Source/DialogEditor/Private/DialogGraphDataAsset.cpp | 478 | 调用 PresentationScriptToJson 将编辑器命令数组序列化为 JSON |