Inventory

This is the way of how to get the Inventory API Functions.

local TPZInv = exports.tpz_inventory:getInventoryAPI()

---

Important Information

Lot of API Functions are also having an extra information about using those functions through the Player Object (xPlayer). This is an extra feature that is provided by the Core Base to use Inventory API Functions directly through the Player Object (Only the ones that have a source parameter as requirement). Using Inventory API Functions directly from the Player Object can be very useful.

---

API Functions

Register Usable Items

The following API function `registerUsableItem` is to register a usable item, get the used item data and perform any actions of your preference.

If you are wondering, why does script name is a required parameter, it is because sometimes, you want to know where an item has been registered to. This is the debugging example: [script:tpz_inventory] Callback for the following item {goldpan} has been successfully registered from the following script: tpz_goldpanning

-- @param source     = returns the player source.
-- @param item       - returns the item name.
-- @param itemId     - returns the itemId (itemId exists only for non-stackable items) otherwise it will return as "0"
-- @param id         - returns the item id which is located in the tpz_items table.
-- @param label      - returns the item label name.
-- @param weight     - returns the item weight.
-- @param durability - returns the durability (exists only for non-stackable items).
-- @param metadata   - returns the metadata that you have created on the given item.

TPZInv.registerUsableItem("itemName", "scriptName", function(data)
    
end)

The following API function `unRegisterUsableItem` is to un-register a registered usable item.

TPZInv.unRegisterUsableItem(itemName)

Containers

Events

New Container Registration

-- @param containerName: requires a container name.
-- @param containerWeight: requires the maximum container weight.
-- @param insert : requires a boolean value (false / true) to insert to the containers database the new registered container inventory / not.
-- @param contents: a non-required parameter which requires a table form (only experienced developers).
-- @param data : a non-required parameter which allows your container to have unique data.
-- For example: { allowlisted = 1 } - this data allows this container to not remove any durability from food items.
TriggerEvent("tpz_inventory:registerContainerInventory", containerName, containerWeight, insert, contents)

Unregister a container by its id (permanently).

-- @param containerId: requires a container id (not name).
TriggerEvent("tpz_inventory:unregisterCustomContainer", containerId)

Unregister a container by its name (permanently) - v.1.0.0+

-- @param containerName: requires a container name (not id).
TriggerEvent("tpz_inventory:unregisterCustomContainerByName", containerName)

Register a container contents manually (experienced developers only).

-- @param containerId: requires a container id (not name).
-- @param contents : requires a table form.
TriggerEvent("tpz_inventory:registerCustomContainerInventoryContents", containerId, contents)

Upgrade a container weight by its id.

-- @param containerId: requires a container id (not name).
-- @param extraWeight: requires a double integer value.
TriggerEvent("tpz_inventory:upgradeContainerInventoryWeight", containerId, extraWeight)

API Functions

Returns container inventory data.

-- @param containerId : requires an existing container name (not id)
-- returns integer
local containerId = TPZInv.getContainerIdByName(containerName)

Returns if container exists by the input id - v.1.0.0+

-- @param containerId : requires an existing container id (not name)
-- returns boolean
local containerExist = TPZInv.doesContainerExistById(containerId)

Returns if container exists by the input name - v.1.0.0+

-- @param containerName : requires an existing container name (not id)
-- returns boolean
local containerExist = TPZInv.doesContainerExistByName(containerName)

Returns container inventory data.

-- @param containerId : requires an existing container id (not name)
-- returns table (.name, maxWeight, .inventory, .busy, etc).
local containerData = TPZInv.getContainerData(containerId)

Returns container inventory contents .

-- @param containerId : requires an existing container id (not name)
-- returns table
local contents = TPZInv.getContainerInventoryContents(containerId)

Returns the weight of an inventory container.

-- @param containerId : requires an existing container id (not name)
-- returns double integer.
local containerWeight = TPZInv.getContainerWeight(containerId)

Returns an item quantity from the selected container .

-- @param containerId : requires an existing container id (not name)
-- @param item : requires an item name.
-- returns integer.
local itemQuantity = TPZInv.getContainerItemQuantity(containerId, item)

Checks if the container can carry an item quantity.

-- @param containerId : requires an existing container id (not name)
-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- returns boolean.
local canCarryItem = TPZInv.canCarryContainerItem(containerId, item, quantity)

Checks if the container can carry an weapon.

-- @param containerId : requires an existing container id (not name)
-- @param weaponName: requires a weapon name.
-- @param quantity : requires a quantity.
-- returns boolean.
local canCarryWeapon = TPZInv.canCarryContainerWeapon(containerId, weaponName)

Removes an item quantity from the selected container.

