init

Plugins/Item/FItemDef.md

@@ -0,0 +1,97 @@
+# FItemDef
+
+## 基本信息
+- **类型**: USTRUCT, 继承 FTableRowBase
+- **父类**: FTableRowBase
+- **源文件**: Plugins/Item/Source/Item/Public/ItemFactory.h
+- **模块**: Item
+
+## 功能概述
+物品类型的DataTable行定义。存储设计师创作元数据：显示名称、图标、描述、掉落Actor类、编辑器注释、默认动态属性（TArray<FItemPropertyEntry>）以及bHasTracer标记。
+
+## 设计用意
+设计时数据契约。每行代表一种物品类型（如"Sword"、"Apple"）。运行时由ItemFactory读取以创建FItemInstance。FTableRowBase继承支持UDataTable::FindRow查找。
+
+## 职责范围
+定义某种物品类型的模板/蓝图。不包含运行时状态（运行时状态由FItemInstance持有）。由设计师在DataTable资产中编辑。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| FItemPropertyEntry | 包含 (UPROPERTY成员) | Plugins/Item/Source/Item/Public/ItemFactory.h |
+
+## 对外接口
+FItemDef 继承自 FTableRowBase，作为 DataTable 的行结构体，由设计师在 DataTable 资产中编辑。运行时通过 UItemRegistrySubsystem::GetItemDef(FName ItemType) 获取。
+
+**可编辑字段：**
+- **ItemName** (FText): 物品显示名称。复制到 FItemView::ItemName。
+- **DefaultIcon** (TObjectPtr<UTexture2D>): 物品默认图标。复制到 FItemView::Icon。
+- **ItemDescription** (FText): 物品描述文本。复制到 FItemView::ItemDescription。
+- **DropActorClass** (TSoftClassPtr<AActor>): 物品掉落时生成的 Actor 类（软引用，不强制加载）。
+- **EditorComment** (FString): 编辑器注释，仅供设计时参考，不影响运行时行为。
+- **DefaultItemProps** (TArray<FItemPropertyEntry>): 物品类型的默认动态属性数组。由 ItemFactory::ConvertDefaultProps 在物品创建时转换并写入 FItemInstance::ItemData。
+- **bHasTracer** (bool): 是否为此类型的物品创建 UItemTracer。为 true 时，ItemFactory 会在属性包中添加 Internal_ItemTracer 对象，用于追踪物品位置和广播移动事件。
+
+**运行时读取方式：**
+调用 UItemRegistrySubsystem::GetItemDef(ItemType) 返回 FItemDef 的副本（值语义）。在使用前应检查 ItemName 是否为空来判断查找是否成功（参见 DefaultContainer.cpp:118 的检查逻辑）。
+
+## 使用方法
+FItemDef 作为 DataTable 行结构体使用。设计师在 DataTable 中为每种物品类型创建一行。
+
+**从注册表获取物品定义：**
+```cpp
+// ItemRegistrySubsystem.cpp:32-42
+FItemDef UItemRegistrySubsystem::GetItemDef(FName ItemType) const
+{
+    for (const auto& Pair : ItemDefMap)
+    {
+        if (Pair.Value)
+        {
+            const FItemDef* Found = Pair.Value->FindRow<FItemDef>(
+                ItemType, TEXT("GetItemDef"));
+            if (Found) return *Found;  // 返回副本
+        }
+    }
+    return FItemDef();  // 空定义（ItemName 为空）
+}
+```
+
+**在物品创建前验证定义有效性：**
+```cpp
+// DefaultContainer.cpp:117-118
+FItemDef Def = Registry->GetItemDef(ItemType);
+if (Def.ItemName.IsEmpty()) return false;  // 检查 ItemName 非空
+```
+
+**传递给 ItemFactory 创建实例：**
+```cpp
+// DefaultContainer.cpp:121
+TUniquePtr<FItemInstance> NewItem =
+    ItemFactory::CreateItemInstance(Def, ItemType);
+```
+
+**构建视图时使用：**
+FItemViewFactory::CreateView 从 FItemDef 复制 ItemName、ItemDescription、DefaultIcon 到 FItemView（ItemViewFactory.cpp:11-19）：
+```cpp
+static void PopulateCommon(FItemView& View, const FItemDef& Def,
+    const FItemInstance& Instance,
+    const TScriptInterface<const IItemContainer>& ItemContainer)
+{
+    View.ItemID = Instance.ItemID;
+    View.ItemType = Instance.ItemType;
+    View.ItemName = Def.ItemName;
+    View.ItemDescription = Def.ItemDescription;
+    View.Icon = Def.DefaultIcon;
+    View.Location = ItemContainer;
+}
+```
+
+## 用例
+- `Plugins/Item/Source/Item/Public/ItemFactory.h:103-122` -- FItemDef 结构体定义（所有 UPROPERTY 字段 + FTableRowBase 继承）。
+- `Plugins/Item/Source/Item/Private/ItemRegistrySubsystem.cpp:32-42` -- GetItemDef() 遍历所有已注册 DataTable，通过 FindRow<FItemDef> 查找并返回物品定义。
+- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:63` -- GetItemViews 中通过 Registry->GetItemDef(Item->ItemType) 获取物品的 FItemDef，传递给 FItemViewFactory。
+- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:77` -- GetItemViewByID 中获取物品定义并传递给工厂。
+- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:117` -- CreateItem 中获取 FItemDef，检查 ItemName 非空后将 Def 传递给 ItemFactory::CreateItemInstance。
+- `Plugins/Item/Source/Item/Private/ItemFactory.cpp:6-24` -- CreateItemInstance 接收 FItemDef 参数，读取 DefaultItemProps 和 bHasTracer 来构造物品。
+- `Plugins/Item/Source/Item/Private/ItemViewFactory.cpp:11-19` -- PopulateCommon 从 FItemDef 复制 ItemName、ItemDescription、DefaultIcon 到 FItemView。
+- `Plugins/Item/Source/Item/Private/ItemViewFactory.cpp:87-93` -- CreatePreviewView 仅使用 FItemDef 构造预览视图（无运行时数据）。