# Generate Patches — How It Works

This document explains the logic behind `generate_patches.py`, the script that produces the rebalance `config.cpp`.

---

## Purpose

Many Arma 3 mods define ammo and armor with values that don't match RHS standards. This script:

1. Reads the extracted CSV data for every installed mod
2. Compares each mod's values against RHS as the baseline
3. Generates a `config.cpp` mod that overrides non-RHS values to match RHS equivalents

The result is a single drop-in mod that normalizes your entire mod list to RHS balance.

---

## Overview of the Process

```
Per-mod CSV files (data/)
        |
        v
 +-------------------+
 | Load baseline     |  Reads RHS + vanilla + RHS sub-mods
 | (RHS / vanilla)   |  as the "correct" reference values
 +-------------------+
        |
        v
 +-------------------+
 | Classify every    |  Each ammo/armor item is sorted into a
 | entry into tiers  |  "tier" group based on caliber or protection level
 +-------------------+
        |
        v
 +-------------------+
 | Build baseline    |  For each tier, pick one representative RHS entry
 | lookup table      |  to use as the reference values
 +-------------------+
        |
        v
 +-------------------+
 | Compare each mod  |  For every non-RHS entry, look up its tier's
 | against baseline  |  RHS baseline and record any differences
 +-------------------+
        |
        v
 +-------------------+
 | Generate          |  Write a config.cpp that overrides every
 | config.cpp        |  differing value to match the RHS baseline
 +-------------------+
        |
        v
 output/config.cpp   (the rebalance mod)
 output/unmatched.csv (items with no RHS equivalent)
```

---

## Step 1: Loading Baseline Data

The script loads CSVs from these folders as the baseline (the "correct" values):

| Folder | Source |
|---|---|
| `_rhs` | RHS AFRF (Russian equipment) |
| `_rhsusf` | RHS USMC (American equipment) |
| `_rhsgref` | RHS GREF (generic/other factions) |
| `_rhssaf` | RHS SAF (Serbian equipment) |
| `_vanilla` | Arma 3 base game (BI) |
| `_ace` | ACE3 mod (ballistic overrides) |

All entries from these mods are pooled together. When two entries exist in the same tier, RHS entries are preferred over vanilla.

---

## Step 2: Classification — Putting Items Into Tiers

Every ammo and armor item is classified into a **tier**. Items in the same tier are considered equivalent — a 5.56mm round from mod A should have similar stats to a 5.56mm round from RHS.

### Ammo Classification

Ammo is classified by **two properties**: a **caliber tier** (the type of round) and a **subtype** (ball, AP, tracer, etc.).

#### How Caliber Tier Is Determined

The script checks the ammo class name against a list of patterns. The first pattern that matches wins. This is done by name, not by the numeric `caliber` value, because Arma's `caliber` property is a penetration coefficient, not the actual bullet caliber.

| Pattern in class name | Tier | Typical RHS values (hit / caliber / speed) |
|---|---|---|
| `9x19`, `9mm`, `9x18` | `pistol_9mm` | 5 / 0.4 / 370 |
| `45acp`, `.45` | `pistol_45acp` | 6 / 0.5 / 260 |
| `57x28`, `5.7` | `smg_57x28` | 4 / 0.3 / 390 |
| `46x30`, `4.6` | `smg_46x30` | 4 / 0.3 / 375 |
| `545x39`, `5.45` | `rifle_545x39` | 9 / 0.65 / 900 |
| `556x45`, `5.56` | `rifle_556x45` | 9 / 0.87 / 920 |
| `762x39` | `rifle_762x39` | 11 / 1.2 / 730 |
| `762x51`, `.308` | `rifle_762x51` | 11.6 / 1.6 / 800 |
| `762x54` | `rifle_762x54` | 11.6 / 1.8 / 830 |
| `300blk` | `rifle_300blk` | (no RHS baseline) |
| `338`, `338lapua` | `sniper_338` | (no RHS baseline) |
| `408`, `cheytac` | `sniper_408` | (no RHS baseline) |
| `127x99`, `50bmg`, `12.7` | `hmg_50` | 22 / 2.8 / 900 |
| `145x114`, `14.5` | `hmg_145` | 28 / 3.5 / 950 |
| `20mm` | `cannon_20` | 30 / 1.2 / 1000 |
| `23mm` | `cannon_23` | 40 / 1.5 / 950 |
| `25mm` | `cannon_25` | 60 / 2.0 / 900 |
| `30mm` | `cannon_30` | 80 / 2.5 / 850 |
| `35mm` | `cannon_35` | 85 / 2.5 / 850 |
| `40mm`, `mk19` | `cannon_40` | 100 / 2.5 / 800 |
| `mortar`, `82mm`, `81mm` | `mortar_82` | varies |
| `100mm` and above | `gun_heavy` | varies |
| `12gauge`, `buckshot` | `shotgun_12g` | varies |
| `rocket`, `pg7`, `rpg` | `rocket` | varies |
| `missile`, `titan`, `hellfire` | `missile` | varies |
| `grenade`, `40mm_he` | `grenade_40mm` | varies |
| `mine`, `ied`, `satchel` | `explosive` | varies |
| `penetrator`, `heat` | `penetrator` | varies |

