Documentation
Vehicle Meta Files
vehicles.meta, handling.meta, carcols, carvariations explained.
Every custom vehicle in FiveM requires a set of XML meta files that tell the game engine how to treat the vehicle. These four files are the minimum required set.
The core identity file — registers the model with the game engine, sets its class, audio, layout, and spawn behaviour. Full field reference is below.
Controls all physics parameters. The most important values are fMass, fInitialDriveForce, fDriveInertia, and the traction/suspension blocks. Always start from a known-good vanilla vehicle and adjust incrementally.
Maps livery indices to texture dictionary entries and configures paint layer behaviour. Each variation entry defines which YTD textures are loaded for that livery slot and what extras are spawned with it.
Defines emergency lighting kits and siren colour sequences. Each Kit entry links to a set of light IDs and their flash patterns, which correspond to the sequences you build in Blinklab.
vehicles.meta — field reference
vehicles.meta is the core file that defines a vehicle's properties in FiveM. It uses binary XML format — edit it as plain text in any text editor after exporting from OpenIV.
Core identity
| Field | Description |
|---|---|
| modelName | Internal spawn name (e.g. police3). Must match your .yft filename exactly. Always lowercase. |
| txdName | Texture dictionary name the model references. Usually identical to modelName. |
| handlingId | Links to the handling entry in handling.meta. Must match the handlingName value there. |
| gameName | Display name shown in-game (e.g. in the chop shop). Usually a GXT label. |
| vehicleMakeName | Manufacturer label shown in the HUD (e.g. BRAVADO). Can be a custom GXT key or a vanilla value. |
| audioNameHash | Determines engine and exhaust sounds. Use a vanilla vehicle name (e.g. POLICE) to inherit its audio. |
Layout & camera
| Field | Description |
|---|---|
| layout | Vehicle layout hash — controls door/seat animations and enter/exit positions. Match to a vanilla vehicle with a similar door count and silhouette. |
| cameraName | Third-person camera rig. Controls how far back and high the camera sits. |
| aimCameraName | Camera used when aiming a weapon from the vehicle. |
| bonnetCameraName | Bonnet (hood) cam preset name. |
| povCameraName | First-person camera preset. |
| PovCameraOffset | XYZ offset applied to the first-person camera inside the cabin. |
Visual & physics
| Field | Description |
|---|---|
| wheelScale | Front wheel render scale multiplier. 1.0 = model default. |
| wheelScaleRear | Rear wheel render scale multiplier. |
| defaultBodyHealth | Starting body health. Vanilla vehicles use 1000.0. |
| damageMapScale | Scales how quickly visual damage accumulates (dents, scratches). |
| dirtLevelMax | Maximum dirt accumulation level (0.0 – 1.0). |
| HDTextureDist | Distance at which the high-detail texture is swapped in. |
| lodDistances | Array of four LOD switch distances (near → far). |
Spawning & performance
| Field | Description |
|---|---|
| vehicleClass | Integer 0–20 that determines the vehicle category (see table below). |
| vehicleType | Engine type: AUTOMOBILE, BIKE, QUAD, PLANE, HELI, BOAT, SUBMARINE, TRAILER. |
| plateType | Licence plate style (0 = blue/white, 1 = yellow/black, etc.). |
| wheelType | Wheel category for mod shop options (0 = Sport, 1 = Muscle, etc.). |
| estimatedMaxSpeed | Approximate top speed in m/s (0–300). Used by AI pathfinding and the minimap. |
| maxNum | Max simultaneous instances spawned in traffic. |
| frequency | Traffic spawn frequency weight relative to other vehicles in the same class. |
| swankness | Prestige level that determines spawn areas (0 = common, 4 = very exclusive). |
| seats | Number of passenger seats (driver is not counted). |
| visibleSpawnDistScale | Multiplier on the distance at which the vehicle becomes visible. |
Vehicle classes (0–20)
| ID | Class | Example |
|---|---|---|
| 0 | Compact | Blista |
| 1 | Sedan | Stanier |
| 2 | SUV | Granger |
| 3 | Coupe | Exemplar |
| 4 | Muscle | Dominator |
| 5 | Sports Classic | Monroe |
| 6 | Sports | Elegy RH8 |
| 7 | Super | Adder |
| 8 | Motorcycle | Bati 801 |
| 9 | Off-road | Mesa |
| 10 | Industrial | Phantom |
| 11 | Utility | Sadler |
| 12 | Van | Rumpo |
| 13 | Cycle | Tribike |
| 14 | Boat | Dinghy |
| 15 | Helicopter | Maverick |
| 16 | Plane | Luxor |
| 17 | Service | Taxi |
| 18 | Emergency | Police |
| 19 | Military | Rhino |
| 20 | Commercial | Packer |
Minimal example
<Item type="CVehicleModelInfo__InitDataList__InitData"> <modelName>my_police</modelName> <txdName>my_police</txdName> <handlingId>POLICE</handlingId> <gameName>MY_POLICE</gameName> <vehicleMakeName>CHEVAL</vehicleMakeName> <audioNameHash>POLICE</audioNameHash> <layout>LAYOUT_STD_HIGHSEAT</layout> <cameraName>DEFAULT_FOLLOW_VEHICLE_CAMERA</cameraName> <aimCameraName>DEFAULT_SCRIPTED_CAMERA</aimCameraName> <vehicleClass>18</vehicleClass> <vehicleType>AUTOMOBILE</vehicleType> <plateType>0</plateType> <wheelType>0</wheelType> <defaultBodyHealth value="1000.00" /> <maxNum value="10" /> <frequency value="30" /> <seats value="3" /> </Item>
modelName and txdName. The game engine is case-sensitive on Linux-based servers and a mismatch will cause the vehicle to silently fail to load.Common issues
Vehicle doesn't spawn
modelName doesn't match the .yft filename, or the stream folder path in fxmanifest.lua is wrong.
Textures missing / black model
txdName doesn't match the .ytd filename, or the .ytd isn't declared in the files block of fxmanifest.lua.
Wrong engine sound
audioNameHash references a vehicle that doesn't exist in this context. Use a guaranteed vanilla value like POLICE or SULTAN.
Broken enter/exit animations
layout value doesn't suit the vehicle body shape. Copy the layout from a vanilla vehicle with a similar door count and silhouette.
AI drives erratically
estimatedMaxSpeed is set too high or too low. Match it to the actual top speed from fInitialDriveMaxFlatVel in handling.meta.
Discussion