carvariations.xml

The carvariations.xml file defines visual customization options for vehicles, including paint colors, wheels, bumpers, spoilers, and other cosmetic modifications.

File Structure

<?xml version="1.0" encoding="UTF-8"?>
<CVehicleVariationsFile>
  <Variations>
    <Item>
      <modelName>adder</modelName>
      <colors>
        <color id="0">
          <primaryColour>0</primaryColour>
          <secondaryColour>0</secondaryColour>
          <pearlColor>0</pearlColor>
        </color>
      </colors>
      <wheels>
        <wheel id="0" modelName="wheel_sr1" />
        <wheel id="1" modelName="wheel_sr2" />
      </wheels>
    </Item>
  </Variations>
</CVehicleVariationsFile>

Color Variations

Define available paint color combinations for a vehicle:

<colors>
  <color id="0">
    <primaryColour>0</primaryColour>   <!-- Main color (black) -->
    <secondaryColour>0</secondaryColour> <!-- Stripe/trim color -->
    <pearlColor>0</pearlColor>         <!-- Pearl effect -->
  </color>
  <color id="1">
    <primaryColour>3</primaryColour>   <!-- Green -->
    <secondaryColour>1</secondaryColour> <!-- White stripe -->
    <pearlColor>27</pearlColor>        <!-- Metal pearl effect -->
  </color>
</colors>

Color Component References

Element	Purpose	Source
primaryColour	Main vehicle color	carcols.xml ID
secondaryColour	Stripe/accent color	carcols.xml ID
pearlColor	Pearl/metallic effect	carcols.xml ID
wheelColor	Wheel color	carcols.xml ID

Wheel Variations

Define available wheel options:

<wheels>
  <wheel id="0" modelName="wheel_sport_01" />
  <wheel id="1" modelName="wheel_sport_02" />
  <wheel id="2" modelName="wheel_lowrider_01" />
  <wheel id="3" modelName="wheel_muscle_01" />
  <wheel id="4" modelName="wheel_suv_01" />
</wheels>

Common Wheel Types

wheel_sport_ - Sports/racing wheels
wheel_tuner_ - Tuner/street wheels
wheel_lowrider_ - Lowrider wheels
wheel_muscle_ - Muscle car wheels
wheel_suv_ - SUV/truck wheels
wheel_offroad_ - Off-road wheels

Exterior Modifications

<modShop>
  <ModType id="0">
    <ModName>Bumper_F</ModName>
    <Modification id="0" modelName="bumper_f_1" />
    <Modification id="1" modelName="bumper_f_2" />
    <Modification id="2" modelName="bumper_f_custom" />
  </ModType>
  <ModType id="1">
    <ModName>Bumper_R</ModName>
    <Modification id="0" modelName="bumper_r_1" />
    <Modification id="1" modelName="bumper_r_2" />
  </ModType>
  <ModType id="2">
    <ModName>Spoiler</ModName>
    <Modification id="0" modelName="spoiler_1" />
    <Modification id="1" modelName="spoiler_2" />
  </ModType>
</modShop>

Common Modification Slots

Type	Slot	Items
Bumper_F	0	Front bumpers
Bumper_R	1	Rear bumpers
Spoiler	2	Spoilers
Skirts	3	Side skirts
Hoods	4	Engine hoods
Roof	5	Roof options
Doors	6	Door variations
Windows	7	Window tints
Exhaust	8	Exhaust pipes
Turbo	9	Turbo upgrades

Livery Variations

Define paint jobs and decal options:

<liveries>
  <livery id="0" modelName="livery_racing_01" />
  <livery id="1" modelName="livery_tribal_01" />
  <livery id="2" modelName="livery_flames_01" />
  <livery id="3" modelName="livery_camo_01" />
</liveries>

Full Example

