# 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 |