Obtén y establece propiedades de vehículos en FiveM: lib, ESX y QBCore

Síntomas típicos:

A car comes out of the garage as a stock car: no colour, no turbo, no wheels, plain plate.

La apariencia y la puesta a punto de un vehículo se llaman sus propiedades. Para mantenerlas, las lees de un vehículo desovado, las almacenas como JSON, y las aplicas al siguiente que desovas. Este artículo muestra la función que proporciona cada framework, la única regla sobre el mod kit, y cómo guardar el resultado en la base de datos.

#Qué contienen las propiedades

Una tabla de propiedades contiene todo lo que el garaje debe restaurar: modelo, matrícula, colores, livery, mods por índice, tipo de rueda, humo de llantas, neon, tinte de ventana, extras y valores de salud. Es una tabla de Lua simple, así que la conviertes en texto con json.encode para almacenarla.

#ox_lib

Si ox_lib está en tu servidor, esta es la forma más corta, y la única que necesitas en QBox:

-- client
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local props = lib.getVehicleProperties(vehicle)

-- later, on a spawned vehicle
lib.setVehicleProperties(vehicle, props)

Ambas son funciones del cliente. Funcionan con cualquier framework porque leen el juego directamente.

#ESX

ESX tiene su propio par en el cliente:

local props = ESX.Game.GetVehicleProperties(vehicle)

ESX.Game.SetVehicleProperties(vehicle, props)

Obtén el objeto primero con ESX = exports['es_extended']:getSharedObject(). Si ESX es nil, mira arreglando esx:getSharedObject.

#QBCore

QBCore tiene las mismas dos funciones en el cliente:

local QBCore = exports['qb-core']:GetCoreObject()

local props = QBCore.Functions.GetVehicleProperties(vehicle)

QBCore.Functions.SetVehicleProperties(vehicle, props)

En QBox, usa el par de ox_lib anterior.

Consejo: si escribes un script que tiene que funcionar en los tres frameworks, comprueba cuál se está ejecutando y llama al par correspondiente, o simplemente usa ox_lib en todas partes ya que ya es una dependencia de la mayoría de servidores modernos.

#SetVehicleModKit viene primero

El juego ignora SetVehicleMod hasta que el vehículo tenga un mod kit establecido. Las funciones anteriores lo manejan, pero si escribes tu propio código de aplicación, hazlo en este orden:

SetVehicleModKit(vehicle, 0)

SetVehicleMod(vehicle, 11, 3, false)   -- engine, level 3
SetVehicleMod(vehicle, 12, 2, false)   -- brakes
ToggleVehicleMod(vehicle, 18, true)    -- turbo

El primer argumento de SetVehicleModKit es el kit, y 0 es el que todos usan. Los tipos de mod son números: 11 es el motor, 12 frenos, 13 transmisión, 15 suspensión, 16 armadura, y 18 es el turbo, que se alterna en lugar de establecerse. Los colores, ruedas, neon y tinte tienen sus propios nativos como SetVehicleColours, SetVehicleWheelType y SetVehicleNeonLightEnabled.

Escribir esto a mano raramente vale la pena. Es largo, y la librería ya cubre cada caso. Úsalo para un ajuste ocasional, no para un garaje.

#Guarda en la base de datos

Las propiedades se almacenan como texto JSON en una columna de texto largo. El flujo habitual es:

1. El cliente lee las propiedades del vehículo.
2. Las envía al servidor con la matrícula.
3. El servidor las codifica y las guarda.

-- client
local props = lib.getVehicleProperties(vehicle)
TriggerServerEvent('my_garage:saveProps', props.plate, props)

-- server
RegisterNetEvent('my_garage:saveProps', function(plate, props)
    local src = source
    -- check here that this player owns that plate before saving
    MySQL.update('UPDATE owned_vehicles SET vehicle = ? WHERE plate = ?', {
        json.encode(props), plate
    })
end)

La misma llamada en QBCore y QBox escribe la columna mods de player_vehicles. Los nombres de columnas están en el artículo de tablas de garaje.

Cuidado: nunca confíes en la matrícula y las propiedades del cliente sin verificar la propiedad en el servidor. De lo contrario, un jugador puede sobrescribir el vehículo de otro. Mira asegurando eventos de servidor.

#Restaura cuando el vehículo se desova

Lee el JSON, decodifícalo, luego aplícalo después de que el vehículo exista en este cliente:

local row = MySQL.single.await('SELECT vehicle FROM owned_vehicles WHERE plate = ?', { plate })
local props = json.decode(row.vehicle)

-- send props to the client that owns the car, which applies:
lib.setVehicleProperties(vehicle, props)

Las reglas para aplicar:

• El vehículo debe existir y estar cargado. Aplica justo después de CreateVehicle, con una espera en DoesEntityExist para los de red. Mira desovando vehículos.
• El modelo debe ser el mismo. Las propiedades de un modelo diferente aplican los índices de mod incorrectos.
• Ejecútalo en el cliente que tiene control del vehículo. Aplicar desde un cliente que no lo posee puede fallar.

#Problemas comunes

Mods perdidos después de almacenar. El guardado se ejecutó después de que el coche fue eliminado, así que guardaste una tabla vacía. Lee las propiedades primero, luego elimina.

La matrícula cambia después de restaurar. La matrícula guardada es parte de las propiedades. Si desovas con una matrícula y aplicas propiedades con otra, las propiedades ganan. Asegúrate de que ambas coincidan, o las claves y la base de datos dejan de coincidir.

Los colores son incorrectos. Un color personalizado se almacena con sus propios valores RGB, que algunos scripts antiguos no restauran. Usa la función actual de tu framework.

JSON demasiado grande o inválido. La columna vehicle debe ser un tipo de texto largo, y los datos deben venir de json.encode. Una tabla con las claves en forma numérica y de cadena mixta puede codificarse como una lista en lugar de un objeto, así que siempre carga y compara una fila guardada cuando depures.

Coches personalizados o addon. Las partes de mod personalizadas dependen del meta del modelo y su stream. Si falta una parte del modelo, el índice no hace nada. Mira añadiendo coches addon.

#Lista de comprobación