-- @param containerId : requires an existing container id (not name)
-- @param item : requires an item name.
-- @param quantity: requires the quantity to be removed.
-- @param itemId : requires an itemId if the item is non-stackable.
TPZInv.removeContainerItem(containerId, item, quantity, itemId)

Removes a weapon from the selected container.

-- @param containerId : requires an existing container id (not name)
-- @param weaponName: requires the weapon name.
-- @param itemId : requires a weapon itemId.
TPZInv.removeContainerWeapon(containerId, weaponName, itemId)

Add an item quantity to the selected container (if exists).

-- @param containerId : requires an existing container id (not name)
-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- @param itemId : Required only if the item which is given already exists and has itemId.
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).
-- For not showing durability to a non stackable item, set metadata.durability to -1.
TPZInv.addContainerItem(containerId, item, quantity, itemId, metadata)

Add a weapon to the selected container (if exists).

-- @param containerId : requires an existing container id (not name)
-- @param weaponName : requires an item name.
-- @param itemId : Required only if the item which is given already exists and has itemId.
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).
-- For not showing durability to a non stackable item, set metadata.durability to -1.
TPZInv.addContainerWeapon(containerId, weaponName, itemId, metadata)

General Functions

Returns player inventory contents.

-- returns table
local contents = TPZInv.getInventoryContents(source)

-- Using GetPlayer Object (xPlayer)
-- returns table
local contents = xPlayer.getInventoryContents()

Returns player inventory max weight.

-- returns double integer.
local maxWeight = TPZInv.getInventoryMaxWeight()

Returns current player inventory total weight.

-- returns double integer.
local totalWeight = TPZInv.getInventoryTotalWeight(source)

-- Using GetPlayer Object (xPlayer)
-- returns double integer.
local totalWeight = xPlayer.getInventoryTotalWeight()

Saves all the player inventory contents (Accounts are not part of the inventory).

TPZInv.saveInventoryContents(source)

-- Using GetPlayer Object (xPlayer)
xPlayer.saveInventoryContents()

Clear all the player inventory contents (Accounts are not part of the inventory).

TPZInv.clearInventoryContents(source)

-- Using GetPlayer Object (xPlayer)
xPlayer.clearInventoryContents()

Close Player Inventory

TPZInv.closeInventory(source)
TriggerClientEvent('tpz_inventory:closePlayerInventory', source)

-- Using GetPlayer Object (xPlayer)
xPlayer.closeInventory()

Items

Returns the selected item weight.

-- @param item : requires the item name.
-- returns double integer.
local itemWeight = TPZInv.getItemWeight(item)

Returns the selected item data.

-- @param item : requires the item name.
-- returns table.
local itemData = TPZInv.getItemData(item)

-- itemData:
-- itemData.label : returns string.
-- itemData.weight : returns double integer value.
-- itemData.remove : returns integer (0-1)
-- itemData.description : returns string
-- itemData.action : returns string
-- itemData.stackable : returns integer (0-1)
-- itemData.droppable : returns integer (0-1)
-- itemData.closeInventory : returns integer (0-1)

Returns the selected item label name.

-- @param item : requires the item name.
-- returns string.
local itemLabel = TPZInv.getItemLabel(item)

Returns if the selected item is stackable / not.

-- @param item : requires the item name.
-- returns integer (0-1).
local isItemStackable = TPZInv.isItemStackable(item)

Returns if the selected item is removable / not.

-- @param item : requires the item name.
-- returns integer (0-1).
local isItemRemovable = TPZInv.isItemRemovable(item)

Returns an item quantity from the player's inventory.

-- @param item : requires the item name.
-- returns integer.
local itemQuantity = TPZInv.getItemQuantity(source, item)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires the item name.
-- returns integer.
local itemQuantity = xPlayer.getItemQuantity(item)

Checks if the player inventory can carry the input weight.

-- @param weight : requires a weight input.
-- returns boolean.
local canCarryWeight = TPZInv.canCarryWeight(source, weight)

-- Using GetPlayer Object (xPlayer)
-- @param weight : requires a weight input.
-- returns boolean.
local canCarryWeight = xPlayer.canCarryWeight(weight)

Checks if the player's inventory can carry an item quantity.

-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- returns boolean.
local canCarryItem = TPZInv.canCarryItem(source, item, quantity)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- returns boolean.
local canCarryItem = xPlayer.canCarryItem(item, quantity)

Add an item quantity to the player's inventory.

-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).
-- For not showing durability to a non stackable item, set metadata.durability to -1.
TPZInv.addItem(source, item, quantity, metadata)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param quantity : requires a quantity.
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).
-- For not showing durability to a non stackable item, set metadata.durability to -1.

xPlayer.addItem(item, quantity, metadata)

Removes an item quantity from the player's inventory.