If no name pattern matches, the script falls back to the `simulation` property:

| Simulation | Tier |
|---|---|
| `shotBullet` (speed < 350) | `bullet_subsonic` |
| `shotBullet` (other) | `bullet_unknown` |
| `shotShell` + explosive > 0.5 | `shell_he` |
| `shotShell` (other) | `shell_ap` |
| `shotMissile` | `missile` |
| `shotRocket` | `rocket` |
| `shotGrenade` | `grenade_40mm` |
| `shotIlluminating`, `shotSmokeX` | `utility` |

#### How Subtype Is Determined

Within each caliber tier, items are further sorted into subtypes by checking the class name for keywords:

| Condition | Subtype |
|---|---|
| Speed > 0 and < 350 m/s | `subsonic` |
| Name contains "ap" | `ap` |
| Name contains "tracer" | `ball_tracer` |
| Name contains "match", "sniper", "otm", "mk262", "mk316" | `match` |
| Name contains "incendiary" or "incen" | `incendiary` |
| Name contains "hedp" | `hedp` |
| Name contains "he" (but not "hedp") | `he` |
| Everything else | `ball` |

### Armor Classification

Armor is classified by **item type** (Vest or HeadGear) and a **protection tier**.

#### Vest Tiers

Based on the `armor_chest` value (front plate protection):

| Chest Armor Value | Tier | Examples |
|---|---|---|
| 0 (no plate) | `soft` | Cloth vests, chest rigs |
| 1 - 16 | `light` | Plate carrier lite, PASGT vest |
| 17 - 31 | `medium` | IOTV, SPC, 6B13 |
| 32 - 50 | `heavy` | Full battle carrier |
| 50+ | `eod` | EOD suits, GL carriers |

#### Helmet Tiers

Based on the `armor_head` value:

| Head Armor Value | Tier | Examples |
|---|---|---|
| 0 (no armor) | `cap` | Berets, caps |
| 1 - 6 | `light` | Cloth helmets, bump helmets |
| 7 - 15 | `medium` | PASGT, MICH |
| 16 - 25 | `heavy` | ACH, ECH, 6B47 |
| 25+ | `special` | Specialized heavy helmets |

---

## Step 3: Building the Baseline Lookup Table

After all entries are loaded and classified, the script builds a lookup table. For each tier, it picks one representative RHS entry to use as the reference.

**Example:** For the `rifle_556x45` / `ball` tier, the baseline might be RHS's `B_556x45_Ball` with:
- hit = 9
- caliber = 0.87
- typicalSpeed = 920
- airFriction = -0.001033
- deflecting = 21

Any 5.56mm ball round from any other mod will be compared against these values.

---

## Step 4: Finding Overrides

For each non-RHS mod entry, the script:

1. Looks up the entry's tier in the baseline table
2. If the tier exists in the baseline, compares every field
3. If a field differs and the mod's value is not zero, records a change to the baseline value

### What Gets Compared

**Ammo fields (14 values):**

| Field | Arma Config Name | What It Controls |
|---|---|---|
| `hit` | `hit` | Direct damage on impact |
| `indirect_hit` | `indirectHit` | Splash damage |
| `indirect_hit_range` | `indirectHitRange` | Splash radius (meters) |
| `caliber` | `caliber` | Penetration coefficient |
| `typical_speed` | `typicalSpeed` | Muzzle velocity (m/s) |
| `air_friction` | `airFriction` | Drag coefficient |
| `deflecting` | `deflecting` | Min ricochet angle (degrees) |
| `explosive` | `explosive` | 0 = kinetic, 1 = explosive |
| `ace_caliber` | `ACE_caliber` | Actual bullet diameter (mm) |
| `ace_bullet_length` | `ACE_bulletLength` | Bullet length (mm) |
| `ace_bullet_mass` | `ACE_bulletMass` | Bullet mass (grams) |
| `ace_drag_model` | `ACE_dragModel` | Drag curve (1=G1, 7=G7, etc.) |
| `ace_transonic` | `ACE_transonicStabilityCoef` | Transonic stability (0-1) |
| `ace_mv_var` | `ACE_muzzleVelocityVariationSD` | Velocity spread (%) |

