Arma 3: Vehicle Customisation

1.42 The Vehicle Customization (VhC) is the system responsible for the customization of vehicles, either, defined or randomized. It consists of a set of config properties and classes and a set of functions. It has been introduced in Arma 3 v1.42 in order to replace the old system which consisted in a set of scripts.

Usage

Here is the header of the main function, BIS_fnc_initVehicle which should be enough to understand how to use it:

/*
	Description:
	This function aims to simplify the way to customize vehicles. It can change the textures and/or the animation sources of a given object. Usage of this function is explained in the below examples.

	Important note: Unless it explicitly mentionned (example case 10), the function will restore the initial state of every animation sources of the given object.

	Additional information:
	OPREP - http://dev.arma3.com/post/oprep-vehicle-customization
	Community Wiki - https://community.bistudio.com/wiki/Vehicle_Customization_%28VhC%29

	Parameter(s):
		0: vehicle to customize
		1: Variant (textures)
			BOOL - true to restore default texture source ; false to skip texture source change
			VOID - Nil to skip the texture source change
			ARRAY - Array of texture sources with their given probability: ["textureSource1", 0.5, "textureSource2", 0.5]
			STRING - Variant class name(from the configFile >> cfgVehicles or from the missionConfigfile >> cfgVehicleTemplate)
			SCALAR - index of the texture source (same as the old system)
		2: Animations
			BOOL - true to restore init phase of every animation sources
			VOID - Nil to skip change of the animation sources
			ARRAY - Array of animation sources and probability: ["AnimationSource1", 0.5, "animationSource2", 0.5]. Note, if the first element is false, it will skip the reset of the animation sources
			STRING - Variant class name(from the configFile >> cfgVehicles or from the missionConfigfile >> cfgVehicleTemplate)
		3: Mass
			BOOL - true to set the default mass, false to disable the mass change
			SCALAR - Mass to add or remove the vehicle

	Returns:
	BOOL - True if success, otherwise, false

	Examples:
	1) Do nothing because default VAR texture and VAR animation are "false"
	result = [this] call bis_fnc_initVehicle;

	2) Restore default texture and animation sources (reset)
	result = [this, true, true] call bis_fnc_initVehicle;

	3) Randomize everything according to the config file
	result = [this, "", []] call bis_fnc_initVehicle; //<-- Prefered
	result = [this, "", ""] call bis_fnc_initVehicle;

	4) Skip everything
	result = [this, nil, nil] call bis_fnc_initVehicle; //<-- Prefered
	result = [this, false, false] call bis_fnc_initVehicle;

	5) Apply the given texture and ignore the animations
	Priority is given to [missionConfigFile, "CfgVehicleTemplates"]
	result = [this, "TemplateName", nil] call bis_fnc_initVehicle;

	6) random weighted on the given texture sources and their probability, then randomize the animation sources according to the config file
	result = [this, ["MyTextureSource1", 0.5, "MyTextureSource2", 0.6], []] call bis_fnc_initVehicle;

	7) MyAnimationSource1 phase has a 50% chance to be set to 1 and MyAnimationSource2 has a 70% chance to be set to 1
	result = [this, nil, ["MyAnimationSource1", 0.5, "MyAnimationSource2", 0.7]] call bis_fnc_initVehicle;

	8) MyAnimationSource1 phase will be 1 whereas MyAnimationSource2 will be set to 0
	result = [this, nil, ["MyAnimationSource1", 1, "MyAnimationSource2", 0]] call bis_fnc_initVehicle;

	9) Change animation sources with a given template
	result = [this, nil, "MyTemplate"] call bis_fnc_initVehicle;

	10) Change animation source with a given array of probabilities but skip the reset of all animation sources
	// Algo: Skip the change of texture, [don't reste of the animation sources, proceed the given animation sources with their, probabilities], skip the change of mass
	result = [this, nil, [false,"MyAnimationSource1", 0.5, "MyAnimationSource2", 0.8], nil] call bis_fnc_initVehicle;

	11) Restore the vehicle to its default state as defined in the config (texture, animation sources, mass)
	result = [this, true, true, true] call bis_fnc_initVehicle;
*/

Implementation

Missions

The system offers a simple way to define your own deliveries and to prevent randomization of a given vehicle, its class or even its kind. Here an example of mission configuration file.

Prevent randomization

