vehicles.meta explained, field by field

vehicles.meta holds one <Item> per vehicle inside <InitDatas>. When the file is loaded, the game creates a vehicle model for each Item and resolves the things it points at: the handling entry, the layout, the cameras and the explosion info. On FiveM it is loaded with data_file 'VEHICLE_METADATA_FILE'.

The tag names below come from the game's own data schema, so they are exact. A typical add-on entry starts as a copy of the stock vehicle that is closest to it, with the identity fields changed.

<?xml version="1.0" encoding="UTF-8"?>
<CVehicleModelInfo__InitDataList>
  <residentTxd>vehshare</residentTxd>
  <residentAnims />
  <InitDatas>
    <Item>
      <modelName>mycar</modelName>
      <txdName>mycar</txdName>
      <handlingId>MYCAR</handlingId>
      <gameName>MYCAR</gameName>
      <vehicleMakeName>KARIN</vehicleMakeName>
      <audioNameHash>sultan</audioNameHash>
      <layout>LAYOUT_STANDARD</layout>
      <cameraName>DEFAULT_FOLLOW_VEHICLE_CAMERA</cameraName>
      <wheelScale value="0.293000" />
      <wheelScaleRear value="0.293000" />
      <HDTextureDist value="5.000000" />
      <lodDistances content="float_array">
        10.000000
        25.000000
        50.000000
        100.000000
        500.000000
        500.000000
      </lodDistances>
      <flags>FLAG_AVERAGE_CAR FLAG_POOR_CAR</flags>
      <type>VEHICLE_TYPE_CAR</type>
      <plateType>VPT_BACK_PLATES</plateType>
      <dashboardType>VDT_SULTAN</dashboardType>
      <vehicleClass>VC_SPORT</vehicleClass>
      <wheelType>VWT_SPORT</wheelType>
      <!-- copy the remaining tags from the stock vehicle you start from -->
    </Item>
  </InitDatas>
  <txdRelationships>
    <Item>
      <parent>vehshare</parent>
      <child>mycar</child>
    </Item>
  </txdRelationships>
</CVehicleModelInfo__InitDataList>

Five fields tie the entry to the model files and to the other metas, and each one has to match its counterpart exactly.

Field	Meaning	Must match
modelName	Model file name and spawn name.	stream/<modelName>.yft
txdName	Texture dictionary file name.	stream/<txdName>.ytd
handlingId	Name of the handling entry to use.	handlingName in handling.meta
gameName	Text label key for the display name. Stored in a 12-character buffer, so keep it to 11 characters or fewer.	A label added with AddTextEntry
vehicleMakeName	Text label key for the manufacturer. Same length limit.	Optional label

handlingId can point at a stock handling entry such as SULTAN. In that case the vehicle needs no handling.meta of its own.

These fields pick ready-made setups by name. The names refer to entries that already exist in the game, or to ones you add in another meta file.

Field	Schema default	Meaning
layout	LAYOUT_STANDARD	Seat layout from vehiclelayouts.meta: seats, entry points and animations. See vehiclelayouts.meta explained.
audioNameHash	empty	Name of the audio setup to use, normally the model name of a stock vehicle.
cameraName	DEFAULT_FOLLOW_VEHICLE_CAMERA	Third-person follow camera.
aimCameraName	DEFAULT_THIRD_PERSON_VEHICLE_AIM_CAMERA	Camera used while aiming from the vehicle.
bonnetCameraName, povCameraName	empty	Bonnet and first-person cameras.
coverBoundOffsets	STANDARD_COVER_OFFSET_INFO	Cover positions around the vehicle.
explosionInfo	EXPLOSION_INFO_DEFAULT	Which explosion setup is used when the vehicle blows up.
vfxInfoName	VFXVEHICLEINFO_CAR_GENERIC	Visual effects set (exhaust, wheel effects).
numSeatsOverride	-1	Forces the seat count; -1 leaves it to the layout.

lodDistances is a list of six distances in metres that decide which version of the model is drawn. The first value is the range of the high-detail model; when it is greater than zero the game also registers a second model file named <modelName>_hi.

Position	Internal name	Model version drawn up to this distance
1	VLT_HD	High-detail model (_hi.yft).
2	VLT_LOD0	Highest LOD inside the main .yft.
3	VLT_LOD1	Second LOD.
4	VLT_LOD2	Third LOD.
5	VLT_LOD3	Fourth LOD.
6	VLT_LOD_FADE	The vehicle stops being drawn. If this is 0 the game uses the fifth value.

The stock Sultan uses 10, 25, 50, 100, 500, 500. HDTextureDist (default 5.0) is the distance for high-resolution textures. LODs themselves are explained in what are LODs in FiveM vehicles.

Other rendering fields: wheelScale and wheelScaleRear set the front and rear wheel scale, dirtLevelMin and dirtLevelMax (0 to 1) set how dirty the vehicle spawns, diffuseTint is a color tint, and damageMapScale and damageOffsetScale (0 to 1) limit visual deformation.

How the six distances map to the LOD levels of the model, with the values we use, is in how to optimise a FiveM vehicle.

