Vehicle Meta Files

What is vehicles.meta?

vehicles.meta is the XML file that registers a vehicle model with GTA V. Each entry names the model, its texture dictionary, the handling profile, the engine audio, the seat layout, the vehicle type and class, and dozens of visual settings such as wheel size and LOD distances. Without a vehicles.meta entry an add-on model is only a set of files the game knows nothing about, so it cannot be spawned. In FiveM the file is loaded with the VEHICLE_METADATA_FILE data file type.

Structure of the file

The root element is CVehicleModelInfo__InitDataList. Vehicles are Item entries inside InitDatas, followed by a txdRelationships block that chains texture dictionaries together. A real entry has well over a hundred tags; the ones below are those that matter when installing or renaming a car.

xml
<CVehicleModelInfo__InitDataList>
  <residentTxd>vehshare</residentTxd>
  <InitDatas>
    <Item>
      <modelName>mycar</modelName>
      <txdName>mycar</txdName>
      <handlingId>MYCAR</handlingId>
      <gameName>MYCAR</gameName>
      <vehicleMakeName>MYBRAND</vehicleMakeName>
      <audioNameHash>ADDER</audioNameHash>
      <layout>LAYOUT_LOW</layout>
      <type>VEHICLE_TYPE_CAR</type>
      <vehicleClass>VC_SUPER</vehicleClass>
      <!-- many more tags -->
    </Item>
  </InitDatas>
  <txdRelationships>
    <Item>
      <parent>vehshare</parent>
      <child>mycar</child>
    </Item>
  </txdRelationships>
</CVehicleModelInfo__InitDataList>
Abridged vehicles.meta entry

Key tags

TagMeaning
modelNameThe spawn name. Must equal the .yft file name.
txdNameThe .ytd that holds the vehicle's textures.
handlingIdThe handlingName of the profile to use in handling.meta.
gameNameA text label key for the display name, not the display name itself.
audioNameHashThe engine sound set, usually the name of a stock vehicle.
layoutThe seat and animation layout from vehiclelayouts.meta.
typeVehicle type, for example VEHICLE_TYPE_CAR or VEHICLE_TYPE_BIKE.
vehicleClassClass shown in menus and used by scripts, for example VC_SPORT.
lodDistancesDistances at which the model switches LOD.

Need this file for a car that came without one? The Vehicles.meta Generator writes it from a spawn name. Open the Vehicles.meta Generator

Loading it in FiveM

The file has to be both sent to clients and registered with the game. That takes two entries in fxmanifest.lua:

lua
files {
    'data/vehicles.meta',
}

data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'

Because gameName is only a label key, the car's name shows as NULL on the HUD until a client script registers the label, for example AddTextEntry('MYCAR', 'My Car'). An add-on zip from the converter includes such a script as vehicle_names.lua, with a name derived from the key; edit the quoted text in it to rename the car. For any other resource, the NULL name fix has the complete script and the manifest line that loads it.

Common errors and fixes

  • Invalid model when spawning: modelName does not match the .yft name, or the data_file line is missing. See invalid model.
  • Car has no textures: txdName does not match the .ytd file name.
  • Car drives like a default vehicle or not at all: handlingId does not match any handlingName that is loaded.
  • Car is silent or sounds wrong: audioNameHash points at a sound set that does not exist. Use a stock vehicle name from the GTA 5 vehicle spawn names list, or see the custom engine sounds guide.
  • Two cars interfere with each other: two resources define the same modelName. Model names must be unique across the server.

The free Vehicles.meta Generator writes a valid vehicles.meta, a matching carvariations.meta, the display-name script and the manifest from a single spawn name.

Frequently asked questions

Where does vehicles.meta go in a FiveM resource?

Anywhere outside the stream folder, most often in a data folder or the resource root. It must be listed under files in fxmanifest.lua and registered with a data_file line of type VEHICLE_METADATA_FILE.

Does a replace vehicle need a vehicles.meta?

No. A replace vehicle reuses the entry of the stock car it overwrites. You only add a vehicles.meta if you want to change that car's settings.

Why does my car show NULL as its name?

The gameName tag is a text label key. If no script registers a label for that key with AddTextEntry, the game has no text to display and shows NULL. Add-on zips from this site's converter include that script as vehicle_names.lua; for other resources you add it yourself.

Skip the manual work

Paste a gta5-mods.com vehicle link and get a FiveM-ready resource with the manifest and metas in place. 3 free conversions, no signup.

  • 3 conversions free, no account needed
  • 2 more free if you leave an email
  • After that: $15 once for unlimited conversions and the Pro tools. No subscription, 14-day refund policy