Como criar um add-on de veículo no FiveM: do .yft solto ao resource que dá ensure

Você comprou ou ganhou um carro e recebeu três arquivos soltos. Falta o resource: a pasta que o servidor carrega, com o manifesto e os metas que dizem ao jogo que aquele modelo existe, como ele se chama e como ele anda. Este guia monta esse resource do zero, explica cada meta e lista a ordem de conferência quando o carro não spawna.

Add-on ou replace: qual escolher

São duas formas de colocar um carro na cidade, e a escolha muda tudo que vem depois.

• Replace. O carro novo ocupa o lugar de um carro do jogo base. Não precisa de meta novo, mas você perde o original e todo script que citava aquele modelo passa a spawnar o carro novo.
• Add-on. O carro entra como modelo novo, com nome próprio. Exige meta, e é o caminho certo para cidade: o jogo base fica intacto e o carro pode ser citado por nome em garagem, concessionária e loja.

Para servidor de roleplay, add-on é a resposta em praticamente todos os casos.

A anatomia do resource

Um add-on de veículo tem três partes: o manifesto, os arquivos do carro e os metas. O layout que a comunidade adotou, e que evita 90% dos problemas de caminho, é este:

• fxmanifest.lua na raiz do resource.
• stream/ com o .yft, o _hi.yft e o .ytd.
• data/ com vehicles.meta, handling.meta e carvariations.meta.

O manifesto precisa declarar os metas duas vezes: uma para empacotar o arquivo e outra para dizer ao jogo que tipo de dado ele é.

fx_version 'cerulean'
game 'gta5'

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

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

Esquecer a linha files é um clássico: o data_file aponta para um arquivo que nunca foi empacotado, e o jogo carrega o resource sem os dados do carro.

vehicles.meta: a identidade do carro

É o meta que registra o modelo. Os campos que você precisa acertar:

• modelName. O nome de spawn, e precisa ser igual ao nome do arquivo .yft, sem extensão.
• txdName. Normalmente o mesmo nome do modelo; é como o jogo acha o dicionário de texturas.
• handlingId. A ponte com o handling.meta. Tem que bater com o handlingName de lá.
• gameName. O nome que aparece na tela, curto.
• vehicleClass e flags. Classe do veículo e comportamentos, como ter porta-malas ou aceitar livery.

A regra de ouro: nome de arquivo, modelName e txdName andam juntos. Renomear um e esquecer os outros é a causa número um de carro que não aparece.

handling.meta: o mínimo para o carro andar

O handling.meta guarda o comportamento: massa, força de motor, freio, tração, suspensão e dano. Sem uma entrada válida, o carro pode até spawnar e ficar impossível de dirigir.

O único campo que precisa de atenção na montagem é o handlingName, porque ele é a ponte com o handlingId do vehicles.meta. O resto é ajuste de direção, e cada parâmetro está explicado no guia de handling.meta.

carvariations.meta: cores, livery e extras

É o meta das variações. Ele define quais combinações de cor o carro pode nascer, quais liveries existem em cada cor, quais extras aparecem e a probabilidade de placa.

Duas coisas importam na prática. A primeira é o modelName, que precisa bater com o resto. A segunda é o bloco <liveries>: é ele que libera cada índice de livery, e ele só funciona se a lataria do carro tiver o shader certo, como explica o guia de livery.

O carvariations.meta é também o meta que mais chega quebrado. Ele é o mais longo dos três e o mais editado na mão, então tag aberta e bloco pela metade são comuns.

Como montar tudo em 1 clique

Montar na mão funciona e ensina. O problema é escala: dez carros por semana viram dez chances de errar um nome ou deixar um XML quebrado.

No Texturize Studio o caminho é outro: você solta a pasta do carro, ele mostra o veículo em 3D, lê os metas que vieram junto e gera o resource completo em um clique, no layout padrão stream/ e data/, com o manifesto apontando para os caminhos certos.

O que ele faz com os seus metas é o ponto que importa: meta válido é reaproveitado como está, para não perder o handling que você ajustou; meta que falta é gerado; e meta malformado é regenerado, porque todo meta é validado como XML antes de entrar no zip. Se você renomear o modelo na hora de gerar, o nome novo propaga para modelName, txdName, handlingId e handlingName de uma vez. Gerar o add-on não consome crédito.

1. Separe os arquivos do carroJunte o .yft, o _hi.yft e o .ytd numa pasta, com os metas que vieram, se vieram.
2. Abra a pasta no StudioO carro aparece em 3D e os metas da pasta são lidos, com a ficha de handling ao lado de cada .yft.
3. Confira a ficha do handlingVeja se massa, força de motor e freio fazem sentido para o tipo de carro antes de empacotar.
4. Escolha o nome de spawn e a classeO nome propaga para modelName, txdName, handlingId e handlingName. A classe define os metas que faltarem.
5. Gere o add-onSai o resource com fxmanifest.lua, stream/ e data/, com todo meta validado como XML. Não consome crédito.
6. Instale e dê ensureExtraia a pasta em resources, acrescente o ensure no server.cfg e reinicie o servidor.
7. Spawne e confira o consoleUse o nome de modelo que você definiu. O console aponta qualquer meta com problema na subida.

Instalar e testar

Com o resource pronto, a instalação é a de sempre: a pasta vai para resources e o servidor precisa carregá-la.

• ensure no server.cfg. Sem isso o resource existe e não sobe.
• Reinicie o servidor na primeira instalação. Meta de veículo é lido na subida, então recarregar o resource sozinho não basta.
• Confira o console. Erro de meta aparece na subida, com o caminho do arquivo problemático.
• Spawne pelo nome que você colocou em modelName.

Erros comuns e a ordem de conferência

Quando o carro não aparece, siga esta ordem em vez de reinstalar tudo:

1. O resource subiu? Falta de ensure resolve metade dos casos.
2. Algum meta quebrou? XML malformado derruba o carregamento e o console diz qual arquivo. A linha é mais ou menos assim:

Error: Failed to parse resources:/meucarro/data/carvariations.meta in rage::parManager::LoadFromStructure(const char*, ...). Make sure this is a well-formed XML/PSO file.

3. Os nomes batem? Arquivo .yft, modelName e txdName precisam ser o mesmo nome.
4. O handling existe? handlingId no vehicles.meta e handlingName no handling.meta, iguais.
5. Faltou o par de arquivos? Carro sem _hi.yft aparece mas perde detalhe de perto.
6. Carro invisível ou sem colisão? Normalmente arquivo de stream corrompido ou incompleto.