Plus 4 ACE array fields compared as text:
- `ACE_ballisticCoefficients[]` — drag coefficient at different velocities
- `ACE_velocityBoundaries[]` — velocity thresholds for BC changes
- `ACE_muzzleVelocities[]` — muzzle velocity per barrel length
- `ACE_barrelLengths[]` — barrel lengths for velocity interpolation

**Armor fields (16 values):**

For each body part (Head, Neck, Chest, Diaphragm, Abdomen, Body, Arms, Legs):
- `armor` — additional armor points
- `passThrough` — 0 = full block, 1 = no protection

### What Does NOT Get Overridden

- Fields where the mod's value is zero (treated as "not defined, keep it")
- `passThrough` values where both the mod and RHS baseline are 1.0 (no change for unarmored areas)

---

## Step 5: Generating config.cpp

The output is a standard Arma 3 `config.cpp` with three sections:

### CfgPatches (Dependency Declaration)

Each mod that has overrides gets a dependency entry:

```cpp
class CfgPatches {
    class armadump_afou {
        units[] = {};
        weapons[] = {};
        requiredAddons[] = {"afou"};
    };
};
```

This tells Arma to load our overrides after the original mod.

### CfgAmmo (Ammo Overrides)

```cpp
class CfgAmmo {
    class B_afou_556x45_Ball {
        airFriction = -0.001033;
        caliber = 0.87;
        deflecting = 21;
        hit = 9;
        typicalSpeed = 920;
    };
};
```

Only fields that differ from RHS are listed. Fields not listed keep their original mod values.

### CfgWeapons (Armor Overrides)

```cpp
class CfgWeapons {
    class MyMod_Vest {
        class ItemInfo {
            class HitpointsProtectionInfo {
                class Chest {
                    armor = 24;
                    passThrough = 0.5;
                };
                class Abdomen {
                    armor = 16;
                    passThrough = 0.6;
                };
            };
        };
    };
};
```

Only body parts with differing armor values are listed.

---

## Step 6: Unmatched Items

Items that are classified into a tier with no RHS baseline equivalent are written to `output/unmatched.csv` for manual review.

**Common reasons an item is unmatched:**

| Reason | Example |
|---|---|
| Caliber has no RHS equivalent | `.300 Blackout`, `.57x28mm`, `.338 Lapua` |
| Subtype has no RHS equivalent | Tracer variants when only ball exists in RHS |
| Simulation-based fallback tier | Unknown simulation type |

These items are **not** included in the generated config.cpp. They retain their original mod values.

---

## What You End Up With

After running the script:

1. **`output/config.cpp`** — Drop this into an `@mod/addons/` folder and load it in Arma. It silently overrides every non-RHS ammo and armor value to match RHS balance.

2. **`output/unmatched.csv`** — A spreadsheet of items that couldn't be matched. Review these to decide if they need manual adjustment.

3. **No changes to original mods** — The script only reads data. Original mod files are untouched.

---

## Example: Tracing One Entry

Taking the AFou mod's 5.56mm ball round as an example:

1. **Classification**: Class name `B_afou_556x45_Ball` matches pattern `556x45` -> tier `rifle_556x45`. No "tracer", "ap", etc. in name -> subtype `ball`.

2. **Baseline lookup**: Tier `rifle_556x45` / `ball` maps to RHS's `B_556x45_Ball`:
   - hit = 9, caliber = 0.87, typicalSpeed = 920, airFriction = -0.001033, deflecting = 21

3. **Comparison**: AFou's values differ on airFriction, caliber, deflecting, hit, typicalSpeed.

5. **Override generated**: The config.cpp sets those 5 fields to RHS values. All other fields (ACE properties, cost, etc.) keep AFou's original values.

---

## Limitations

- **Tier-based, not per-class matching**: All 5.56mm ball rounds are normalized to the same RHS reference. If a mod intentionally makes a round weaker or stronger (e.g., training ammo), it will be overwritten.
- **No threshold filtering**: Even a difference of 0.001 generates an override. There is no minimum difference filter.
- **First RHS entry wins**: If multiple RHS entries exist in the same tier, the first one encountered is used. This is usually fine since RHS values within a tier are consistent.
- **Unmatched items skipped**: Calibers without an RHS equivalent (like .300 BLK) are left untouched.