UnityAI/business-reference/playballoons/features/背包.md

背包

分类

• 项目功能

目的

记录道具、资源数量、背包数据同步、资源展示和奖励入包逻辑。

关键文件

用途	路径	说明
背包管理器	Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/HFBagManager.cs	单例 AbsHFSingleRunTime，管理背包页签、道具/资源数量
背包数据结构	Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/StItem.cs	单个道具数据
背包数据结构	Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/stItemInfo.cs	道具信息
道具类型枚举	Assets/Game/GameHFScripte/GameFunction/Logic/Constant/enItemType.cs	货币、材料、防御塔、经验、道具等
背包窗口	Assets/Game/GameHFScripte/GameFunction/UIWindows/ItemWindow/ItemWindow.cs	单个道具/资源展示单元
GM 调试	Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_BagData.cs	GM 修改背包数据入口
资源配置	XLSX_SRC/CN/Resource.xlsx	资源/道具基础配置

数据流

登录初始化

HFLoginManager.RequestLoginData
  -> PlayerFlushC2S(All = true)
  -> 服务端推送 GetBagItemS2C（待确认具体时序）
  -> HFBagManager.OnPushBagItem
  -> AddItem(item)
  -> HFEvent_InitBag.Dispatch

增量更新

PlayerResourceChangeS2C
  -> ItemChange.Add / Del / Update
  -> HFBagManager.OnUpdateBagItem
  -> AddItem / DelItem
  -> HFEvent_BagItemUpdate.Dispatch

关键 API

方法	用途
Init(int maxpage)	初始化背包页签
AddItem(Item item)	添加/更新道具
DelItem(...)	删除道具
GetGameResourceCount(int resId)	按 resid 快速获取资源数量
GetItemCount(int resid)	遍历具体 item 累加数量
BagPageIndex	当前背包页签

内部存储

• m_BagPage：按页签保存 RB_Tree。
• m_DicPageUUid：按 resid 记录 uuid 到 page 的映射。
• m_DicItemCount：按 resid 快速记录数量（当前为覆盖值，不是累加值）。

关键事件

• enHFSTCEvent.GetBagItem：首次推送背包数据。
• enHFSTCEvent.PlayerResourceChange：资源/道具增量变化。
• HFEvent_InitBag：背包初始化完成。
• HFEvent_BagItemUpdate：背包数据更新。

已确认内容

背包 manager：

• 主类：HFBagManager
• 基类：AbsHFSingleRunTime<HFBagManager>
• 初始化：HFGameStart.InitManager 访问 HFBagManager.Instance 时创建。

监听的服务端事件：

• GetBagItemS2C -> OnPushBagItem
• PlayerResourceChangeS2C -> OnUpdateBagItem

首次背包数据：

HFLoginManager.RequestLoginData
  -> PlayerFlushC2S(All = true)
  -> 服务端推送 GetBagItemS2C（待确认具体时序）
  -> HFBagManager.OnPushBagItem
  -> AddItem
  -> HFEvent_InitBag.Dispatch

增删改更新：

PlayerResourceChangeS2C
  -> ItemChange.Add / Del / Update
  -> AddItem / DelItem
  -> HFEvent_BagItemUpdate.Dispatch

内部存储：

• m_BagPage：按页签保存 RB_Tree。
• m_DicPageUUid：按 resid 记录 uuid 到 page 的映射。
• m_DicItemCount：按 resid 快速记录数量。
• GetGameResourceCount(resId)：常用于资源数量展示。
• GetItemCount(resid)：遍历具体 item 累加数量。

梳理任务

• 找到 HFBagManager 或背包 manager 的入口和生命周期。
• 梳理背包数据来源：登录初始化、网络消息、GM 请求或本地配置。
• 梳理道具和资源的查询 API。
• 梳理背包更新事件如何驱动 UI 刷新。
• 梳理奖励入包和奖励展示的关系。

待确认

• 背包是否区分道具、资源、卡片。
• 背包数据是否全部来自服务器。
• 是否有消耗、添加、合并、排序等本地逻辑。
• PlayerFlushS2C 和 GetBagItemS2C 的服务端推送时序需确认。
• m_DicItemCount[resid] = count 当前是覆盖值，不是累加值，是否符合资源类型语义待确认。

相关框架

• 事件框架
• 网络框架
• UI 框架
• 数据/配置框架

---

文档关联

注意：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。

关联模块

模块	文档	关联原因
登录	登录	HFLoginManager.RequestLoginData 触发背包首次初始化
商店	商店	商店购买/出售涉及背包道具增减
奖励/道具展示	奖励/道具展示	奖励入包展示、道具配置（Resource.xlsx、Gift.xlsx）
塔/角色养成	塔/角色养成	养成消耗涉及背包资源扣除
地图/关卡进度	地图/关卡进度	关卡奖励可能涉及背包道具更新
GM/调试功能	GM/调试功能	GMWindow_BagData 为 GM 修改背包数据入口

关联框架文档

框架	文档	关联原因
事件框架	事件框架	HFEvent_InitBag、HFEvent_BagItemUpdate 事件驱动
网络框架	网络框架	GetBagItemS2C、PlayerResourceChangeS2C 协议
UI 框架	UI 框架	ItemWindow 为背包 UI 展示单元
数据/配置框架	数据/配置框架	Resource.xlsx 资源配置源
内存/对象管理	内存/对象管理	RB_Tree 存储结构、对象池

关联规则

规则	文档	关联原因
模块登记规则	30-模块登记规则.md	背包模块登记与状态
归档规则	50-归档规则.md	变更后需同步归档相关文档
架构说明	10-架构说明.md	背包为全局数据模块，涉及架构分层
开发规则	20-开发规则.md	数据管理、事件使用规范

关联 Spec / OpenSpec

Spec	文档	关联原因
规则工作流 Spec	2026-06-11-rules-workflow-v1.md	项目文档和规则系统建立