Inventario, ítems yarmas

Quasar Framework (qs-core) incluye un inventario FiveM completo listo para usar: un inventario por slots y peso con slots rápidos y una rueda de ítems, maleteros de vehículos, guanteras y alijos, tiendas, hambre y sed, y todas las armas de GTA como ítems del inventario. Es el mismo inventario para todos los scripts de tu servidor: un script de ESX que llama a xPlayer.addInventoryItem, un script de QBCore que llama a Player.Functions.AddItem y un script de Quasar Framework que llama a exports['qs-core']:AddItem ponen el ítem en el mismo slot del mismo jugador.

Esta página cubre cuatro recursos de la carpeta [core], todos instalados por la receta de txAdmin:

El catálogo de ítems (la etiqueta, el peso y el comportamiento de cada ítem) vive en qs-core, así que los scripts de ESX y QBCore leen los mismos ítems.

El inventario#

Abrir y cerrar#

Pulsa F1 para abrir tu inventario y F1 otra vez (o Esc) para cerrarlo. El inventario no te congela: puedes seguir caminando, corriendo, saltando y conduciendo mientras está abierto, lo que hace que saquear un maletero u ordenar ítems en movimiento se sienta natural.

Los jugadores pueden reasignar todas estas teclas en Settings → Key Bindings → FiveM. Como dueño del servidor, tú defines las predeterminadas en qs-coreinventory/shared/config.lua (Config.OpenKey, Config.RadialKey); los jugadores que ya guardaron su propia asignación la conservan.

El encabezado del inventario muestra cuántos slots están en uso (por ejemplo 12/30 slots) y el peso que llevas frente al límite (por ejemplo 8.4 / 50 kg).

Slots, peso y stacks#

Cada personaje tiene 30 slots y puede cargar 50 kg. Los pesos se guardan en gramos.

Cuántas unidades de un ítem caben en un slot:

• Las armas y los ítems marcados como unique ocupan un slot cada uno.

• Los arrojables (granadas, molotovs…) se apilan hasta 10.

• Un ítem con su propio valor stack lo usa.

• Todo lo demás se apila hasta Config.DefaultStack (64).

• Dos copias de un ítem solo se apilan si sus metadatos (info) son idénticos: un script que da un número de serie o un valor de calidad a un ítem mantiene esas copias en slots separados.

Si algo te haría superar el límite de peso, recibes Too heavy to carry … y no se agrega nada; si no queda espacio en los slots, recibes Inventory full.

Mover, dividir, dar, tirar y usar#

El menú del clic derecho tiene un selector de cantidad (−, +, escribe un número o haz clic en el total para tomarlo todo) siempre que el stack tenga más de un ítem.

Mover ítems a un maletero, guantera o alijo comprueba su límite de peso. Cuando solo cabe una parte de un stack, se mueve la parte que cabe y el resto se queda contigo.

Etiquetas de ítems y la caja de ítems#

Cada slot muestra su número, la imagen del ítem, la cantidad y la etiqueta del ítem (el nombre legible, como Water Bottle para water). Las etiquetas vienen del catálogo de ítems, no de los archivos de idioma: para renombrar un ítem, cambia su label (consulta Agregar un ítem nuevo más abajo).

Cada vez que se agrega o se quita un ítem de tu inventario (una compra, un regalo, comer, un script que te da una recompensa), una breve notificación de la caja de ítems muestra el ítem, la cantidad y si se agregó o se quitó.

Slots rápidos 1–5#

Las teclas 1 a 5 usan lo que haya en los slots 1 a 5 de tu inventario, sin abrirlo. Pon ahí tus armas, comida y vendas y podrás sacar una pistola o comerte un sándwich con una sola tecla.

El cambio de slot de arma propio de GTA en esas teclas se bloquea un momento cada vez que las pulsas, así que el juego nunca cambia de arma a tus espaldas.

La rueda de ítems (TAB)#

La rueda de ítems reemplaza la rueda de armas de GTA. Mantener TAB nunca abre la rueda de armas nativa en un servidor con Quasar Framework; en su lugar abre una rueda construida a partir de tu inventario.

1. Mantén TAB. La rueda se abre alrededor del centro de la pantalla con tus primeros cinco slots, numerados del 1 al 5.

2. Apunta con el mouse hacia un ítem. El nombre y la cantidad del ítem resaltado aparecen en el centro (el centro en sí es una zona muerta, así que no se selecciona nada hasta que sales de ella).

