firestorm/MECHSPECSHEET/README.md

MECHSPECSHEET

Generates a stock-mech specification spreadsheet directly from the FireStorm source tree, so the numbers come from the data the game actually loads instead of being transcribed by hand.

python3 generate-mech-specs.py      # writes mech-specifications-5.1.0b.xlsx
python3 verify-mech-specs.py        # checks the result, prints PASS/ISSUES

Both scripts are standard library only. An .xlsx is a zip of XML, and only xl/worksheets/sheet1.xml is rewritten, so the template's fonts, column widths and drawings survive untouched. No openpyxl needed.

Contents

File	What it is
generate-mech-specs.py	The extractor. Reads the roster from core.build, parses each chassis, writes the workbook.
verify-mech-specs.py	Five independent checks on a generated workbook.
template/mech-spec-template.xlsx	The original 5.0.7D workbook, kept as the layout template. Its single hand-made Battlemaster row is the calibration reference.
mech-specifications-5.1.0b.xlsx	Current output: 65 stock chassis, 55 columns.

Current output

65 chassis (37 Inner Sphere, 28 Clan; 23 Assault, 17 Heavy, 13 Medium, 12 Light). Every non-weapon column is populated for every chassis.

The roster is whatever Content/core.build registers, via lines of the form instance=mechs\<folder>\<base>.instance. The six staged V4H chassis (Champion, Dasher, Griffin, Jenner IIC, Marauder, Thunderbolt) are not included because they are not registered yet; they will appear automatically once they are, with no change to this tool.

Column reference

Columns 1-24 and 51-55 come from the template. Columns 25-50 are the weapon grid, widened from the original (see Layout changes).

#	Column	Source
1	Mech Chassis	Portrait filename in hsh/Mechs/ (these are the localized display names), title-cased; falls back to the folder name
2	Is_Playable	y for everything in core.build
3	Release Version	Constant SOURCE_VERSION in the script (currently 5.1.0b)
4	Technology	.data TechType -> IS / Clan
5	Weight (tons)	.data MaxVehicleTonnage
6	Class	Derived from tonnage: <=35 Light, <=55 Medium, <=75 Heavy, else Assault
7	External Armor Type	.subsystems Armor block ArmorType
8	Internal Structure Type	.subsystems Armor block InternalType
9	Armor Points	Installed: sum of the Armor block's per-zone tons x points-per-ton (see Armour)
10	JumpJets	JumpJetSubsystem present in .subsystems
11	Light Amplification	.instance DoesHaveLightAmp (default 1)
12-15	ECM / AMS / LAMS / Beagle	Corresponding subsystem present in .subsystems
16	# of Flushes	.instance MaxCoolant / 5
17	Heat Sinks	Count of heatsink subsystems, doubled if they are DoubleHeatSink
18	Top Speed Normal (kph)	min(MinMaxSpeed + MPSPerUpgrade * EngineUpgrades, MaxSpeed) * 3.6
19	Top Speed Gimped (kph)	.data MaxGimpSpeed * 3.6
20	Acceleration	.data Acceleration
21	Deceleration	.data Decceleration (double-c is canonical in the engine)
22	Turn Rate (rad/sec)	.data TopSpeedTurnRate (degrees) x pi/180
23	Twist Range (degrees)	.torso TwistRadius x 2, macros resolved through MechTorso.defines
24	Twist Speed	.torso TwistSpeed, same macro resolution
25-50	Weapon grid	.subsystems weapon blocks, placed by InternalLocation
51-54	Rating bars	.instance PowerRating / ArmorRating / SpeedRating / HeatRating
55	(template note)	Left blank

Weapon cells read Weapon Name (ammo), with (Rear) appended when the block sets WeaponFacing=1.

Data sources

All under Gameleap/mw4/Content/:

