CfgVehicles Config Reference

INTRO

Arma 3 documentation is scattered to the 4 winds, and this applies to config file properties as much as anything. This is an attempt to make a single master list of properties with links to [sources]. Yes, there are other partial lists but they have problems: short/confusing "official" descriptions, obsolete information, and no links to further sources. So rather than wreak havoc with these lists, this article is an attempt to make an easier-to-digest resource (at least by Arma standards!).

(P.S. This list was initially compiled in Fall of 2014, and should be up-to-date as of that point.)

WARNING! Work in progress! Lots of missing entries, resorting to do, etc.

Existing Config pages

Here is a list of existing config pages on the Biki. They contain mostly semi-official descriptions of properties. Unfortunately, these descriptions tend to be short, incomplete, and/or confusing--particularly for new modders:

CfgVehicles Config Reference
CfgAmmo Config Reference
CfgMagazines Config Reference
CfgWeapons Config Reference
Model Config

This page is like a "Config Properties for Dummies" or a "Config Properties Explained". If you want the official description, go to the linked pages. If you want a more thorough explanation, use this page.

(Once this page is complete, a sensible route may be to integrate its information into the existing pages to reduce redundancy).

How Do Configs Work?

All configs get merged into one big config in memory when the game starts. Where duplicates exist, which config takes precedence depends on load order - the last config loaded "wins" by overwriting any previous value(s). Load order is determined by mod folder order, PBO name, but most importantly/properly by the "requiredAddons" section of the CfgPatches class.

CfgPatches & requiredAddons

The requiredAddons array in CfgPatches is how you control the load order of configs. "requiredAddons" means "load these other config files before you load this one." (And "this one" means the name of the class containing the requiredAddons statement). [ A,...]

How Many Config Files?

One consequence of the above discussion is the fact that you can technically spread your configs across tons of little files or ball them up into one big one or anything in between--with some exceptions^ (which are dicussed further below). Barring those exceptions, there is no iron-clad rule that requires certain classes (e.g. CfgAmmo, CfgVehicles, etc.) to be separated or located within particular filenames. It is essentially a matter of clarity, ease of editing, and consistency to help others understand your work.

^Known exceptions:

1. #include'd .h/.hpp files are usually in the same folder or a subfolder of the #include'ing config, but apparently they can be anywhere as long as you #include "pathtofile".
2. CfgSkeleton & CfgModels classes should be in either: a "model.cfg" file or a "[same-name-as-P3D].cfg" file. Unlike other config classes, these ones should not be thrown into random files.
3. The model.cfg file must be in the same folder as--or in a parent folder of--the object (P3D) it configures.

WEAPONS

For understandable reasons, weapons data is scattered across several different config classes. Defining a weapon properly requires working with all these classes.

CfgAmmo

Most projectile-specific properties are located here. Some relevant properties you might expect to find here however--muzzle velocity for example--are located in the other weapon classes (either CfgMagazines or CfgWeapons).

airFriction

float

How much the projectile slows down as it travels through the air^. (A way of expressing aerodynamic drag).

This & initSpeed define a projectile's trajectory in Arma (for unpowered ones like Bullets & Shells--Rockets & Missiles have additional rocket thrust features that influence their flight). As soon as an unpowered projectile is fired, it starts to slow down due to drag. The formula is:

airFriction = deceleration / velocity²

e.g. a projectile with a muzzle velocity of 1640 m/s which slows down 94 m/s/s (i.e. by 94 m/s in the first second) has an airFriction of:

-94/1640² ≈ 0.0000035