3. Suelta TAB para usar el ítem resaltado: sacar esa arma, comerte esa hamburguesa.

4. O haz clic en un segmento para usarlo de inmediato. Esc cierra la rueda sin usar nada.

Los slots vacíos muestran Empty y los ítems que no se pueden usar muestran Not usable; seleccionarlos no hace nada. Mientras la rueda está abierta no puedes apuntar, disparar ni cambiar de arma, y se cierra sola un segundo después de soltar TAB si no se eligió nada. No se abre mientras el inventario está abierto, mientras el menú de pausa u otro menú está en pantalla, ni mientras estás muerto.

Muerto u ocupado#

Cuando estás derribado, el inventario y la rueda de ítems se cierran y no se pueden abrir, y los slots rápidos no hacen nada hasta que te reaniman. No se pueden usar ítems mientras corre una barra de progreso (por ejemplo, mientras comes), y el servidor acepta como máximo 10 usos cada 3 segundos por jugador.

Ítems iniciales#

Los personajes nuevos reciben Config.StartingItems la primera vez que cargan:

Config.StartingItems = {
    { name = 'water',   count = 2 },
    { name = 'bread',   count = 2 },
    { name = 'phone',   count = 1 },
    { name = 'id_card', count = 1 },
}

Contenedores: maleteros, guanteras y alijos#

Los contenedores se abren con la tecla del inventario, lado a lado con tu propio inventario. Cuando pulsas F1, Quasar Framework elige el contenedor por ti:

1. Sentado en un vehículo → su guantera.

2. A pie, de pie en la parte trasera de un vehículo → su maletero.

3. A pie, dentro de una zona de alijo → ese alijo.

4. En otro caso → solo tu inventario.

Maletero del vehículo#

Para abrir un maletero:

• Debes estar a pie — desde dentro de un vehículo, F1 abre la guantera.

• Colócate en la parte trasera del vehículo: a menos de Config.TrunkReach (1.8 m) de un punto justo detrás de su parachoques trasero.

• El vehículo debe estar sin seguro y debes tener sus llaves (de qs-corevehiclekeys). Si no, ves The vehicle is locked or you have no keys.

Cuando se abre el maletero, la tapa del maletero se abre en el auto. Cierra el inventario y la tapa se cierra. Aléjate más de Config.TrunkCloseDistance (5 m), o deja que el auto se vaya, y el maletero se cierra con Trunk closed — too far from the vehicle.

Guantera#

Abre tu inventario sentado en cualquier asiento de un vehículo del que tienes llaves y la guantera se abre a su lado. Sal del vehículo y se cierra con Glovebox closed — you left the vehicle.

Si qs-corevehiclekeys no está en ejecución, se omite la comprobación de llaves y para los maleteros solo importa si el vehículo tiene seguro.

Alijos#

Un alijo es una caja de almacenamiento con nombre: un casillero de pandilla, una caja fuerte de una casa, un casillero de evidencias de la policía. Tiene dos partes:

1. La definición (servidor): un id, una etiqueta, slots, peso máximo y columnas. Regístralo en Config.Stashes o con el export RegisterStash.

2. El lugar (cliente): una zona de alijo — con coordenadas y un radio. Abre tu inventario dentro del radio y el alijo se abre a su lado; sal y se cierra. Un script también puede abrir un alijo directamente con el export de cliente OpenStash (desde un menú de target, un ítem, un comando…).

El id es lo que identifica el contenido: dos zonas con el mismo id abren el mismo alijo, y el contenido se guarda en la base de datos bajo ese id.

Quasar Framework incluye un alijo policial listo para usar: el Evidence Locker (police_evidence, 50 slots, 200 kg) en la comisaría, registrado por qs-police y que solo pueden abrir los policías.

1. Define el alijo

   En qs-coreinventory/shared/config.lua, agrégalo a Config.Stashes:

   Config.Stashes = {
       { id = 'town_locker', label = 'Town Locker', slots = 50, maxWeight = 200000, columns = 5 },
   }

   O desde cualquier script de servidor:

   exports['qs-core']:RegisterStash('town_locker', 'Town Locker', 50, 200000, 5)

   Lo que omitas usa los valores predeterminados: etiqueta Stash, 50 slots, 100000 g, 5 columnas.

2. Colócalo en el mundo

   Desde un script de cliente de tu propio recurso, registra una zona con el mismo id. Párate en el lugar y usa /coords para obtener la posición.

   exports['qs-core']:RegisterStashZone('town_locker', vec3(-268.48, -957.71, 31.22), { radius = 2.0 })

   radius tiene un valor predeterminado de 2.0 metros. Quita la zona otra vez con exports['qs-core']:RemoveStashZone('town_locker').