File	Provides
core.build	The roster. Presence here is what makes a chassis playable.
Mechs/<dir>/<base>.data	Tonnage, tech, heat, movement, CanLoad* flags
Mechs/<dir>/<base>.instance	Rating bars, coolant, LightAmp fitted
Mechs/<dir>/<base>.subsystems	The stock loadout: armour type and tonnage, heat sinks, engine upgrades, weapons, electronics
Mechs/<dir>/<base>.engine	MPSPerUpgrade for the speed calculation
Mechs/<dir>/<base>.torso	Twist range and speed (usually macro references)
Subsystems/Armor.data	Points per ton by armour type
Defines/MechTorso.defines	Torso macro values
../hsh/Mechs/*.bmp	Display names

.damage is deliberately not used for armour. See below.

Armour: why tons, not multipliers

The Armor block in .subsystems looks like per-zone multipliers:

ArmorType=Standard
InternalType=EndoSteel
LeftArm=1.45
CenterFrontTorso=2.05

They are tons of armour, not multipliers. The proof is in MechLab.cpp GetCurrentMechArmorData:

tonnage_array[i] = armor_array[i] / *points_per;

so points = tons x points_per, with the rate chosen by armour type from Content/Subsystems/Armor.data:

PointsPerStandardTon=32   PointsPerFerroTon=38
PointsPerReflectiveTon=30 PointsPerReactiveTon=30  PointsPerSolarianTon=60

Battlemaster: 13.0 tons x 32 = 416 points.

Cross-check against MechLab.cpp:796, which is also the formula written into the template's own header:

armor_bar = (TotalArmor / 535) * 100

416/535 x 100 = 77.8%, against a stored ArmorRating of 79. 50 of the 65 chassis agree within 5 points, which is good corroboration.

An earlier attempt summed MaxArmorValue from .damage scaled by those numbers. That yields armour capacity (1024 for the Battlemaster), not what is fitted. .damage MaxArmorValue is the per-zone cap the mechlab will not let you exceed; it is not the stock allocation.

Judgement calls

Columns 10-15 mean installed, not can load. The Battlemaster's .data says CanLoadECM=Yes, CanLoadAMS=Yes, CanLoadLAMS=Yes, CanLoadBeagle=Yes, yet the template sample marks all four n. The template is right: these describe the stock loadout, so they are read from .subsystems, not .data.

Column 7 follows the data, not the sample. The template sample says Ferro-Fibrous for the Battlemaster; battlemaster.subsystems says ArmorType=Standard. Internal structure (Endo Steel) matched exactly, so the sample cell looks like a guess. The data wins.

Columns 51-54 are pulled, not recomputed. These are the authored bar values from .instance. The template header carries formulas for them, but the stored values are what the game ships. Note that MechLab recomputes the bars live while you edit a mech (MechLab.cpp:794-796), so the stored values are the selection-screen figures, and the two can drift: 15 of 65 chassis diverge from the /535 armour formula by more than 5 points, Fafnir worst at 38. That is a property of the source data, not an extraction error.

Column 3 says 5.1.0b. This is the current source tree, not the 5.0.7D drop the template came from. Change SOURCE_VERSION if you need a different stamp.

Layout changes

The template gives each arm three weapon slots. The Gladiator mounts six Clan Medium Pulse Lasers in its right arm, so three were being silently dropped.

Before widening anything, the maximum was measured per location across all 65 chassis:

Location	Template slots	Max used	Worst case
Head	1	1	Atlas
Left arm	3	3	Deimos
Right arm	3	6	Gladiator
Left torso	4	4	Mauler
Right torso	4	4	Chimera
Centre torso	2	2	Annihilator
Special 1	3	2	Ares
Special 2	3	3	Ares

Only the right arm overflowed. Right_Arm_4/5/6 were inserted after Right_Arm_3, following the existing naming, and everything from the old column 32 onward shifted right by three. The workbook is now 55 columns.

If a future chassis overflows another location, the generator prints a overflowed ... -- widen LOC_COLS warning naming the mech and location. Widen the entry in LOC_COLS, add matching NEW_HEADERS, and bump NCOLS.

Weapon names

Weapon labels are derived from the subsystem filename, since the .subsystems blocks carry no display string. Three rules cover almost everything:

camelCase -> spaced        ClanMediumPulseLaser -> Clan Medium Pulse Laser
ACRONYM+Word -> split      ClanERSmallLaser     -> Clan ER Small Laser
letters+digits -> split    SRM6                 -> SRM 6

Two source files are entirely upper case and cannot be split by any general rule, so they are special-cased: CLANLRM10 and ERPPC. 44 distinct weapon names are produced; if a new one reads oddly, check the filename first.

Pitfalls

Folder case. core.build writes mechs\annihilator\... but the folder is Annihilator. The generator builds a case-insensitive directory index; file lookups inside a chassis folder are case-insensitive too.

Encoding. Content files are CRLF and contain legacy high bytes. They are read as latin-1. Do not decode them as UTF-8.

Engine upgrades matter. Top speed is not MaxSpeed. It is MinMaxSpeed + MPSPerUpgrade x EngineUpgrades, capped at MaxSpeed. The Battlemaster ships with EngineUpgrades=5, which is exactly what turns 65.0 kph into the template's 90.02 kph. Getting this wrong is silently plausible, which is why the sample row is worth calibrating against.

Display names are not folder names. Folder Blackhawk is displayed as "Black Hawk", Madcat as "Mad Cat". The portrait filenames in hsh/Mechs/ carry the localized names, so they are used as the name source.

Verification

verify-mech-specs.py runs five checks:

1. Layout - weapon and rating headers are where they should be.
2. Fill rates - every non-weapon column populated for every chassis.
3. Calibration - the generated Battlemaster row against the template's hand-made sample, weapon cells only. This is the important one: those 11 cells are an independent statement of the loadout, so if they still match, .subsystems is being read correctly.
4. Weapon names - flags camelCase remnants and long capital runs that suggest an unsplit filename.
5. Armour cross-check - installed points against the stored ArmorRating bar via the /535 formula, reported as a distribution.

Expected result today: PASS, 55 columns x 65 chassis, all 11 sample weapon cells matching, 44 clean weapon names, 50/65 armour bars within 5 points.

Updating

Re-run the generator. It re-reads the roster each time, so:

• registering the six new chassis in core.build adds six rows automatically
• editing any .subsystems loadout is picked up with no code change
• adding a weapon needs no change unless its filename defeats the naming rules

Then run the verifier and check it still reports PASS.