-- @param item : requires an item name.
-- @param quantity: requires the quantity to be removed.
-- @param itemId : requires an itemId if the item is non-stackable (integer only).
TPZInv.removeItem(source, item, quantity, itemId)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param quantity: requires the quantity to be removed.
-- @param itemId : requires an itemId if the item is non-stackable (integer only).

xPlayer.removeItem(item, quantity, itemId)

Add item durability to the selected item.

-- @param item : requires an item name.
-- @param durability: requires the durability input to be added on the item.
-- @param itemId : requires an itemId (integer only).
TPZInv.addItemDurability(source, item, durability, itemId)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param durability: requires the durability input to be added on the item.
-- @param itemId : requires an itemId (integer only).

xPlayer.addItemDurability(item, durability, itemId)

Remove item durability from the selected item.

-- @param item : requires an item name.
-- @param durability: requires the durability input to be removed from the item.
-- @param itemId : requires an itemId (integer only).
TPZInv.removeItemDurability(source, item, durability, itemId)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param durability: requires the durability input to be removed from the item.
-- @param itemId : requires an itemId (integer only).

xPlayer.removeItemDurability(item, durability, itemId)

Get item durability from the selected item.

-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- returns integer.
local itemDurability = TPZInv.getItemDurability(source, item, itemId)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- returns integer.
local itemDurability = xPlayer.getItemDurability(item, itemId)

Get item metadata from the selected item.

-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- returns table.
local itemMetadata = TPZInv.getItemMetadata(source, item, itemId)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- returns table.
local itemMetadata = xPlayer.getItemMetadata(item, itemId)

Add item metadata to the selected item.

-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- @param metadata : requires the metadata (table)
TPZInv.addItemMetadata(source, item, itemId, metadata)

-- Using GetPlayer Object (xPlayer)
-- @param item : requires an item name.
-- @param itemId : requires an itemId (integer only).
-- @param metadata : requires the metadata (table)
xPlayer.addItemMetadata(item, itemId, metadata)

Weapons

Returns the selected weapon label name.

-- @param weaponName : requires the weapon name.
-- returns string.
local itemLabel = TPZInv.getWeaponLabel(weaponName)

Checks if the player's inventory can carry a weapon.

-- @param weaponName : requires the weapon name.
-- returns boolean.
local canCarryWeapon = TPZInv.canCarryWeapon(source, weaponName)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- returns boolean.
local canCarryWeapon = xPlayer.canCarryWeapon(weaponName)

Checks if the player's inventory has a weapon by its id.

-- @param weaponName : requires the weapon name.
-- @param weaponId : requires a weaponId (string only).
-- returns boolean.
local hasWeapon = TPZInv.doesPlayerHaveWeapon(source, weaponName, weaponId)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- @param weaponId : requires a weaponId (string only).
-- returns boolean.
local hasWeapon = xPlayer.doesPlayerHaveWeapon(weaponName, weaponId)

Add a weapon to the player's inventory.

-- @param weaponName : requires the weapon name.
-- @param weaponId : A non-required parameter, if weaponId is null, it will automatically create a weaponId (string only).
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).
TPZInv.addWeapon(source, weaponName, weaponId, metadata)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- @param weaponId : A non-required parameter, if weaponId is null, it will automatically create a weaponId (string only).
-- @param metadata : A non-required parameter.
-- (!) metadata can hold multiple values (includes custom ones).

xPlayer.addWeapon(weaponName, weaponId, metadata)

Remove a weapon from the player's inventory.

-- @param weaponName : requires the weapon name.
-- @param weaponId : requires a weaponId (string only).
TPZInv.removeWeapon(source, weaponName, weaponId)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- @param weaponId : requires a weaponId (string only).
xPlayer.removeWeapon(weaponName, weaponId)

Add weapon durability to the selected item.

-- @param weaponName : requires the weapon name.
-- @param durability: requires the durability input to be added on the weapon.
-- @param weaponId : requires a weaponId (string only).

TPZInv.addWeaponDurability(source, weaponName, durability, weaponId)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- @param durability: requires the durability input to be added on the weapon.
-- @param weaponId : requires a weaponId (string only).

xPlayer.addWeaponDurability(weaponName, durability, weaponId)

Remove item durability from the selected item.

-- @param weaponName : requires the weapon name.
-- @param durability: requires the durability input to be removed from the weapon.
-- @param weaponId : requires a weaponId (string only).
TPZInv.removeWeaponDurability(source, weaponName, durability, weaponId)

-- Using GetPlayer Object (xPlayer)
-- @param weaponName : requires the weapon name.
-- @param durability: requires the durability input to be removed from the weapon.
-- @param weaponId : requires a weaponId (string only).

xPlayer.removeWeaponDurability(weaponName, durability, weaponId)

---