Como adicionar carros mods no FiveM GTA RP: passo a passo completo

Adicionar carros customizados num servidor FiveM RP é uma das demandas mais comuns de owners — e também uma das que mais geram dor de cabeça por organização ruim. O problema raramente é o arquivo do carro em si: é a estrutura de resource, os metadados obrigatórios e a ordem de streaming.

Este tutorial é para owners e desenvolvedores de servidores FiveM GTA RP que querem adicionar veículos addon (que não substituem carros vanilla) de forma organizada, sem quebrar concessionárias do framework e sem virar uma pasta [cars] ingovernável com 400 resources soltos.

Tempo estimado de execução: 20 a 30 minutos por carro, ou 1 hora para montar um pack organizado com 10 a 20 veículos. Vou cobrir desde a estrutura de pastas até o registro no banco de dados pro carro aparecer na concessionária do seu framework.

Pré-requisitos

Garanta que você não está rodando em modo OneSync legacy num servidor moderno — addons de carro funcionam melhor em OneSync infinity, que é o padrão atual do FiveM.

Estrutura de pastas do resource

A primeira regra: um resource por carro ou um resource por pack temático (carros policiais, supercarros, sedans). Não misture carros aleatórios num único resource gigante — debugar fica impossível quando um deles quebra.

A estrutura padrão de um carro addon é:

resources/[cars]/lambo2024/
├── fxmanifest.lua
├── stream/
│   ├── lambo2024.yft
│   ├── lambo2024_hi.yft
│   └── lambo2024.ytd
└── data/
    ├── vehicles.meta
    ├── carvariations.meta
    ├── carcols.meta
    └── handling.meta

A pasta [cars] com colchetes é uma categoria — o FiveM reconhece automaticamente e organiza todos os resources de carros dentro dela. Não é obrigatório, mas mantém o resources/ limpo quando você tem 200 carros.

Criando o resource passo a passo

Vou usar como exemplo um carro fictício chamado lambo2024. Substitua pelo nome do seu modelo em todos os comandos.

cd /caminho/do/servidor/resources
mkdir -p [cars]/lambo2024/stream
mkdir -p [cars]/lambo2024/data

# via SFTP ou cp local
cp lambo2024.yft     [cars]/lambo2024/stream/
cp lambo2024_hi.yft  [cars]/lambo2024/stream/
cp lambo2024.ytd     [cars]/lambo2024/stream/

fx_version 'cerulean'
game 'gta5'

author 'NomeDoCriador'
description 'Lamborghini 2024 Addon'
version '1.0.0'

files {
    'data/vehicles.meta',
    'data/carvariations.meta',
    'data/carcols.meta',
    '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'
data_file 'HANDLING_FILE'            'data/handling.meta'

# server.cfg
ensure [cars]
# ou pra resources individuais:
ensure lambo2024

refresh
ensure lambo2024

Validando os metadados

A maioria dos travamentos vem de vehicles.meta ou handling.meta malformados. Vale conferir manualmente antes do primeiro start.

<Item>
    <modelName>lambo2024</modelName>
    <txdName>lambo2024</txdName>
    <handlingId>lambo2024</handlingId>
    <gameName>lambo2024</gameName>
    <vehicleMakeName>LAMBORGHINI</vehicleMakeName>
    <!-- resto da config -->
</Item>

<Item type="CHandlingData">
    <handlingName>lambo2024</handlingName>
    <fMass value="1700.00" />
    <fInitialDragCoeff value="9.85" />
    <!-- ... -->
</Item>

Registrando o carro no framework RP

Adicionar o resource não é suficiente — o carro precisa estar na tabela vehicles do banco pra aparecer na concessionária e ser comprável pelos jogadores.

ESX Framework

Em ESX legacy, conecte no MySQL e rode:

INSERT INTO vehicles (name, model, price, category)
VALUES ('Lamborghini 2024', 'lambo2024', 850000, 'super');

O campo model precisa ser EXATAMENTE o spawn name do carro (mesmo valor do <modelName> do vehicles.meta).

QBCore Framework

Em QBCore, edite qb-core/shared/vehicles.lua:

['lambo2024'] = {
    ['name'] = 'Lamborghini 2024',
    ['brand'] = 'Lamborghini',
    ['model'] = 'lambo2024',
    ['price'] = 850000,
    ['category'] = 'super',
    ['hash'] = `lambo2024`,
    ['shop'] = 'pdm',
},

Reinicie o qb-core depois (restart qb-core no console).

Verificação

Pra confirmar que tudo funcionou, entre no servidor como admin e use:

/car lambo2024

Ou em frameworks com command de spawn próprio (/spawncar no ESX, /admincar em alguns scripts QB). O carro deve aparecer com textura completa, som de motor e física consistente.

Verifique também o console do servidor durante o start. Output esperado:

Started resource lambo2024
Loading vehicle metadata: data/vehicles.meta
Loading handling: data/handling.meta

Se aparecer Failed to load, Unable to parse XML ou Duplicate handling ID, o erro está num dos .meta. Veja a seção de resolução de problemas abaixo.

Resolução de problemas

Carro spawna sem textura (chequered)

Causa: divergência entre modelName no vehicles.meta e o nome do .yft, ou .ytd faltando no stream. Solução: confirme que os 3 nomes batem (arquivo, modelName, txdName) e que o .ytd está em stream/.

Erro “Vehicle not found” ao usar /car

Causa: resource não foi carregado ou ensure não está no server.cfg. Solução: rode refresh seguido de ensure lambo2024 no console. Se persistir, confira que o fxmanifest.lua declara os 4 data_file corretamente.

Servidor trava durante o load

Causa: handling.meta com valor inválido (texto onde espera número) ou XML malformado. Solução: rode developer 1 no console do servidor antes do start pra ver mensagens detalhadas. Geralmente o erro aponta a linha exata.

Carro aparece na concessionária mas não compra

Causa: registro no banco está com model errado. Solução: confirme que o valor do campo model na tabela vehicles é idêntico ao spawn name (case-sensitive).

Próximos passos

Depois do primeiro carro funcionando, vale automatizar o resto do fluxo:

• Criar um pack único com 10 a 30 carros agrupados por categoria (super, sport, sedan) em vez de 30 resources separados.
• Adicionar carcols.meta customizado pra liberar tuning visual nos seus carros (rodas, capôs, escapamentos).
• Implementar lazy load com set sv_streamerMode 1 em servidores com 400+ veículos pra reduzir tempo de download inicial.
• Configurar handling realista usando ferramentas como o Handling Editor in-game antes de exportar pro .meta final.
• Versionar o [cars]/ em git separado pra rastrear mudanças e fazer rollback fácil.

Se você está rodando um servidor FiveM RP em produção com pack pesado de carros, uma VPS dedicada pra game servers da Hostini entrega CPU single-thread alto e SSD NVMe — o que faz diferença real no tempo de stream de assets quando 64 jogadores conectam ao mesmo tempo.