Prueba ya Smartphone V3Consíguelo Black Friday empieza enBlack Friday · 25% de descuento en toda la tienda · Tiempo limitadoComprar ahora

QUASARSTORE

[49.5] Inventory

Comandos yexports

Comandos, exports, eventos y state bags de qs-inventory para desarrolladores de FiveM: AddItem, RemoveItem, HasItem, CanCarryItem, almacenes y maleteros.

Sección: 49.5
Leer: 8 min
Actualizado: 11 nov

■ 8 min read · Actualizado 11 nov 2026

Comandos#

Los comandos de jugador son asignaciones de teclas de FiveM, así que cada jugador puede cambiar sus teclas en ESC → Settings → Key Bindings → FiveM. Los comandos de administración comprueban los grupos de administradores del framework; los dos paneles también aceptan su ace.

Comando	Quién	Descripción
`/inventory`	Todos	Abre el inventario, o la guantera, el maletero, el botín, el contenedor de basura o la máquina expendedora que tengas al lado. `TAB` por defecto.
`/hotbar` · `+quickwheel`	Todos	Muestra la hotbar, o abre la rueda rápida mientras se mantiene pulsado, según la elección del jugador. `Z` por defecto.
`slot1` – `slot6`	Todos	Usan las ranuras rápidas 1–5 y la ranura protegida. Teclas `1`–`6`.
`/reloadweapon`	Todos	Recarga el arma en la mano con munición del inventario. `R` por defecto.
`/handsup`	Todos	Levanta o baja las manos, mientras Hands up está activado. `X` por defecto.
`inventory:throw`	Todos	Lanza el arma en la mano. `H` por defecto; se puede dejar sin tecla.
`/searchplayer`	Todos	Registra al jugador más cercano con las manos arriba, o muerto cuando se permite saquear a jugadores muertos.
`/inventoryconfig`	Admin	Abre el panel de configuración. Ace `command.inventoryconfig`.
`/inventorycreator`	Admin	Abre el creador. Ace `command.inventorycreator`.
`/giveitem <id> <item> [amount]`	Admin	Da un ítem, con sus metadatos rellenados (DNI, licencias, bolsas, matrículas).
`/giveweapon <id> <weapon> [ammo]`	Admin	Da un arma con número de serie y la munición cargada.
`/openinventorytarget <id>`	Admin	Abre el inventario de otro jugador, desde cualquier lugar.
`/clearinv [id]`	Admin	Vacía el inventario de un jugador — el tuyo si no indicas id.
`/resetinv <stash\|trunk\|glovebox> <id>`	Admin	Libera un stash, maletero o guantera bloqueado como "in use".
`/inventoryextraweight <id> [kg]`	Admin	Da a un personaje peso de carga extra, guardado para ese personaje. Sin kg muestra el valor actual; 0 lo elimina.
`/repairweapon <amount>`	Admin	Fija el estado del arma que tienes en las manos. También necesita el ace `command.repairweapon`.
`/randomitems`	Admin	Te da diez ítems aleatorios, para pruebas.
`testwebhooks`	Consola	Envía un mensaje de prueba a cada webhook de Discord configurado e indica cuáles funcionaron.

Las teclas por defecto se configuran en Settings → Key binds, y los nombres de los comandos de los dos paneles en Settings → Access & commands. <id> es el id de servidor del jugador.

Con Debug mode activado (Settings → General, avanzado), se registran comandos de prueba adicionales para administradores — inventory:openStash, inventory:search, inventory:openOther y tres comandos de stash — y la consola se llena de logs. Desactívalo en un servidor en producción.

Exports de cliente#

Se llaman como exports['qs-inventory']:Name(...) desde un script de cliente.

Comprobar ítems

lua

-- 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()

El inventario del jugador también está en el state bag LocalPlayer.state.inventory.

Abrir un stash

lua

-- Opens Stash_<id> right away: id, slots, max weight in grams, label
exports['qs-inventory']:RegisterStash('house_' .. houseId, 50, 200000, 'House storage')

Estado del inventario

lua

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)

Armas

lua

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()

Ropa

lua

-- 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()

Metadatos del jugador

lua

-- What the server stored with SetMetaData for this player (call it from a thread)
local meta = exports['qs-inventory']:GetMetaData()

Exports de servidor#

Se llaman como exports['qs-inventory']:Name(...) desde un script de servidor. Los nombres de ítems van en minúsculas; los pesos, en gramos.

Añadir y quitar ítems

lua

-- 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 comprueba el peso, las ranuras libres y los límites de carga, da a cada arma un número de serie y a cada ítem un estado de 100, y muestra la notificación del ítem. Cada añadido correcto se registra en la pestaña Stats del creador con el nombre del resource que lo llamó.

Comprobar ítems

lua

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')

Cada ítem lleva sus metadatos en info: info.quality es su estado (0–100), y un arma tiene info.serie y info.ammo.

Metadatos y estado

lua

-- 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)

Ítems utilizables

lua

exports['qs-inventory']:CreateUsableItem('lockpick', function(source, item)
    -- item.slot, item.info...
    TriggerClientEvent('my-heist:useLockpick', source)
end)

En QBCore y Qbox, esto también registra el ítem en el framework. Los ítems con un bloque client en su definición ejecutan primero su animación y barra de progreso.

Inventarios completos

