ox-inventory

ox_inventory

基于格子的背包系统，支持重量、元数据、储物箱、商店和钩子。支持 ox_core、esx 和 qbx_core。

激活约定

当用户要求给予、拿取、统计或检查物品，注册储物箱或商店，定义新物品，对背包操作作出反应，或从 qb-inventory 或 esx inventory 迁移时，加载此技能。

硬性规则

• 所有操作都通过 exports.ox_inventory:<fn>(...) 调用。没有全局表。
• 仅在服务端授予、移除和统计物品。客户端导出仅用于显示和 UI 决策。
• AddItem 可能失败。务必检查返回值：玩家可能超重或没有空格。
• 收取付款或移除交易物品之前，先调用 CanCarryItem 检查，切勿事后检查。
• 切勿臆造物品名称。物品必须存在于 data/items.lua 中，否则会静默失败。
• inv 可以是玩家来源、标识符或储物箱 ID。传入错误值会返回 nil，而不是报错。
• 元数据不同时，物品将无法堆叠。不要在元数据中存放易变数据。

决策条件

目标	调用
给予物品	AddItem(inv, item, count, metadata, slot)
拿取物品	RemoveItem(inv, item, count, metadata, slot)
先检查空间	CanCarryItem(inv, item, count, metadata)
玩家拥有多少个物品	GetItemCount(inv, item, metadata, strict)
读取一个格子	GetSlot(inv, slot)
跨格子查找物品	Search(inv, 'slots'|'count', item, metadata)
持久化存储	RegisterStash(...)
短期存储	CreateTemporaryStash(properties)
对玩家操作作出反应	registerHook(event, cb, options)

执行步骤

1. 确认 ox_inventory 在 ox_lib 和框架核心之后启动。
2. 确定运行端：修改在服务端执行，显示在客户端执行。
3. 对于交易或奖励，按顺序调用：CanCarryItem -> 收取付款 -> AddItem -> 验证返回值。
4. 引用新物品之前，先在 data/items.lua 中定义。阅读 rules/items.md。
5. 对移动、打开或购买操作作出反应时，使用钩子而不是轮询。

输出约定

返回可运行的 Lua 代码，并使用 exports.ox_inventory，明确区分服务端和客户端。引入新物品时，附上 data/items.lua 条目。

参考资料

• rules/server-exports.md — 服务端的物品和背包函数。
• rules/client-exports.md — 重量、当前武器、打开背包。
• rules/items.md — 在 data/items.lua 中定义物品。
• rules/stashes.md — 储物箱、商店和临时存储。
• rules/hooks.md — registerHook 和取消操作。

上游文档：https://overextended.dev/ox_inventory