Reference

vehicles.meta

The declaration file for a vehicle: which model and textures to load, which handling to use, how it seats and films, where it spawns, and the flags that change its behaviour.

File structure

vehicles.meta declares one <Item> per vehicle inside <InitDatas>. It is the file the game reads to know a vehicle exists at all — if a model is missing here, nothing else you write will be loaded.

The second half of the file, <txdRelationships>, describes texture inheritance: which parent dictionary a vehicle texture dictionary falls back to. Most add-ons declare their own txd as a child of vehicles_.._txd or leave it standalone.

Skeleton

<CVehicleModelInfo__InitDataList>
  <residentTxd>vehshare</residentTxd>
  <InitDatas>
    <Item>
      <modelName>mycar</modelName>
      <txdName>mycar</txdName>
      <handlingId>MYCAR</handlingId>
      <!-- … -->
    </Item>
  </InitDatas>
  <txdRelationships>
    <Item>
      <parent>vehicles_sports_interior</parent>
      <child>mycar</child>
    </Item>
  </txdRelationships>
</CVehicleModelInfo__InitDataList>

Identity and assets

Name	Type	Description	Typical
modelName	string	Spawn name and the name of the .yft file. Lowercase, no spaces, must be unique on the server.	—
txdName	string	Texture dictionary to load. Almost always identical to modelName.	—
handlingId	string	The handlingName to pull from handling.meta. Case-sensitive.	—
gameName	string	Internal label used to look up the display name in the GXT text files.	—
vehicleMakeName	string	Manufacturer label, shown before the model name in-game. Leave empty for no make.	—
audioNameHash	string	Engine and horn sound set to inherit. Empty means the game uses modelName, which only works if a matching audio set exists — point it at a stock vehicle instead.	—
layout	enum	Seating and entry/exit animation set. Decides how many seats there are and how peds get in. Must match the seat bones present in the model.	LAYOUT_STANDARD, LAYOUT_LOW, LAYOUT_VAN, LAYOUT_TRUCK
ptfxAssetName	string	Particle effect asset for exhaust smoke, damage and destruction effects.	weap_xs_vehicle_weapons or null
expressionDictName	string	Animation dictionary for procedural bone movement such as suspension travel.	null
expressionName	string	Specific expression inside that dictionary.	null
animConvRoofDictName	string	Animation dictionary for a convertible roof. Only used when the model has one.	—
animConvRoofName	string	Roof animation clip name.	—
animConvRoofWindowsAffected	string	Which windows drop when the roof folds.	—
vfxInfoName	enum	Visual effect profile — exhaust, tyre smoke and dirt behaviour.	VFXVEHICLEINFO_CAR_GENERIC
explosionInfo	enum	Explosion profile when the vehicle is destroyed.	EXPLOSION_INFO_DEFAULT
scenarioLayout	string	Scenario set used by ambient peds around the parked vehicle. Usually empty.	—
coverBoundOffsets	string	Named cover offset profile telling NPCs where they can take cover against the body.	—
NmBraceOverrideSet	string	Euphoria bracing set used by occupants before a crash.	—

Cameras and first person

These fields decide where the player looks from. The offsets are the ones you will actually spend time on: they are what stops the first-person camera sitting inside the roof or behind the seat.

