Vehículos

Quasar Framework (qs-core) incluye un completo sistema de vehículos para FiveM para servidores de roleplay: llaves de vehículos con cierre, apertura y puente, 31 garajes con vista previa 3D, un concesionario con sala de exposición y herramientas de administración para generar, reparar y eliminar vehículos. Cada vehículo con dueño vive en una sola tabla vehicles, así que las llaves, los garajes, el concesionario y tus propios scripts coinciden en quién es dueño de qué, ya sea que el resto de tu servidor use scripts de ESX, QBCore o Quasar Framework.

Nada de esto necesita una sola línea de código para funcionar: la receta de txAdmin inicia todos los recursos, y todo lo que quieras cambiar está en un archivo Lua config.lua.

Controles de vehículos de un vistazo#

U y G son asignaciones de teclas de FiveM: cada jugador puede reasignarlas en Settings → Key Bindings → FiveM. Las indicaciones E usan la tecla de contexto del juego y no se pueden reasignar.

Llaves de vehículos FiveM (qs-corevehiclekeys)#

Las llaves pertenecen a una matrícula. Si te sientas en el asiento del conductor de un vehículo de cuya matrícula no tienes llaves, el motor se mantiene apagado y no puedes irte: necesitas las llaves, o una ganzúa y buen pulso. Los pasajeros nunca quedan bloqueados.

Quién recibe llaves#

Conducir sin llaves#

Cuando eres el conductor y no tienes llaves, el motor se apaga y se impide que arranque solo. Una indicación de ayuda te dice qué hacer:

• Con una ganzúa en tu inventario: "Hold G to hotwire".

• Sin ella: "You need keys to drive this. Get a lockpick to hotwire it".

En cuanto recibes las llaves (por la comprobación de dueño, de un amigo, de un administrador o con un puente exitoso), el bloqueo se levanta en medio segundo y puedes arrancar el motor. Configura Config.RequireKeysToDrive = false si quieres que cualquiera pueda conducir cualquier vehículo.

Cerrar y abrir (U)#

Pulsa U para alternar el cierre:

• Dentro de un vehículo, actúa sobre ese vehículo. A pie, actúa sobre el vehículo más cercano a menos de 5 m (Config.LockDistance).

• Necesitas las llaves de esa matrícula; si no, verás "You don't have keys for this vehicle".

• A pie, tu personaje pulsa el mando de la llave, las luces parpadean y recibes "Vehicle locked" o "Vehicle unlocked".

• El nuevo estado del cierre se sincroniza con todos los jugadores del servidor.

Las llaves también protegen el almacenamiento del vehículo en qs-coreinventory: el maletero solo se abre si el vehículo está abierto y tienes sus llaves, y la guantera necesita las llaves. Consulta Inventario, ítems y armas.

Hacer el puente con una ganzúa (G)#

Hacer el puente es la forma de robar un vehículo en Quasar Framework. Necesitas ser el conductor de un vehículo sin llaves y llevar al menos una lockpick (se vende en la Hardware Store por $35).

1. Súbete al asiento del conductor

   Siéntate en un vehículo del que no tengas llaves. El motor se queda apagado y, si llevas una ganzúa, la indicación te invita a hacerle el puente.

2. Pulsa G

   Se abre el minijuego de la ganzúa. Una ganzúa gira alrededor de un anillo: pulsa SPACE mientras está dentro de la zona resaltada para fijar el pin.

3. Supera todas las rondas

   Por defecto son 3 rondas (Config.HotwireRounds, de 1 a 6). En cada ronda la zona se hace más pequeña y la ganzúa más rápida. Un fallo termina el intento. ESC o Backspace cancelan, y tras 30 segundos el intento falla solo.

4. Vete conduciendo, o corre

   Si lo logras, recibes las llaves, el motor arranca y ves "The engine roars to life".

Cuando el intento falla (un fallo, una cancelación o el tiempo límite):

• Se quita una lockpick de tu inventario (Config.BreakLockpickOnFail) y ves "The lockpick snapped".

• La alarma del vehículo se dispara.

• Si qs-police está en ejecución, todos los policías reciben una alerta "Vehicle break-in reported" en tu posición. Las alertas se limitan a una cada 8 segundos por jugador, así que insistir con intentos no satura a la policía.

Consulta Trabajos, policía y EMS para ver el lado policial de la alerta.

Compartir llaves con /givekeys#

Siéntate en el vehículo (en cualquier asiento) y asegúrate de tener sus llaves; luego:

Dar llaves entrega una copia — tú conservas las tuyas. Ves "You handed over the keys" y el otro jugador ve "You received vehicle keys".

Llaves de administrador con /adminkeys#

Los administradores pueden darse a sí mismos o a cualquiera las llaves del vehículo en el que están sentados:

