init

Plugins/Dialog/FDialogTextData.md

@@ -0,0 +1,70 @@
+# FDialogTextData
+
+## 基本信息
+- **类型**: USTRUCT(BlueprintType)
+- **父类**: FTableRowBase
+- **源文件**: Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h
+- **模块**: Dialog
+
+## 功能概述
+DataTable 行结构体，用于存储本地化对话文本。包含 bIsChoice 标志、Source/Target 标识符、DialogText 正文和 ChoiceText 标签。当 bIsChoice 为 true 时，表示一个玩家选项。Source 和 Target 组成复合键，用于子系统索引构建。
+
+## 设计用意
+将对话内容（说了什么）与表现逻辑（如何展示）分离。DataTable 存储方式支持本地化和独立编辑。同一结构体通过 bIsChoice 标志同时服务于对话行和选项两种用途。复合键（Source|Target）用于对相关行进行分组。
+
+## 职责范围
+单条对话文本的数据容器。由 UDialogPresentationSubsystem 索引到 DialogTextIndex（按 Source 索引）或 ChoiceTextIndex（按 Source|Target 索引）中。不执行任何查找操作。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+（无项目内依赖）
+
+## 对外接口
+作为 DataTable 行结构体，供外部代码通过 `UDataTable::FindRow<FDialogTextData>()` 读取。
+
+关键字段：
+- **bIsChoice** (bool): 标识该行是普通对话文本 (false) 还是玩家选项文本 (true)。该标志决定行数据在 `BuildIndexes()` 中被索引到 `DialogTextIndex` 还是 `ChoiceTextIndex`。
+- **Source** (FName): 源节点 ID，即对话所属节点的标识符。在 `DialogTextIndex` 中作为单键，在 `ChoiceTextIndex` 中与 Target 组成复合键。
+- **DialogText** (FText): 对话正文。仅当 `bIsChoice == false` 时有意义。可通过 `UPresentationJsonLibrary::GetDialogText` 或 `UDialogPresentationSubsystem::GetDialogTextFromMapTable` 读取。
+- **Target** (FName): 目标节点 ID，即该选项跳转到的节点。仅当 `bIsChoice == true` 时有意义。
+- **ChoiceText** (FText): 选项显示文本。仅当 `bIsChoice == true` 时有意义。可通过 `UPresentationJsonLibrary::GetChoicesText` 或 `UDialogPresentationSubsystem::GetChoiceTextFromMapTable` 读取。
+
+外部代码建议通过 `UDialogPresentationSubsystem` 的查询方法（`GetDialogTextFromMapTable` / `GetChoiceTextFromMapTable`）来获取文本，而不是直接遍历 DataTable。
+
+## 使用方法
+在编辑器中构造对话文本行并写入 DataTable：
+```cpp
+// Plugins/Dialog/Source/DialogEditor/Private/DialogGraphDataAsset.cpp:500-505
+FDialogTextData DialogTextRowData;
+FName DialogTextRowName = FName(*FString::Printf(TEXT("%s_%d"), *DialogNode->NodeID.ToString(), RowNameSuffix++));
+DialogTextRowData.bIsChoice = false;
+DialogTextRowData.Source = DialogNode->NodeID;
+DialogTextRowData.DialogText = DialogNode->DialogText;
+NewTable->AddRow(DialogTextRowName, DialogTextRowData);
+```
+
+编辑器中构造选项文本行：
+```cpp
+// Plugins/Dialog/Source/DialogEditor/Private/DialogGraphDataAsset.cpp:523-529
+FDialogTextData ChoiceTextRowData;
+ChoiceTextRowData.bIsChoice = true;
+ChoiceTextRowData.Source = DialogNode->NodeID;
+ChoiceTextRowData.ChoiceText = ChoiceIndex >= 0 && ChoiceIndex < DialogNode->ChoicePinValue.Num() ? DialogNode->ChoicePinValue[ChoiceIndex++] : FText::GetEmpty();
+ChoiceTextRowData.Target = LinkedNode->NodeID;
+NewTable->AddRow(ChoiceTextRowName, ChoiceTextRowData);
+```
+
+运行时通过子系统查询：
+```cpp
+// Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp:76
+FDialogTextData* Result = DialogTextIndex.Find(Source);
+```
+
+## 用例
+| 文件 | 行号 | 用途 |
+|------|------|------|
+| Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp | 71,76,84,90,109-122 | 在 DialogTextIndex/ChoiceTextIndex 中索引和查找文本行 |
+| Plugins/Dialog/Source/Dialog/Private/DialogPresentationScript.cpp | 135-148 | UPresentationJsonLibrary 的 GetDialogText/GetChoicesText 直接读取字段 |
+| Plugins/Dialog/Source/DialogEditor/Private/DialogGraphDataAsset.cpp | 500-533 | 编辑器从对话图节点导出 MapTable 时构造文本行数据 |
+| Plugins/Dialog/Source/Dialog/Public/DialogPresentationSubsystem.h | 19,50,53,64 | FHelperArray 的 Data 成员类型；子系统查询方法返回类型 |