Solução de problemas de veículo add-on no FiveM: causas e correções

Sintoma	Causa mais provável	Correção
O comando de spawn diz que o modelo não existe	Resource não iniciado, vehicles.meta não carregado, ou modelName diferente do nome do .yft	Não dá spawn
O veículo fica invisível ou demora a aparecer	Modelo ou texturas grandes demais; falta o _hi.yft	Veículo invisível
Texturas brancas, cinza ou faltando	txdName diferente do nome do .ytd, ou uma textura não está no dicionário	Texturas faltando
O veículo cai pelo chão	Modelo exportado sem colisão	Cai pelo mapa
Dirige como outro carro, ou as edições de handling não fazem nada	handlingId não bate, ou o nome é usado duas vezes	Handling errado
Sem peças de tuning, ou com peças de outro carro	ID de kit duplicado no carcols.meta	Problemas de tuning
O nome aparece como NULL ou como um código	Sem text label para o gameName	Nome errado
O jogador senta errado ou não consegue entrar	O layout não combina com os bones do modelo	Assentos e entrada

Antes de qualquer coisa, olhe o console do servidor quando o resource inicia e o console do client (F8) quando você dá spawn no veículo. Os dois dizem o nome do arquivo com o qual têm problema.

Se o jogo diz que o modelo não existe, o veículo nunca foi registrado. Confira nesta ordem:

1. O resource está rodando. ensure mycar está no server.cfg e o nome da pasta está escrito igual. Uma pasta dentro de uma pasta de categoria como [cars] não é problema.
2. O vehicles.meta está tanto em files quanto em data_file 'VEHICLE_METADATA_FILE', com o caminho certo. Veja a referência de data_file.
3. Os nomes batem. O nome de spawn é o modelName, e o arquivo do modelo tem que ser stream/<modelName>.yft.
4. O XML é válido. Uma tag sem fechar deixa o arquivo inteiro ilegível. Abra em um editor que valide XML.
5. Os arquivos estão extraídos. O FiveM não carrega arquivos .rpf colocados em stream, então os arquivos .yft e .ytd têm que ser tirados de dentro deles.

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 um resource pago nem inicia e o console mostra "You lack the required entitlement", a causa é a chave do servidor, não o veículo: veja como corrigir o erro de entitlement.

Um veículo que dá spawn (dá para sentar nele, a câmera segue) mas não aparece desenhado é quase sempre um problema de streaming.

• Arquivos grandes demais. Procure no console do servidor por "uses ... MiB of physical memory". O próprio FXServer diz que eles "lead to streaming issues (such as models not loading/rendering)". Reduza as texturas como descrito em arquivos de modelo do veículo e o aviso de 16 MiB.
• Falta o _hi.yft. Quando o primeiro valor de lodDistances está acima de zero, o jogo pede o <modelName>_hi.yft para veículos perto da câmera. Inclua esse arquivo exatamente com esse nome.
• Veículos pesados demais em um mesmo lugar. A memória se soma por modelo único, então um encontro de carros pode falhar onde um carro sozinho funciona.

• Nome do dicionário. O txdName do vehicles.meta tem que ser igual ao nome do arquivo .ytd sem a extensão.
• Textura fora do dicionário. Abra o .ytd e confira se toda textura que os materiais usam está lá com o mesmo nome.
• Texturas compartilhadas. Se o modelo depende de texturas do vehshare ou de um dicionário compartilhado de um pacote de veículos, esse dicionário tem que ser o pai do dicionário do veículo em txdRelationships.
• Liveries. Elas precisam de FLAG_HAS_LIVERY e de texturas terminando em _sign_1, _sign_2 e assim por diante.

A colisão de um veículo fica guardada dentro do .yft. Um modelo exportado sem os bounds de colisão não tem onde se apoiar, então ele atravessa a rua ou afunda até o teto. A correção é no modelo: abra na ferramenta em que ele foi feito, adicione a colisão e exporte de novo. Nenhum arquivo meta resolve isso.

Se só as rodas afundam ou a carroceria raspa no chão, a colisão existe e o problema é a suspensão: veja fSuspensionRaise e os limites de curso em handling.meta explicado.

Como adicionar os bounds no Blender está em como configurar a colisão de veículo no Sollumz.

• Nome que não bate. O handlingId do vehicles.meta tem que ser igual ao handlingName do handling.meta.
• Arquivo não carregado. O handling.meta precisa de files mais data_file 'HANDLING_FILE'.
• Nome usado duas vezes. Se dois resources definem o mesmo handlingName, suas edições podem estar indo para o que o jogo não está usando. Use um nome único por veículo.
• Bloco de sub-handling errado. Um VEHICLE_TYPE_BIKE precisa de CBikeHandlingData, um carro de CCarHandlingData.
• Edições não aplicadas. Reinicie o resource, reconecte e dê spawn em um veículo novo antes de julgar uma mudança.

Os IDs de kit do carcols.meta são compartilhados por todos os veículos do servidor. Quando dois kits têm o mesmo id, o jogo move um deles para outro ID, e os veículos que usam aquele kit podem acabar com as peças erradas ou sem nenhuma. Troque o id para um número que nenhum outro veículo usa. Os IDs de sirene e de luz entram em conflito do mesmo jeito.

Confira também se o nome do kit na lista kits do carvariations.meta é igual ao kitName do carcols.meta, e se todo modelo de peça indicado no kit está na pasta stream. Detalhes em carvariations e carcols explicados.

O verificador de conflito de IDs do carcols lista todo ID de kit usado por mais de um carcols.meta no servidor.

O gameName é uma chave de text label, não o nome em si. Adicione o label em um script de client, e mantenha a chave com 11 caracteres ou menos:

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

O layout do vehicles.meta decide os assentos e as animações de entrada, e ele espera certos bones no modelo: bones de assento como seat_dside_f e bones de porta como door_dside_f. Escolha um layout feito para o mesmo tipo de veículo (um layout de moto para uma moto, um layout de duas portas para um carro de duas portas), e confira se o modelo tem os bones que o layout indica. Como os layouts são montados está em vehiclelayouts.meta explicado.

Se nada disso ajudar, remonte o resource do zero com como adicionar um veículo add-on ao FiveM e teste depois de cada arquivo.