/adminkeys        # keys for you
/adminkeys 12     # keys for player 12

Debes estar sentado en el vehículo ("You are not in a vehicle" si no), y el objetivo debe estar conectado ("No one nearby" si no). El comando necesita el ACE command.adminkeys, que add_ace group.admin command allow en el server.cfg incluido ya concede. No hace nada desde la consola del servidor. Consulta Administración.

Llaves tras reconectar#

Las llaves viven en la sesión de juego del jugador y no se guardan. Tras reconectar (o reiniciar qs-corevehiclekeys):

• Vehículos propios: no hay que hacer nada. La primera vez que te sientas en el asiento del conductor, la comprobación de dueño te devuelve las llaves.

• Cualquier otra llave (de /givekeys, un puente, /car o el menú de administración): se pierde. Pídela de nuevo al dueño, vuelve a hacer el puente o pídesela a un administrador.

El estado del cierre de un vehículo tampoco se guarda.

Configuración de las llaves de vehículos#

Archivo: [core]/qs-corevehiclekeys/config.lua

Rendimiento#

El sistema de llaves está hecho para un resmon bajo. Una sola comprobación se ejecuta cada 500 ms — nada se ejecuta en cada frame. La propiedad se consulta al servidor una vez por matrícula y sesión, y los cambios de cierre solo se envían cuando alguien pulsa la tecla. No se escribe nada en la base de datos.

Garajes FiveM (qs-garage)#

Los jugadores guardan y sacan sus vehículos en 31 garajes repartidos por Los Santos, Blaine County y Paleto Bay. Cada garaje está marcado en el mapa con un marcador azul Garage, y al abrir uno ves tus vehículos en una vista previa 3D cinematográfica sobre una plataforma giratoria.

Ubicaciones de los garajes#

Todos los garajes son públicos: no hay garajes de trabajo ni de bandas, y todos los jugadores ven todos los marcadores. El id entre paréntesis es lo que se guarda en la columna garage de la tabla vehicles.

Abrir un garaje#

Acércate al punto del garaje. A menos de 3 m ves "Press E to open the garage". Pulsa E y:

• Tu personaje se queda inmóvil y el HUD se oculta.

• La cámara se desliza hasta el punto de vista previa del garaje y tu primer vehículo aparece sobre una plataforma que gira lentamente.

• El menú muestra cada vehículo con su matrícula, su estado (Stored o Out), combustible, motor y carrocería.

• Haz clic en un vehículo para verlo: el actual se desvanece y aparece el nuevo, con sus colores y modificaciones reales.

• Pulsa Take out, o Close para salir.

El vehículo de la vista previa solo lo ves tú. Si no tienes nada aquí, el menú muestra "No vehicles in this garage."

Qué vehículos muestra un garaje#

Un garaje muestra:

• todos los vehículos de tu personaje guardados en este garaje, estén dentro o fuera en ese momento;

• además de todos tus vehículos que no tienen un garaje válido — un vehículo que compraste en el concesionario y aún no has guardado, o uno cuyo garaje se eliminó o se renombró en la configuración. Estos aparecen en todos los garajes y se pueden sacar desde cualquiera de ellos. Guardarlos en cualquier lugar les asigna ese garaje como su nuevo hogar.

Los vehículos pertenecen a tu personaje, no a tu cuenta: cada personaje en multicharacter tiene su propio contenido en los garajes.

Sacar un vehículo#

Selecciona un vehículo y pulsa Take out. El garaje comprueba que:

1. El vehículo pertenece a tu personaje.

2. Pertenece a este garaje, o a ningún garaje válido.

3. No está ya fuera, en el mundo.

Entonces el vehículo aparece en el punto de aparición del garaje con su matrícula, sus colores y modificaciones guardados, el daño de motor y carrocería guardado y el combustible guardado. Está limpio y abierto, recibes las llaves, y quedas en el asiento del conductor con "Vehicle taken out". El vehículo queda marcado como Out en la base de datos.

El garaje no despeja el punto de aparición antes de generar el vehículo, así que pon los puntos de aparición donde los jugadores no suelan dejar sus vehículos.

Guardar un vehículo#

Conduce hasta cualquier punto de garaje. A menos de 3 m ves "Press E to store this vehicle". Pulsa E:

• Debes ser el conductor ("You must be in the driver seat" si no).

• El vehículo debe estar registrado a nombre de tu personaje. Tener sus llaves no basta: el vehículo de un amigo, uno al que le hiciste el puente o uno generado con /car se rechaza con "This is not your vehicle".

• Sirve cualquier garaje, sin importar de qué garaje salió el vehículo. El garaje donde lo guardas se convierte en su hogar.

