Como adicionar um veículo add-on a um servidor FiveM

Um veículo add-on tem nome de modelo próprio e carrega ao lado dos veículos originais do GTA V, sem substituir nenhum deles. No FiveM ele fica em um resource do servidor: o servidor envia os arquivos para cada jogador que entra, então ninguém instala nada à mão.

	Add-on	Replace
Nome do modelo	Novo (por exemplo mycar)	Um que já existe (por exemplo sultan)
Veículo original	Continua no jogo	É trocado para todos os jogadores
Arquivos meta	Precisa de uma entrada própria no vehicles.meta	Pode reaproveitar a entrada original
Uso típico	Carros do servidor, lojas, veículos de emprego	Trocas visuais dos carros do trânsito

1. Crie uma pasta para o resource dentro da pasta resources do servidor.
2. Coloque os arquivos .yft e .ytd em uma subpasta stream.
3. Coloque os arquivos .meta em uma subpasta data.
4. Escreva um fxmanifest.lua que liste cada meta em files e em uma linha data_file.
5. Adicione ensure <folder name> ao server.cfg e reinicie o servidor.
6. Dê spawn no veículo pelo nome do modelo.

Cada arquivo meta também tem seu próprio guia, com link na tabela da próxima seção.

Um veículo add-on se divide em dois grupos de arquivos: os binários do modelo, que vão em stream/, e os metas em XML, que dizem ao jogo o que o modelo é e como ele se comporta. O jogo só exige o modelo, as texturas e uma entrada no vehicles.meta. Os outros metas adicionam handling, cores, tuning e assentos.

Arquivo	Pasta	O que faz	Necessário?
mycar.yft, mycar_hi.yft	stream	O modelo 3D. Veja arquivos de modelo do veículo.	Sim
mycar.ytd	stream	O dicionário de texturas.	Sim
vehicles.meta	data	Registra o modelo: nome, tipo, layout, flags. Veja vehicles.meta explicado.	Sim
handling.meta	data	Física: massa, potência, aderência, suspensão. Veja handling.meta explicado.	Só se o veículo tiver um handlingId próprio
carvariations.meta	data	Combinações de cores, mod kit, configurações de luz e sirene.	Recomendado
carcols.meta	data	Kits de tuning, sirenes e conjuntos de luzes personalizados. Veja carvariations e carcols.	Só para peças de tuning ou sirenes personalizadas
vehiclelayouts.meta	data	Assentos, pontos de entrada e animações personalizados. Veja vehiclelayouts.meta explicado.	Só para assentos ou animações personalizados

Pacotes de veículos feitos para FiveM já vêm como um resource com essas pastas. Um veículo baixado como mod de single-player costuma vir como um arquivo dlc.rpf. Os mesmos arquivos estão lá dentro, mas precisam ser extraídos e organizados na estrutura abaixo.

Ferramenta	Usada para
CodeWalker	Navegar pelos arquivos do jogo, visualizar modelos e exportar arquivos .meta originais para copiar uma entrada.
Blender com o add-on Sollumz	Importar, editar e exportar modelos de veículo (.yft) e dicionários de texturas (.ytd).
Qualquer editor de texto	Editar os arquivos .meta e o fxmanifest.lua, que são texto puro.

O jeito mais rápido de escrever os metas de um veículo novo é copiar as entradas do veículo original mais parecido com ele e trocar os nomes.

Para criar ou alterar o modelo em si, veja como fazer um veículo FiveM no Blender com o Sollumz. Transformar um dlc.rpf de single-player em resource está em como converter um carro de single-player em add-on FiveM, e as duas ferramentas são comparadas em CodeWalker vs Sollumz.

Um resource de veículo é uma pasta dentro da pasta resources do servidor com um fxmanifest.lua, uma pasta stream e uma pasta para os metas. O nome da pasta é o nome do resource. A pasta dos metas pode ter qualquer nome, e a maioria chama de data.

resources/
  mycar/
    fxmanifest.lua
    data/
      handling.meta
      vehicles.meta
      carcols.meta
      carvariations.meta
    stream/
      mycar.yft
      mycar_hi.yft
      mycar.ytd