Name	Type	Description	Typical
cameraName	enum	Third-person follow camera profile — distance and height behind the vehicle.	DEFAULT_FOLLOW_VEHICLE_CAMERA
aimCameraName	enum	Camera used while aiming a weapon from the vehicle.	DEFAULT_THIRD_PERSON_VEHICLE_AIM_CAMERA
bonnetCameraName	enum	Hood camera profile. Pick the variant matching the vehicle height.	VEHICLE_BONNET_CAMERA_STANDARD
povCameraName	enum	First-person driver camera profile.	DEFAULT_POV_CAMERA
PovCameraOffset	x y z, metres	Fine position of the first-person camera. Adjust Z to raise or lower the eye line, Y to move forward or back from the seat.	—
PovCameraVerticalAdjustmentForRollCage	float	Extra vertical shift used when a roll cage mod is fitted.	—
PovPassengerCameraOffset	x y z	Same offset for the front passenger.	—
PovRearPassengerCameraOffset	x y z	Same offset for rear seats.	—
FirstPersonDriveByIKOffset	x y z	Hand position when shooting out of the window in first person.	—
FirstPersonProjectileDriveByIKOffset	x y z	Same, for throwing grenades and similar.	—
FirstPersonDriveByUnarmedIKOffset	x y z	Arm position when leaning out unarmed.	—
FirstPersonMobilePhoneOffset	x y z	Where the phone sits in the driver’s hand in first person.	—
FirstPersonPassengerMobilePhoneOffset	x y z	Same for the passenger.	—
shouldUseCinematicViewMode	boolean	Whether the cinematic camera mode is offered for this vehicle.	true
shouldCameraTransitionOnClimbUpDown	boolean	Smooths the camera when climbing onto or off the vehicle.	—
shouldCameraIgnoreExiting	boolean	Keeps the camera still while the player exits.	—
cinematicPartCamera	list	Named cameras used by the cinematic mode to frame wheels and engine parts.	—

Wheels, dirt and LOD

Name	Type	Description	Typical
wheelScale	float	Front wheel size multiplier applied to aftermarket wheels. Too large and the wheels poke through the arches; too small and they float inside them.	0.2–0.35
wheelScaleRear	float	Same for the rear wheels.	0.2–0.35
dirtLevelMin	0.0–1.0	Lowest dirt level the vehicle can spawn with.	0.0
dirtLevelMax	0.0–1.0	Highest dirt level. Set both to 0.0 for a vehicle that always spawns clean.	0.3–0.7
envEffScaleMin / envEffScaleMax	float	Range of environmental weathering applied to the paint.	—
envEffScaleMin2 / envEffScaleMax2	float	Second weathering channel, used by some shaders.	—
damageMapScale	float	Intensity of the visual damage texture blended over the body.	0.3–0.6
damageOffsetScale	float	How far the mesh physically deforms on impact.	0.3–0.6
diffuseTint	ARGB hex	Global tint applied over the diffuse textures. 0x00FFFFFF leaves the paint untouched.	—
steerWheelMult	float	Rotation multiplier for the steering wheel model — visual only.	1.0
HDTextureDist	metres	Distance at which the high-definition textures stop being used.	5.0–15.0
lodDistances	list of floats	Distances at which each LOD level swaps in, from highest detail to lowest. Shorter distances stream less geometry and cost less performance; too short and players see models visibly popping.	—
visibleSpawnDistScale	float	Scales how far away the vehicle can appear in traffic.	1.0
identicalModelSpawnDistance	metres	Minimum distance before the same model can spawn again nearby.	20–80
maxNumOfSameColor	integer	How many of this vehicle can share a colour on screen at once.	1–10
minSeatHeight	float	Lowest seat height, used to place occupants correctly.	—
defaultBodyHealth	float	Starting body health. 1000 is the standard value.	1000

Classification and spawning

Name	Type	Description	Typical
type	enum	Vehicle category the physics engine uses. Must match what the model actually is.	VEHICLE_TYPE_CAR
plateType	enum	Which number plates the model carries.	VPT_FRONT_AND_BACK_PLATES
dashboardType	enum	Dial set used for the first-person dashboard.	VDT_GENTAXI
vehicleClass	enum	Class shown in menus and used by races and dealership scripts.	VC_SPORT
wheelType	enum	Which aftermarket wheel category is offered in the mod shop.	VWT_SPORT
swankness	enum	Perceived wealth of the vehicle. Affects NPC reactions and where it spawns naturally.	SWANKNESS_3
frequency	0–100	How often the vehicle appears in ambient traffic. 0 stops it spawning naturally.	0 for add-ons
maxNum	integer	Maximum number allowed in the world at once.	1–10
AllowPretendOccupants	boolean	Lets the game draw fake occupants at distance instead of streaming real peds.	—
pretendOccupantsScale	float	Density of those fake occupants.	—
AllowJoyriding	boolean	Whether NPCs may steal and joyride it.	—
AllowSundayDriving	boolean	Whether it appears in relaxed ambient traffic.	—
AllowBodyColorMapping	boolean	Whether the secondary colour maps onto body panels.	—
rewards	list	Reward entries granted for owning or delivering the vehicle.	—
trackerPathWidth	float	Width used by the AI pathing system when the vehicle follows roads.	2.0
weaponForceMult	float	Multiplier on the physical push bullets apply to the vehicle.	1.0

