Initial commit: ArmADump ammo/armor rebalance tool

- SQF extraction scripts (ammo, armor, weapons, magazines) with ACE3 properties - Python pipeline: extract_csvs, split_by_mod, generate_patches - Generates CfgPatches config.cpp normalizing non-RHS values to RHS baseline - Documentation: REFERENCE.md, GENERATE_PATCHES_EXPLAINED.md, AGENTS.md
2026-07-20 18:27:33 +02:00
commit 83d2cb6c52
11 changed files with 2194 additions and 0 deletions
@@ -0,0 +1,82 @@
+# ArmADump
+
+Arma 3 config export and rebalance tool. Exports ammo/armor/weapons/magazines to CSV, then generates a CfgPatches mod to normalize non-RHS values to RHS baseline.
+
+## What this repo is
+
+### Extraction scripts (run in Arma 3)
+- **`ammo.sqf`** — CfgAmmo export with vanilla + ACE3 ballistics properties. Uses BFS with `sleep 0` batching.
+- **`armor.sqf`** — Vest + HeadGear export with per-body-part armor/passthrough values.
+- **`weapons.sqf`** — Weapon export with ACE barrel properties (`ACE_barrelLength`, `ACE_barrelTwist`).
+- **`magazines.sqf`** — Magazine export linking to ammo classes with `initSpeed`.
+
+### Legacy scripts (kept for reference)
+- **`sheet1.sqf`** — Weapons + magazines (old format).
+- **`sheet2.sqf`** — Items/gear (old format).
+- **`sheet3_ammo.sqf`** — Ammo (old format, no ACE properties).
+- **`classesExport.sqf`** — Original monolithic script.
+
+### Processing pipeline (Python)
+- **`scripts/split_by_mod.py`** — Reads raw CSVs from `.rpt`, splits into per-mod folders under `data/`.
+- **`scripts/generate_patches.py`** — Compares all mods to RHS baseline, generates `output/config.cpp`.
+
+### Reference
+- **`REFERENCE.md`** — Quick reference for all config values (vanilla + ACE3).
+
+## Workflow
+
+### Step 1: Run extraction scripts in Arma 3
+Run each script in debug console (or `execVM`). Each outputs CSV via `diag_log` to `.rpt`:
+```
+execVM "ammo.sqf"
+execVM "armor.sqf"
+execVM "weapons.sqf"
+execVM "magazines.sqf"
+```
+
+### Step 2: Extract CSVs from .rpt
+```bash
+python scripts/extract_csvs.py "path/to/arma3.rpt"
+```
+Parses the `.rpt` log and extracts CSVs between `--- ... START/END ---` markers into `ammo_raw.csv`, `armor_raw.csv`, `weapons_raw.csv`, `magazines_raw.csv`.
+
+### Step 3: Split by mod
+```bash
+python scripts/split_by_mod.py
+```
+Creates `data/[mod_name]/` folders with per-mod CSVs. Baseline mods (`_rhs`, `_vanilla`, `_ace`) sort first.
+
+### Step 4: Generate rebalance mod
+```bash
+python scripts/generate_patches.py
+```
+Produces:
+- `output/config.cpp` — CfgPatches config with overrides
+- `output/unmatched.csv` — Items with no RHS equivalent (review manually)
+
+### Step 5: Load in Arma
+Drop `output/config.cpp` into an `@mod/addons/config.cpp` structure and load it.
+
+## How the scripts work
+
+- Each SQF script takes optional arguments: `[name, CfgPatches name]` for a mod, `[name]` for vanilla BIS.
+- Uses `diag_log text(...)` for CSV output — extract from `.rpt` log.
+- Separator is `;` (semicolon). No quoting.
+- `configSourceAddonList` tags each entry with its source CfgPatches class.
+- `ammo.sqf` uses iterative BFS with combined traversal+extraction and `sleep 0` every 200 entries.
+
+## Conventions
+
+- SQF files use 8-space indentation (tabs).
+- CSVs use `;` delimiter.
+- Python scripts use UTF-8 encoding.
+- Per-mod folders use the CfgPatches class name as folder name.
+
+## Gotchas
+
+- Scripts output to Arma's `.rpt` log, not directly to a file.
+- `ammo.sqf` uses `sleep` which requires scheduled environment (`execVM` or `spawn`).
+- CfgAmmo BFS depth limit of 8 levels prevents exponential blowup.
+- `continue` keyword avoided for pre-2.14 Arma compatibility.
+- `generate_patches.py` classifies ammo by (caliber_tier, subtype). Items with no RHS tier match appear in `unmatched.csv`.
+- Armor matching uses (type, mass_tier). Soft armor items (chest_armor=0) are in their own tier.