BIS fnc initVehicle

1.42

Hover & click on the images for description

Description

Description:

/*
	Author: Julien `Tom_48_97` VIDA

	Description:
	This function aims to simplify the way to customise 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 mentioned (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; //<-- Preferred
	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) (For the texture, the first item of the texture list is used)
	result = [this, true, true, true] call bis_fnc_initVehicle;

*/

Execution:

call

Groups:

Uncategorised

Syntax

Syntax:

Syntax needed

Return Value:

Return value needed

Examples

Example 1:

result = [this, "", []] call BIS_fnc_initVehicle;

Example 2:

result = [this, ["MyTextureSource1", 0.5, "MyTextureSource2", 0.6], []] call BIS_fnc_initVehicle;

Example 3:

result = [this, nil, ["MyAnimationSource1", 0.5, "MyAnimationSource2", 0.7]] call BIS_fnc_initVehicle;

Additional Information

See also:

Vehicle Customization (VhC)CfgVehicleTemplatesdisableRandomization

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note

Bottom Section

Posted on November 27, 2017 - 22:45 (UTC)

chemicalbliss

If you are passing variables as parameters, but sometimes the variable must be nil (and you don't want script errors), you have two options:

1. Use the getVariable function like so;
[ _myVehicle, missionNamespace getVariable ["_MyTextureVariable", nil], missionNamespace getVariable ["_MyAnimationVariable", nil] ] call BIS_fnc_initVehicle;
2. Use this small snippet;
_getVariableOrNil = { if (!isNil (_this select 0)) exitWith { call compile (_this select 0); }; nil; }; [ _myVehicle, ["_MyTextureVariable"] call _getVariableOrNil, ["_MyAnimationVariable"] call _getVariableOrNil ] call BIS_fnc_initVehicle