nss_libs - Inventory

Wraps VORP Inventory to provide a unified API for item checks, item manipulation, carry-weight checks, weapon management, usable-item registration, inventory change listeners, and NUI image helpers.

---

How to use

Server side

-- Obtain the server API once (e.g. at resource start).
---@type NssLibsInventoryApi
local inventory = exports.nss_libs:getInventoryApi(GetCurrentResourceName())

local _source = 12 -- Example server player id.

-- Check whether the player has at least 3 coal.
if inventory:existsItem(_source, 'coal', 3) then
    -- Remove 3 coal and add 1 refined_coal.
    inventory:subItem(_source, 'coal', 3)
    inventory:addItem(_source, 'refined_coal', 1)
end

-- Read the complete player inventory.
---@type NssLibsInventoryNamedUserInventoryItemList|nil
local inv = inventory:getUserInventory(_source)

-- Clean up when the resource stops.
inventory:destroy()

Client side

-- Obtain the client API once (e.g. at resource start).
---@type NssLibsInventoryClientApi
local inventory_client = exports.nss_libs:getClientInventoryApi(GetCurrentResourceName())

-- Use an inventory item by its crafted id and item name.
inventory_client.useItem(12, 'coal')

-- Use a weapon by its weapon id and weapon name.
inventory_client.useWeapon(5, 'WEAPON_REVOLVER_CATTLEMAN')

---

API Reference

exports.nss_libs:getInventoryApi(resource_name)

Returns the server-side inventory API instance scoped to resource_name.

Param	Type	Default	Description
resource_name	string	—	Name of the consuming resource (GetCurrentResourceName())

Returns NssLibsInventoryApi — the server-side inventory API instance.

---

exports.nss_libs:getClientInventoryApi(resource_name)

Returns the client-side inventory API instance scoped to resource_name.

Param	Type	Default	Description
resource_name	string	—	Name of the consuming resource (GetCurrentResourceName())

Returns NssLibsInventoryClientApi — the client-side inventory API instance.

---

NssLibsInventoryApi (server)

All methods use colon notation (:method()).

---

Item checks

.existsItem(_source, item_name, required_qty?)

Checks whether the player has at least required_qty of the given item.

Param	Type	Default	Description
_source	number	—	Server player id
item_name	string	—	Internal item name
required_qty	number?	1	Minimum quantity required

Returns boolean — true if the player has enough of the item.

Simple check

-- Returns true when the player has at least 1 coal.
local has_coal = inventory:existsItem(_source, 'coal')

With quantity

-- Returns true when the player has at least 5 coal.
local has_five = inventory:existsItem(_source, 'coal', 5)

---

.existsItems(_source, item_list)

Checks whether the player has all items in item_list. Returns false as soon as any item is missing.

Param	Type	Default	Description
_source	number	—	Server player id
item_list	NssLibsExistItemItem[]	—	Array of items to check

Returns boolean — true if the player has all items.

local has_all = inventory:existsItems(_source, {
    { name = 'coal',  qty = 3 },
    { name = 'water', qty = 1 },
})

---

.getItemCount(_source, item_name)

Returns the number of units the player has of the given item. Returns 0 if the item is not in the inventory.

Param	Type	Default	Description
_source	number	—	Server player id
item_name	string	—	Internal item name

Returns number — the item count.

local count = inventory:getItemCount(_source, 'coal')

---

.existsItemInDb(item_name)

Checks whether an item with the given name is registered in the items database table.

Param	Type	Default	Description
item_name	string	—	Internal item name

Returns boolean — true if the item exists in the database.

if inventory:existsItemInDb('coal') then
    -- Item is known to the framework.
end

---

.requireItemsInDb(resource_name, item_names, additional_error_message?, silent?)

Checks whether all given items exist in the database. Logs errors for missing items.

Param	Type	Default	Description
resource_name	string	—	Name of the calling resource (used in error messages)
item_names	string | string[]	—	Single item name or array of item names
additional_error_message	string?	—	Extra context appended to error messages
silent	boolean?	—	When true, suppresses error output

Returns boolean — true if all items exist in the database.

