Introduction
Handles all the player's storage such as personal, vehicle, stash, drops
qb-shops integration for displaying all items available to buy
Built-in support for usable vending machines
All exports listed are SERVER only unless specified
Inventory State
The inventory state is controlled via state bags using a state bag name of inv_busy. You can use this state to control whether the inventory should be able to be opened or not
Example (server):
RegisterCommand('checkState', function(source) local player = Player(source) local state = player.state.inv_busy print('Inventory current state is', state)end, true)RegisterCommand('lockInventory', function(source) local player = Player(source) player.state.inv_busy = true print('Inventory current state is', state)end, true)RegisterCommand('unlockInventory', function(source) local player = Player(source) player.state.inv_busy = false print('Inventory current state is', state)end, true)Example (client):
RegisterCommand('lockInventory', function() LocalPlayer.state:set('inv_busy', true, true)end, false)RegisterCommand('unlockInventory', function() LocalPlayer.state:set('inv_busy', false, true)end, false)Item Info
You can use SetItemData to achieve this
Items support additional information that can be added to them via an info attribute. This information will display on the item when the player hovers over it in a key,value pair format
Example:
RegisterCommand('addItemWithInfo', function(source, args) local itemName = args[1] if not itemName then return end local info = { uniqueData1 = 'uniqueData1', uniqueData2 = 'uniqueData2', uniqueData3 = 'uniqueData3', uniqueData4 = 'uniqueData4', } exports['qb-inventory']:AddItem(source, itemName, 1, false, info, 'qb-inventory:testAdd')end, true)RegisterCommand('editItemWithInfo', function(source) local Player = QBCore.Functions.GetPlayer(source) if not Player then return end local items = Player.PlayerData.items local itemInfo = items[1] print(json.encode(itemInfo, { indent = true })) itemInfo.info = { newInfo = 'New Info' } print(json.encode(itemInfo, { indent = true })) items[1] = itemInfo Player.Functions.SetPlayerData('items', items)end, true)LoadInventory
This function will retrieve the players inventory from the database via their unique identifier aka citizenid
exports['qb-inventory']:LoadInventory(source, citizenid)source:
numbercitizenid:
stringreturns:
table
RegisterCommand('getInv', function(source) local Player = QBCore.Functions.GetPlayer(source) local citizenId = Player.PlayerData.citizenid local items = exports['qb-inventory']:LoadInventory(source, citizenid) print(json.encode(items, { indent = true }))end)SaveInventory
This function saves the players current items to the database
exports['qb-inventory']:SaveInventory(source, offline)source:
numberoffline:
boolean
Example:
RegisterCommand('saveInv', function(source) exports['qb-inventory']:SaveInventory(source, false)end)ClearInventory
exports['qb-inventory']:ClearInventory(source, filterItems)source:
numberfilterItems:
string | table
Example:
RegisterCommand('clearInventoryExcludeItem', function(source, args) local filterItem = args[1] if not filterItem then return end exports['qb-inventory']:ClearInventory(source, filterItem) print('Inventory cleared for player '..source..', excluding item: '..filterItem)end, true)RegisterCommand('clearInventoryExcludeItems', function(source) local filterItems = {'item1', 'item2'} exports['qb-inventory']:ClearInventory(source, filterItems) print('Inventory cleared for player '..source..', excluding items: '..table.concat(filterItems, ', '))end, true)CloseInventory
exports['qb-inventory']:CloseInventory(source, identifier)source:
numberidentifier:
string
Example:
RegisterCommand('closeInventory', function(source) exports['qb-inventory']:CloseInventory(source) print('Inventory closed for player '..source)end, true)RegisterCommand('closeInventoryByName', function(source, identifier) exports['qb-inventory']:CloseInventory(source, identifier) print('Inventory closed for player '..source..' and inventory '..identifier..' set to closed')end, true)OpenInventory
exports['qb-inventory']:OpenInventory(source, identifier, data)source:
numberidentifier:
string | optionaldata:
table | optional
Example:
RegisterCommand('openinv', function(source) exports['qb-inventory']:OpenInventory(source)end, true)RegisterCommand('openinvbyname', function(source, args) local inventoryName = args[1] exports['qb-inventory']:OpenInventory(source, inventoryName)end, true)RegisterCommand('openinvbynamewithdata', function(source, args) local inventoryName = args[1] local data = { label = 'Custom Stash', maxweight = 400000, slots = 500 } exports['qb-inventory']:OpenInventory(source, inventoryName, data)end, true)OpenInventoryById
exports['qb-inventory']:OpenInventoryById(source, playerId)source:
numberplayerId:
number
Example:
RegisterCommand('openplayerinv', function(source, args) local playerId = tonumber(args[1]) exports['qb-inventory']:OpenInventoryById(source, playerId)end, true)OpenInventoryById will close the target players inventory (if open) and lock it via state. It will then unlock when the opening player closes it
CreateShop
exports['qb-inventory']:CreateShop(shopData)shopData:
table
local items = { { name = 'sandwich', amount = 10, price = 5 }}RegisterCommand('createShop', function(source) local playerPed = GetPlayerPed(source) local playerCoords = GetEntityCoords(playerPed) exports['qb-inventory']:CreateShop({ name = 'testShop', label = 'Test Shop', coords = playerCoords, -- optional slots = #items, items = items })end, true)Coords being passed to createShop will be checked against the player's current coords when OpenShopis called if coords were provided during createShop
OpenShop
exports['qb-inventory']:OpenShop(source, name)source:
numbername:
string
RegisterCommand('openShop', function(source) exports['qb-inventory']:OpenShop(source, 'testShop')end)CanAddItem
exports['qb-inventory']:CanAddItem(source, item, amount)source:
numberitem:
stringamount:
numberreturns:
boolean
Example:
RegisterCommand('canAddItem', function(source, args) local itemName = args[1] local amount = tonumber(args[2]) if not itemName or not amount then return end local canAdd, reason = exports['qb-inventory']:CanAddItem(source, itemName, amount) if canAdd then print('Can add '..amount..' of item '..itemName) else print('Cannot add '..amount..' of item '..itemName..'. Reason: '..reason) endend, true)AddItem
exports['qb-inventory']:AddItem(identifier, item, amount, slot, info, reason)identifier:
numberitem:
stringamount:
numberslot:
number | booleaninfo:
table | booleanreason:
stringreturns:
boolean
Example:
RegisterCommand('addItem', function(source, args) local itemName = args[1] if not itemName then return end exports['qb-inventory']:AddItem(source, itemName, 1, false, false, 'qb-inventory:testAdd')end, true)RemoveItem
exports['qb-inventory']:RemoveItem(identifier, item, amount, slot, reason)identifier:
numberitem:
stringamount:
numberslot:
number | booleanreason:
stringreturns:
boolean
RegisterCommand('removeItem', function(source, args) local itemName = args[1] if not itemName then return end exports['qb-inventory']:RemoveItem(source, itemName, 1, false, 'qb-inventory:testRemove')end, true)SetInventory
exports['qb-inventory']:SetInventory(source, items)source:
numberitems:
table
Example:
RegisterCommand('setInventory', function(source) local items = { { name = 'sandwich', amount = 10, type = 'item', info = {}, slot = 1 }, { name = 'water_bottle', amount = 10, type = 'item', info = {}, slot = 2 } } exports['qb-inventory']:SetInventory(source, items)end, true)SetItemData
This function uses GetItemByName to find the itemName being passed
exports['qb-inventory']:SetItemData(source, itemName, key, val)source:
numberitemName:
stringkey:
stringval:
string | tablereturns:
boolean
Example:
RegisterCommand('setItemData', function(source, args) local itemName = args[1] local key = args[2] local val = args[3] if not itemName or not key or not val then return end local success = exports['qb-inventory']:SetItemData(source, itemName, key, val) if success then print('Set data for item '..itemName..': '..key..' = '..val) else print('Failed to set data for item '..itemName) endend, true)Item Info Example:
RegisterCommand('setItemData', function(source) local itemName = 'markedbills' local key = 'info' local val = { worth = 1000 } if not itemName or not key or not val then return end local success = exports['qb-inventory']:SetItemData(source, itemName, key, val) if success then print('Set data for item '..itemName..': '..key..' = '..json.encode(val, { indent = true })) else print('Failed to set data for item '..itemName) endend, true)UseItem
exports['qb-inventory']:UseItem(itemName, ...)itemName:
string. . . :
function
Example:
RegisterCommand('useItem', function(source, args) local itemName = args[1] if not itemName then return end exports['qb-inventory']:Useitem(itemName, function() print('Used item with the name of '..itemName) end)end, true)HasItem
This export is also available to use on the client
exports['qb-inventory']:HasItem(source, items, amount)source:
numberitems:
string | tableamount:
numberreturns:
boolean
Example:
RegisterCommand('hasSingleItem', function(source) local item = 'item1' local amount = 5 local hasItem = exports['qb-inventory']:HasItem(source, item, amount) if hasItem then print('Player '..source..' has '..amount..' of '..item) else print('Player '..source..' does not have '..amount..' of '..item) endend, true)RegisterCommand('hasMultipleItems', function(source) local items = {'item1', 'item2'} local amount = 5 local hasItems = exports['qb-inventory']:HasItem(source, items, amount) if hasItems then print('Player '..source..' has '..amount..' of each item: '..table.concat(items, ', ')) else print('Player '..source..' does not have '..amount..' of each item: '..table.concat(items, ', ')) endend, true)RegisterCommand('hasMultipleItemsWithAmounts', function(source) local itemsWithAmounts = {item1 = 5, item2 = 10} local hasItemsWithAmounts = exports['qb-inventory']:HasItem(source, itemsWithAmounts) if hasItemsWithAmounts then print('Player '..source..' has the specified items with their amounts') else print('Player '..source..' does not have the specified items with their amounts') endend, true)GetSlotsByItem
exports['qb-inventory']:GetSlotsByItem(items, itemName)items:
tableitemName:
stringreturns:
table
Example:
RegisterCommand('getSlots', function(source, args) local itemName = args[1] if not itemName then return end local Player = QBCore.Functions.GetPlayer(source) local items = Player.PlayerData.Items local slots = exports['qb-inventory']:GetSlotsByItem(items, itemName) for _, slot in ipairs(slots) do print(slot) endend, true)GetFirstSlotByItem
exports['qb-inventory']:GetFirstSlotByItem(items, itemName)items:
tableitemName:
stringreturns:
number
Example:
RegisterCommand('getFirstSlot', function(source, args) local itemName = args[1] if not itemName then return end local Player = QBCore.Functions.GetPlayer(source) local items = Player.PlayerData.Items local slot = exports['qb-inventory']:GetFirstSlotByItem(items, itemName) if slot then print('First slot containing item '..itemName..' is: '..slot) else print('No slot found containing item '..itemName) endend, true)GetItemBySlot
exports['qb-inventory']:GetItemBySlot(source, slot)source:
numberslot:
numberreturns:
table
Example:
RegisterCommand('getItem', function(source, args) local slot = tonumber(args[1]) if not slot then return end local item = exports['qb-inventory']:GetItemBySlot(source, slot) if item then print('Item in slot '..slot..' is: '..item.name) else print('No item found in slot '..slot) endend, true)GetItemByName
exports['qb-inventory']:GetItemByName(source, item)source:
numberitem:
stringreturns:
table
Example:
RegisterCommand('getItemByName', function(source, args) local itemName = args[1] if not itemName then return end local item = exports['qb-inventory']:GetItemByName(source, itemName) if item then print('First occurrence of item '..itemName..' is in slot: '..item.slot) else print('No item found with name '..itemName) endend, true)GetItemsByName
exports['qb-inventory']:GetItemsByName(source, item)source:
numberitem:
stringreturns:
table
Example:
RegisterCommand('getItemsByName', function(source, args) local itemName = args[1] if not itemName then return end local items = exports['qb-inventory']:GetItemsByName(source, itemName) if #items > 0 then print('Items named '..itemName..' found in slots:') for _, item in ipairs(items) do print(item.slot) end else print('No items found with name '..itemName) endend, true)GetItemCount
exports['qb-inventory']:GetItemCount(source, items)source:
numberitems:
string | tablereturns:
number
Example:
RegisterCommand('getItemCount', function(source, args) local itemName = args[1] if not itemName then return end local itemCount = exports['qb-inventory']:GetItemCount(source, itemName) if itemCount and itemCount > 0 then print('You have '..itemCount..' of item: '..itemName) else print('No items found with name '..itemName) endend, true)RegisterCommand('getItemCounts', function(source) local itemNames = {"apple", "banana", "orange"} local itemCount = exports['qb-inventory']:GetItemCount(source, itemNames) if itemCount and itemCount > 0 then print('You have '..itemCount..' of the items: '..table.concat(itemNames, ", ")) else print('No items found with the names: '..table.concat(itemNames, ", ")) endend, true)