Adding or replacing existing carcols.dat settings

---

This page explains how you can create your own carcols.dat files for your server, be it to add car colors for your DL vehicles or to replace existing carcols.dat settings.

Using appropriate material colors on your model

Before you continue, please make sure you tell the game which parts of your model are colorable. You can do this by using the following material colors:

Material color	Used for
#3cff00	The game will will use the vehicle's current primary color to paint all faces that use this material.
#ff00af	The game will will use the vehicle's current secondary color to paint all faces that use this material.
#00ffff	The game will will use the vehicle's current tertiary color to paint all faces that use this material.
#ff00ff	The game will will use the vehicle's current quaternary color to paint all faces that use this material.

Mapping regions on your vehicle with standard materials using this color is not necessary, but you should at least map all the areas with a standard material using the primary color material color. Of course - if you are a vehicle modder none of this should be new to you, as this step of the process is known by pretty much all vehicle modders out there. Neither UG nor UG-MP really change this step in the process.

Overview of carcols.dat

As is the case with other data files which allow you to replace existing lines, it is highly recommended to work with an empty carcols.dat file. Only the files you place in your carcols.dat file really affect the game, so copypasting the stock GTA:UG carcols.dat file for your server is not necessary. A clean carcols.dat file looks like this:

# This is an empty carcols.dat file.
car
end
car4
end

Adding new carcols.dat lines

Working with carcols.dat files is incredibly simple and straightforward. Most vehicles will have their carcols.dat entries stored in the car section. This section allows you to specify color variations with a primary and secondary color ID. Youc an find these here. We will be working within this section in this guide as well. If you want to use four different car colours you can by using the car4 section, however keep in mind that existing SA-MP natives only allow you to work with primary and secondary colors. Anyways, here's how a simple carcols.dat line looks like:

car
Vehicle name, Primary color 1,Secondary color 1, Primary color 2,Secondary color 2, ...
end

Each line must start with a valid model name, and what follows is a variable number of primary and secondary colors variations. As you can tell, neither the primary nor secondary colors are random at all; they are instead linked together. Let's assume we have the following carcols.dat entry:

car
ferrari, 127,6, 1,0
end

Our Ferrari has two different color variations - in variation 1 the primary color is red and the secondary is yellow, and in variation 2 the primary color is white whereas the secondary color is black. If the game spawns our car for the first time, it uses the first color variation, and the car will thus spawn with red and yellow colors. If the game spawns our car for the second time, it uses the second color variation, and the car will spawn with black and white colors. After reaching the final color variation, the game picks variation 0 again the next time around. Other instances where the next color variation is chosen is if the vehicle gets resprayed in a Pay N Spray garage, for example. So as you can see, there's no randomness to this process at all. You have a lot of control while the colors the game picks are quite predictable.

Replacing carcols.dat lines

Now that we know how to add new carcols.dat entries, it's time to try and replace some existing lines. The way you do this is essentially the same as when you add new lines - the only difference is that we need to get the model name of the vehicle whose carcols.dat line should be replaced. You can obtain this by browsing the vehicles.ide file in the data folder in your game installation directory. You may replace a carcols.dat line multiple times - however once you call RemoveDataFile the initial settings will be restored. In other words, the first carcols.dat line that was added.

Making the game load your custom carcols.dat file

Now that we've added our carcols.dat lines, it's time to tell the file loader as well as our downloader about our new file. We will assume that the file is stored under assets/carcoldl-test/carcoldl-test.dat in this example.

With that said, your assets.json should look like this:

[
    ...
	{
		"name": "Carcol DL - Test for carcol DL",
		"author": "dkluin",
		"type": "carcols",
		"files": [
			"carcoldl-test/carcoldl-test.dat"
		]
	}    
]

...and our OnGameModeInit like this:

public OnGameModeInit()
{
    ...

    // Tell the file loader about our carcols.dat file
    AddDataFile("carcoldl-test/carcoldl-test.dat", DATAFILE_CARCOLSETS);
    return 1;
}

After following these steps you may restart your server to see the changes.