local ok = inventory:requireItemsInDb(
    GetCurrentResourceName(),
    { 'coal', 'refined_coal' },
    'Required by the crafting system.'
)

---

Item manipulation

.addItem(_source, item_name, qty?, metadata?)

Adds qty units of the item to the player's inventory.

Param	Type	Default	Description
_source	number	—	Server player id
item_name	string	—	Internal item name
qty	number?	1	Amount to add
metadata	table?	—	Metadata table attached to the item

Returns nothing.

Simple

inventory:addItem(_source, 'coal', 5)

With metadata

inventory:addItem(_source, 'custom_item', 1, { quality = 'rare', durability = 100 })

---

.addItems(_source, item_list)

Adds multiple items at once.

Param	Type	Default	Description
_source	number	—	Server player id
item_list	NssLibsExistItemItem[]	—	Array of items to add

Returns nothing.

inventory:addItems(_source, {
    { name = 'coal',  qty = 3 },
    { name = 'water', qty = 2 },
})

---

.subItem(_source, item_name, qty?, metadata?)

Removes qty units of the item from the player's inventory.

Param	Type	Default	Description
_source	number	—	Server player id
item_name	string	—	Internal item name
qty	number?	1	Amount to remove
metadata	table?	—	Metadata table for targeting a specific item instance

Returns nothing.

inventory:subItem(_source, 'coal', 3)

---

.subItems(_source, item_list)

Removes multiple items at once.

Param	Type	Default	Description
_source	number	—	Server player id
item_list	NssLibsExistItemItem[]	—	Array of items to remove

Returns nothing.

inventory:subItems(_source, {
    { name = 'coal',  qty = 3 },
    { name = 'water', qty = 1 },
})

---

.subItemByCraftedId(_source, crafted_id)

Removes a specific item instance identified by its crafted id.

Param	Type	Default	Description
_source	number	—	Server player id
crafted_id	number	—	The unique crafted item id

Returns boolean — true on success.

local removed = inventory:subItemByCraftedId(_source, 42)

---

.setItemMetadata(_source, crafted_id, new_metadata?, new_amount?)

Updates the metadata (and optionally the amount) of an existing crafted item. If new_amount is greater than the current amount, delta items are created for the difference.

Param	Type	Default	Description
_source	number	—	Server player id
crafted_id	number	—	The unique crafted item id
new_metadata	table?	—	Replacement metadata table. Pass nil to clear metadata
new_amount	number?	—	New total amount for the stack

Returns boolean — true on success.

local ok = inventory:setItemMetadata(_source, 42, { quality = 'fine' }, 3)

---

.cleanUpItemFromCraftedItemsTable(_source, char_id, item_name)

Deletes entries for the given character and item name directly from the items_crafted database table via DELETE.

Param	Type	Default	Description
_source	number	—	Server player id
char_id	number	—	Character id of the player
item_name	string	—	Internal item name

Returns boolean — true on success.

local ok = inventory:cleanUpItemFromCraftedItemsTable(_source, char_id, 'broken_tool')

---

Carry checks

.canCarryAdditionalItem(_source, item_name, qty)

Returns true if the player has enough carry capacity to receive qty more of the item.

Param	Type	Default	Description
_source	number	—	Server player id
item_name	string	—	Internal item name
qty	number	—	Amount to check

Returns boolean — true if the player can carry the items.

if inventory:canCarryAdditionalItem(_source, 'coal', 5) then
    inventory:addItem(_source, 'coal', 5)
end

---

.canCarryAdditionalItems(_source, item_list)

Returns true if the player can carry all items in the list.

Param	Type	Default	Description
_source	number	—	Server player id
item_list	NssLibsExistItemItem[]	—	Array of items to check

Returns boolean — true if the player can carry all items.

local can_carry = inventory:canCarryAdditionalItems(_source, {
    { name = 'coal',  qty = 3 },
    { name = 'water', qty = 2 },
})

---

Inventory data

.getUserInventory(_source)

Returns the player's complete inventory as a map keyed by item name. Returns nil if the inventory could not be retrieved.

Param	Type	Default	Description
_source	number	—	Server player id

