Obter e definir propriedades de veículos no FiveM: lib, ESX e QBCore

Sintomas típicos:

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

A aparência e sintonia de um veículo são chamadas de suas propriedades. Para mantê-las, você as lê de um veículo spawnado, as armazena como JSON e as aplica ao próximo que spawna. Este artigo mostra a função que cada framework fornece, a regra sobre o kit de mod, e como salvar o resultado no banco de dados.

#O que as propriedades contêm

Uma tabela de propriedades contém tudo que a garagem deve restaurar: modelo, placa, cores, livery, mods por índice, tipo de roda, fumaça de pneu, neon, matiz de janela, extras e valores de saúde. É uma tabela Lua simples, então você a transforma em texto com json.encode para armazenamento.

#ox_lib

Se ox_lib estiver no seu servidor, esse é o caminho mais curto, e o único que você precisa no QBox:

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

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

Ambas são funções de cliente. Funcionam com qualquer framework porque leem o jogo diretamente.

#ESX

ESX tem seu próprio par no cliente:

local props = ESX.Game.GetVehicleProperties(vehicle)

ESX.Game.SetVehicleProperties(vehicle, props)

Obtenha o objeto primeiro com ESX = exports['es_extended']:getSharedObject(). Se ESX for nil, veja corrigindo esx:getSharedObject.

#QBCore

QBCore tem as mesmas duas funções no cliente:

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

local props = QBCore.Functions.GetVehicleProperties(vehicle)

QBCore.Functions.SetVehicleProperties(vehicle, props)

No QBox, use o par ox_lib acima.

Dica: se você escrever um script que deve funcionar nos três frameworks, verifique qual está rodando e chame o par correspondente, ou apenas use ox_lib em todo lugar, já que é uma dependência da maioria dos servidores modernos.

#SetVehicleModKit vem primeiro

O jogo ignora SetVehicleMod até que o veículo tenha um kit de mod definido. As funções acima o tratam, mas se você escrever seu próprio código de aplicação, faça-o nesta ordem:

SetVehicleModKit(vehicle, 0)

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

O primeiro argumento de SetVehicleModKit é o kit, e 0 é o que todos usam. Os tipos de mod são números: 11 é o motor, 12 freios, 13 transmissão, 15 suspensão, 16 armadura, e 18 é o turbo, que é alternado em vez de definido. Cores, rodas, neon e matiz têm seus próprios natives como SetVehicleColours, SetVehicleWheelType e SetVehicleNeonLightEnabled.

Escrever isso à mão raramente vale a pena. É longo, e a biblioteca já cobre todos os casos. Use para uma modificação única, não para uma garagem.

#Salve no banco de dados

As propriedades são armazenadas como texto JSON em uma coluna de texto longo. O fluxo usual é:

1. O cliente lê as propriedades do veículo.
2. As envia ao servidor com a placa.
3. O servidor as codifica e salva.

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

A mesma chamada no QBCore e QBox escreve a coluna mods de player_vehicles. Os nomes das colunas estão em o artigo de tabelas de garagem.

Atenção: nunca confie na placa e propriedades do cliente sem verificar propriedade no servidor. Caso contrário, um jogador pode sobrescrever o veículo de outro. Veja garantindo eventos de servidor.

#Restaure quando o veículo spawna

Leia o JSON, decodifique-o, então aplique-o após o veículo existir neste 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)

As regras para aplicar:

• O veículo deve existir e estar carregado. Aplique logo após CreateVehicle, com uma espera em DoesEntityExist para os em rede. Veja spawnando veículos.
• O modelo deve ser o mesmo. Propriedades de um modelo diferente aplicam os índices de mod errados.
• Execute no cliente que tem controle do veículo. Aplicar de um cliente que não o possui pode falhar.

#Problemas comuns

Mods perdidos após armazenar. O salvamento correu após o carro ser deletado, então você salvou uma tabela vazia. Leia as propriedades primeiro, depois delete.

Placa muda após restaurar. A placa salva faz parte das propriedades. Se você spawna com uma placa e aplica propriedades com outra, as propriedades vencem. Certifique-se de que ambas correspondem, ou as chaves e o banco de dados deixam de corresponder.

Cores estão erradas. Uma cor personalizada é armazenada com seus próprios valores RGB, que alguns scripts antigos não restauram. Use a função atual do seu framework.

JSON muito grande ou inválido. A coluna vehicle deve ser um tipo de texto longo, e os dados devem vir de json.encode. Uma tabela com as chaves em forma numérica e de string mista pode codificar como uma lista em vez de um objeto, então sempre carregue e compare uma linha salva quando debugar.

Carros personalizados ou addon. Partes de mod personalizadas dependem do meta do modelo e de seu stream. Se uma parte estiver faltando do modelo, o índice não faz nada. Veja adicionando carros addon.

#Lista de verificação