A3Rebalancer/AGENTS.md

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

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

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

python scripts/generate_patches.py

Produces:

• output/<mod>/config.cpp — Per-mod CfgPatches config with overrides
• output/unmatched.csv — Items with no RHS equivalent (review manually)

Step 5: Load in Arma

Drop the output/ folder contents into @mod/addons/<mod>/config.cpp structure and load it. Each subfolder is an independent addon with its own CfgPatches dependency.

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.