98 lines
5.0 KiB
Markdown
98 lines
5.0 KiB
Markdown
# 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 构造预览视图（无运行时数据）。
|