Documentation
Every qs-inventory command, client and server export, event and state bag for FiveM developers: AddItem, RemoveItem, HasItem, CanCarryItem, stashes, trunks, CreateShop, OpenShop, usable items and hooks.
Player commands are FiveM key bindings, so each player can change their keys in ESC → Settings → Key Bindings → FiveM. Admin commands check the framework's admin groups; the two panels also accept their ace.
Command | Who | Description |
|---|---|---|
| Everyone | Opens the inventory, or the glovebox, trunk, drop, dumpster or vending machine beside you. |
|
+quickwheelEveryone |
Shows the hotbar, or opens the quick wheel while held, depending on the player's choice. |
| Everyone | Use quick slots 1–5 and the protected slot. Keys |
| Everyone | Reloads the weapon in hand with ammo from the inventory. |
| Everyone | Raises or lowers the hands, while Hands up is on. |
| Everyone | Throws the weapon in hand. |
| Everyone | Searches the closest player with their hands up, or dead when looting dead players is allowed. |
| Admin | Opens the settings panel. Ace |
| Admin | Opens the creator. Ace |
| Admin | Gives an item, with its metadata filled in (ID cards, licences, bags, plates). |
| Admin | Gives a weapon with a serial number and the ammo loaded. |
| Admin | Opens another player's inventory, from anywhere. |
| Admin | Empties a player's inventory — yours without an id. |
| Admin | Frees a stash, trunk or glovebox stuck as "in use". |
| Admin | Sets the condition of the weapon in your hands. Needs the ace |
| Admin | Gives you ten random items, for testing. |
| Console | Sends a test message to every configured Discord webhook and says which ones worked. |
The default keys are set in Settings → Key binds, and the names of the two panel commands in Settings → Access & commands. <id> is the player's server id.
With Debug mode on (Settings → General, advanced), extra test commands are registered for admins —
inventory:openStash,inventory:search,inventory:openOtherand three stash commands — and the console fills with logs. Turn it off on a live server.
Called as exports['qs-inventory']:Name(...) from a client script.
-- Does the player have it? A name, a list, or a { name = amount } table
local hasLockpick = exports['qs-inventory']:HasItem('lockpick')
local hasBoth = exports['qs-inventory']:HasItem({ 'lockpick', 'screwdriverset' })
local hasEnough = exports['qs-inventory']:HasItem({ water_bottle = 2 })
-- How many in total
local count = exports['qs-inventory']:Search('water_bottle')
-- The whole inventory (slot-keyed table) and the item list
local items = exports['qs-inventory']:getUserInventory()
local list = exports['qs-inventory']:GetItemList()The player's inventory is also in the state bag LocalPlayer.state.inventory.
-- Opens Stash_<id> right away: id, slots, max weight in grams, label
exports['qs-inventory']:RegisterStash('house_' .. houseId, 50, 200000, 'House storage')local open = exports['qs-inventory']:inInventory()
exports['qs-inventory']:closeInventory()
-- Block the inventory, hotbar and quick slots (e.g. while cuffed or in a minigame)
exports['qs-inventory']:setInventoryDisabled(true)
local blocked = exports['qs-inventory']:CheckIfInventoryBlocked()
-- Compact layout
local compact = exports['qs-inventory']:isInCompact()
exports['qs-inventory']:setCompactMode(true)
-- Give GTA's weapon wheel back to the game
exports['qs-inventory']:WeaponWheel(true)local weapon = exports['qs-inventory']:GetCurrentWeapon() -- the item in hand, or {}
local name = exports['qs-inventory']:getCurrentWeapon() -- 'weapon_pistol' or nil
local parts = exports['qs-inventory']:getConfigWeaponAttachments('WEAPON_PISTOL')
local tints = exports['qs-inventory']:GetWeaponTints()-- Pause the clothing watcher while your clothing menu is open
exports['qs-inventory']:setInClothing(true)
exports['qs-inventory']:setInClothing(false)
-- The default outfit used when a piece is taken off
local defaults = exports['qs-inventory']:GetClothingDefaults()-- What the server stored with SetMetaData for this player (call it from a thread)
local meta = exports['qs-inventory']:GetMetaData()Called as exports['qs-inventory']:Name(...) from a server script. Item names are lowercase; weights are in grams.
-- AddItem(source, item, amount, slot?, info?)
if exports['qs-inventory']:AddItem(source, 'water_bottle', 2) == true then
-- added
end
-- With metadata
exports['qs-inventory']:AddItem(source, 'id_card', 1, nil, { firstname = 'John', lastname = 'Doe' })
-- RemoveItem(source, item, amount, slot?, metadata?)
exports['qs-inventory']:RemoveItem(source, 'water_bottle', 1)
-- Like /giveitem and /giveweapon: metadata filled in, logged to the admin webhook
exports['qs-inventory']:GiveItemToPlayer(source, 'driver_license', 1)
exports['qs-inventory']:GiveWeaponToPlayer(source, 'weapon_pistol', 60)AddItem checks weight, free slots and carry limits, gives every weapon a serial number and every item a condition of 100, and shows the item notification. Every successful add is recorded in the creator's Stats tab under the name of the resource that called it.
local ok = exports['qs-inventory']:HasItem(source, 'lockpick') -- or a list, or { name = amount }
local fits = exports['qs-inventory']:CanCarryItem(source, 'goldbar', 5)
local total = exports['qs-inventory']:GetItemTotalAmount(source, 'water_bottle')
local first = exports['qs-inventory']:GetItemByName(source, 'phone')
local all = exports['qs-inventory']:GetItemsByName(source, 'phone')
local inSlot = exports['qs-inventory']:GetItemBySlot(source, 3)
local inventory = exports['qs-inventory']:GetInventory(source) -- slot-keyed table
local used, weight = exports['qs-inventory']:GetTotalUsedSlots(source)
local label = exports['qs-inventory']:GetItemLabel('water_bottle')-- Replace the metadata of the item in a slot, e.g. spend 10% of its condition
local item = exports['qs-inventory']:GetItemByName(source, 'firstaid')
item.info.quality = item.info.quality - 10
exports['qs-inventory']:SetItemMetadata(source, item.slot, item.info)
-- Per-player data that is not an item (saved in inventory_metadata)
exports['qs-inventory']:SetMetaData(identifier, { armor = 50 })
-- Change an item's definition while the server runs
local ok, reason = exports['qs-inventory']:UpdateItem('water_bottle', newDefinition)exports['qs-inventory']:CreateUsableItem('lockpick', function(source, item)
-- item.slot, item.info...
TriggerClientEvent('my-heist:useLockpick', source)
end)On QBCore and Qbox this registers the item with the framework too. Items with a client block in their definition run their animation and progress bar first.
-- Empty it, keeping some items
exports['qs-inventory']:ClearInventory(source, { 'id_card', 'phone' })
-- Replace it with a slot-keyed table
exports['qs-inventory']:SetInventory(source, items)
-- Save it now
exports['qs-inventory']:SaveInventory(source)-- Make the player open Stash_<id>
exports['qs-inventory']:RegisterStash(source, 'police_evidence', 100, 500000, 'Evidence')
-- Read and change a stash without opening it
local items = exports['qs-inventory']:GetStashItems('Stash_police_evidence')
exports['qs-inventory']:AddItemIntoStash('Stash_police_evidence', 'tosti', 3, nil, {}, 100, 500000)
exports['qs-inventory']:RemoveItemIntoStash('Stash_police_evidence', 'tosti', 1)
local fits = exports['qs-inventory']:StashCanCarryItem('Stash_police_evidence', 'goldbar', 2)
-- Empty a stash that nobody has open
exports['qs-inventory']:ClearOtherInventory('stash', 'Stash_police_evidence')local trunk = exports['qs-inventory']:GetOtherInventoryItems('trunk', plate)
local glovebox = exports['qs-inventory']:GetOtherInventoryItems('glovebox', plate)
-- AddItemToOtherInventory(type, id, slot, otherSlot, item, amount, info?)
exports['qs-inventory']:AddItemToOtherInventory('trunk', plate, 1, nil, 'spare_tire', 1)
exports['qs-inventory']:RemoveItemFromOtherInventory('trunk', plate, 1, 'spare_tire', 1)
-- A plate changed: move its trunk and glovebox with it
exports['qs-inventory']:UpdateVehiclePlate(oldPlate, newPlate)exports['qs-inventory']:CreateShop({
name = 'hardware_paleto',
label = 'Paleto Hardware',
coords = vector3(-421.8, 6136.3, 31.9),
account = 'money',
restock = 60,
items = {
{ name = 'lockpick', price = 200, amount = 10, stock = 20 },
{ name = 'repairkit', price = 350, amount = 5 },
},
})
exports['qs-inventory']:OpenShop(source, 'hardware_paleto') -- true, or false if refusedOpenShop refuses a player more than 5 m from the shop's coordinates. An optional groups = { police = 0 } limits a shop to jobs.
local weapon = exports['qs-inventory']:GetCurrentWeapon(source) -- the weapon item in that player's hands
local serial = exports['qs-inventory']:CreateSerialNumber()
local plate = exports['qs-inventory']:GeneratePlate()-- Everything made in /inventorycreator, or one kind:
-- 'stash', 'shop', 'seller', 'crafting', 'item', 'weapon'
local shops = exports['qs-inventory']:GetCreatorRecords('shop')exports['qs-inventory']:registerHook('buyItem', function(payload)
-- payload.source, payload.itemName, payload.amount, payload.metadata
end)
exports['qs-inventory']:unregisterHook('buyItem')See Integrations for both hooks and their payloads.
Event | Side | Arguments | When |
|---|---|---|---|
| Server | itemName, source, item | Any item is used. |
| Server | source, item, amount | An item is added or removed. |
| Server | source, item, amount, amountInSlot | An item is added or removed. |
| Both | — | Settings were changed in /inventoryconfig. |
| Client | — | The player's inventory changed. |
| Client | focused | The inventory takes or releases the mouse. |
| Client | weaponName | A weapon is drawn. |
Event | Side | Arguments | Does |
|---|---|---|---|
| Server | type, id, other?, model?, label? | Opens a |
| Server | shopName | Opens a shop registered with |
| Client | stashId | Tells the inventory which stash was just opened. |
| Client | — | Closes the inventory and saves what was open. |
| Client | items, show | Shows or hides the "Required" boxes at the bottom of the screen. |
| Client | item, 'add' | 'remove' | 'use' | Shows an item notification. |
| Client | — | Gives the ESX starter items once. |
| Client | fuel | Updates the petrol can in hand. |
Player(source).state.inventory — LocalPlayer.state.inventory on the client — holds the player's whole inventory and updates on every change. inv_busy is true while the player is busy using an item; the inventory refuses to open meanwhile.
Exports return false or nil when they refuse, and print the reason to the console when it helps. AddItem returns true only when the item was really added, so compare with == true; a player who is too heavy or over a carry limit is told so in game. Before removing what a player is paying with, check HasItem or GetItemTotalAmount first.
Each item carries its metadata in info: info.quality is its condition (0–100), and a weapon has info.serie and info.ammo.
Stashes made in the creator use the id creator_<record id>; GetCreatorRecords('stash') lists them.