// No action will be taken regarding the following vehicles (either, names, classes or kind)
disableRandomization[] =
{
	// "AllVehicles",		// No randomization at all
	// "Air",				// No randomization at all for air vehicles
	// "land",				// No randomization at all for land vehicles
	// "Ship",				// No randomization at all for sea vehicles
	"air_f",				// There won't be any randomization on every air vehicles
	"C_Hatchback_01_F",		// No random on Hatchbacks
	"truck_withoutRandom"	// No random for this given vehicle
};

Add your own liveries

To do so, a new mission config file has been introduced - CfgVehicleTemplates. It regroups every variants used from the main function (bis_fnc_initVehicle)

class CfgVehicleTemplates
{

This variant has a textureList property, a list of texture sources directly defined from an addon, at the config level. If there is more than 1 entry in the texture list, a weighted random will be performed between them. Having one entry means this entry will be picked up on every call of the function.

	class BIS_Offroad_01_default
	{
		vehicles[] =  // It is used by the [[Eden Editor]] to determine which vehicle classes can be supposed with use this template
		{
				"classNameA",
				"classNameB"
		};
		displayName = "Default";		// <optional> Could be handy if you plan to add some UI, not used by the VhC
		author = "Bohemia Interactive";	// <optional> Could be handy if you plan to add some UI, not used by the VhC
		factions[] =					// This template will be available for the following factions
		{
			"BLU_F", "BLU_G_F",	// Side Blufor
			"OPF_F", "OPF_G_F",	// Side Opfor
			"IND_F", "IND_G_F",	// Side independent
			"CIV_F"				// Side civilian
		};
		// List of texture sources defined in ConfigFile >> "CfgVehicles" >> "VehicleClass" >> "TextureSources"
		// Only on source will be chosen within the following by a weighted random
		textureList[] =
		{
			"guerilla_01", 1,
			"guerilla_02", 1,
			"guerilla_03", 1,
			"guerilla_04", 1
		};
		// Animation sources
		animationList[] =
		{
			"HideBumper1", 1,	// Class of an animation source, probabily (wherein 1 means 100% to set the phase to 1)
			"HideBumper2", 1,
			"HideConstruction", 1,
			"HideDoor1", 0,		// The phase of the animation source will always be set to 1
			"HideDoor2", 0,
			"HideGlass2", 0,
			"HideBackpacks", 1,
			"HideDoor3", 0.33 	// There is a 33% chance that this animation source phease is set to 1
		};
	};

The following has textures[] instead of textureList[], meaning the function will define these texture files and won't search for texture sources.

	class BIS_Offroad_01_stripped
	{
		displayName = "Stripped";
		author = "Bohemia Interactive";
		textures[] =
		{
			"\A3\Soft_F\Offroad_01\Data\Offroad_02_ext_CO.paa", //Must with extension!
			"\A3\Soft_F\Offroad_01\Data\Offroad_02_ext_CO.paa"
		};
		materials[] =
		{
			"", // Material to use for the first texture (ignore if the string is empty)
			"\A3\Structures_F\Data\Windows\window_set.rvmat" // Material to use for the second texture
		};
		animationList[] =
		{
			"HideBumper1", 1,
			"HideBumper2", 1,
			"HideConstruction", 1,
			"HideDoor1", 1,
			"HideDoor2", 1,
			"HideGlass2", 1,
			"HideBackpacks", 1,
			"HideDoor3", 0.33
		};
	};

The following class interstates from "BIS_Offroad_01_default" which has a textureList, meaning this class contains textureList and textures. In this case, the textures property will be used and textureList will be ignored.

	class hotpink: BIS_Offroad_01_default
	{
		displayName="hotpink (ugly test)";
		author="Tom_48_97";
		textures[] = { "#(rgb,8,8,3)color(1,0.411,0.705,1)" };
	};

... and the CfgVehicleTemplates closure bracket

};

Addon

In the best case of use, the bellow classes and information should be defined in the base config class of the vehicle, but obviously, this is not always possible.

Base class

class Dummy_vehicle_base_F: Helicopter_Base_H
{
	scope = 0; // A base class should has scope = 0 (private)
	model = "\A3\Dummy\Dummy_vehicle\dummy.p3d";

