FiveM Inventory & Weapons — Quasar Framework (qs-core) | Quasar Store | Quasar Store
Documentation
Inventory, Items & Weapons
FiveM inventory for ESX and QBCore: slots, weight, item wheel, trunks, stashes, shops, hunger and thirst, and all 105 GTA weapons as items in Quasar Framework.
Quasar Framework (qs-core) ships a complete FiveM inventory out of the box: a slot and weight inventory with quick slots and an item wheel, vehicle trunks, gloveboxes and stashes, shops, hunger and thirst, and every GTA weapon as an inventory item. It is the same inventory for every script on your server — an ESX script that calls xPlayer.addInventoryItem, a QBCore script that calls Player.Functions.AddItem and a Quasar Framework script that calls exports['qs-core']:AddItem all put the item in the same slot of the same player.
This page covers four resources of the [core] folder, all installed by the txAdmin recipe:
Resource
What it does
qs-coreinventory
The inventory itself: slots, weight, stacks, the item wheel, quick slots, trunks, gloveboxes and stashes.
qs-coreweapons
Turns all 105 GTA weapons and their ammo into items and removes GTA's free weapons and cash.
Press F1 to open your inventory and F1 again (or Esc) to close it. The inventory does not freeze you: you can keep walking, sprinting, jumping and driving while it is open, which makes looting a trunk or sorting items on the move feel natural.
Action
Default key
Notes
Open / close the inventory
F1
Key mapping Toggle inventory, command inventory.
Close
Esc
Opening the pause menu also closes it.
Use slots 1–5
1 – 5
Key mappings Use inventory slot 1…5.
Item wheel
TAB (hold)
Key mapping Item wheel. See below.
Players can rebind all of these in Settings → Key Bindings → FiveM. As the server owner you set the defaults in qs-coreinventory/shared/config.lua (Config.OpenKey, Config.RadialKey); players who already saved their own binding keep it.
The header of the inventory shows how many slots are in use (for example 12/30 slots) and your carried weight against the limit (for example 8.4 / 50 kg).
Every character has 30 slots and can carry 50 kg. Weights are stored in grams.
Option
Default
What it does
Config.Slots
30
Slots in the player inventory.
Config.Columns
5
Columns of the player grid.
Config.MaxWeight
50000
Carry limit in grams (50 kg).
Config.DefaultStack
64
How many of one item fit in one slot, unless the item sets its own stack.
How many of an item fit in one slot:
Weapons and items marked unique take one slot each.
Throwables (grenades, molotovs…) stack up to 10.
An item with its own stack value uses it.
Everything else stacks up to Config.DefaultStack (64).
Two copies of an item only stack if their metadata (info) is identical — a script that gives a serial number or a quality value to an item keeps those copies in separate slots.
If something would push you over the weight limit you get Too heavy to carry … and nothing is added; if there is no room left in the slots you get Inventory full.
Drag an item with the left mouse button onto another slot.
Moves it to an empty slot, stacks it onto the same item, or swaps the two items. Works between your inventory and an open trunk, glovebox or stash.
Use
Double-click a usable item, or right-click → Use.
Eats, drinks, equips a weapon, loads ammo… whatever the item does.
Split
Right-click a stack, choose the amount, then Split.
Moves that amount to the first empty slot of the same container. You can split off at most one less than the whole stack.
Give
Right-click, choose the amount, then Give.
Gives it to the nearest player within 3.5 m. They must be able to carry it; otherwise you see They can't carry that and keep the item. Both players get a notification.
Drop
Right-click, choose the amount, then Drop.
Destroys that amount. There are no ground drops.
Take
Double-click an item in a trunk, glovebox or stash, or right-click → Take.
Moves it into your inventory (whole stack, or the amount you chose).
The right-click menu has an amount selector (−, +, type a number, or click the total to take everything) whenever the stack holds more than one item.
Moving items into a trunk, glovebox or stash checks its weight limit. When only part of a stack fits, the part that fits is moved and the rest stays with you.
Every slot shows its slot number, the item's picture, the amount and the item's label (the readable name, such as Water Bottle for water). Labels come from the item catalogue, not from the language files — to rename an item, change its label (see Adding a new item below).
Every time an item is added to or removed from your inventory — a purchase, a gift, eating, a script giving you a reward — a short item box notification shows the item, the amount and whether it was added or removed.
Keys 1 to 5 use whatever sits in slots 1 to 5 of your inventory, without opening it. Put your weapons, food and bandages there and you can draw a pistol or eat a sandwich in one key press.
GTA's own weapon-slot switching on those keys is blocked for a moment every time you press them, so the game never switches weapons behind your back.
The item wheel replaces GTA's weapon wheel. Holding TAB never opens the native weapon wheel on a Quasar Framework server; it opens a wheel built from your inventory instead.
HoldTAB. The wheel opens around the centre of the screen with your first five slots, numbered 1 to 5.
Aim with the mouse towards an item. The highlighted item's name and amount appear in the centre (the centre itself is a dead zone, so nothing is selected until you move out of it).
ReleaseTAB to use the highlighted item — draw that weapon, eat that burger.
Or click a segment to use it straight away. Esc closes the wheel without using anything.
Empty slots show Empty and items that cannot be used show Not usable; selecting them does nothing. While the wheel is open you cannot aim, shoot or switch weapons, and it closes by itself a second after you release TAB if nothing was picked. It will not open while the inventory is open, while the pause menu or another menu is on screen, or while you are dead.
Option
Default
What it does
Config.RadialKey
'TAB'
Default key of the Item wheel key mapping.
Config.RadialSlots
5
How many inventory slots (from slot 1) the wheel shows. The quick-slot keys are always 1 to 5.
When you are downed the inventory and the item wheel close and cannot be opened, and quick slots do nothing until you are revived. Items cannot be used while a progress bar is running (for example while you are eating), and the server accepts at most 10 uses every 3 seconds per player.
You must be on foot — from inside a vehicle F1 opens the glovebox instead.
Stand at the back of the vehicle: within Config.TrunkReach (1.8 m) of a point just behind its rear bumper.
The vehicle must be unlocked and you must have its keys (from qs-corevehiclekeys). Otherwise you see The vehicle is locked or you have no keys.
When the trunk opens, the boot lid opens on the car. Close the inventory and the lid shuts. Walk more than Config.TrunkCloseDistance (5 m) away, or let the car drive off, and the trunk closes with Trunk closed — too far from the vehicle.
Open your inventory while sitting in any seat of a vehicle you have keys for and the glovebox opens next to it. Leave the vehicle and it closes with Glovebox closed — you left the vehicle.
Option
Default
What it does
Config.TrunkSlots
10
Trunk slots.
Config.TrunkColumns
5
Trunk grid columns.
Config.TrunkMaxWeight
100000
Trunk weight limit in grams.
Config.TrunkReach
1.8
Distance in metres from the rear of the vehicle at which F1 opens the trunk.
Config.TrunkCloseDistance
5.0
The trunk closes past this distance in metres. Also the fallback closing radius of a stash zone.
Config.GloveboxSlots
5
Glovebox slots.
Config.GloveboxColumns
5
Glovebox grid columns.
Config.GloveboxMaxWeight
15000
Glovebox weight limit in grams.
If qs-corevehiclekeys is not running, the keys check is skipped and only the lock state matters for trunks.
A stash is a named storage box — a gang locker, a house safe, a police evidence locker. It has two parts:
The definition (server): an id, a label, slots, maximum weight and columns. Register it in Config.Stashes or with the RegisterStash export.
The place (client): a stash zone — coordinates and a radius. Open your inventory inside the radius and the stash opens next to it; walk out and it closes. A script can also open a stash directly with the OpenStash client export (from a target menu, an item, a command…).
The id is what identifies the contents: two zones with the same id open the same stash, and the contents are saved in the database under that id.
Quasar Framework ships one stash ready to use: the police Evidence Locker (police_evidence, 50 slots, 200 kg) at the police station, registered by qs-police and opened only by police officers.
Define the stash
In qs-coreinventory/shared/config.lua, add it to Config.Stashes:
Saved instantly. Every change to a trunk, glovebox or stash is written to the database (trunk_inventories, glovebox_inventories, stash_inventories) and survives restarts.
Trunks and gloveboxes belong to the plate. The contents follow the plate text, so a vehicle with the same plate always has the same trunk and glovebox.
One container at a time. You see your inventory plus one trunk, glovebox or stash.
Weight limits apply to everything you move in, as described above.
Weapons leave your hands. Put your equipped weapon in a trunk or stash and it is removed from your character.
These items come with qs-core (qs-core/shared/items.lua). Other resources add their own: food and drinks from qs-needs, every weapon and ammo type from qs-coreweapons, and medical items from qs-ambulance.
Item
Label
Weight
Usable
What it does
water
Water Bottle
500 g
Yes
Drink: +30 thirst (qs-needs).
bread
Bread
300 g
Yes
Eat: +25 hunger (qs-needs).
bandage
Bandage
100 g
Yes
With qs-ambulance: stops one level of bleeding and restores 25 HP. Without it: restores 20 HP.
phone
Phone
190 g
Yes
Starting item, ready for a phone resource. On its own it only shows a notice when used.
id_card
ID Card
10 g
No
Starting item.
weapon_pistol
Pistol
1,000 g
Yes
Equips a pistol. qs-coreweapons replaces this definition with its own (see Weapons below).
lockpick
Lockpick
100 g
Yes
Needed to hotwire a vehicle you have no keys for (qs-corevehiclekeys); one breaks when the hotwire fails.
repairkit
Repair Kit
2,500 g
Yes
Sold at hardware stores. No built-in effect: give it one with RegisterUsableItem.
screwdriver
Screwdriver
200 g
Yes
Sold at hardware stores. No built-in effect: give it one with RegisterUsableItem.
Register items from a server script that starts after qs-core. The inventory, the shops and the ESX and QBCore bridges all read the same catalogue, so an item registered once is available everywhere. Registering a name that already exists replaces its definition.
lua
-- server side, in any resource that starts after qs-core
exports['qs-core']:RegisterItems({
pizza = { label = 'Pizza', weight = 500, useable = true, description = 'A hot slice.' },
gold_bar = { label = 'Gold Bar', weight = 1000, stack = 10 },
rare_watch = { label = 'Rare Watch', weight = 150, unique = true },
})
For a single item: exports['qs-core']:RegisterItem('pizza', { label = 'Pizza', weight = 500, useable = true }). You can also add items to the base list in qs-core/shared/items.lua.
Add them to BridgeItems in es_extended/config/items.lua. They are registered in Quasar Framework when es_extended starts (only if an item with that name does not exist yet):
useable = true only allows the item to be used; the effect comes from a script. Register a handler on the server — it works with qs-coreinventory and with qs-inventory:
lua
exports['qs-core']:RegisterUsableItem('pizza', function(source, slot, info)local player = exports['qs-core']:GetPlayer(source)
if player and player:removeItem('pizza', 1, slot) then
TriggerClientEvent('qs:client:notify', source, 'That hit the spot.', 'success')
endend)
The inventory does not remove the item for you: remove it in the handler if it is consumed.
One handler per item: registering it again replaces the previous one.
Every use of a non-weapon item also fires the server event qs:server:usedItem(source, itemName, slot, info), which you can listen to instead of registering a handler.
Items with a weapon field are always equipped; handlers and events are not fired for them.
Test it with /giveitem <id> pizza 5 (admin). ESX scripts that use ESX.RegisterUsableItem and QBCore scripts that use QBCore.Functions.CreateUseableItem keep working through the bridges — see ESX & QBCore Compatibility.
Driving the inventory from your own scripts?AddItem, RemoveItem, HasItem, CanCarryItem, GetItemCount, GetSlotView, GetItemBySlot, SetItemInfo and the client exports are listed in Commands and Exports.
qs-coreshops adds the stores of a FiveM roleplay city: 24/7 supermarkets, LTD gas stations, Rob's Liquor, hardware stores, Ammunation and a medical supply point for EMS. Each location has a shopkeeper and a map blip.
Walk up to a shopkeeper. Within 2.2 m you see Press E to browse …; press E and the shop opens with your cash balance. Pick an item and an amount (up to 100 per purchase) and buy it. The HUD hides while the shop is open and comes back when you close it.
Every purchase is checked on the server, so modified clients cannot buy cheaper or from across the map:
Check
Message if it fails
The shop exists and sells that item. The price is read from the server config, never from the client.
—
You have the right job (job shops).
You are not allowed here. (when opening)
You are within 5 m of one of the shop's locations.
—
You can carry the amount (weight and slots).
You can't carry that much
You have enough money in the pay account (cash by default).
Not enough money
The money is taken first and the item given after; if the item cannot be added, the money is refunded automatically. Purchases appear in money logs with the reason shop:<name> (and shop-refund:<name> for refunds).
Give a shop a job and only players with that job see its blip, get the prompt and can buy there. The Medical Supplies point is an example (job = 'ambulance'). Ammunation ships with the line -- job = 'police' commented out: remove the -- to turn it into a police-only armory shop.
Every product must be registered in the item catalogue (base items, qs-needs, qs-coreweapons, or your own RegisterItems). Products whose item does not exist are hidden from the shop.
Add a product to an existing shop
Add a line to the list in Config.Products. For example, to sell crowbars at hardware stores:
lua
hardware = {
{ name = 'lockpick', price = 35 },
{ name = 'screwdriver', price = 20 },
{ name = 'repairkit', price = 250 },
{ name = 'weapon_crowbar', price = 60 },
},
Prices are whole dollars and must be at least 1.
Or create a new shop
Get the position and heading with /coords (admin) where the shopkeeper should stand, then add this at the end of qs-coreshops/config.lua:
lua
Config.Products.cafe = {
{ name = 'coffee', price = 4 },
{ name = 'sandwich', price = 9 },
}
Config.Shops[#Config.Shops + 1] = {
name = 'cafe',
label = 'Coffee Shop',
ped = 'mp_m_shopkeep_01',
scenario = 'WORLD_HUMAN_STAND_MOBILE',
blip = { sprite = 52, color = 2, scale = 0.6 },
-- job = 'police', -- uncomment to make it a job shop
items = Config.Products.cafe,
locations = {
vec4(0.0, 0.0, 0.0, 0.0), -- paste the vec4 printed by /coords
},
}
Restart the shops
Run restart qs-coreshops in the server console (or txAdmin). Shops are read from the config on start; there is no export to add them at runtime.
qs-needs gives every character hunger and thirst from 0 to 100, shown as bars on the HUD (see Chat, HUD & Roleplay). New characters start at 100 and the values are saved with the character.
Use a food or drink item (from the inventory, the item wheel or a quick slot). One item is consumed, your character plays an eating or drinking animation with the item in hand while a progress bar shows Eating or Drinking, and the values go up (never above 100). You get You ate the Burger. or You drank the Water Bottle. You cannot use another item until the animation ends.
Item
Label
Hunger
Thirst
Type
Added by
water
Water Bottle
—
+30
Drink
qs-core
bread
Bread
+25
—
Food
qs-core
burger
Burger
+45
—
Food
qs-needs
sandwich
Sandwich
+30
—
Food
qs-needs
cola
Cola
+5
+25
Drink
qs-needs
coffee
Coffee
—
+15
Drink
qs-needs
energy_drink
Energy Drink
—
+35
Drink
qs-needs
All of them are sold in 24/7 Supermarkets and LTD Gasoline, and the drinks also at Rob's Liquor.
verb = 'drink' plays the drinking animation; anything else plays the eating one.
Sell it and restart
Add it to a shop list (see Adding a shop or a product above) and restart qs-needs and the resource that registers the item.
Changing needs from your own scripts? Set them through the character's metadata, from 0 to 100: exports['qs-core']:SetMetadata(source, 'hunger', 100). The HUD updates at once, and QBCore scripts read the same values in PlayerData.metadata.hunger and thirst.
qs-coreweapons makes every GTA weapon an inventory item — 105 of them — plus 9 ammo types. Weapons are carried, traded, stored and sold like any other item: they weigh something, take one slot each, can be given to another player, locked in a trunk or bought at Ammunation. There is no hidden loadout.
Weapons have no commands, keys or exports of their own: you equip them by using the item — from the inventory, the item wheel (TAB) or a quick slot (1–5).
Use an ammo item to load it. It goes into the weapon in your hands if it takes that ammo, otherwise into the first weapon you carry that does. You see Loaded +30 rounds and one ammo item is consumed. If you have no weapon for it you see You have no weapon that takes this ammo and nothing is consumed.
Item
Label
For
Rounds per item
Weight
ammo_pistol
Pistol Ammo
Pistols
12
200 g
ammo_smg
SMG Ammo
SMGs
30
300 g
ammo_rifle
Rifle Ammo
Rifles
30
400 g
ammo_shotgun
Shotgun Shells
Shotguns
8
300 g
ammo_sniper
Sniper Ammo
Snipers
10
500 g
ammo_mg
MG Ammo
Machine guns, Minigun, Widowmaker
100
700 g
ammo_launcher
Launcher Round
Launchers
1
1,500 g
ammo_flare
Flare Shell
Flare Gun
1
100 g
ammo_taser
Taser Cartridge
Taser
1
50 g
Ammo items stack like normal items (64 per slot). Melee weapons, throwables and equipment have no ammo item.
A weapon leaves your hands when its item leaves your inventory#
The weapon in your hands is the item in your inventory. Drop it, give it away, sell it, or move it into a trunk, glovebox or stash, and the weapon is removed from your character at once. For throwables, the number you can throw always matches the number of items you carry.
Weapons are items, so scripts that give weapon items work as expected: xPlayer.addInventoryItem('weapon_pistol', 1) in ESX, Player.Functions.AddItem('weapon_pistol', 1) in QBCore, or exports['qs-core']:AddItem(source, 'weapon_pistol', 1).
cat decides the ammo it uses and how many rounds it comes with (melee, pistol, smg, shotgun, rifle, mg, sniper, launcher, flare, taser, throwable, misc). Add ammo = n to set the rounds yourself.
Add a new ammo type (optional)
For a new category, give it a magazine size and an ammo item with the same cat:
Stand on foot at the back of the vehicle (within 1.8 m), make sure it is unlocked and that you have its keys. If you are sitting inside, F1 opens the glovebox instead.
Where did the item I dropped go?
Dropping deletes the item; there are no ground drops. Use Give to hand items to another player, or store them in a trunk, glovebox or stash.
An item is missing from a shop.
Shops hide products whose item is not registered. Register the item (or start the resource that registers it, for example qs-ambulance for icepack and burn_cream) and restart qs-coreshops.
Pressing TAB does not open GTA's weapon wheel.
That is intended: on Quasar Framework TAB opens the item wheel, built from your first five slots. Put your weapons there.
How do I change the inventory size or weight limit?
Edit Config.Slots and Config.MaxWeight in qs-coreinventory/shared/config.lua and restart the resource.
Can I use Quasar Store's qs-inventory instead?
Yes. Run qs-inventory instead of qs-coreinventory and Quasar Framework routes every item, shop and weapon through it. See Integrations.
Does it work with ESX and QBCore inventory functions?
Yes. xPlayer.addInventoryItem, xPlayer.getInventoryItem, Player.Functions.AddItem, Player.Functions.RemoveItem and the rest go to the same inventory. Scripts that call qb-inventory or ox_inventory exports directly are not covered — see ESX & QBCore Compatibility.