Returns NssLibsInventoryNamedUserInventoryItemList | nil — the player inventory.

---@type NssLibsInventoryNamedUserInventoryItemList|nil
local inv = inventory:getUserInventory(_source)
if inv then
    local coal_entry = inv['coal']
end

---

.getUserWeapons(_source)

Returns the player's weapons as a map keyed by weapon name. Returns nil if the weapons could not be retrieved.

Param	Type	Default	Description
_source	number	—	Server player id

Returns NssLibsInventoryNamedUserWeaponList | nil — the player weapons.

---@type NssLibsInventoryNamedUserWeaponList|nil
local weapons = inventory:getUserWeapons(_source)

---

.getItemsFromDb(_source, item_names)

Loads item definitions from the database. Returns a map keyed by item name.

Param	Type	Default	Description
_source	number	—	Server player id
item_names	string | string[]	—	Single item name or array of item names

Returns NssLibsInventoryNamedItemList — the item definitions.

---@type NssLibsInventoryNamedItemList
local items = inventory:getItemsFromDb(_source, { 'coal', 'water' })
local coal_def = items['coal']

---

Weapons

.canCarryWeapon(_source, weapon_name, amount)

Checks whether the player can carry an additional weapon. Uses an async promise internally.

Param	Type	Default	Description
_source	number	—	Server player id
weapon_name	string	—	Internal weapon name (e.g. 'WEAPON_REVOLVER_CATTLEMAN')
amount	number	—	Amount to check

Returns boolean — true if the player can carry the weapon.

if inventory:canCarryWeapon(_source, 'WEAPON_REVOLVER_CATTLEMAN', 1) then
    inventory:createWeapon(_source, 'WEAPON_REVOLVER_CATTLEMAN')
end

---

.createWeapon(_source, weapon_name, ammo?, custom_serial?, custom_label?, custom_desc?)

Creates a weapon and adds it to the player's inventory.

Param	Type	Default	Description
_source	number	—	Server player id
weapon_name	string	—	Internal weapon name
ammo	table?	—	Table mapping ammo type to quantity, e.g. { ['ammo_revolver'] = 24 }
custom_serial	string?	—	Custom serial number string
custom_label	string?	—	Custom display label
custom_desc	string?	—	Custom description text

Returns nothing.

inventory:createWeapon(
    _source,
    'WEAPON_REVOLVER_CATTLEMAN',
    { ['ammo_revolver'] = 24 },
    'SN-1234',
    'Old Cattleman',
    'A worn but reliable revolver.'
)

---

Usable items

.registerUsableItem(item_name, callback)

Registers an item as usable. The callback fires whenever a player uses the item.

Param	Type	Default	Description
item_name	string	—	Internal item name
callback	function	—	Called when a player uses the item

Callback parameters:

Param	Type	Description
source	number	Server player id
item_name	string	Internal item name
metadata	table	Item metadata
item_id	number	Inventory item id
crafted_item_id	number	Unique crafted item id
label	string	Display label of the item

Returns nothing.

inventory:registerUsableItem('coal', function(source, item_name, metadata, item_id, crafted_item_id, label)
    -- Remove the used item and apply its effect.
    inventory:subItemByCraftedId(source, crafted_item_id)
    TriggerClientEvent('my_resource:applyCoalEffect', source)
end)

---

Inventory change listener

.listenInventoryChange(callback)

Registers a debounced listener that fires whenever the inventory of any player changes.

Param	Type	Default	Description
callback	function	—	Receives the server player id of the affected player

Returns nothing.

inventory:listenInventoryChange(function(_source)
    -- Inventory of player _source has changed.
end)

---

Custom and bank inventory events

Each listener returns an NssLibsSharedHelperEventHandlerApi that can be used to stop listening later.

.onCustomInventoryOpen(callback)

Fires when a player opens a custom inventory (vorpCore:openCustomInventory).

Param	Type	Default	Description
callback	function	—	fun(source, custom_inv_name, custom_inv_id, custom_inv_capacity)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

inventory:onCustomInventoryOpen(function(source, name, id, capacity)
    print(('Player %d opened custom inventory "%s" (id=%d, cap=%d)'):format(source, name, id, capacity))
end)