<?xml version="1.0" encoding="UTF-8"?>
<CVehicleVariationsFile>
  <Variations>
    <Item>
      <modelName>mycustom</modelName>
      
      <colors>
        <color id="0">
          <primaryColour>0</primaryColour>
          <secondaryColour>0</secondaryColour>
          <pearlColor>27</pearlColor>
        </color>
        <color id="1">
          <primaryColour>2</primaryColour>
          <secondaryColour>1</secondaryColour>
          <pearlColor>0</pearlColor>
        </color>
      </colors>
      
      <wheels>
        <wheel id="0" modelName="wheel_sport_01" />
        <wheel id="1" modelName="wheel_tuner_01" />
        <wheel id="2" modelName="wheel_lowrider_01" />
      </wheels>
      
      <modShop>
        <ModType id="0">
          <ModName>Spoiler</ModName>
          <Modification id="0" modelName="spoiler_carbon" />
          <Modification id="1" modelName="spoiler_aggressive" />
        </ModType>
      </modShop>
      
      <liveries>
        <livery id="0" modelName="livery_custom_01" />
        <livery id="1" modelName="livery_custom_02" />
      </liveries>
    </Item>
  </Variations>
</CVehicleVariationsFile>

Best Practices

Reference existing models - Use proven wheel/mod names
Keep it organized - Group similar modifications
Test all variations - Ensure models exist and load
Consistent naming - Use clear, logical names
Document options - Note what each ID represents

Testing Variations

Spawn vehicle in-game
Use modshop to test modifications
Apply each color combination
Try each wheel option
Verify liveries display correctly

Common Issues

Missing wheels - Verify model names exist
Modifications not appearing - Check mod shop references
Colors not applying - Verify IDs in carcols.xml
Liveries broken - Ensure texture files are included
Crashed on spawn - Invalid model name reference

carvariations.meta Breakdown

Root Vehicle Model Definition

Property	Purpose
`<modelName>`	Unique vehicle identifier - must match vehicles.meta modelName (e.g., `07gal`)
`<txdName>`	Texture dictionary reference (usually same as modelName) (e.g., `07gal`)

Color Variations Configuration

Property	Purpose
`<indices>`	Array of 6 color ID values: primary1, secondary1, primary2, secondary2, primary3, secondary3 (e.g., `[92, 27, 4, 1, 92, 0]`)
`<liveries>`	Array of 8 boolean flags controlling active livery/paint job variations (e.g., `[false, false, false, false, false, false, false, false]`)
`<platformId>`	License plate style identifier (e.g., `VPT_FRONT_AND_BACK_PLATES`)

Understanding the Indices Array

The indices array maps to these color slots in carcols.meta:

indices[0] - Primary Color 1 (Main vehicle color, carcols.xml ID e.g., 92)
indices[1] - Secondary Color 1 (Stripe/trim, carcols.xml ID e.g., 27)
indices[2] - Primary Color 2 (Hood/roof accent, carcols.xml ID e.g., 4)
indices[3] - Secondary Color 2 (Door stripe, carcols.xml ID e.g., 1)
indices[4] - Primary Color 3 (Body accents, carcols.xml ID e.g., 92)
indices[5] - Secondary Color 3 (Trim details, carcols.xml ID e.g., 0)

Modification Kits & Customization

Property	Purpose
`<kitItem id="">`	References a mod kit from carcols.meta by ID (e.g., `id="2998"` references kit with id 2998)
`<kitName>`	The kit identifier string to match with carcols.meta (e.g., `2998_07gal_modkit`)
`<allowRandomMods>`	Whether NPCs can randomly apply these mods to traffic spawns (Boolean: true/false)
`<randomWeight>`	How often this mod appears on random traffic (Float 0.0-1.0, higher = more frequent)

Window & Physical Configuration

Property	Purpose
`<windowBreakability>`	How easily windows break (Float value, higher = more fragile)
`<bodyHealth>`	Starting body/chassis health value (Float HP amount)

License Plate Configuration

Property	Purpose
`<plateIndex>`	Which plate style to use from plateTypes list (Integer ID)
`<plateProbability>`	Probability-weighted options for random plates (Container element)
`<Item>`	Individual plate option with name and weight (e.g., `<Item><name>Standard White</name><weight>25</weight></Item>`)
`<weight>`	Chance percentage this plate appears (Integer 0-100, all items total ~100)

Lighting & Siren Configuration

