Documentation
Integrate Quasar Inventory with ESX, QBCore and Qbox, appearance and target scripts, qb-inventory and ox_inventory exports, ambulance, clothing shops, police searches, starter items, fuel, hooks and Discord logs.
The inventory never assumes which framework or script you run. It looks at what is started when it boots, and every framework- or script-specific piece lives in a small bridge file under client/custom/ and server/custom/ that you can read and edit.
Layer | Supported | Bridge |
|---|---|---|
Framework | ESX, QBCore, Qbox |
|
Appearance |
illenium-appearance, qs-appearance, rcore_clothing, esx_skin, qb-clothing |
|
Target | ox_target, qb-target |
|
Other inventories | qb-inventory and ox_inventory exports |
|
Notifications | qs-interface, otherwise ox_lib | — |
3D text | qs-textui, otherwise native text | — |
ESX | QBCore | Qbox | |
|---|---|---|---|
Player table |
|
|
|
Items read from |
|
|
|
Cash |
|
|
|
Admins | groups | permissions | same as QBCore |
Starter items |
| qb-core's own | qb-core's own |
On QBCore the inventory replaces the player's AddItem, RemoveItem, GetItemBySlot, GetItemByName, GetItemsByName, ClearInventory and SetInventory functions, so scripts using Player.Functions.AddItem keep working. On ESX, items registered as usable through ESX are picked up automatically.
Many scripts call another inventory directly. Inventory answers those calls itself, so they keep working without edits:
exports['qb-inventory']:AddItem, RemoveItem, HasItem, CanCarryItem, GetItemByName, GetItemsByName, GetItemBySlot, ClearInventory, SetInventory, OpenShop, CreateShop, CreateUsableItem, GetStashItems, AddItemIntoStash, RemoveItemIntoStash, OpenInventory (opens a stash), OpenInventoryById (opens another player) and the rest of the qb-inventory API are routed to qs-inventory. The real qb-inventory is stopped when Config.BypassQbInventory = true.
exports.ox_inventory:AddItem, RemoveItem, CanCarryItem, GetItem, Search, GetSlot, GetSlotWithItem, GetSlotsWithItem, SetMetadata, Items, GetCurrentWeapon, ClearInventory, RegisterShop and RegisterStash work on the server, and Search, Items, getCurrentWeapon and openInventory on the client. Items come back with ox-style and fields. , and are not supported and print a warning.
Scripts that only check GetResourceState('ox_inventory') will not see it as started. Remove that check or the ox_inventory dependency from those scripts — or, on Qbox, uncomment provide 'ox_inventory' in qs-inventory/fxmanifest.lua.
ClearInventory empties a player's inventory and can keep a list of items. A typical use is the ambulance job's "lose items on respawn":
local keep = {
'id_card', -- items that are NOT removed
'phone',
}
exports['qs-inventory']:ClearInventory(source, keep)For esx_ambulancejob, change the esx_ambulancejob:removeItemsAfterRPDeath callback in its server/main.lua:
ESX.RegisterServerCallback('esx_ambulancejob:removeItemsAfterRPDeath', function(source, cb)
local xPlayer = ESX.GetPlayerFromId(source)
if Config.RemoveCashAfterRPDeath then
if xPlayer.getMoney() > 0 then
xPlayer.removeMoney(xPlayer.getMoney(), 'Death')
end
if xPlayer.getAccount('black_money').money > 0 then
xPlayer.setAccountMoney('black_money', 0, 'Death')
end
end
if Config.RemoveItemsAfterRPDeath then
exports['qs-inventory']:ClearInventory(source, { 'id_card', 'phone' })
end
cb()
end)The inventory checks what the character wears every second or so and turns it into clothing items. While a player is inside a clothing shop menu, pause that check so trying clothes on does not create items; resume it when the menu closes:
-- when your clothing menu opens
exports['qs-inventory']:setInClothing(true)
-- when it closes
exports['qs-inventory']:setInClothing(false)Most paid clothing scripts already include these two calls. When the inventory closes, the outfit is saved through the detected appearance resource:
Resource | Saved with |
|---|---|
illenium-appearance · qs-appearance |
|
rcore_clothing |
|
esx_skin |
|
qb-clothing | the |
none | not saved (standalone) |
Any resource can open a stash by id. The client and server exports open Stash_<id>:
-- client
exports['qs-inventory']:RegisterStash('locker_' .. lockerId, 50, 100000, 'Locker')
-- server
exports['qs-inventory']:RegisterStash(source, 'locker_' .. lockerId, 50, 100000, 'Locker')The event form gives you full control over the id:
local stashId = 'locker_' .. lockerId
TriggerServerEvent('inventory:server:OpenInventory', 'stash', stashId, { maxweight = 100000, slots = 50 }, nil, 'Locker')
TriggerEvent('inventory:client:SetCurrentStash', stashId) -- so it saves and unlocks on closeFor a personal stash, include the player's identifier in the id. Items can be put in or taken out of a stash without opening it with AddItemIntoStash and RemoveItemIntoStash on the server. Jobs Creator (jaksam) stashes, safes and armories are mapped to qs-inventory stashes automatically.
Create shops on the server and open them for a player:
exports['qs-inventory']:CreateShop({
name = 'police_armory',
label = 'LSPD Armory',
coords = vec3(452.3, -980.0, 30.7), -- optional: player must be within 5 m
account = 'bank', -- 'money' (cash) or 'bank'
groups = { police = 0 }, -- optional: job and minimum grade
items = {
{ name = 'weapon_pistol', price = 500, amount = 10 },
{ name = 'pistol_ammo', price = 50, amount = 100 },
},
})
exports['qs-inventory']:OpenShop(source, 'police_armory')A client can open a registered shop with TriggerServerEvent('inventory:openShop', 'police_armory'). With Config.DisableShopGenerationOnClient = true, shops can only be built on the server like this, which stops modified clients from inventing their own prices. For ready-made shops on the map with stock and deliveries, use qs-shops — see Shops and Add-ons.
Open another player's inventory, limited to one section if you like:
-- client
TriggerServerEvent('inventory:server:OpenInventory', 'otherplayer', targetServerId, {
type = 'all', -- 'all', 'hotbar' or 'wallet'
})hotbar shows only the five quick slots, wallet only cards, IDs and cash, all everything. Items in Config.notStolenItems cannot be taken, and the protected slot is only visible to the jobs in Config.PoliceJobs while Config.PoliceCanSeeSixthSlot is on. Without a framework police script, /searchplayer and the inventory:client:search event search the nearest player with hands up.
QBCore and Qbox give starter items themselves. On ESX, list them in server/custom/framework/esx.lua:
StarterItems = {
['id_card'] = 1,
['water_bottle'] = 5,
['tosti'] = 5,
['phone'] = 1,
}Then trigger the inventory's event once the character has been created — in esx_identity/client/main.lua, inside the register NUI callback, after the success notification:
ESX.ShowNotification(TranslateCap('thank_you_for_registering'))
TriggerEvent('inventory:client:GiveStarterItems') -- starter itemsTrigger it only once per new character; the ID card and licences are filled with the character's data.
To make weapon_petrolcan lose fuel as it is used with LegacyFuel or a similar script, find this line in the fuel script's client:
SetPedAmmo(ped, 883325847, math.floor(GetAmmoInPedWeapon(ped, 883325847) - fuelToAdd * 100))and add this right below it:
TriggerEvent('inventory:client:LegacyFuel', math.floor(GetAmmoInPedWeapon(ped, 883325847) - fuelToAdd * 100))Resource | Integration |
|---|---|
qs-smartphone-pro | Hotbar keys are blocked while the phone is open, and phone items are cleaned up when removed. |
qs-vehiclekeys | Plate generation for the |
qs-banking | Credit card items call |
qs-weapondraw · qs-weaponsonback | Holster and draw events. |
jobs_creator (jaksam) | Stashes, safes, armories and player search use qs-inventory. |
jonska-itemthrowing | Alternative item throwing with |
evo-k9-v2 | K9 sniffing exports for player, trunk and glovebox inventories. |
um-idcard | ID cards and licences. |
ps-mdt | Registers weapons bought in shops. |
kq_placeable_items | External placement with |
qb-drugs · qb-shops · qb-methlab | Dealer and shop stock updates; lab keys. |
lb-phone | Item checks through the |
wasabi_ambulance | Dead state on ESX. |
Hooks let your resource react to what the inventory does, without editing it. Two are fired, and both are notifications — the return value is ignored:
Hook | Fires | Payload |
|---|---|---|
| After every successful shop purchase. |
|
| When an item is moved, stacked or swapped between any two inventories — player, stash, trunk, glovebox, drop, dumpster or another player. |
|
exports['qs-inventory']:registerHook('swapItems', function(p)
if p.toType == 'stash' then
print(('%s stored %sx %s'):format(p.source, p.count, p.fromSlot.name))
end
end)swapItems fires as the move is processed, before the final weight check, so treat it as "a move was attempted" when you log it.
Every move between inventories goes through the server: it checks the slots, the amounts, the weight, the items that cannot be stored and whether the player really has that second inventory open. Negative amounts are rejected and reported to the exploit webhook. Config.DisableShopGenerationOnClient = true makes shops server-only, and inv_busy locks the inventory while a progress bar or another action is running to prevent duplication.
Paste a webhook URL for each category you want in server/custom/webhook/webhook.lua:
Webhooks = {
['exploit'] = '', -- blocked exploit attempts
['admin'] = '', -- /giveitem, /giveweapon, the admin give panel
['bought'] = '', -- shop purchases
['sell'] = '', -- sales at sell points
['swap'] = '', -- swaps inside a player's inventory
['drop'] = '', -- ground drops
['stash'] = '',
['trunk'] = '',
['glovebox'] = '',
['garbage'] = '',
['robbery'] = '',
['giveitem'] = '', -- player to player
['crafting'] = '',
['traphouse'] = '',
}Run testwebhooks in the server console to send a test message to every configured channel.
The language is Config.Language, read from the qs:locale convar, so setr qs:locale "es" in server.cfg switches every Quasar resource at once. Translations are JSON files in locales/, and any key missing from a translation falls back to English. To add one, copy en.json to a new code, translate the values and set that code as the language.
metadatacountGetInventoryItemsInventoryCustomDrop