0 Fork 0

Files

T

西风逍遥游andCursor Agent 068085a93c feat: 高扩展性背包 / 物品栏模块 (inventory) (#17 )

* feat: add extensible inventory/backpack module

Introduce eve.Inventory with data-driven items, Bag containers,
EquipmentSet, pluggable accept/capacity/stack rules, change events,
script bindings, tests, docs, and a playable example.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

* fix: inventory tests for CHECK_EQ double-eval and never-stack slots

Store side-effecting call results before CHECK_EQ (zeroerr evaluates LHS
twice), and treat non-merging stack rules as per-slot capacity 1.

Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

2026-08-10 13:03:46 +08:00

4.0 KiB

Raw Blame History

背包 / 物品栏模块

脚本入口： eve.Inventory()

数据驱动的物品定义、固定格容器（背包/箱子）、跨包转移、具名装备栏，以及可插拔的接纳 / 容量 / 堆叠规则。

基本用法

local inv = eve.Inventory();
inv.registerItemsFromJson(@"[
  {""id"":""potion.hp"",""displayName"":""治疗药水"",""maxStack"":20,""weight"":0.2,""tags"":[""potion""]},
  {""id"":""sword.iron"",""maxStack"":1,""weight"":3.5,""equipSlot"":""weapon"",""tags"":[""weapon""]}
]");

local bag = inv.newBag(20);
bag.setId("player");
bag.setMaxWeight(50.0);
bag.addItem("potion.hp", 5);
print(bag.countItem("potion.hp") + "\n");

对象关系与调用时机

Inventory 持有进程级物品定义表，并创建 Bag / EquipmentSet。容量策略名、接纳规则名、堆叠规则名都是字符串；内置规则开箱即用，自定义规则需在 C++ 侧 InventorySystem::register*。变更事件可在操作后用 getChangeEvent* 轮询。

目标导向指南

做玩家背包与任务栏

newBag(n) 建主背包；另建一个 acceptTags 仅含 "quest" 的袋子作任务栏。主背包可 addRejectTag("quest") 拒绝任务物品误入。

穿脱装备

newEquipmentSet() 后 defineSlot("weapon")，可选 addSlotAllowedTag。从背包 findItem 得到槽位，再 equipFromBag / unequipToBag。属性加成请在脚本或 C++ registerChangeHook 里对接 rpg 模块，背包本身不依赖 RPG。

常见问题

未先 registerItemsFromJson / C++ registerItem 就 addItem，会放入 0 个。
canAddItem 表示能否放入全部请求数量；addItem 允许部分成功。
maxWeight / maxVolume 为 <=0 时该维度不限制（仍受所选 capacityPolicy 约束）。

API 快查

addAcceptTag()、addItem()、addRejectTag()、addSlotAllowedTag()、addSlotTag()、canAddItem()、canAddItemReason()、clear()、clearAcceptTags()
clearChangeEvents()、clearItemDefinitions()、clearRejectTags()、clearSlot()、clearSlotAllowedTags()、countItem()、defineSlot()、destroy()、equipFromBag()
findItem()、findItemByTag()、getAcceptRule()、getAcceptTag()、getAcceptTagCount()、getCapacityPolicy()、getChangeEventAction()、getChangeEventBagId()、getChangeEventCount()
getChangeEventEquipSlot()、getChangeEventItemId()、getChangeEventOtherBagId()、getChangeEventOtherSlot()、getChangeEventQuantity()、getChangeEventSlot()、getExtra()、getId()、getItemCategory()
getItemDefinitionCount()、getItemDisplayName()、getItemEquipSlot()、getItemExtra()、getItemMaxStack()、getItemVolume()、getItemWeight()、getKind()、getMaxVolume()
getMaxWeight()、getName()、getRejectTag()、getRejectTagCount()、getSlotCount()、getSlotDurability()、getSlotInstanceId()、getSlotItemId()、getSlotName()
getSlotProp()、getSlotQuantity()、getStackRule()、getUsedSlotCount()、getUsedVolume()、getUsedWeight()、hasAcceptRule()、hasCapacityPolicy()、hasItemDefinition()
hasSlot()、hasStackRule()、isSlotEmpty()、itemHasTag()、moveSlot()、newBag()、newEquipmentSet()、registerItemsFromJson()、removeAt()
removeItem()、setAcceptRule()、setCapacityPolicy()、setExtra()、setId()、setKind()、setMaxVolume()、setMaxWeight()、setSlotCount()
setSlotDurability()、setSlotProp()、setStackRule()、slotHasTag()、splitStack()、swapSlots()、transferItem()、transferSlot()、unequipToBag()

使用要点

将 Bag / EquipmentSet 保存在全局或实体状态中，不要每帧 newBag。
浮点重量/体积在脚本侧为 float。
自定义接纳/容量/堆叠回调只能在 C++ 注册；脚本通过策略名字符串选用。

源码： src/modules/inventory/
设计文档： docs/dev/背包系统设计.md
相关测试： 在 test/ 中搜索 inventory。

4.0 KiB Raw Blame History