A3Rebalancer/REFERENCE.md

# Arma 3 / ACE3 Config Values Reference

Quick reference for all config properties relevant to ammo ballistics and armor protection.

---

## CfgAmmo — Vanilla Properties

| Property | Type | Description |
|---|---|---|
| `simulation` | String | Physics model: `shotBullet`, `shotShell`, `shotMissile`, `shotRocket`, `shotGrenade`, `shotSubmunitions`, `shotSpread`, `shotIlluminating`, `shotSmokeX`, `shotTimeBomb`, `shotMine`, `shotLaser`, `shotDeploy` |
| `hit` | Number | Direct damage on impact. Bullets: 5-25, Shells: 50-200, Missiles: 100-10000 |
| `indirectHit` | Number | Splash damage at impact point. 0 for bullets, high for HE. |
| `indirectHitRange` | Number | Splash radius in meters. 0 for bullets, 3-15 for HE/shells. |
| `caliber` | Number | Penetration coefficient. <1 = weak, 1 = standard, >1 = armor-piercing. Formula: effective_armor = armor / caliber |
| `typicalSpeed` | Number | Muzzle velocity in m/s for vanilla drag model. |
| `airFriction` | Number | Vanilla drag coefficient (always negative). Higher magnitude = more drag. |
| `visibleFire` | Number | How much firing reveals position. 2-3 for small arms, 32 for cannon. |
| `audibleFire` | Number | How loud the shot is. 0.25 suppressed, 16-40 unsuppressed, 200-250 cannon. |
| `cost` | Number | AI ammo expenditure priority. 0.7 for bullets, 100-500 for missiles. |
| `explosive` | Number | 0 = kinetic penetrator, 1 = HE/explosive. |
| `deflecting` | Number | Minimum angle (degrees) for ricochet. 0 = none, 5 = base, 60 = very high. |
| `airLock` | Number | 0 = none, 1 = lock-on capable. |
| `cartridge` | String | Visual cartridge effect class (e.g., `FxCartridge_556`). |

### Simulation Types

| Simulation | Used For | Key Behavior |
|---|---|---|
| `shotBullet` | Rifle/pistol rounds, submunitions | Traced, ricochets, penetration |
| `shotShell` | Cannon shells, grenades, penetrators | Explosive, splash damage |
| `shotMissile` | Guided missiles, rockets | Lock-on, tracking, airFriction > 0 |
| `shotRocket` | Unguided rockets | Untracked flight, airFriction > 0 |
| `shotGrenade` | Hand/UGL grenades | Arched trajectory |
| `shotSubmunitions` | Cluster submunitions | Deploys children |
| `shotSpread` | Shotgun pellets | Spread pattern |
| `shotIlluminating` | Flares | Light emission |
| `shotSmokeX` | Smoke grenades | Particle effects |

---

## CfgAmmo — ACE3 Properties

All ACE3 properties are placed **directly on the ammo class** (no sub-class nesting).

| Property | Type | Unit | Description |
|---|---|---|---|
| `ACE_caliber` | Number | mm | Actual bullet diameter (e.g., 5.69 for 5.56 NATO) |
| `ACE_bulletLength` | Number | mm | Bullet length from base to tip (e.g., 23.012 for M855) |
| `ACE_bulletMass` | Number | grams | Bullet mass (e.g., 4.0176 for M855 5.56mm) |
| `ACE_ballisticCoefficients[]` | Array | — | BC value(s). Single value or velocity-dependent array. Higher BC = less drag. |
| `ACE_velocityBoundaries[]` | Array | m/s | Velocity thresholds where BC changes. Empty `{}` for single BC. |
| `ACE_dragModel` | Number | — | 1=G1, 2=G2, 5=G5, 6=G6, 7=G7 (boat tail), 8=G8. Most rifle ammo = G7. |
| `ACE_standardAtmosphere` | String | — | `"ICAO"` (standard) or `"ASM"` (Army Standard Meteorological) |
| `ACE_muzzleVelocities[]` | Array | m/s | Muzzle velocities at corresponding barrel lengths. |
| `ACE_barrelLengths[]` | Array | mm | Barrel lengths for velocity interpolation. Same size as muzzleVelocities. |
| `ACE_transonicStabilityCoef` | Number | 0-1 | Transonic stability. Default 0.5. |
| `ACE_muzzleVelocityVariationSD` | Number | % | Velocity spread standard deviation. 2 = 2%. |

### ACE Drag Models

| Value | Model | Used For |
|---|---|---|
| 1 | G1 | Flat-base bullets (pistol, some SMG) |
| 2 | G2 | Ogive projectiles |
| 5 | G5 | Boat-tail, low L/D |
| 6 | G6 | Boat-tail, high L/D |
| 7 | G7 | Long-range match (most 7.62mm, .338, .50 BMG) |
| 8 | G8 | Very low drag bullets |

---

## CfgWeapons — Armor Properties (HitpointsProtectionInfo)

**Path:** `configFile >> "CfgWeapons" >> "Item" >> "ItemInfo" >> "HitpointsProtectionInfo" >> "BodyPart"`

### Body Parts

