69 lines
4.5 KiB
Markdown
69 lines
4.5 KiB
Markdown
# IInventory
|
||
|
||
## 基本信息
|
||
- **类型**: UINTERFACE + C++ 接口 (Blueprintable)
|
||
- **父类**: UInterface
|
||
- **源文件**: Plugins/Item/Source/Item/Public/Inventory.h
|
||
- **模块**: Item
|
||
|
||
## 功能概述
|
||
位于IItemContainer之上的更高层、蓝图友好的物品栏接口。所有函数均使用BlueprintNativeEvent。提供RequestMoveItem/ReceiveItem握手模式，用于物品栏间的物品转移。与IItemContainer不同，此接口可以在Blueprint中实现。
|
||
|
||
## 设计用意
|
||
连接底层C++ IItemContainer与Blueprint游戏逻辑的桥梁。允许Blueprint Actor参与物品交换，而无需实现完整的IItemContainer契约。双函数握手模式支持网络化的物品栏交互模式。
|
||
|
||
## 职责范围
|
||
提供Blueprint可访问的物品栏协议。实现者处理Request/Receive握手。不定义存储或属性访问（这些委托给IItemContainer）。
|
||
|
||
## 项目内依赖
|
||
| 依赖项 | 关系 | 源文件 |
|
||
|--------|------|--------|
|
||
| ItemContainer.h | #include | Plugins/Item/Source/Item/Public/ItemContainer.h |
|
||
|
||
## 对外接口
|
||
IInventory 是 Blueprint 友好的物品栏接口（UINTERFACE 标记了 BlueprintType 和 Blueprintable），所有方法使用 BlueprintNativeEvent，允许在 Blueprint 中实现和覆写。
|
||
|
||
**查询方法（BlueprintCallable, BlueprintNativeEvent）：**
|
||
- **GetItemViews()** → TArray<FItemView>: 返回物品栏中所有物品的视图快照。调用方（如 UI Widget）通过 TScriptInterface<IInventory> 调用此方法获取物品列表数据。
|
||
- **GetItemViewByID(const FGuid&)** → FItemView: 按 ID 查找单个物品视图。
|
||
- **GetItemCount()** → int32: 返回当前物品栏中的物品数量。
|
||
|
||
**物品交换协议（BlueprintCallable, BlueprintNativeEvent）：**
|
||
- **RequestMoveItem(const FGuid&, const TScriptInterface<IInventory>&)**: 请求将指定物品移动到目标物品栏。调用方（发送方）调用此方法。典型实现在内部委托给 IItemContainer::MoveItem。此方法无返回值，移动成功或失败由调用方自行判断。
|
||
- **ReceiveItem(const FGuid&, const TScriptInterface<IItemContainer>&)** (BlueprintAuthorityOnly): 从来源容器接收指定物品。目标方（接收方）实现此方法。来源容器以 IItemContainer 接口形式传入，接收方可调用其 GetItemViewByID 获取物品信息后执行接收逻辑。
|
||
|
||
Request/Receive 握手模式使两个物品栏可以在 Blueprint 层完成物品交换，无需了解对方的内部实现。
|
||
|
||
## 使用方法
|
||
IInventory 在 Blueprint 中实现。典型实现者是 BP_InventoryComp 及其子类 BP_DropItemInvComp。
|
||
|
||
**Blueprint 实现模式：**
|
||
在 Blueprint 中，实现者覆写 BlueprintNativeEvent 方法。例如 BP_InventoryComp：
|
||
- GetItemViews 返回缓存的 ViewCache 数组。
|
||
- GetItemViewByID 从 ViewCache 中按 ID 查找。
|
||
- GetItemCount 返回 ViewCache.Num()。
|
||
- RequestMoveItem 内部调用其持有的 DefaultContainer 的 IItemContainer::MoveItem。
|
||
- ReceiveItem 接收来源容器的物品后刷新本地视图缓存。
|
||
|
||
**物品栏间交换流程：**
|
||
```
|
||
发送方: RequestMoveItem(ItemID, TargetInventory)
|
||
→ 内部调用 DefaultContainer->MoveItem(ItemID, TargetContainer)
|
||
→ TargetContainer->InjectPayload(...) // C++ 层注入
|
||
→ 更新本地 ViewCache / 广播 OnViewChanged
|
||
|
||
接收方: ReceiveItem(ItemID, SourceContainer)
|
||
→ 从 SourceContainer 获取物品信息
|
||
→ 刷新本地 ViewCache / 广播 OnViewChanged
|
||
```
|
||
|
||
**持有容器：**
|
||
IInventory 实现者不直接存储物品，而是持有一个 UDefaultContainer（或其子类 BP_DefaultContainer）的引用，将 IInventory 方法委托给 IItemContainer 实现。这保持了 Blueprint 逻辑层（IInventory）与存储层（IItemContainer）的分离。
|
||
|
||
## 用例
|
||
- `Plugins/Item/Source/Item/Public/Inventory.h:20-40` -- IInventory 接口的完整声明（所有 BlueprintNativeEvent 方法定义）。
|
||
- `Plugins/Item/Source/Item/Private/Inventory.cpp:6` -- Inventory.cpp 实现文件，目前为空（仅注释说明为非纯虚函数提供默认实现）。
|
||
- `Document/Content/Blueprints/BP_InventoryComp.md` -- BP_InventoryComp 是 IInventory 的 Blueprint 实现者，包装 UDefaultContainer 并持有 ViewCache/OnViewChanged。
|
||
- `Document/Content/Blueprints/BP_DropItemInvComp.md` -- BP_DropItemInvComp 继承 BP_InventoryComp，是掉落物场景的 IInventory 实现，在 BeginPlay 时自动创建物品。
|
||
- `Document/Content/Blueprints/WBP_InventoryView.md` -- UI Widget 通过引用 BP_InventoryComp（IInventory 实现者）获取 ViewCache 数据显示物品列表。
|