lua

-- 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)

Peso de carga

lua

-- Extra carry weight in grams, on top of Settings → Capacity. Saved per character.
-- The target is a server id or a character identifier.
exports['qs-inventory']:SetPlayerExtraWeight(source, 20000)          -- true, 20000
exports['qs-inventory']:AddPlayerExtraWeight(source, 5000)           -- a negative amount takes away

local extra = exports['qs-inventory']:GetPlayerExtraWeight(source)  -- grams
local max = exports['qs-inventory']:GetPlayerMaxWeight(source)      -- base + extra, in grams

0 elimina el peso extra. SetPlayerExtraWeight y AddPlayerExtraWeight devuelven true y el nuevo total, o false cuando no se encuentra al jugador. Los administradores hacen lo mismo con /inventoryextraweight.

Stashes

lua

-- 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')

Los stashes creados en el creador usan el id creator_<record id>; GetCreatorRecords('stash') los lista.

Maleteros y guanteras

lua

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)

Tiendas

lua

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 refused

-- Paid by the society of the buyer's job
exports['qs-inventory']:CreateShop({
    name = 'mechanic_parts',
    label = 'Mechanic Parts',
    coords = vector3(-347.2, -133.5, 39.0),
    account = 'society',
    society = 'mechanic',  -- or jobs = { { name = 'mechanic', grade = 0 } }
    items = {
        { name = 'repairkit', price = 250, amount = 1 },
    },
})

OpenShop rechaza a un jugador a más de 5 m de las coordenadas de la tienda. Un groups = { police = 0 } opcional limita una tienda a ciertos trabajos.

Con account = 'society', el dinero sale de la cuenta de society del trabajo del comprador, y solo los miembros del trabajo de la tienda pueden comprar: society (un trabajo), jobs (varios, cada uno con un rango mínimo) o groups. Una tienda de society sin trabajo configurado no la puede usar nadie.

Armas, números de serie y matrículas

lua

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()

Registros del creador

lua

-- Everything made in /inventorycreator, or one kind:
-- 'stash', 'shop', 'seller', 'crafting', 'item', 'weapon'
local shops = exports['qs-inventory']:GetCreatorRecords('shop')

Hooks

lua

exports['qs-inventory']:registerHook('buyItem', function(payload)
    -- payload.source, payload.itemName, payload.amount, payload.metadata
end)

exports['qs-inventory']:unregisterHook('buyItem')

Consulta Integraciones para ambos hooks y sus payloads.

Eventos#

Eventos que puedes escuchar#

Evento	Lado	Argumentos	Cuándo
`inventory:usedItem`	Servidor	itemName, source, item	Se usa cualquier ítem.
`esx:onAddInventoryItem · esx:onRemoveInventoryItem`	Servidor	source, item, amount	Se añade o quita un ítem.
`qb-inventory:server:itemAdded · itemRemoved`	Servidor	source, item, amount, amountInSlot	Se añade o quita un ítem.
`qs-inventory:admin:settingsApplied`	Ambos	—	Se cambió la configuración en /inventoryconfig.
`ox_inventory:updateInventory`	Cliente	—	Cambió el inventario del jugador.
`inventory:setFocus`	Cliente	focused	El inventario toma o libera el ratón.
`weapons:client:DrawWeapon`	Cliente	weaponName	Se desenfunda un arma.

Eventos que puedes disparar#

Evento	Lado	Argumentos	Función
`inventory:server:OpenInventory`	Servidor	type, id, other?, model?, label?	Abre un `stash`, `trunk`, `glovebox`, `shop`, `selling`, `crafting` o `otherplayer` junto al inventario del jugador. `other` contiene `maxweight` y `slots`, o `label` y `items`; un maletero lo necesita.
`inventory:openShop`	Servidor	shopName	Abre una tienda registrada con `CreateShop`.
`inventory:client:SetCurrentStash`	Cliente	stashId	Indica al inventario qué stash se acaba de abrir.
`inventory:client:forceCloseInventory`	Cliente	—	Cierra el inventario y guarda lo que estaba abierto.
`inventory:client:requiredItems`	Cliente	items, show	Muestra u oculta las casillas "Required" en la parte inferior de la pantalla. `items` es una lista de `{ name, image }`.
`qs-inventory:client:ItemBox`	Cliente	item, 'add' \| 'remove' \| 'use'	Muestra una notificación de ítem.
`inventory:client:GiveStarterItems`	Cliente	—	Da los ítems iniciales de ESX una sola vez.
`inventory:client:LegacyFuel`	Cliente	fuel	Actualiza el bidón de gasolina en la mano.

State bags#

Player(source).state.inventory — LocalPlayer.state.inventory en el cliente — contiene todo el inventario del jugador y se actualiza con cada cambio. inv_busy es true mientras el jugador está ocupado usando un ítem; mientras tanto, el inventario no se abre.

Sobre los errores#

Los exports devuelven false o nil cuando se niegan, e imprimen el motivo en la consola cuando es útil. AddItem devuelve true solo cuando el ítem se ha añadido realmente, así que compara con == true; a un jugador con demasiado peso o por encima de un límite de carga se le avisa en el juego. Antes de quitar aquello con lo que paga un jugador, comprueba HasItem o GetItemTotalAmount primero.

[··] Documentación

Cargandola guía