Obtenir et définir les propriétés des véhicules dans FiveM : lib, ESX et QBCore

Symptômes typiques :

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

L'apparence et le tuning d'un véhicule sont appelés ses propriétés. Pour les garder, vous les lisez depuis un véhicule généré, les stockez en JSON, et les appliquez au suivant que vous générez. Cet article montre la fonction que chaque framework fournit, la règle unique sur le kit de mods, et comment sauvegarder le résultat dans la base de données.

#Ce que les propriétés contiennent

Un tableau de propriétés contient tout ce que le garage doit restaurer : modèle, plaque, couleurs, livrée, mods par index, type de roue, fumée de pneu, néon, teinte de fenêtre, suppléments et valeurs de santé. C'est une table Lua simple, donc vous la transformez en texte avec json.encode pour le stockage.

#ox_lib

Si ox_lib est sur votre serveur, c'est le plus court, et le seul dont vous avez besoin sur QBox :

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

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

Les deux sont des fonctions client. Elles fonctionnent avec n'importe quel framework car elles lisent le jeu directement.

#ESX

ESX a sa propre paire sur le client :

local props = ESX.Game.GetVehicleProperties(vehicle)

ESX.Game.SetVehicleProperties(vehicle, props)

Obtenez d'abord l'objet avec ESX = exports['es_extended']:getSharedObject(). Si ESX est nil, voir fixing esx:getSharedObject.

#QBCore

QBCore a les mêmes deux fonctions sur le client :

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

local props = QBCore.Functions.GetVehicleProperties(vehicle)

QBCore.Functions.SetVehicleProperties(vehicle, props)

Sur QBox, utilisez la paire ox_lib ci-dessus.

Conseil : si vous écrivez un script qui doit fonctionner sur les trois frameworks, vérifiez lequel s'exécute et appelez la paire correspondante, ou utilisez simplement ox_lib partout puisque c'est déjà une dépendance de la plupart des serveurs modernes.

#SetVehicleModKit d'abord

Le jeu ignore SetVehicleMod jusqu'à ce que le véhicule ait un kit de mods défini. Les fonctions ci-dessus le gèrent, mais si vous écrivez votre propre code d'application, faites-le dans cet ordre :

SetVehicleModKit(vehicle, 0)

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

Le premier argument de SetVehicleModKit est le kit, et 0 est celui que tout le monde utilise. Les types de mods sont des nombres : 11 est le moteur, 12 freins, 13 transmission, 15 suspension, 16 armure, et 18 est le turbo, qui est activé au lieu d'être défini. Les couleurs, les roues, le néon et la teinte ont leurs propres natives comme SetVehicleColours, SetVehicleWheelType et SetVehicleNeonLightEnabled.

Écrire ceci à la main vaut rarement le coup. C'est long, et la bibliothèque couvre déjà tous les cas. Utilisez-le pour un ajustement unique, pas pour un garage.

#Enregistrer dans la base de données

Les propriétés sont stockées en tant que texte JSON dans une colonne de texte long. Le flux habituel est :

1. Le client lit les propriétés du véhicule.
2. Il les envoie au serveur avec la plaque.
3. Le serveur encode et les enregistre.

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

Le même appel sur QBCore et QBox écrit la colonne mods de player_vehicles. Les noms de colonnes sont dans the garage tables article.

Attention : ne faites jamais confiance à la plaque et aux propriétés du client sans vérifier la propriété sur le serveur. Sinon, un joueur peut écraser le véhicule de quelqu'un d'autre. Voir securing server events.

#Restaurer quand le véhicule se génère

Lisez le JSON, décodez-le, puis appliquez-le après que le véhicule existe sur ce client :

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)

Les règles d'application :

• Le véhicule doit exister et être chargé. Appliquez juste après CreateVehicle, avec une attente sur DoesEntityExist pour les en réseau. Voir spawning vehicles.
• Le modèle doit être le même. Les propriétés d'un modèle différent appliquent les mauvais index de mods.
• Exécutez-le sur le client qui contrôle le véhicule. L'application depuis un client qui ne le possède pas peut échouer.

#Problèmes courants

Mods perdus après stockage. La sauvegarde s'est déroulée après la suppression de la voiture, donc vous avez sauvegardé une table vide. Lisez les propriétés en premier, puis supprimez.

La plaque change après la restauration. La plaque enregistrée fait partie des propriétés. Si vous générez avec une plaque et que vous appliquez des propriétés avec une autre, les propriétés gagnent. Assurez-vous que les deux correspondent, ou les clés et la base de données cessent de correspondre.

Les couleurs sont mauvaises. Une couleur personnalisée est stockée avec ses propres valeurs RGB, que certains anciens scripts ne restaurent pas. Utilisez la fonction actuelle de votre framework.

JSON trop grand ou invalide. La colonne vehicle doit être de type texte long, et les données doivent provenir de json.encode. Un tableau avec les clés sous une forme numérique et chaîne mixte peut encoder en tant que liste au lieu d'objet, donc chargez et comparez toujours une ligne enregistrée quand vous déboguez.

Voitures personnalisées ou addon. Les pièces de modification personnalisées dépendent du meta du modèle et de son stream. Si une pièce manque au modèle, l'index ne fait rien. Voir adding addon cars.

#Liste de contrôle