Five fields each take one value from a fixed list. Anything off the list is invalid.

Field	Values
type	VEHICLE_TYPE_CAR, _PLANE, _TRAILER, _QUADBIKE, _DRAFT, _SUBMARINECAR, _AMPHIBIOUS_AUTOMOBILE, _AMPHIBIOUS_QUADBIKE, _HELI, _BLIMP, _AUTOGYRO, _BIKE, _BICYCLE, _BOAT, _TRAIN, _SUBMARINE
vehicleClass	VC_COMPACT (0), VC_SEDAN, VC_SUV, VC_COUPE, VC_MUSCLE, VC_SPORT_CLASSIC, VC_SPORT, VC_SUPER, VC_MOTORCYCLE, VC_OFF_ROAD, VC_INDUSTRIAL, VC_UTILITY, VC_VAN, VC_CYCLE, VC_BOAT, VC_HELICOPTER, VC_PLANE, VC_SERVICE, VC_EMERGENCY, VC_MILITARY, VC_COMMERCIAL, VC_RAIL, VC_OPEN_WHEEL (22)
plateType	VPT_FRONT_AND_BACK_PLATES, VPT_FRONT_PLATES, VPT_BACK_PLATES, VPT_NONE
wheelType	VWT_SPORT, VWT_MUSCLE, VWT_LOWRIDER, VWT_SUV, VWT_OFFROAD, VWT_TUNER, VWT_BIKE, VWT_HIEND, VWT_SUPERMOD1 to VWT_SUPERMOD5
dashboardType	VDT_BANSHEE, VDT_BOBCAT, VDT_CAVALCADE, VDT_COMET, VDT_DUKES, VDT_FACTION, VDT_FELTZER, VDT_FEROCI, VDT_FUTO, VDT_GENTAXI, VDT_MAVERICK, VDT_PEYOTE, VDT_RUINER, VDT_SPEEDO, VDT_SULTAN, VDT_SUPERGT, VDT_TAILGATER, VDT_TRUCK, VDT_TRUCKDIGI, VDT_INFERNUS, VDT_ZTYPE, VDT_LAZER, VDT_SPORTBK, VDT_RACE, VDT_LAZER_VINTAGE, VDT_PBUS2

type has to agree with the handling: a VEHICLE_TYPE_BIKE needs a handling entry with a bike sub-handling block, a car needs a car block. wheelType decides which wheel category the tuning menu offers.

<flags> is a space-separated list of names. Each name switches one behaviour on. The schema defines about 200 of them. The table has the ones add-on authors touch most, with the description from the game data.

Flag	Effect
FLAG_HAS_LIVERY	The vehicle has liveries; a texture is swapped when it spawns.
FLAG_EXTRAS_ALL	All suitable extras are turned on.
FLAG_EXTRAS_REQUIRE	One of the available extras must be picked.
FLAG_EXTRAS_STRONG	Extras do not break off.
FLAG_IS_ELECTRIC	The vehicle has no petrol tank.
FLAG_NO_BOOT	The vehicle is not considered for boot inventory.
FLAG_IS_VAN	Van: the rear doors open sideways.
FLAG_LAW_ENFORCEMENT, FLAG_EMERGENCY_SERVICE	Marks police and emergency vehicles.
FLAG_NO_RESPRAY	Cannot be resprayed at garages.
FLAG_CANNOT_BE_MODDED	Stops the vehicle from being modded.
FLAG_DONT_SPAWN_AS_AMBIENT, FLAG_DONT_SPAWN_IN_CARGEN	Keeps the vehicle out of ambient traffic and out of parked-car generators.
FLAG_DRIVER_NO_DRIVE_BY	The driver cannot do drive-bys.
FLAG_HAS_BULLETPROOF_GLASS	The glass cannot be smashed.
FLAG_RICH_CAR, FLAG_AVERAGE_CAR, FLAG_POOR_CAR	Which kinds of peds can be used as drivers.
FLAG_HEADLIGHTS_USE_ACTUAL_BONE_POS	Headlights use the real bone position.

A group of fields only matters when the game itself spawns the vehicle in traffic. On most roleplay servers add-on vehicles are spawned by scripts, so these can stay at the values of the stock vehicle you copied.

• frequency and maxNum: how often and how many can exist in ambient traffic.
• swankness: SWANKNESS_0 to SWANKNESS_5, from run-down to very nice.
• identicalModelSpawnDistance and maxNumOfSameColor (default 10): keep identical vehicles from clustering.
• defaultBodyHealth: default 1000.
• trailers, drivers, extraIncludes, requiredExtras: lists for trailers that can attach, forced driver models and extras that spawn together.

residentTxd, at the top of the file, names a texture dictionary that stays loaded for the vehicles in the file. Stock files use vehshare, the shared vehicle textures. txdRelationships, at the bottom, is a list of parent and child pairs: when a texture is not found in the child dictionary the game looks in the parent.

That is how a vehicle whose .ytd does not contain the common textures still finds them in vehshare, and how several vehicles can share one custom dictionary: make it the parent of each vehicle's txdName.