init

Plugins/Dialog/FHelperArray.md

@@ -0,0 +1,54 @@
+# FHelperArray
+
+## 基本信息
+- **类型**: USTRUCT(BlueprintType)
+- **父类**: （无）
+- **源文件**: Plugins/Dialog/Source/Dialog/Public/DialogPresentationSubsystem.h
+- **模块**: Dialog
+
+## 功能概述
+简单的包装结构体，持有 TArray<FDialogTextData>。仅因 Unreal 的 TMap 无法将裸 TArray 作为 UPROPERTY 值类型而存在。用作 ChoiceTextIndex 中的 Map 值类型。
+
+## 设计用意
+UE 引擎限制的变通方案。将数组包装在 USTRUCT 中使其成为有效的 TMap 值类型，以满足 GC 追踪要求。无其他用途。
+
+## 职责范围
+技术性包装结构体。仅在 UDialogPresentationSubsystem 的 ChoiceTextIndex Map 中使用。单一 UPROPERTY 成员：TArray<FDialogTextData> Data。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| FDialogTextData | 包含（TArray成员） | Plugins/Dialog/Source/Dialog/Public/DialogPresentationScript.h |
+
+## 对外接口
+BlueprintType 结构体，纯粹的技术性包装器，唯一用途是使 `TArray<FDialogTextData>` 能够作为 `TMap` 的值类型。
+
+唯一字段：
+- **Data** (TArray<FDialogTextData>): 被包装的 FDialogTextData 数组。
+
+外部代码通过 `UDialogPresentationSubsystem::GetChoiceTextFromMapTable` 获取 `TArray<FDialogTextData>`，通常不会直接操作此结构体。该结构体仅在 `ChoiceTextIndex` 内部使用，作为 `TMap<FName, FHelperArray>` 的值类型。
+
+## 使用方法
+子系统内部索引构建时查找或创建键值对：
+```cpp
+// Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp:120-121
+FName Key = FName(*FString::Printf(TEXT("%s|%s"), *Row->Source.ToString(), *Row->Target.ToString()));
+ChoiceTextIndex.FindOrAdd(Key).Data.Add(*Row);
+```
+
+子系统内部查询时解包数组：
+```cpp
+// Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp:90-92
+if (FHelperArray* Result = ChoiceTextIndex.Find(Key))
+{
+    return Result->Data;  // O(1) 返回
+}
+```
+
+## 用例
+| 文件 | 行号 | 用途 |
+|------|------|------|
+| Plugins/Dialog/Source/Dialog/Public/DialogPresentationSubsystem.h | 15-20 | 结构体定义，位于子系统头文件中 |
+| Plugins/Dialog/Source/Dialog/Public/DialogPresentationSubsystem.h | 66 | ChoiceTextIndex 的 Map 值类型：`TMap<FName, FHelperArray>` |
+| Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp | 90-92 | GetChoiceTextFromMapTable 中解包返回 Data 数组 |
+| Plugins/Dialog/Source/Dialog/Private/DialogPresentationSubsystem.cpp | 121 | BuildIndexes 中通过 FindOrAdd 追加选项行到对应复合键的数组 |