carcols.meta and carvariations.meta: How Vehicle Customization Is Wired

Two metadata files control vehicle customization in GTA V: carcols.meta defines the available customization options globally, and carvariations.meta assigns specific subsets of those options to individual vehicles. The GTAMods wiki documents both. This post walks through what each file is responsible for.

carcols.meta: the global definitions

The GTAMods wiki summary: "Carcols controls vehicle colors, license plates, mod kits, wheels, and lights." Importantly, carcols is "not for assigning these things to particular vehicles, for that see carvariations.ymt."

The documented top-level sections of carcols.meta are:

• VehiclePlates - license plate textures and font settings
• Colors - vehicle paint colors with metallic properties
• MetallicSettings - shine/specular characteristics for paint finishes
• WindowColors - tint options for vehicle windows
• Kits - modification packages with visual and performance changes (this is where tuning shop options live)
• Wheels - rim and tire options organized by category
• Lights - indicator, headlight, taillight, and reversing light configurations
• Sirens - emergency vehicle siren settings
• GlobalVariationData - default xenon light properties
• XenonLightColors - custom xenon lighting options

carvariations.meta: the per-vehicle assignments

carvariations.meta is what tells the engine "vehicle X uses color set A, mod kit B, wheel category C, light cluster D." Without carvariations, your vehicle has no defined paint slots, no tuning shop entries, and no specific wheel options - it can only render with whatever defaults the engine guesses.

For each vehicle, the carvariations entry typically includes:

• A reference to the modKit defined in carcols.meta
• Color combinations the vehicle can spawn or be painted with
• Wheel type and a list of compatible wheel rim options
• Window tint defaults
• License plate type

How they get registered in fxmanifest.lua

Both files need to be ship-listed AND registered with the data file system:

files {
  'data/carcols.meta',
  'data/carvariations.meta',
}

data_file 'CARCOLS_FILE' 'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

Forgetting either step is one of the most common reasons "the car spawns but the tuning shop has no options" - the meshes are present and the YFT loaded fine, but the customization data never registered.

Mod kits in detail

The Kits section of carcols.meta defines modification packages. Each kit has a unique numeric ID and a list of available modifications: spoilers, bumpers, exhausts, hoods, roofs, side skirts, etc. Each modification slot references a specific mesh on the vehicle (using the mod_* dummy names like mod_bumper_f, mod_spoiler).

The carvariations entry for a specific vehicle then references the kit ID, and that connection is what makes the tuning shop show those options.

Common gotchas

• modKit ID conflicts. Two custom vehicles using the same numeric kit ID will collide. Reserve unique IDs for your custom vehicles.
• Missing dummy on the model. A kit can advertise mod_spoiler, but if there is no mod_spoiler dummy on the chassis, the option appears in the menu but does nothing.
• Color combinations. Without a colorCombinations entry in carvariations, your vehicle paint slots may not respond as expected.

Sources

• GTAMods Wiki: Carcols.ymt
• GTAMods Wiki: vehicles.meta (cross-reference for vehicle-side fields)