Items & inventory API

All of this is server side on bs_inventory. The full list with file and line is on the bs_inventory API page.

Defining an item

Add it to Items.Definitions in bs_inventory/config/config_items.lua:

radio_part = { label = 'Radio part', category = 'material', weight = 0.3, w = 1, h = 1,
               stack = 10, usable = false, value = 20 },

Field
label	shown name
category	medical, food, drink, weapon, ammo, material, tool, booster, gadget, drug, gear… drives the F10 tabs and some behaviour
weight, w, h	kg and grid size
stack	max per slot
usable	can be used from the inventory
value	base price for traders
data	behaviour: heal, hunger, thirst, armour, weapon, ammo, drug, handled, defaultMeta, craftingStation…

Definitions are synced into bs_item_definitions on start.

Give, take, count

local inv = exports.bs_inventory

inv:GiveItem(src, 'bandage', 2)                      -- metadata optional
inv:GiveItem(src, 'booster_drone', 1, { battery = 50, capacity = 'medium' })
inv:RemoveItem(src, 'bandage', 1)
local n = inv:CountItem(src, 'bandage')

local def  = inv:GetItem('bandage')                  -- runtime definition
local list = inv:ItemMetaList(src, 'booster_drone')  -- metadata of every stack
inv:SetItemMeta(src, slot, 'booster_drone', meta, true)
inv:Refresh(src)                                     -- push state to the client

Check the return value of GiveItem. A full bag is a real case.

Making an item do something when used

Two ways:

1. Use the built-in data fields (heal, hunger…) and the inventory does it.
2. Handle it yourself. Set data.handled = true so the inventory doesn’t consume it, then listen to the use hook and remove it yourself when it worked:

-- server, in your resource
AddEventHandler('bsesx:useItem:radio_part', function(src)
    if not doTheThing(src) then return end
    exports.bs_inventory:RemoveItem(src, 'radio_part', 1)
end)

The bsesx:useItem:<item> event fires for every used item after the built-in effects. It’s named for the ESX bridge but it’s a plain server event, any resource can listen.

If you also report big item gains to the anti-cheat: exports.bs_guard:ReportItem(src, item, amount).

Containers

Anything with slots that isn’t the player bag: crates, car boots, stashes, event drops.

inv:RegisterContainer('myres:crate:1', { width = 6, height = 4, maxWeight = 150.0, label = 'Crate' })
-- optional 3rd arg: a src that is allowed to open it right away
inv:ContainerGive('myres:crate:1', 'scrap_metal', 5)
inv:OpenContainerFor(src, 'myres:crate:1')
local has = inv:ContainerHasItems('myres:crate:1')
local items = inv:ContainerContents('myres:crate:1')

Register it on the server after your own checks (distance, lock, ownership). The inventory only trusts this table for size, never what a client says. Ids are max 64 chars, prefix them with your resource. bs_events/server/sv_main.lua is a clean example.

Loadouts (hotbar, boosters, gadgets)

inv:LoadoutGet(src, 'gadget')                     -- includes metadata
local ok, meta = inv:LoadoutTake(src, 'gadget', 1, 1, 'booster_drone')
inv:LoadoutPut(src, 'gadget', 1, 'booster_drone', meta)

Weapons and ammo

ItemForWeapon(model) gives the item for a WEAPON_X, AmmoItemFor(weaponName) the ammo item.

Wiping

WipeInventory(src) empties a player. Superadmin only from the F10 menu, use it with care from code.