3. O ábrelo desde un script

   En lugar de una zona (o además de ella), abre el alijo desde una opción de target, un menú o un ítem:

   exports['qs-coreinventory']:OpenStash('town_locker')

   Un alijo abierto de esta forma queda abierto hasta que el jugador cierra el inventario.

4. Reinicia y prueba

   Reinicia los recursos que editaste, entra en la zona y pulsa F1.

Cómo se comportan los contenedores#

• Se guardan al instante. Cada cambio en un maletero, guantera o alijo se escribe en la base de datos (trunk_inventories, glovebox_inventories, stash_inventories) y sobrevive a los reinicios.

• Los maleteros y guanteras pertenecen a la matrícula. El contenido sigue al texto de la matrícula, así que un vehículo con la misma matrícula siempre tiene el mismo maletero y la misma guantera.

• Un contenedor a la vez. Ves tu inventario más un maletero, guantera o alijo.

• Los límites de peso se aplican a todo lo que metes, como se describe arriba.

• Las armas salen de tus manos. Pon tu arma equipada en un maletero o alijo y se le quita a tu personaje.

Ítems#

Ítems base#

Estos ítems vienen con qs-core (qs-core/shared/items.lua). Otros recursos agregan los suyos: comida y bebidas de qs-needs, cada arma y tipo de munición de qs-coreweapons, y los ítems médicos de qs-ambulance.

Campos de la definición de ítem#

Agregar un ítem nuevo#

Registra ítems desde un script de servidor que se inicie después de qs-core. El inventario, las tiendas y los puentes de ESX y QBCore leen el mismo catálogo, así que un ítem registrado una vez está disponible en todas partes. Registrar un nombre que ya existe reemplaza su definición.

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

BridgeItems = {
    pizza = { label = 'Pizza', weight = 500, useable = true, description = 'A hot slice.' },
}

QBCore.Shared.Items = {
    pizza = { name = 'pizza', label = 'Pizza', weight = 500, type = 'item', unique = false, useable = true, shouldClose = true, description = 'A hot slice.' },
}

Hacer que un ítem sea utilizable#

useable = true solo permite usar el ítem; el efecto viene de un script. Registra un handler en el servidor; funciona con qs-coreinventory y con qs-inventory:

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

• El inventario no quita el ítem por ti: quítalo en el handler si se consume.

• Un handler por ítem: registrarlo otra vez reemplaza el anterior.

• Cada uso de un ítem que no es arma también dispara el evento de servidor qs:server:usedItem(source, itemName, slot, info), que puedes escuchar en lugar de registrar un handler.

• Los ítems con un campo weapon siempre se equipan; para ellos no se disparan handlers ni eventos.

Pruébalo con /giveitem <id> pizza 5 (admin). Los scripts de ESX que usan ESX.RegisterUsableItem y los scripts de QBCore que usan QBCore.Functions.CreateUseableItem siguen funcionando a través de los puentes; consulta Compatibilidad con ESX y QBCore.

¿Controlas el inventario desde tus propios scripts? AddItem, RemoveItem, HasItem, CanCarryItem, GetItemCount, GetSlotView, GetItemBySlot, SetItemInfo y los exports de cliente están en Comandos y exports.

Tiendas#

qs-coreshops agrega las tiendas de una ciudad roleplay de FiveM: supermercados 24/7, gasolineras LTD, Rob's Liquor, ferreterías, Ammunation y un punto de suministros médicos para EMS. Cada ubicación tiene un tendero y un blip en el mapa.

Tipos de tienda#

Qué vende cada tienda#

Comida y bebidas — normal (24/7 Supermarket y LTD Gasoline):

