71 lines
4.9 KiB
Markdown
71 lines
4.9 KiB
Markdown
# 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 |
|