Se guarda el estado actual del vehículo, este desaparece y ves "Vehicle stored".

Qué guarda un garaje#

Añadir un garaje#

Puedes añadir garajes en dos lugares. garages.lua contiene los 31 garajes por defecto en un formato de una línea y genera por ti el id, la etiqueta, el marcador y la posición de la indicación. config.lua acepta el formato completo cuando quieres tu propio id o un marcador distinto.

1. Obtén las tres posiciones

   Usa el comando de administrador /coords en cada lugar. Imprime vec4(x, y, z, heading) en la consola F8 y en pantalla.

   • Punto del menú: donde los jugadores pulsan E. Los jugadores también conducen hasta este punto para guardar.

   • Punto de aparición: donde aparecen los vehículos que se sacan. Orienta el punto hacia donde debe salir el vehículo.

   • Punto de vista previa: donde se coloca el vehículo de la vista previa 3D. La cámara se sitúa 5.2 m delante del vehículo según esta orientación, así que orienta el heading hacia un espacio abierto.

2. Añade el garaje

   garages.lua (one line)config.lua (full control)

   -- [addons]/qs-garage/garages.lua, inside the `extra` table
   { name = 'Beach House Garage', menu = vec3(-1520.40, -430.10, 35.44), spawn = vec4(-1515.20, -425.80, 35.20, 230.0), preview = vec4(-1530.00, -440.00, 35.30, 140.0) },

   El id se genera a partir del nombre: beach_house_garage. El marcador es el marcador azul estándar de Garage.

3. Reinicia el garaje

   Ejecuta restart qs-garage en la consola del servidor (o reinicia el servidor). La lista de ids de garaje válidos se crea cuando el recurso inicia.

Configuración de los garajes#

Archivo: [addons]/qs-garage/config.lua

El bucle del garaje espera 1.5 s cuando estás a más de 40 m de todos los garajes y solo dibuja la indicación en cada frame mientras estás a menos de 3 m de uno.

Concesionario de vehículos FiveM (qs-vehicleshop)#

El concesionario vende vehículos directamente a los jugadores. Está en Premium Deluxe Motorsport en el centro de Los Santos, marcado con un marcador Dealership, donde un vendedor espera con su portapapeles.

Comprar un vehículo#

1. Habla con el vendedor

   Acércate a él. A menos de 2.5 m ves "Press E to browse the dealership". Pulsa E.

2. Recorre la sala de exposición

   Tu personaje se queda inmóvil y el HUD se oculta. La cámara se mueve a la sala de exposición, donde el primer vehículo de la primera categoría gira sobre una plataforma. El menú muestra las pestañas de categorías, los vehículos con sus precios y tus saldos de efectivo y banco.

3. Vista previa

   Haz clic en cualquier vehículo para cambiar el de la sala de exposición, con un breve fundido entre ellos. Los vehículos de la sala llevan la matrícula SHOWROOM y solo tú puedes verlos.

4. Comprar

   Pulsa Buy. El precio sale del catálogo del servidor, nunca del juego del jugador, y el servidor comprueba que sigas en el concesionario.

5. Llévatelo

   Ves "Vehicle purchased! Plate: QS…", la sala de exposición se cierra y tu vehículo nuevo te espera en el punto de entrega con el tanque lleno, limpio y abierto. Recibes las llaves y quedas en el asiento del conductor.

Pago y matrículas#

• Pago: las cuentas de Config.PayAccounts se prueban en orden — bank primero, luego cash. La primera cuenta que tenga el precio completo lo paga todo; un precio nunca se reparte entre cuentas. La transacción se registra con el motivo vehicleshop:<model>.

• Matrícula: QS seguido de 5 letras y dígitos aleatorios (por ejemplo QS7K2XA), comprobada en la base de datos para que sea única.

Después de la compra: guardar tu vehículo nuevo#

El vehículo se guarda como tuyo de inmediato, marcado como Out, con el garaje legion (Config.DefaultGarage). legion no es uno de los 31 ids de garaje, así que, hasta que lo guardes, el vehículo aparece en todos los garajes:

• Llévalo a cualquier garaje y guárdalo desde el asiento del conductor. Ese garaje se convierte en su hogar.

• Si lo pierdes antes de guardarlo (destruido, reinicio del servidor…), abre cualquier garaje y sácalo de nuevo.

¿Prefieres que los vehículos nuevos pertenezcan a un garaje concreto? Configura Config.DefaultGarage con uno de los ids de garaje, por ejemplo 'pillbox_hill_garage'. Así, los vehículos nuevos solo se muestran en ese garaje.

Catálogo por defecto#

Añadir vehículos y categorías#