Os arquivos em stream/ são reconhecidos pelo nome do arquivo, então não entram no manifest. Os arquivos meta não têm esse atalho. Cada um precisa ser declarado no manifest.

O manifest declara cada arquivo meta duas vezes: uma em files, para o servidor enviá-lo aos jogadores, e outra em uma linha data_file, para o jogo carregá-lo como o tipo certo de dado. As duas estão documentadas na referência do resource manifest do FiveM.

fx_version 'cerulean'
game 'gta5'

files {
  'data/handling.meta',
  'data/vehicles.meta',
  'data/carcols.meta',
  'data/carvariations.meta',
}

data_file 'HANDLING_FILE'          'data/handling.meta'
data_file 'VEHICLE_METADATA_FILE'  'data/vehicles.meta'
data_file 'CARCOLS_FILE'           'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

• fx_version 'cerulean' e game 'gta5' são obrigatórios no topo de todo manifest de FiveM.
• Um meta que está em data_file mas falta em files nunca chega ao jogador, então o veículo não vai existir para ele.
• A string do tipo tem que bater com o arquivo: HANDLING_FILE para o handling.meta, VEHICLE_METADATA_FILE para o vehicles.meta, e assim por diante. A lista completa está na referência de data_file para veículos.

Adicione uma linha com o nome da pasta do resource ao server.cfg e reinicie o servidor. O ensure inicia o resource, ou reinicia se ele já estiver rodando.

ensure mycar

Com o servidor rodando, você pode digitar refresh e depois ensure mycar no console do servidor em vez de reiniciar tudo. Se um jogador que já estava conectado não enxergar o veículo, peça para ele reconectar.

O nome de spawn é o modelName do vehicles.meta, que também é o nome do arquivo .yft. Use esse nome em qualquer menu de admin ou comando de spawn de veículo. Se o servidor ainda não tem um comando de spawn, este script de client adiciona o /car mycar:

RegisterCommand('car', function(_, args)
  local model = GetHashKey(args[1] or 'mycar')
  if not IsModelInCdimage(model) then return print('model not found') end
  RequestModel(model)
  while not HasModelLoaded(model) do Wait(0) end
  local ped = PlayerPedId()
  local veh = CreateVehicle(model, GetEntityCoords(ped), GetEntityHeading(ped), true, false)
  SetPedIntoVehicle(ped, veh, -1)
  SetModelAsNoLongerNeeded(model)
end)

O nome que o jogo mostra para o veículo vem do gameName. Esse campo é uma chave de text label, então sem o label o HUD mostra a chave crua. Registre o label em um script de client:

-- client script: readable name for <gameName>MYCAR</gameName>
AddTextEntry('MYCAR', 'My Car GT')

Quando um veículo add-on não carrega, na maioria das vezes é um nome que não bate entre dois arquivos. Em cada linha abaixo, os dois nomes têm que ser idênticos:

stream/mycar.yft                 <modelName>mycar</modelName>
stream/mycar.ytd                 <txdName>mycar</txdName>
handling.meta <handlingName>     <handlingId>MYCAR</handlingId>
carvariations.meta <modelName>   <modelName>mycar</modelName>
vehiclelayouts.meta <Name>       <layout>LAYOUT_STANDARD</layout>
carcols.meta <kitName>           carvariations.meta <kits><Item>

Se o veículo dá spawn mas algo está errado (sem texturas, física errada, sem peças de tuning), siga o guia de solução de problemas de veículos.

Não. Um resource de veículo não tem nenhum script que dependa de ESX, QBCore ou QBox, então os passos acima são os mesmos em qualquer framework. O framework só entra quando o veículo vai ser vendido em uma concessionária ou guardado em uma garagem, e essa parte está em como adicionar um veículo personalizado ao ESX, QBCore ou QBox.

O Coil S-Cooter é um exemplo dessa estrutura funcionando: uma pasta stream com o modelo, as texturas e os dicionários de animação, e uma pasta data com handling, vehicles, carvariations, vehiclelayouts e clip sets, tudo carregado por linhas data_file, sem script.