---

.onBankInventoryOpen(callback)

Fires when a player opens a bank inventory (vorp_bank:ReloadBankInventory).

Param	Type	Default	Description
callback	function	—	fun(source, bank_name)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

inventory:onBankInventoryOpen(function(source, bank_name)
    print(('Player %d opened bank "%s"'):format(source, bank_name))
end)

---

.onMoveToCustomInventory(callback)

Fires when a player moves an item to a custom inventory (vorp_inventory:MoveToCustom).

Param	Type	Default	Description
callback	function	—	fun(source, data: NssLibsItemMoveToCustomInvData)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

---

.onMoveToBankInventory(callback)

Fires when a player moves an item to a bank inventory (vorp_bank:MoveToBank).

Param	Type	Default	Description
callback	function	—	fun(source, data: NssLibsItemMoveToBankInvData)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

---

.onTakeFromCustomInventory(callback)

Fires when a player takes an item from a custom inventory (vorp_inventory:TakeFromCustom).

Param	Type	Default	Description
callback	function	—	fun(source, data: NssLibsItemMoveToCustomInvData)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

---

.onTakeFromBankInventory(callback)

Fires when a player takes an item from a bank inventory (vorp_bank:TakeFromBank).

Param	Type	Default	Description
callback	function	—	fun(source, data: NssLibsItemMoveToBankInvData)

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

---

Image helpers

These return NUI-ready paths that can be passed directly to frontend components.

.getMoneyImage()

Returns string — the NUI path to the money icon.

---

.getGoldImage()

Returns string — the NUI path to the gold icon.

---

.getWeaponImage(weapon_name)

Returns the NUI path to the icon for a single weapon.

Param	Type	Default	Description
weapon_name	string	—	Internal weapon name

Returns string — the NUI path to the weapon icon.

---

.getWeaponImages(weapon_names)

Returns a map of weapon name to NUI path for multiple weapons.

Param	Type	Default	Description
weapon_names	string | string[]	—	Single weapon name or array of weapon names

Returns NssLibsInventoryAllWeaponImageList — map of weapon name to NUI path.

local images = inventory:getWeaponImages({ 'WEAPON_REVOLVER_CATTLEMAN', 'WEAPON_BOW' })
local icon = images['WEAPON_REVOLVER_CATTLEMAN']

---

Utility

.closeInventory(player)

Closes the inventory UI for the given player.

Param	Type	Default	Description
player	number	—	Server player id

Returns nothing.

inventory:closeInventory(_source)

---

.destroy()

Removes all event listeners and cleans up the API instance. Call this in onResourceStop.

Returns nothing.

AddEventHandler('onResourceStop', function(resource_name)
    if resource_name == GetCurrentResourceName() then
        inventory:destroy()
    end
end)

---

NssLibsInventoryClientApi (client)

Client functions use dot notation (.method()).

.useItem(item_crafted_id, item_name)

Uses an inventory item via the VORP framework bridge.

Param	Type	Default	Description
item_crafted_id	number	—	The unique crafted item id
item_name	string	—	Internal item name

Returns nothing.

---

.useWeapon(weapon_id, weapon_name)

Uses a weapon via the VORP framework bridge.

Param	Type	Default	Description
weapon_id	number	—	The weapon id
weapon_name	string	—	Internal weapon name

Returns nothing.

---

Types

NssLibsExistItemItem

Used in bulk item check and manipulation methods.

Field	Type	Description
name	string	Internal item name
qty	number	Item quantity
metadata	table?	Optional metadata table

---

NssLibsInventoryItem

Item definition as stored in the database.

Field	Type	Description
id	number	Database id
internal_name	string	Internal item name
label	string	Display label
limit	number	Stack/carry limit
type	string	Item type
usable	boolean	Whether the item can be used
desc	string	Item description
metadata	table	Item metadata
image	string	NUI image path

---

NssLibsInventoryUserInventoryItem

Like NssLibsInventoryItem but represents an item in a player's live inventory. Has a count field instead of can_remove.

Field	Type	Description
count	number	Current quantity in inventory