	class EventHandlers: EventHandlers
	{
		// (_this select 0): the vehicle
		// """" Random texture source (pick one from the property textureList[])
		// []: randomize the animation sources (accordingly to the property animationList[])
		// false: Don't change the mass even if an animation source has a defined mass
		init = "if (local (_this select 0)) then { [(_this select 0), """", [], false] call bis_fnc_initVehicle; };";
	};

	/*---------------------------------------------------------------------------
		Animation sources
	---------------------------------------------------------------------------*/
	class animationSources: animationSources
	{
		class animationSource1
		{
			// name of the animation / element (displayed in the Virtual Garage)
			displayName = "Add source...";
			// Author of the textures (displayed in the Virtual Garage)
			author = $STR_A3_Bohemia_Interactive;
			source = "user";
			animPeriod = 0.000001;
			initPhase = 0;

			// if the animation phase is 0, then the given cargo indexes (lockCargo) will be locked
			// if undefined, default value of lockCargoAnimationPhase is 0
			lockCargoAnimationPhase = 0;
			lockCargo[] = { 0, 1, 5 };

			// if forceAnimatePhase is equal to the phase of this animation sources, every sources from forceAnimate will be changed with their given phase
			forceAnimatePhase = 0;
			// animationSource1, phase, animationSource2, phase... No probabilities here, only true or false
			forceAnimate[] = { "animationSource1", 0, "animationSource2", 1 };

			// The following code is called by BIS_fnc_initVehicle each time the phase is changed
			onPhaseChanged = "if ((_this select 1) == 1) then { /* run if the phase is 1 */ } else { /* run if the phase is 0 */ };";

			// Mass of the source, can be negative or positive
			// If the phase is 1, the given mass will be added, otherwise, it will be subtracted
			mass = 20;
		};
		class animationSource2: animationSource1 {};
		class animationSource3: animationSource1 {};
		class animationSource4: animationSource1 {};
	};

	/*---------------------------------------------------------------------------
		Texture sources
	---------------------------------------------------------------------------*/
	class textureSources
	{
		// This texture source will be available for every defined factions
		class white
		{
			// Display name of the texture
			displayName = "White";
			// Author of the texture
			author = $STR_A3_Bohemia_Interactive;
			// Paths to the texture files, in the same order as the hidden selections
			textures[] = { "\A3\Dummy\Dummy_vehicle\dummy_vehicle_ext_1_co.paa" };
			// This source should be available for the following factions
			factions[] =
			{
				"BLU_F", "BLU_G_F",	// Side Blufor
				"OPF_F", "OPF_G_F",	// Side Opfor
				"IND_F", "IND_G_F",	// Side independent
				"CIV_F"				// Side civilian
			};
		};

		// This texture source will be available for every factions (currents and futures)
		class black
		{
			displayName = "Black";
			author = $STR_A3_Bohemia_Interactive;
			textures[] = { "\A3\Dummy\Dummy_vehicle\dummy_vehicle_ext_1_co.paa" };
			factions[] = {};
		};

		// This texture source will be available only for the FIA (whatever its side)
		class yellow
		{
			displayName = "Yellow";
			author = $STR_A3_Bohemia_Interactive;
			textures[] = { "\A3\Dummy\Dummy_vehicle\dummy_vehicle_ext_1_co.paa" };
			factions[] =
			{
				"BLU_G_F",
				"OPF_G_F",
				"IND_G_F"
			};
		};
		
		// This texture source will be available only for the BLU_F faction
		class red
		{
			displayName = "Red";
			author = $STR_A3_Bohemia_Interactive;
			textures[] = { "\A3\Dummy\Dummy_vehicle\dummy_vehicle_ext_1_co.paa" };
			factions[] =
			{
				"BLU_F"
			};
		};
	};
};

Variants / derivatives

class B_dummy_vehicle_F: Dummy_vehicle_1_base_F
{
	displayName = "I'm nothing";
	author = $STR_A3_Bohemia_Interactive;

	scope = 2;
	scopeCurator = 2;

	side = 1;
	faction = BLU_F;

	textureList[] =
	{
		"White", 1,
		"Black", 0.5,
		"Red", 0.5,
		"Yellow", 0.5
	};

	/* Random animations, also used to determine the allowed animation sources
	1 means 100% - This state of the given source WILL BE set to 1, 0 means the opposite
	[_animationSource1, probability1, _animationSource2, probability2, ...] */
	animationList[] =
	{
		"animationSource1", 0.5,
		"animationSource2", 0.5,
		"animationSource3", 0.5,
		"animationSource4", 0.5
	};
};

/*---------------------------------------------------------------------------
	Dummy vehicle used by the initVehicle function, for pre defined variants
---------------------------------------------------------------------------*/
class B_dummy_vehicle_red_F: B_dummy_vehicle_F
{
	CFGVEHICLES_VARIANT_DISPLAYNAME("B_dummy_vehicle_F", "Red")
	CFGVEHICLES_VARIANT_DUMMY
	textureList[] = { "Red", 1 };
	animationList[] =
	{
		"animationSource2", 1,
		"animationSource3", 1,
		"animationSource4", 0.3
	};
};