86 lines
4.7 KiB
Markdown
86 lines
4.7 KiB
Markdown
# ItemFactory
|
||
|
||
## 基本信息
|
||
- **类型**: C++ 静态类（非UCLASS）
|
||
- **父类**: (无)
|
||
- **源文件**: Plugins/Item/Source/Item/Public/ItemFactory.h
|
||
- **模块**: Item
|
||
|
||
## 功能概述
|
||
用于创建FItemInstance对象的纯静态工厂。唯一公开方法CreateItemInstance生成GUID、将FItemDef::DefaultItemProps转换为属性包、可选合并覆盖项，并在bHasTracer为true时添加UItemTracer。为FItemInstance的友元类。
|
||
|
||
## 设计用意
|
||
集中化、单一入口的物品创建。确保每个物品都有有效GUID、已填充的默认值和一致的Tracer设置。友元访问阻止外部代码构造未初始化的物品。
|
||
|
||
## 职责范围
|
||
仅负责物品实例化。接收FItemDef + 类型名称返回TUniquePtr<FItemInstance>。私有辅助方法处理属性转换和合并。
|
||
|
||
## 项目内依赖
|
||
| 依赖项 | 关系 | 源文件 |
|
||
|--------|------|--------|
|
||
| FItemInstance | friend class | Plugins/Item/Source/Item/Public/ItemFactory.h |
|
||
| FItemDef | 参数类型 | Plugins/Item/Source/Item/Public/ItemFactory.h |
|
||
| UInternalItemProperty | 调用 | Plugins/Item/Source/Item/Public/ItemFactory.h |
|
||
| UItemTracer | 创建 (NewObject) | Plugins/Item/Source/Item/Public/ItemFactory.h |
|
||
|
||
## 对外接口
|
||
ItemFactory 是纯 C++ 静态类（非 UCLASS），仅提供一个公开静态方法作为物品创建的唯一入口：
|
||
|
||
- **CreateItemInstance(const FItemDef& ItemDef, FName ItemType, const FInstancedPropertyBag* OverrideProps = nullptr)** → TUniquePtr<FItemInstance>: 根据物品定义创建并返回一个新的物品实例。
|
||
|
||
**参数说明：**
|
||
- ItemDef: 物品的 DataTable 行定义，提供默认属性、显示信息等。
|
||
- ItemType: 物品类型名称（通常与 DataTable 行名一致），写入 FItemInstance::ItemType。
|
||
- OverrideProps: 可选的特化属性集。传入 nullptr 则仅使用 ItemDef 中的 DefaultItemProps。非空时，会在 DefaultItemProps 基础上合并覆盖值（同一属性名会被覆盖）。
|
||
|
||
**返回值：**
|
||
返回 TUniquePtr<FItemInstance>。创建的物品实例具有以下特征：
|
||
- 自动生成唯一 ItemID（FGuid::NewGuid()）。
|
||
- ItemData 已填充 DefaultItemProps + OverrideProps 的合并属性。
|
||
- 如果 ItemDef.bHasTracer 为 true，ItemData 中额外包含 Internal_ItemTracer 键的 UItemTracer 对象。
|
||
|
||
**调用限制：**
|
||
此方法是创建 FItemInstance 的唯一入口。FItemInstance 的构造函数是 private/default（通过 friend class ItemFactory 控制），外部代码无法直接构造 FItemInstance。
|
||
|
||
## 使用方法
|
||
ItemFactory 的唯一使用场景是通过 UDefaultContainer::CreateItem 创建物品。
|
||
|
||
**调用 CreateItemInstance（DefaultContainer.cpp:121）：**
|
||
```cpp
|
||
bool UDefaultContainer::CreateItem(FName ItemType,
|
||
TArray<FGuid>& NewItemIDs, int32 Count)
|
||
{
|
||
UItemRegistrySubsystem* Registry = GetRegistry(this);
|
||
if (!Registry) return false;
|
||
FItemDef Def = Registry->GetItemDef(ItemType);
|
||
if (Def.ItemName.IsEmpty()) return false;
|
||
|
||
for (int32 i = 0; i < Count; ++i)
|
||
{
|
||
TUniquePtr<FItemInstance> NewItem =
|
||
ItemFactory::CreateItemInstance(Def, ItemType);
|
||
if (!NewItem) return false;
|
||
NewItemIDs.Add(NewItem->ItemID);
|
||
this->InjectPayload(MoveTemp(NewItem));
|
||
}
|
||
return true;
|
||
}
|
||
```
|
||
|
||
**调用链：**
|
||
1. 外部通过 IItemContainer::CreateItem 请求创建。
|
||
2. UDefaultContainer::CreateItem 从注册表获取 FItemDef，验证有效性。
|
||
3. 调用 ItemFactory::CreateItemInstance(Def, ItemType) → TUniquePtr<FItemInstance>。
|
||
4. 工厂内部：生成 GUID → 转换默认属性 → 合并覆盖属性 → 按需创建 Tracer。
|
||
5. 容器通过自身的 InjectPayload 将物品注入存储。
|
||
|
||
**不直接调用的场景：**
|
||
ItemFactory 不应被直接调用。所有物品创建都应通过容器的 CreateItem 接口，确保物品被正确注入容器并更新 Tracer。
|
||
|
||
## 用例
|
||
- `Plugins/Item/Source/Item/Public/ItemFactory.h:127-140` -- ItemFactory 类声明（CreateItemInstance 公开方法 + ConvertDefaultProps / MergePropertyBag 私有方法）。
|
||
- `Plugins/Item/Source/Item/Private/ItemFactory.cpp:6-24` -- CreateItemInstance 完整实现：生成 GUID → 转换默认属性 → 合并覆盖属性 → 按需创建 Tracer。
|
||
- `Plugins/Item/Source/Item/Private/ItemFactory.cpp:26-48` -- ConvertDefaultProps 实现：遍历 FItemPropertyEntry 数组，从 ValuePicker 读取值并写入 FInstancedPropertyBag。
|
||
- `Plugins/Item/Source/Item/Private/ItemFactory.cpp:51-84` -- MergePropertyBag 实现：将源属性包的所有属性合并到目标属性包（同名覆盖）。
|
||
- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:121` -- UDefaultContainer::CreateItem 调用 ItemFactory::CreateItemInstance 的唯一外部调用点。
|