godot-inventory-system

场景触发条件（使用哪个脚本？）

场景	打开
槽位背包（WoW 风格堆叠）	inventory_data_resource.gd + item_slot_data.gd + inventory_ui_controller.gd
俄罗斯方块网格（Diablo/RE 占格）	grid_inventory_logic.gd / inventory_grid.gd
装备	物品 Resources + RPG 属性扩展；通过 drag_and_drop_slot.gd 拖动
战利品表	loot_table_resource.gd + item_pickup_node.gd
持久化	inventory_persistence.gd（保存 id 和数量，而非嵌套 Resources）
消耗品	consumable_item_logic.gd
数据库查找	item_database_loader.gd

必须阅读

1. inventory_item_resource.gd — 物品蓝图
2. inventory_data_resource.gd — 两轮堆叠与重量验证
3. inventory_ui_controller.gd — 复用槽位控件的响应式 UI

库存系统中绝对不要做的事

• 绝对不要用节点表示物品 — Item extends Resource。
• 绝对不要在未预检查堆叠和重量的情况下添加物品 — 先验证容量。
• 绝对不要让 UI 静默修改库存数组 — 数据负责修改；UI 负责监听。
• 绝对不要用 float 表示数量 — 堆叠数量使用 int。
• 绝对不要在批量操作中逐个物品发送信号 — 循环结束后只发送一次 inventory_updated。
• 绝对不要硬编码物品引用 — 使用 String/StringName id 和数据库。
• 绝对不要在每次刷新时都 queue_free 并重新创建所有槽位 — 复用槽位控件（参见 UI 控制器）。
• 绝对不要在 _process 中分配新的 Resources。
• 绝对不要在运行时修改共享的物品蓝图 — 对堆叠/槽位实例使用 duplicate(true)，避免一次拾取破坏该 .tres 文件的所有副本。
• 绝对不要在槽位物品为空时访问 .icon — 绘制 UI 前使用 is_instance_valid() 进行检查。

决策流程

添加物品

1. 重量/体积是否符合要求？
2. 第一轮：填满未满的堆叠
3. 第二轮：空槽位/网格占格
4. 返回溢出数量；仅发送一次 UI 信号

UI

• 仅绑定一次 inventory_updated
• 更新现有槽位节点；仅在槽位数量增加时创建新节点

存档

• 仅序列化 item_id / resource_path 和 amount — inventory_persistence.gd

深入配方（按需查阅）

主题	参考资料/脚本
Resource 物品模型	core-architecture.md + inventory_item_resource.gd
两轮堆叠添加	inventory-manager.md + inventory_data_resource.gd
俄罗斯方块网格占格	elite-technical-patterns.md + grid_inventory_logic.gd
装备与制作	equipment-system.md / crafting-integration.md
响应式 UI 与存档 id	ui-integration.md + inventory_persistence.gd

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转至同级领域时加载相关技能，不要预加载整个知识网络。

官方文档

• 资源 — 物品、槽位和库存应使用 Resource 数据（而非 Node），这样堆叠就能保持轻量，并可作为 .tres 数据库共享。
• Resource — 对运行时的堆叠／槽位实例使用 duplicate(true)，这样修改数量就不会损坏共享的物品蓝图。
• GDScript 导出变量 — @export / @export_group 可为物品 Resource 中的 id、图标、max_stack、重量和战利品权重提供 Inspector 配置。
• 使用信号 — 发出 inventory_changed / 槽位信号，让 UI 反映数据；切勿让槽位控件悄悄修改数组。
• 场景组织 — 遵循“信号向上，调用向下”：UI 负责监听；库存 Resource／管理器负责添加、移除和堆叠逻辑。
• GUI 容器 — 在自定义俄罗斯方块式占格之前，先以 GridContainer / 容器尺寸调整为槽位网格的基础。
• Control — 使用原生 _get_drag_data / _can_drop_data / _drop_data 和 set_drag_preview 实现库存拖放交换，无需自定义输入系统。
• 自定义 GUI 控件 — 介绍如何构建绘制图标／数量并支持拖放的槽位 Control。
• 保存游戏 — 与其他玩家存档数据一起持久化保存槽位 id + 数量（而非完整的递归 Resource）。
• ResourceLoader — 加载时通过 resource_path / id 解析物品蓝图，而不是在每个存档数据块中嵌入纹理。
• JSON — 使用紧凑的库存字典（path/id + amount）存入 FileAccess 存档文件，避免嵌套的 Resource 图过于庞大。
• 随机数生成 — 加权战利品抽取和宝箱内容需要使用有种子的 RNG 模式，而不是在 UI 代码中随意散布 randf()。

相关技能

前置条件

• godot-resource-data-patterns — 库存以 Resource 为先（物品、槽位、战利品表）；在创建基于 Node 的物品树之前，先学习组合／序列化模式。
• godot-signal-architecture — 可批处理的 inventory_updated / 槽位信号能让响应式 UI 保持同步，同时避免逐物品发送信号或出现无效连接。
• godot-gdscript-mastery — 类型化 Resource、Array/Dictionary 槽位映射和 int 堆叠运算都需要扎实掌握 GDScript 模式。
• godot-ui-containers — 槽位网格、装备面板和自适应库存窗口都应先基于容器布局，再完善拖放体验。

补充

• godot-save-load-systems — 物品栏持久化必须遵循项目的存档架构进行往返转换（ID + 数量，并确保迁移安全）。
• godot-rpg-stats — 装备加成、负重和消耗品效果需要统一的属性/修正值层。
• godot-economy-system — 商店、买卖和按稀有度加权的战利品表使用相同的物品资源和堆叠规则。
• godot-ability-system — 消耗型卷轴、技能书和赋予能力的装备，可将物品栏授予的能力接入 AbilityManager 注册流程。
• godot-combat-system — 从物品栏装备的武器/护甲会接入伤害和命中处理流程；DamageData 应与物品元数据分开。
• godot-ui-theming — 稀有度颜色、槽位样式和拖拽预览应放在 Theme 资源中，而不是硬编码在槽位脚本里。

下游 / 使用方

• godot-monte-carlo-balancer — 在堆叠数量、重量、掉落率和商店价格由数据驱动后，通过 Monte Carlo 模拟在发布曲线前验证经济/战利品区间。
• godot-genre-action-rpg — 动作 RPG 的背包、装备界面和战利品循环会将此技能与战斗、属性和任务系统组合使用。
• godot-genre-survival — 重量限制、消耗品和稀缺战利品是生存类物品栏的核心约束。
• godot-quest-system — 搜寻/收集任务通过 has_item 查询，并通过相同的物品栏添加/移除 API 发放奖励。

主模块

• godot-master — 库路由器和镜像模块入口；用于发现同级技能，或在领域技能编辑后同步共享脚本镜像。