Property	Purpose
`<lightSettings id="">`	Links to lighting configuration in carcols.meta by ID (e.g., `id="902"`)
`<sirenSettings id="">`	Links to siren/emergency light setup (e.g., `id="0"` for no custom siren)

This section details every XML element in carvariations.meta for color and modification definitions:

Root & Model Definition

Element	Purpose	Example
`<variationData>`	Container for all variations	Parent element
`<modelName>`	Vehicle model this variation applies to	`07gal`

Color Variations

Element	Purpose	Notes
`<colors>`	Container for color combinations	Parent element
`<Item>`	Single color variant set	Repeatable
`<indices>`	Color IDs in sequence	6 values: primary1, secondary1, primary2, secondary2, primary3, secondary3
`<liveries>`	Livery availability flags	8 boolean values

Indices Format Explanation

The <indices> element contains 6 color IDs:

Primary color 1 - First color combo main
Secondary color 1 - First combo accent
Primary color 2 - Second combo main
Secondary color 2 - Second combo accent
Primary color 3 - Third combo main
Secondary color 3 - Third combo accent

Kits & Modifications

Element	Purpose	Example
`<kits>`	Container for mod kit references	Parent element
`<Item>`	Kit name reference	`2998_07gal_modkit`

Window & Physical Configuration

Element	Purpose	Notes
`<windowsWithExposedEdges>`	Windows with visible edge polygons	List of window names

License Plate Configuration

Element	Purpose	Example
`<plateProbabilities>`	Plate spawn probability weights	Container
`<Name>`	Plate style name	`Standard White`
`<Value>`	Probability percentage	`25` (out of 100)

Lighting & Siren Configuration

Element	Purpose	Example
`<lightSettings>`	Light configuration ID reference	`902`
`<sirenSettings>`	Siren sound configuration ID	`0`

Example Complete Variation Entry

<Item>
  <modelName>07gal</modelName>
  <colors>
    <Item>
      <indices content="char_array">
        92
        27
        4
        1
        92
        0
      </indices>
      <liveries>
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
      </liveries>
    </Item>
    <Item>
      <indices content="char_array">
        88
        0
        88
        1
        27
        0
      </indices>
      <liveries>
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
        <Item value="false" />
      </liveries>
    </Item>
  </colors>
  <kits>
    <Item>2998_07gal_modkit</Item>
  </kits>
  <windowsWithExposedEdges />
  <plateProbabilities>
    <Probabilities>
      <Item>
        <Name>Standard White</Name>
        <Value value="25" />
      </Item>
      <Item>
        <Name>Blue Plate</Name>
        <Value value="10" />
      </Item>
    </Probabilities>
  </plateProbabilities>
  <lightSettings value="902" />
  <sirenSettings value="0" />
</Item>

File Structure​

Color Variations​

Color Component References​

Wheel Variations​

Common Wheel Types​

Exterior Modifications​

Common Modification Slots​

Livery Variations​

Full Example​

Best Practices​

Testing Variations​

Common Issues​

carvariations.meta Breakdown​

Root Vehicle Model Definition​

Color Variations Configuration​

Understanding the Indices Array​

Modification Kits & Customization​

Window & Physical Configuration​

License Plate Configuration​

Lighting & Siren Configuration​

Root & Model Definition​

Color Variations​

Indices Format Explanation​

Kits & Modifications​

Window & Physical Configuration​

License Plate Configuration​

Lighting & Siren Configuration​

Example Complete Variation Entry​

File Structure

Color Variations

Color Component References

Wheel Variations

Common Wheel Types

Exterior Modifications

Common Modification Slots

Livery Variations

Full Example

Best Practices

Testing Variations

Common Issues

carvariations.meta Breakdown

Root Vehicle Model Definition

Color Variations Configuration

Understanding the Indices Array

Modification Kits & Customization

Window & Physical Configuration

License Plate Configuration

Lighting & Siren Configuration

Root & Model Definition

Color Variations

Indices Format Explanation

Kits & Modifications

Window & Physical Configuration

License Plate Configuration

Lighting & Siren Configuration

Example Complete Variation Entry