Bebidas — liquor (Rob's Liquor):

Herramientas — hardware (Hardware Store):

Médicos — medical (Medical Supplies, solo EMS):

icepack y burn_cream los registra qs-ambulance; sin él, se ocultan de la tienda.

Armas y munición — weapons (Ammunation):

Cómo funciona la compra#

Acércate a un tendero. A menos de 2.2 m ves Press E to browse …; pulsa E y la tienda se abre con tu saldo en efectivo. Elige un ítem y una cantidad (hasta 100 por compra) y cómpralo. El HUD se oculta mientras la tienda está abierta y vuelve cuando la cierras.

Cada compra se comprueba en el servidor, así que los clientes modificados no pueden comprar más barato ni desde el otro lado del mapa:

Primero se cobra el dinero y después se entrega el ítem; si el ítem no se puede agregar, el dinero se reembolsa automáticamente. Las compras aparecen en los registros de dinero con el motivo shop:<name> (y shop-refund:<name> para los reembolsos).

Tiendas de trabajos#

Dale a una tienda un job y solo los jugadores con ese trabajo ven su blip, reciben el aviso y pueden comprar ahí. El punto Medical Supplies es un ejemplo (job = 'ambulance'). Ammunation viene con la línea -- job = 'police' comentada: quita el -- para convertirla en una armería solo para la policía.

Configuración de tiendas#

Todas las opciones están en qs-coreshops/config.lua.

Agregar una tienda o un producto#

1. Asegúrate de que los ítems existan

   Cada producto debe estar registrado en el catálogo de ítems (ítems base, qs-needs, qs-coreweapons, o los tuyos en RegisterItems). Los productos cuyo ítem no existe se ocultan de la tienda.

2. Agrega un producto a una tienda existente

   Agrega una línea a la lista en Config.Products. Por ejemplo, para vender palancas en las ferreterías:

   hardware = {
       { name = 'lockpick',       price = 35 },
       { name = 'screwdriver',    price = 20 },
       { name = 'repairkit',      price = 250 },
       { name = 'weapon_crowbar', price = 60 },
   },

   Los precios son dólares enteros y deben ser al menos 1.

3. O crea una tienda nueva

   Obtén la posición y la orientación con /coords (admin) donde debe estar el tendero y luego agrega esto al final de qs-coreshops/config.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
       },
   }

4. Reinicia las tiendas

   Ejecuta restart qs-coreshops en la consola del servidor (o en txAdmin). Las tiendas se leen de la configuración al iniciar; no hay ningún export para agregarlas en tiempo de ejecución.

Hambre y sed#

qs-needs le da a cada personaje hambre y sed de 0 a 100, mostradas como barras en el HUD (consulta Chat, HUD y roleplay). Los personajes nuevos empiezan en 100 y los valores se guardan con el personaje.

Cómo bajan#

Qué pasa en cero#

Cuando el hambre o la sed llegan a 0, empiezas a perder 5 HP cada 10 segundos hasta que comes o bebes. Si lo sigues ignorando, terminas derribado.

Comer y beber#

Usa un ítem de comida o bebida (desde el inventario, la rueda de ítems o un slot rápido). Se consume un ítem, tu personaje reproduce una animación de comer o beber con el ítem en la mano mientras una barra de progreso muestra Eating o Drinking, y los valores suben (nunca por encima de 100). Recibes You ate the Burger. o You drank the Water Bottle. No puedes usar otro ítem hasta que termina la animación.

Todos se venden en los 24/7 Supermarket y LTD Gasoline, y las bebidas también en Rob's Liquor.

Configuración de las necesidades#

Todas las opciones están en qs-needs/shared/config.lua (tabla NeedsConfig).

Agregar comida o una bebida#

1. Registra el ítem

   qs-needs no crea ítems por ti. Regístralo como utilizable desde un script de servidor:

   exports['qs-core']:RegisterItem('pizza', { label = 'Pizza', weight = 500, useable = true, description = 'A hot slice.' })

2. Dale su efecto

   En qs-needs/shared/config.lua, agrégalo a NeedsConfig.Consumables:

   NeedsConfig.Consumables = {
       -- ...existing items...
       pizza = { hunger = 60, verb = 'eat' },
       lemonade = { thirst = 40, hunger = 5, verb = 'drink' },
   }

   verb = 'drink' reproduce la animación de beber; cualquier otro valor reproduce la de comer.

3. Véndelo y reinicia

   Agrégalo a una lista de una tienda (consulta Agregar una tienda o un producto más arriba) y reinicia qs-needs y el recurso que registra el ítem.

¿Cambias las necesidades desde tus propios scripts? Defínelas mediante los metadatos del personaje, de 0 a 100: exports['qs-core']:SetMetadata(source, 'hunger', 100). El HUD se actualiza al instante, y los scripts de QBCore leen los mismos valores en PlayerData.metadata.hunger y thirst.

Armas#