| Class | Hitpoint | Coverage |
|---|---|---|
| `Head` | HitHead | Helmet |
| `Neck` | HitNeck | Collar protection |
| `Face` | HitFace | Face shield |
| `Chest` | HitChest | Front plate / upper torso |
| `Diaphragm` | HitDiaphragm | Upper chest, behind sternum |
| `Abdomen` | HitAbdomen | Lower torso |
| `Arms` | HitArms | Arm protection |
| `Legs` | HitLegs | Leg protection |
| `Body` | HitBody | Full body |

### Per-Body-Part Properties

| Property | Type | Description |
|---|---|---|
| `hitpointName` | String | References the hitpoint class (e.g., `"HitChest"`) |
| `armor` | Number | Additional armor points. 0-80 typical range. |
| `passThrough` | Number | 0-1. 0 = full block, 1 = no protection. |

### Armor Value Tiers (RHS baseline)

| Tier | Chest Armor | Example |
|---|---|---|
| Soft / No plate | 0-6 | Caps, berets, light vests |
| Light plate | 8-16 | Plate carrier lite, PASGT |
| Medium plate | 20-31 | IOTV, SPC, 6B13 |
| Heavy plate | 32-50 | Full EOD, heavy carrier |
| EOD / Special | 50-78 | EOD suits, GL carriers |

---

## CfgWeapons — ACE3 Weapon Properties

| Property | Type | Unit | Description |
|---|---|---|---|
| `ACE_barrelLength` | Number | mm | Physical barrel length. Used with ammo's `ACE_muzzleVelocities[]` / `ACE_barrelLengths[]` for velocity interpolation. |
| `ACE_barrelTwist` | Number | mm | Rifling twist rate. 304.8mm = 1:12", 228.6mm = 1:9". |
| `ACE_twistDirection` | Number | — | 1 = right twist (default), -1 = left, 0 = none. |

ACE interpolates muzzle velocity based on weapon barrel length vs ammo barrel length table:

```
Weapon ACE_barrelLength = 368mm
Ammo ACE_barrelLengths[] = {210, 250, 300, 370, 450}
Ammo ACE_muzzleVelocities[] = {723, 764, 796, 843, 900}
Result = interpolated ~844 m/s
```

---

## Caliber Tiers — RHS Baseline

### Small Arms

| Caliber | hit | caliber | speed | ACE_BC (G7) | ACE_mass (g) |
|---|---|---|---|---|---|
| 9x19mm | 5-6 | 0.4 | 360-400 | 0.05-0.08 | 7.5-8.0 |
| .45 ACP | 6-7 | 0.5 | 260 | 0.08-0.12 | 14-15 |
| 5.45x39mm | 9-10 | 0.65 | 900 | 0.12-0.16 | 3.0-3.5 |
| 5.56x45mm | 9 | 0.87 | 920 | 0.12-0.20 | 3.5-4.5 |
| 7.62x39mm | 11 | 1.2 | 730 | 0.12-0.15 | 7.5-8.0 |
| 7.62x51mm | 11.6 | 1.6 | 800 | 0.18-0.30 | 9.0-11.0 |
| 7.62x54mmR | 11.6 | 1.8 | 800-860 | 0.18-0.30 | 9.0-12.0 |
| .338 Lapua | 14-16 | 2.0 | 800-900 | 0.28-0.40 | 16-19 |
| .408 CheyTac | 16-18 | 2.2 | 870-910 | 0.35-0.45 | 19-22 |
| 12.7mm (.50 BMG) | 20-25 | 2.5-3.0 | 900 | 0.35-0.60 | 42-46 |
| 14.5mm | 25-30 | 3.0-4.0 | 950 | 0.40-0.60 | 55-65 |

### Subsonic vs Supersonic

Subsonic ammo (below ~340 m/s) has significantly lower hit and speed values:

| Type | hit | speed | Typical caliber |
|---|---|---|---|
| 9mm Subsonic | 3-4 | 290-310 | 9x19mm |
| 5.56mm Subsonic | 4-5 | 310-330 | 5.56x45mm |
| 7.62mm Subsonic | 6-8 | 300-340 | 7.62x51mm |
| .300 BLK Sub | 5-7 | 300-330 | .300 Blackout |

### AP vs Ball vs Tracer

| Type | caliber modifier | Typical behavior |
|---|---|---|
| Ball (standard) | Baseline | Normal penetration and damage |
| AP (armor-piercing) | +30-50% higher | Higher caliber, lower hit sometimes |
| Tracer | Same as ball | Adds visible trail |
| Incendiary | Same hit, +explosive | Sets fires |
| Subsonic | -40-60% hit, -60% speed | Quieter, less damage |
| HE (high-explosive) | 0 hit, high indirectHit | Splash damage only |

---

## Config Source Identification

To determine which mod defined a class, use:

```sqf
private _sources = configSourceAddonList (configFile >> "CfgAmmo" >> "B_556x45_Ball");
// Returns array of CfgPatches class names, e.g. ["A3_Weapons_F", "ace_ballistics"]
```

This is how we tag each extracted entry with its source mod for per-mod CSV splitting.