1. Añade la categoría

   Las categorías aparecen como pestañas en el orden en que las pones. El primer vehículo de la primera categoría es el que se muestra al abrir la sala de exposición.

   -- [addons]/qs-vehicleshop/config.lua
   Config.Categories = {
       { id = 'compacts', label = 'Compacts' },
       -- ...
       { id = 'muscle', label = 'Muscle' },
   }

2. Añade los vehículos

   Añade una lista bajo el id de la categoría. model es el nombre de spawn, label es lo que leen los jugadores, price está en dólares.

   Config.Vehicles = {
       -- ...existing categories...
       muscle = {
           { model = 'dominator', label = 'Vapid Dominator',  price = 35000 },
           { model = 'gauntlet',  label = 'Bravado Gauntlet', price = 32000 },
       },
   }

   Pon cada modelo una sola vez entre todas las categorías.

3. Reinicia el concesionario

   Ejecuta restart qs-vehicleshop en la consola del servidor.

Añadir otro concesionario#

Añade una segunda entrada dentro de Config.Locations, después de la que viene por defecto. Todos los concesionarios venden el mismo catálogo.

-- [addons]/qs-vehicleshop/config.lua, a new entry inside Config.Locations
{
    ped     = 's_m_m_autoshop_02',                            -- salesman model (optional)
    coords  = vec4(-1255.00, -361.00, 36.91, 300.0),          -- salesman and prompt position
    preview = vec4(-1265.00, -355.00, 36.90, 120.0),          -- showroom car
    spawn   = vec4(-1240.00, -370.00, 37.00, 30.0),           -- delivery point
    blip    = { sprite = 326, color = 3, scale = 0.6, label = 'Dealership' }, -- optional
},

Usa /coords para obtener cada posición. Sin ped no hay vendedor; sin blip no hay marcador en el mapa.

Configuración del concesionario#

Archivo: [addons]/qs-vehicleshop/config.lua

Herramientas de vehículos para administradores#

Los administradores (cualquiera con el ACE command.qs) tienen un conjunto de herramientas de vehículos mediante comandos y el menú de administración en F6. Consulta Administración para saber cómo ser administrador.

Combustible#

La carpeta [bridge] incluye una capa compatible con LegacyFuel, así que los scripts y el HUD que leen exports['LegacyFuel']:GetFuel(vehicle) funcionan sin configurar nada. Mientras conduces, el motor consume combustible (más a altas RPM), y a 0 el motor se apaga. Los garajes guardan el nivel de combustible y lo restauran al sacar el vehículo; los vehículos del concesionario y del menú de administración empiezan con el tanque lleno. La capa no tiene surtidores ni bidones propios. Consulta Integraciones para scripts de combustible.

La tabla vehicles#

Cada vehículo con dueño es una fila de la tabla vehicles, creada por qs-core/sql/qscore.sql.

Scripts de vehículos de ESX y QBCore#

Consulta Compatibilidad con ESX y QBCore para ver todo lo que cubren los puentes.

Para desarrolladores#

local plate = GetVehicleNumberPlateText(vehicle)
exports['qs-corevehiclekeys']:GiveKeys(plate)
if exports['qs-corevehiclekeys']:HasKeys(plate) then
    -- the local player can drive and lock this vehicle
end
exports['qs-corevehiclekeys']:RemoveKeys(plate)
local all = exports['qs-corevehiclekeys']:GetKeys() -- { [plate] = true }

TriggerClientEvent('vehiclekeys:client:SetOwner', source, plate)

local cars = exports['qs-core']:GetCitizenVehicles(citizenid)
for _, car in ipairs(cars) do
    print(car.plate, car.model, car.garage, car.state, car.fuel)
end

local car = exports['qs-core']:GetVehicleByPlate('QS7K2XA') -- row or nil
local taken = exports['qs-core']:PlateExists('QS7K2XA')     -- boolean

local player = exports['qs-core']:GetPlayer(source)
exports['qs-core']:CreateOwnedVehicle({
    citizenid = player.citizenid,
    license   = GetPlayerIdentifierByType(source, 'license'),
    plate     = 'QSGIFT1',
    model     = 'sultan',
    garage    = 'legion_square',
    state     = 1,          -- 1 = parked in the garage
})

exports['qs-core']:UpdateOwnedVehicle(plate, { garage = 'legion_square', state = 1, fuel = 80, engine = 1000.0, body = 1000.0, props = {} })
exports['qs-core']:SetVehicleState(plate, 1, 'legion_square') -- garage is optional

local netId = exports['qs-core']:SpawnVehicle(source, 'sultan', vector4(x, y, z, heading), true)

¿Lo controlas desde tus propios scripts? Todos los comandos, teclas, exports y eventos están en Comandos y exports. ¿Algo no funciona bien? Revisa Errores comunes.