type values

Name	Description
VEHICLE_TYPE_CAR	Four-wheeled ground vehicle. The default for almost every add-on.
VEHICLE_TYPE_BIKE	Motorcycle, with lean physics.
VEHICLE_TYPE_BICYCLE	Pedal-powered, uses stamina.
VEHICLE_TYPE_QUADBIKE	Quad — car physics with bike animations.
VEHICLE_TYPE_BOAT	Water vehicle with buoyancy and propeller physics.
VEHICLE_TYPE_HELI	Helicopter, requires CFlyingHandlingData.
VEHICLE_TYPE_PLANE	Fixed-wing aircraft.
VEHICLE_TYPE_SUBMARINE	Fully submersible vehicle.
VEHICLE_TYPE_SUBMARINECAR	Amphibious car that submerges.
VEHICLE_TYPE_AMPHIBIOUS_AUTOMOBILE	Car that floats and drives on water.
VEHICLE_TYPE_AMPHIBIOUS_QUADBIKE	Amphibious quad.
VEHICLE_TYPE_TRAILER	Towed unit with no engine.
VEHICLE_TYPE_TRAIN	Rail vehicle, follows track nodes.

vehicleClass values

Name	Description
VC_COMPACT	Small city cars.
VC_SEDAN	Saloons.
VC_SUV	Sport utility vehicles.
VC_COUPE	Two-door coupés.
VC_MUSCLE	American muscle.
VC_SPORT_CLASSIC	Classic sports cars.
VC_SPORT	Modern sports cars.
VC_SUPER	Supercars and hypercars.
VC_MOTORCYCLE	Motorcycles.
VC_OFF_ROAD	Off-roaders and buggies.
VC_INDUSTRIAL	Heavy industrial vehicles.
VC_UTILITY	Work and utility vehicles.
VC_VAN	Vans.
VC_CYCLE	Bicycles.
VC_BOAT	Boats.
VC_HELICOPTER	Helicopters.
VC_PLANE	Planes.
VC_SERVICE	Buses and service vehicles.
VC_EMERGENCY	Police, fire and ambulance.
VC_MILITARY	Military vehicles.
VC_COMMERCIAL	Trucks and haulage.
VC_TRAIN	Rail.
VC_OPEN_WHEEL	Formula-style open wheelers.

plateType values

Name	Description
VPT_FRONT_AND_BACK_PLATES	Plates at both ends.
VPT_FRONT_PLATES	Front plate only.
VPT_BACK_PLATES	Rear plate only.
VPT_NONE	No plates at all.

wheelType values

Name	Description
VWT_SPORT	Sport wheels.
VWT_MUSCLE	Muscle wheels.
VWT_LOWRIDER	Lowrider wheels.
VWT_SUV	SUV wheels.
VWT_OFFROAD	Off-road wheels.
VWT_TUNER	Tuner wheels.
VWT_BIKE	Motorcycle wheels.
VWT_HIEND	High-end wheels.
VWT_SUPERMOD1 … VWT_SUPERMOD4	Benny’s and DLC wheel sets.

Doors, extras and trailers

Name	Type	Description
doorsWithCollisionWhenClosed	list	Doors that keep collision while shut. Needed for large doors so players cannot walk through them.
driveableDoors	list	Doors the vehicle can still be driven with while open.
bumpersNeedToCollideWithMap	boolean	Forces bumper collision against world geometry. Costs performance — enable only if needed.
needsRopeTexture	boolean	Loads the rope texture for tow trucks and cranes.
requiredExtras	list	Extras that must always be enabled when the vehicle spawns.
extraIncludes	list	Extras that must appear together. Enabling one forces the others on.
trailers	list	Model names of trailers this vehicle can tow.
additionalTrailers	list	Secondary trailers, for double or triple rigs.
drivers	list	Ped models that spawn as the default driver in ambient traffic.
buoyancySphereOffset	x y z	Offset of the buoyancy sphere, used when the vehicle touches water.
buoyancySphereSizeScale	float	Size of that sphere. Larger values float the vehicle higher.
pOverrideRagdollThreshold	block	Overrides the impact force needed to ragdoll the occupants.
firstPersonDrivebyData	list	Named drive-by data sets, one per seat. Must match the seat count implied by the layout, or drive-by animations break.