(This property appears to be equivalent to Bird-Livingston's "ballistic K factor" * 0.0000001).

^A different formula based on bulletPenetrability & caliber is applied to slow projectiles passing through solid targets (fire geometry).

[A, B, "WW2 Ballistics: Armor and Gunnery" (Bird-Livingston, 2001)]

airLock

bool

Whether this ammo type (& AI using it) can lock onto airborne targets.

(Provided the related CfgWeapons also has locking capability--"canLock" is true). (see "irLock", "laserLock"). (Unlike irLock & laserLock--which have corresponding CfgVehicles properties that they lock onto, airborne targets are identified in some other way).

[A,B,C].

caliber

float≥0

Ability of the projectile to penetrate through target fire geometry (buildings, vehicle armor and components, people, etc.).

Penetration power is dependent on caliber and the projectile's speed. The formula for mm of penetration is:

(projectile speed / 1000)x(caliber)x(bulletPenetrability of the target BISURF)

So higher values mean more penetration. And, of course, as the projectile slows down during its flight, penetration decreases. Restating the formula:

caliber = (mm penetration @speedX)*1000 / (bulletPenetrability * speedX)

(A value of 1 is standardized as 15mm of RHA penetration at 1000m/s.) Note! Adding caliber values to missile or rockets is bugged and results in missiles flying through targets.

[A]

cost

int, ~$, (AI only)

A "monetary" value for each weapon.

This helps AI units decide on whether a weapon is worth using. Presumably AI does not waste high-cost weapons on low-threat or otherwise inappropriate targets. Seems to be vaguely calibrated in units of 1/3-1/4 $USD.

[A, B (contradictory)]

deflecting

int≥0, angle in degrees

Determines how much a projectile ricochets.

When the ammo impacts something at this angle or less, there is a chance it will ricochet--bouncing off the target and doing less than full kinetic damage. Impact angles greater than this will not ricochet. If deflecting = 0, the projectile will never ricochet. Ricochets can occur off of anything other than water: the ground, buildings, vehicles, etc.

[A]

explosive

1≥float≥0

The proportion of the projectile's damage that is explosive (rather than kinetic).

Unlike kinetic damage, explosive damage does not fall off as the projectile gradually loses speed. A value of 1 means the damage is fully explosive, while 0 means fully kinetic. (This property has nothing to do with the colloquial sense of an explosion as 'splash' damage--that property is covered by "indirectHit"). NOTE! Values >=0.7 nullify the penetration capability of the projectile, so keep values below this if you want the projectile to be able to penetrate armor at all. (See "hit", "typicalSpeed").

hit

float>0

The damage done by a direct hit from this projectile.

Damage is applied to global hitpoints ("armor" int) as well as locational ones ("armor" float). (The actual formula for applying damage is somewhat complex, so there is not necessarily a one-to-one application of hit value against hitpoints).[A]

indirectHit

float≥0

'Splash' damage done by a near miss from this projectile.

Projectiles with indirectHit values do damage within a sphere around their impact point (whether they hit the ground or an object). The size of the sphere is determined by "indirectHitRange" and targets within the sphere receive damage.

[A]

indirectHitRange

float≥0, meters

Describes the range of a projectile's 'splash' damage.

This is the base radius within which indirectHit damage is applied. indirectHit damage is actually applied out to 4x this radius, with linear falloff starting at indirectHit and ending at 0. (See "indirectHit"). [A]

initTime

float≥0, seconds, (Missiles only)

How long it takes the missile's rocket motor to start producing thrust after launch.

Missiles are launched at initSpeed. After initTime, the missile starts accelerating based on its thrust parameters. (see "thrust", "thrustTime").

irLock

bool

Whether this ammo type (& AI using it) can lock onto radar targets (CfgVehicles.irTarget = true).

irTarget vehicles are ones that are config'ed to show up on the game's simple "radar" overlay--i.e. tanks, trucks, etc., not humans. (You'd think "ir" would refer to infrared, but it actually refers to radar). (Provided the related CfgWeapons also has locking capability--"canLock" is true).

[A].

laserLock

bool

Whether this ammo type (& AI using it) can lock onto "laser targets", i.e. a laser designator dot (CfgVehicles.laserTarget = true). (Provided the related CfgWeapons also has locking capability--"canLock" is true).

[A,B].

manualControl

bool, (Missiles only)

A type of missile guidance.

True means the missile has SACLOS guidance (i.e. it continuously adjusts to fly toward wherever the player's crosshairs point).

[A,B]

maxSpeed

float>0, m/s, (Missiles only)

Missile speed limit.

This value imposes an upper limit to the speed at which a missile can travel, regardless of its thrust properties. (see "thrust", "thrustTime").

muzzle velocity

Surprise! Muzzle velocity for a projectile is not found in CfgAmmo at all! Instead it is defined in the relevant CfgMagazines class and the property is called "initSpeed".

thrust

[A,B]

thrustTime

float>0, seconds, (Missiles only)

How many seconds the rocket motor will produces thrust before dying out.

(Keep in mind that regardless of these thrust properties, "maxSpeed" puts a ceiling on missile speed).

[A,B, C]

typicalspeed

int>0, m/s

Influences how much damage the projectile does when it hits.

Speed at which the projectile produces full "hit" damage; anything lower produces proportionately less damage (exception: any "explosive" damage component is always full value regardless of the impact speed). Note that this property does nothing to influence the projectile velocity, it used only in the damage calculation. (See "initSpeed", "explosive").

CfgMagazines

Magazine properties plus some projectile-specific stuff that gets stored here instead of CfgAmmo.

initSpeed

int>0, m/s

Sets the muzzle velocity of ammo fired from this Magazine.

(Not to be confused with typicalSpeed, which does not affect projectile speed at all and is instead used for damage calculation only).

CfgWeapons

Gun/launcher-specific properties.

autoFire

bool

Whether the weapon will continue to fire if you hold down trigger.

[A].

canLock

bool

Whether the weapon can lock on to a target (e.g. when a player hits the TAB key)

Must be true for any of the other lock modes to work (airLock, irLock, laserLock). 0 = never, 1 = in cadet mode only, 2 = always.

[A, B]

dispersion

float>0

Basic weapon accuracy.

This affects all projectiles fired from this weapon independent of other effects like AI skill, etc. It describes the weapon's dispersion in radians (1 milliradian = 1 angular mil = 0.001 dispersion, 1 MOA = 0.000290888 dispersion)

weaponLockSystem

cumulative int

How the weapon triggers a target's warning system.

What type(s) of lockDetectionSystem is set off in a vehicle targeted by this weapon: 0 = none, 1 = CM_Lock_Visual, 2 = CM_Lock_IR, 4 = CM_Lock_Laser, 8 = CM_Lock_Radar. Presumably canLock must = 1 for this to be relevant.

[A].

VEHICLES

tbd

CfgVehicles

armor (global)

int>0

Overall hit points/'health' for the vehicle.

You will often see this property referred to as "armor (int)". Supposedly object radius somehow modifies this value, although the formulas offered by BI don't make much sense. Note that locational hit-points are derived from this value--determined by the HitPoint class's own "armor" (float) value. So the lower this value, the weaker all the vehicle's corresponding location HitPoints will also be (i.e. the more damage a location takes with each hit).

[A, B, C].

armorStructural

int>0

Divisor to global damage; the higher the value (beyond 1), the less global damage ("armor"/"hit points") occurs whenever the vehicle gets hit. HitPoints class location damage is not affected by this property; the location takes damage from the hit without modification. Extremely high values practically nullify the (in)famous cumulative "hit points" system of vehicle damage (e.g. plinking a tank to death with a rifle).

[A].

crewVulnerable

bool, (AI only)

damageResistance

float>0

Tells AI units how resistant this vehicle is to damage (so they can decide whether or not to bother attacking based on the weapons they are carrying). The calculation appears to be based only on the target's global armor and size, along with the weapon's hit value; armor & penetration are not factors. The formula for deriving this value is supposedly:

(minHit^2) * (1/armor) * ([0.27/tgtRadius]^2)

where "miHit" is the "hit" value for the weakest weapon that the AI should find useful against the vehicle. How exactly the value is used by the game is a mystery. Possibly the AI check their weapon with this formula and compare it to the config value. Simplifying, one could say the AI checks it's weapon "hit" value against the minimum useful "hit" value the config has defined; if the AI weapon is >= the minimum value, the AI will consider attacking. If the AI's weapon is weaker, it won't.

[A,B,c]

explosionShielding (global)

float≥0

Modifies how global vehicle health is affected by 'splash' damage (indirectHit).

This works the same way as explosionShielding for HitPoint locations: indirectHit damage received is multiplied by this value.

(This property is 10-24-14 devbranch only currently)

hiddenSelections[]

string array

These are references to particular "sections" from the CfgModel (which in turn correspond to selection sets in the P3D) for this vehicle. These sections are designed to create variety within a single model by allowing the parts to be hidden and/or have alternate textures swapped out for variety.

[ A,B, fab.ofp.free.fr/Tutorials/Hidden_Selections.htm, tactical.nekromantix.com/wiki/doku.php?id=arma2:texturing:hiddenselectionstextures]

hiddenSelectionsTextures[]

string array

A list of (pathed) textures for use with hiddenSelections[]. The textures are assigned to the hiddenSelections[] elements in the order they are listed (first texture goes to the first element, and so on). hiddenSelections[] elements with no texture listed will be hidden at game startup, while those with a texture will be displayed and use the texture assigned. (see "hiddenSelections[]").

enginePower

int>0, kilowatts, (PhysX)

Engine power. (hp * 0.745699872 = kW).

[A]

maxOmega

int>;0, radians per second, (PhysX)

Maximum rotational speed of engine. (RPM * 0.104719755 = radians/s).

[A, B]

peakTorque

int>0, Newton-meters, (PhysX)

Maximum engine torque. (=enginePower*1000/maxOmega).

[A, B]

torqueCurve[]

float array, (PhysX)

An array describing how much torque the engine generates at various rotational speeds.

The values are normalized (0-1) so any units can be used to derive these values. The array consists of pairs of values in the form { {rotation1,torque1},{rotation2, torque2}, ...}. The first value in each pair tells the game how far along the RPM curve we are, the second value tells it how much to scale the peakTorque output. These are used to create a virtual graph which the game uses to determine engine power at various rotational speeds.

[A, B]

thrustDelay

int≥0, seconds, (PhysX)

Time it takes for engine to send power to the wheels from a stop.

This property does not affect already moving vehicles (see "clutchStrength" for something along those lines). Values >0 are suggested to reduce the chance that the vehicle's wheels slip every time it starts from a stop.

[A]

clutchStrength

float>0, (PhysX)

How 'tight' the clutch is--how quickly gear changes affect wheel speed.

Low values will mean more slippage and more gradual acceleration after gear changes, higher values mean less slippage and quick delivery of torque to the wheels after gear shifts. BI recommends starting with a value of 10 (for CarX anyway, TankX config values are typically closer to 100).

[A, B]

fuelCapacity

int>0

brakeIdleSpeed

float>0

tankTurnForce

int>0

normalSpeedForwardCoef

float>0

idleRpm

int>0

redRpm

int>0

engineLosses

int≥0

transmissionLosses

int≥0

changeGearMinEffectivity[]

float array

hideWeapons__

bool

minTotalDamageTreshold

float≥0

Protects global vehicle health from damage.

This works the same way as minimalHit for HitPoint locations: damage received below this value is ignored.

(This property is 10-24-14 devbranch only currently)

secondaryExplosion

bool, obsolete?

Does not appear to be used in Arma 3. There are secondary explosions for certain types of destroyed vehicles, but they appear to be hardcoded.

[A].

simulation

string

thermalMode[]

string array

threat[]

float array

[A]

transportSoldier

int≥0

visionmode[]

string array

Which vision types are available to toggle through ("N" key) in this optics view. Options are "Normal","TI","NVG".

waterPPInVehicle

bool

HitPoints class properties

armor (local)

float≥0

You will often see this property referred to as "armor (float)".

explosionShielding

float≥0

Modifies how global vehicle health is affected by 'splash' damage (indirectHit).

A factor applied to indirectHit damage. Values < 1 make a location resistant to indirectHit damage. Theoretically, values > 1 would make the location more sensitive, but this has not been confirmed (some properties have undocumented, hardcoded upper/lower limits). (See "explosionShielding (global)").

[ A, B ].

minimalHit

float≥0

Protects the location from damage.

Damage received below this value is ignored. A value of 0 means the location acts 'normally' and even the slightest damage will reduce its health. (See "armor (local)", "minTotalDamageThreshold").

name

string

Associates the HitPoints location with a named selection set of vertices in the relevant P3D's HitPoints LOD. This way, the game knows what vertices in the model go with what hit location. Additionally, the set name should be the same as a CfgSkeletons bone (so the game also knows which verts move with which vehicle part). (See "visual").

passThrough

1≥float≥0

Proportion of damage to this location that is passed on to damage global vehicle hit points. 0 = the location can be destroyed without affecting overall vehicle health. This cannot be used to make a location cause extra global damage (since values over 1 are treated as = 1). (For that feature, see "depends").

radius

float≥0

Defines the size of the HitPoint vertices in this location of the vehicle's P3D model. The radius creates a "sphere" of effect around each vertex. When fire geometry within this sphere is hit, the location takes damage^.

[A].

^It's actually a bit more complex than this. It appears that the game applies some damage to all locations based on their distance from the hit, with the nearest location taking the most damage of course.

visual

string

Associates the HitPoints location with a corresponding model "section" (defined in CfgModels). This is purely for visual purposes--if the section has multiple damage textures/states, this lets the game know which location damage causes a particular section's appearance to change. (See "name").

[Samples_F\Test_Tank_01\CfgVehicles.hpp].

Typical HitPoints classes

Existing HitPoints classes being used in the game have certain (hard-coded?) properties that you should be aware of.

HitHull

Used in tracked vehicles, this location automatically destroys the vehicle when depleted (regardless of remaining global health/"armor").

HitFuel

Used in wheeled vehicles, this location automatically destroys the vehicle when depleted (regardless of remaining global health/"armor").

HitTrack

Restricts mobility when depleted. Because these locations are not protected by armor plates, they extremely vulnerable to damage unless protected by tweaking explosionShielding (<1) and(/or) minimalHit (>0).

HitWheel

Restricts mobility when depleted. Because these locations are not protected by armor plates, they extremely vulnerable to damage unless protected by tweaking explosionShielding (<1) and(/or) minimalHit (>0).

HitTurret

Prevents the turret (turret optics view) from rotating when depleted.

HitGun

Gun (turret optics view) is stuck at minimum elevation when depleted.

HitAmmo

Ammo locations are not used in vanilla Arma 3, but could be added. Because it has no hard-coded properties, the only way to make it destroy a vehicle is to use the "depends" property to pass on its damage to HitHull/HitFuel.

HitEngine

Restricts mobility when depleted.

HitAvionics

Used in aircraft, it makes the HUD display flicker and disappear when depleted.

HitVRotor

Used in helicopters to represent the tail rotor, it causes the aircraft to spin out of control when depleted.

HitHRotor

Used in helicopters to represent the main rotor, the aircraft loses power when this location is depleted.

Model.cfg

A game model is defined by its P3D file and an associated model.cfg config file that describes the model's components. It consists of two classes: CfgSkeletons & CfgModels.

[ A, B, C, D ]

ARMOR (Materials)

BISURF properties

BISURF material files are assigned to fire geometry in a vehicle's P3D file. They define the physical properties of whatever geometry they've been assigned to. Critical among these properties is armor value as defined by bulletPenetrability (or bulletPenetrabilityWithThickness & Thickness).

bulletPenetrability

int>0

Material strength in terms of how well it resists penetration: lower is stronger.

This is based on how far in mm a BI-standard "7.62mm NATO round" travelling at 1000m/s will penetrate the material. For example, RHA = 15. (Considering it penetrates 15mm of RHA, this is some kind of AP bullet obviously!) It doesn't really matter though, just make sure new weapons are correctly calibrated to penetrate real-world depths based on real-world velocities.

bulletPenetrabilityWithThickness

int>0

If the material has a "thickness" property specified, put its bulletPenetrability value here instead. (See "bulletPenetrability").

Thickness

int>0

Sets a thickness ceiling to the geometry--the idea is to make it easier to model small/thin fire geometry. If the fire geometry is thinner, the actual thickness is used. If the fire geometry is thicker, the "thickness" property overrides it and is used. The game does appear to take into account LOS thickness by evaluating an incoming projectile's angle-of-incidence (relative to the geometry normal).