qs-coreweapons convierte cada arma de GTA en un ítem del inventario (105 en total), además de 9 tipos de munición. Las armas se cargan, intercambian, guardan y venden como cualquier otro ítem: pesan, ocupan un slot cada una, se pueden dar a otro jugador, guardar bajo llave en un maletero o comprar en Ammunation. No hay ningún loadout oculto.

Las armas no tienen comandos, teclas ni exports propios: las equipas usando el ítem, desde el inventario, la rueda de ítems (TAB) o un slot rápido (1–5).

Equipar y enfundar#

• Usa un ítem de arma para sacarla. Viene con las balas de su categoría (ver abajo).

• Úsalo otra vez mientras está en tus manos para enfundarla.

• Usar un arma diferente cambia a ella.

Cuerpo a cuerpo#

Se equipan sin munición. 18 ítems.

Pistolas#

12 balas por cargador, ammo_pistol. La Flare Gun usa ammo_flare y el Taser ammo_taser. 19 ítems.

Subfusiles#

30 balas por cargador, ammo_smg. 8 ítems.

Escopetas#

8 cartuchos por carga, ammo_shotgun. 10 ítems.

Rifles#

30 balas por cargador, ammo_rifle. 14 ítems.

Ametralladoras#

100 balas por carga, ammo_mg. Incluye la Minigun y la Widowmaker. 7 ítems.

Francotiradores#

10 balas por carga, ammo_sniper. 6 ítems.

Armas pesadas y lanzadores#

1 proyectil por carga, ammo_launcher. 8 ítems.

Arrojables#

Los arrojables se apilan hasta 10 por slot y cada uno que lanzas se gasta: lanza una granada y una granada sale de tu inventario. 10 ítems.

Equipamiento#

Herramientas que GTA trata como armas. Vienen con su propio combustible o carga al equiparlas. 5 ítems.

Munición#

Usa un ítem de munición para cargarla. Va al arma que tienes en las manos si usa esa munición; si no, a la primera arma que cargues que la use. Ves Loaded +30 rounds y se consume un ítem de munición. Si no tienes un arma para ella, ves You have no weapon that takes this ammo y no se consume nada.

Los ítems de munición se apilan como ítems normales (64 por slot). Las armas cuerpo a cuerpo, los arrojables y el equipamiento no tienen ítem de munición.

Un arma sale de tus manos cuando su ítem sale de tu inventario#

El arma que tienes en las manos es el ítem de tu inventario. Tírala, regálala, véndela o muévela a un maletero, guantera o alijo, y el arma se le quita a tu personaje al instante. En los arrojables, la cantidad que puedes lanzar siempre coincide con la cantidad de ítems que cargas.

Sin botín nativo de GTA#

En un servidor con Quasar Framework, las armas y el dinero solo vienen de tu economía, nunca del propio GTA:

Armas con scripts de ESX y QBCore#

Las armas son ítems, así que los scripts que dan ítems de armas funcionan como se espera: xPlayer.addInventoryItem('weapon_pistol', 1) en ESX, Player.Functions.AddItem('weapon_pistol', 1) en QBCore, o exports['qs-core']:AddItem(source, 'weapon_pistol', 1).

Agregar un arma#

1. Agrega el arma

   En qs-coreweapons/config.lua, agrega una entrada a WeaponsConfig.Weapons. El arma de GTA debe existir en tu versión del juego, o estar en streaming como arma add-on.

   WeaponsConfig.Weapons = {
       -- ...existing weapons...
       weapon_myrifle = { weapon = 'WEAPON_MYRIFLE', cat = 'rifle', label = 'My Rifle', weight = 3500 },
   }

   cat decide la munición que usa y con cuántas balas viene (melee, pistol, smg, shotgun, rifle, mg, sniper, launcher, flare, taser, throwable, misc). Agrega ammo = n para definir las balas tú mismo.

2. Agrega un nuevo tipo de munición (opcional)

   Para una categoría nueva, dale un tamaño de cargador y un ítem de munición con el mismo cat:

   WeaponsConfig.MagSize.dmr = 20
   
   WeaponsConfig.Ammo.ammo_dmr = { cat = 'dmr', label = 'DMR Ammo', weight = 450 }

3. Reinicia

   Ejecuta restart qs-coreweapons. Los ítems de armas y munición se registran en el catálogo automáticamente: sin SQL y sin lista de ítems que editar.

4. Véndela

   Agrega { name = 'weapon_myrifle', price = 9500 } a Config.Products.weapons en qs-coreshops/config.lua, o dala con /giveitem <id> weapon_myrifle 1.

Configuración de armas#

Preguntas frecuentes#