The flags field

The <flags> element takes a space-separated list of FLAG_ constants. There are well over a hundred; the ones below are the ones that come up constantly when shipping an add-on. Unknown flags are ignored silently, so a typo simply does nothing.

Commonly used flags

Name	Description
FLAG_SPORTS	Marks the vehicle as sporty. Affects AI driving and some radio behaviour.
FLAG_HAS_LIVERY	Required for liveries to appear in the mod shop.
FLAG_HAS_INTERIOR_EXTRAS	The model has extras inside the cabin.
FLAG_EXTRAS_STRONG	Extras do not break off on impact.
FLAG_EXTRAS_ALL	All extras spawn enabled by default.
FLAG_EXTRAS_REQUIRE	Extras follow the requiredExtras list.
FLAG_EXTRAS_ONLY_BREAK_WHEN_DESTROYED	Extras survive until the vehicle is destroyed.
FLAG_NO_BOOT	The vehicle has no opening boot.
FLAG_DONT_CLOSE_DOOR_UPON_EXIT	Doors stay open when the driver leaves.
FLAG_IS_ELECTRIC	Electric drivetrain — no engine sound, no fuel.
FLAG_IS_OFFROAD_VEHICLE	Improves AI handling off-road.
FLAG_IS_BULKY	Treated as a large vehicle by traffic and pathing.
FLAG_BIG	Uses large-vehicle pathing rules.
FLAG_AVERAGE_CAR	Standard AI driving profile.
FLAG_POOR_CAR	Low-value vehicle, spawns in poorer areas.
FLAG_RICH_CAR	High-value vehicle, spawns in wealthy areas.
FLAG_PEDS_CAN_STAND_ON_TOP	Peds can walk on the roof.
FLAG_CAN_BE_DRIVEN_ON	Other vehicles can drive over it — flatbeds and ramps.
FLAG_HAS_BULLETPROOF_GLASS	Windows resist gunfire.
FLAG_NO_BROKEN_DOWN_SCENARIO	Never spawns as a broken-down roadside vehicle.
FLAG_HAS_NO_ROOF	Open-top vehicle — changes rain and camera behaviour.
FLAG_CANNOT_BE_MODDED	Blocks the vehicle from entering the mod shop.
FLAG_HAS_TURRET_SEAT_ON_VEHICLE	The vehicle carries a turret seat.
FLAG_USE_HIGHER_DOOR_TORQUE	Heavier doors, for large or armoured vehicles.
FLAG_HEADLIGHTS_USE_ACTUAL_BONE_POS	Light coronas follow the headlight bones exactly.
FLAG_HAS_REAR_MOUNTED_ENGINE	Engine damage and fire come from the rear.
FLAG_DONT_TIMESLICE_WHEELS	Updates wheel physics every frame. Smoother, more expensive.
FLAG_USE_FAT_INTERIOR_LIGHT	Wider interior light cone.
FLAG_INCREASE_PED_COMFORT_IN_VEHICLE	Reduces occupant ragdoll reactions.
FLAG_RECESSED_HEADLIGHT_CORONAS	Pulls the headlight coronas back into the body.
FLAG_RECESSED_TAILLIGHT_CORONAS	Same for the rear lights.
FLAG_SPAWN_ON_TRAILER	Can spawn already loaded on a trailer.
FLAG_LAW_ENFORCEMENT	Treated as a police vehicle by the AI and wanted system.
FLAG_EMERGENCY_SERVICE	Treated as an emergency vehicle.
FLAG_ALLOWS_RAPPEL	Peds can rappel from it — helicopters.
FLAG_DONT_SPAWN_IN_CARGEN	Never spawns from static car generators.