firestorm/BTFrstrm/mech_loadouts.md

mech_loadouts.csv Catch-Up Notes

This document is for future AI agents or maintainers who need to understand how mech_loadouts.csv was built, where each column comes from, and what files must be updated together when mech data changes.

Purpose

mech_loadouts.csv is a flattened mech audit sheet built from the FireStorm content tree. It combines:

• mech identity and stat data
• current in-game playability status
• installed/default weapon loadouts
• weapon facing and grouping metadata
• zone hardpoint capacity
• notes about missing registration, packaging, or asset support

The CSV is not a primary source of truth. It is a synthesized report built from the mech content files and several registration tables.

Current CSV Column Layout

The important derived columns are:

• In_game_playable
• Weapons_With_Locations
• Default_Installed_Locations
• Available_Slot_Capacity_By_Zone
• Available_Hardpoints
• notes

The existing stat columns before those are mostly direct mech data fields and were not re-derived during the audit.

What Each Derived Column Means

In_game_playable

Yes if the mech is currently in the active playable roster, No otherwise.

This was determined by comparing the mech folder set against the active registration chain:

• Gameleap/code/mw4/Code/MW4/MechLabHeaders.h
• Gameleap/mw4/Content/ShellScripts/MechLabHeaders.h
• Gameleap/mw4/Content/Tables/MechChassisTable.tbl
• Gameleap/mw4/Content/Tables/MechTable.tbl
• Gameleap/mw4/Content/core.build
• plus supporting string and packaging manifests

Practical rule:

• folder presence alone does not make a mech playable
• playable mechs must have the ID/table/build registrations aligned

Weapons_With_Locations

This column lists each installed weapon in the mech¡¯s default subsystem file, with:

• the weapon name
• the InternalLocation
• the WeaponFacing
• the weapon group

Current format:

• WeaponName@Location(Facing) G#

Examples:

• MediumPulseLaser@LeftTorso(Rear) G1
• SRM4@RightTorso(Front) G2
• ClanLRM10@LeftTorso(Side) G2

Derived from the mech¡¯s .subsystems file by reading weapon subsystem blocks.

Important notes:

• WeaponFacing=0 => Front
• WeaponFacing=1 => Rear
• WeaponFacing=2 => Side
• if WeaponFacing is absent, it defaults to Front

Default_Installed_Locations

A compact count summary of where the mech¡¯s default weapons are installed, based on InternalLocation in the .subsystems file.

Example:

• LeftArmx2 | LeftTorsox3 | RightTorsox4 | RightArmx2

This is about installed weapons, not slot capacity.

Available_Slot_Capacity_By_Zone

A compact summary of zone capacities from the mech¡¯s .damage file.

Current format:

• Zone(M# / P# / B# / O#)

Where:

• M = MissileSlots
• P = ProjectileSlots
• B = BeamSlots
• O = OmniSlots

Example:

• LeftTorso(M0/P2/B2/O0)

This reflects what the mech can support in that zone, not what is currently installed.

Available_Hardpoints

A list of zones that have at least one positive slot count in the .damage file.

Current format:

• LeftArm(Front)
• LeftTorso(Front+Rear)
• RightTorso(Side)

This column is a directional summary of where weapons can be mounted.

Important:

• this is derived from slot capacity plus facing information from weapon loadouts
• it is not a literal mechanical port map
• if a zone has multiple facing types in the mech¡¯s default loadout, it can show a combined label such as Front+Rear or Front+Side

Core Data Sources

1. Mech registration and playability

Primary files:

• Gameleap/code/mw4/Code/MW4/MechLabHeaders.h
• Gameleap/mw4/Content/ShellScripts/MechLabHeaders.h
• Gameleap/mw4/Content/Tables/MechChassisTable.tbl
• Gameleap/mw4/Content/Tables/MechTable.tbl
• Gameleap/mw4/Content/core.build

What they control:

• which mechs are actually in the active roster
• which IDs exist in code and script space
• which mech resources are packed into the runtime build

If a mech folder exists but it is not listed in these files, it is usually not playable.

2. Default weapon loadout and weapon-facing metadata

Primary file:

• Gameleap/mw4/Content/Mechs/<MechName>/<mech>.subsystems

Each weapon block typically contains:

• Model= weapon subsystem resource
• InternalLocation= where the weapon is mounted
• Site= mount port name
• GroupIndex= weapon group number
• WeaponFacing= optional facing metadata
• AmmoCount= for ammo-using weapons

The .subsystems file is the source for:

• Weapons_With_Locations
• Default_Installed_Locations
• facing annotations in the hardpoint summaries

3. Slot capacity / hardpoint support

Primary file:

• Gameleap/mw4/Content/Mechs/<MechName>/<mech>.damage

Each section such as [LeftArmInternal] or [RightTorsoInternal] may contain:

• MissileSlots=
• ProjectileSlots=
• BeamSlots=
• OmniSlots=

These are used to derive:

• Available_Slot_Capacity_By_Zone
• Available_Hardpoints

4. Weapon slot type rules in code

Relevant code:

• Gameleap/code/mw4/Code/MW4/MWDamageObject.cpp
• Gameleap/code/mw4/Code/MW4/MWDamageObject.hpp
• Gameleap/code/mw4/Code/MW4/MechLab.cpp
• Gameleap/code/mw4/Code/MW4/Subsystem_Tool.cpp
• Gameleap/code/mw4/Code/MW4/Weapon_Tool.cpp
• Gameleap/code/mw4/Code/MW4/Weapon.hpp
• Gameleap/code/mw4/Code/MW4/Weapon.cpp
• Gameleap/code/mw4/Code/MW4/hudweapon.cpp

What the code does:

• reads slot counts from .damage
• reads InternalLocation and WeaponFacing from .subsystems
• maps weapon slot type and size from the weapon model
• assigns weapons to valid locations during mechlab editing

Facing Semantics

Weapon facing is stored per weapon instance, not as a separate hardpoint label.

Values seen in the data/code:

• 0 = front
• 1 = rear
• 2 = side

Code references:

• Gameleap/code/mw4/Code/MW4/Weapon_Tool.cpp
• Gameleap/code/mw4/Code/MW4/Weapon.hpp
• Gameleap/code/mw4/Code/MW4/Weapon.cpp
• Gameleap/code/mw4/Code/MW4/hudweapon.cpp
• Gameleap/code/mw4/Code/MW4/MechLab.cpp

Important nuance:

• a zone name like LeftTorso does not tell you the facing by itself
• the facing comes from the weapon block¡¯s WeaponFacing
• the same zone can contain multiple weapons with different facings

Group Index Meaning

The G1, G2, etc. suffix in Weapons_With_Locations is the weapon group number from GroupIndex in the subsystem file.

This is not a location or facing field.

Meaning:

• G1 = weapon group 1
• G2 = weapon group 2
• and so on

How The Spreadsheet Was Built

The CSV was assembled by cross-referencing:

• mech folder contents under Gameleap/mw4/Content/Mechs/
• .subsystems weapon blocks
• .damage internal zone capacities
• active roster tables and IDs
• string registration files
• build manifests
• loose UI art assets under Gameleap/mw4/hsh/

The output is a derived audit sheet, not a direct export from a single source file.

Known Pitfalls

1. Folder presence does not mean playable

Some mech folders exist but are not in the active roster tables or headers. These need ID/table/build integration before they are usable in-game.

2. File names are not always canonical

Some mechs use alternate base filenames inside their folder. Do not assume FolderName/FolderName.damage or FolderName/FolderName.subsystems always exist.

Prefer:

• parse the .instance file when present
• otherwise detect the first matching .subsystems / .damage file by extension and content

3. Available_Hardpoints is a summary, not a literal port map

It summarizes zones with capacity and facing hints, but it does not enumerate every exact port or site name.

4. Rear-facing weapons are per-instance

If a mech has one rear-mounted weapon in a torso zone, that does not mean all weapons in that zone are rear-facing.

Update Checklist For Future Changes

If a mech is added or changed, check these in order:

1. update or verify the mech .data, .instance, .subsystems, and .damage files
2. ensure the mech is added to the active ID header(s)
3. update MechChassisTable.tbl and MechTable.tbl
4. update core.build and any related build manifests
5. add any needed string IDs or script references
6. confirm the mech has the expected loose or packed art assets
7. rebuild the CSV derived columns if the data changed

Useful File Map

Mech data

• Gameleap/mw4/Content/Mechs/<MechName>/

Roster and IDs

• Gameleap/code/mw4/Code/MW4/MechLabHeaders.h
• Gameleap/mw4/Content/ShellScripts/MechLabHeaders.h
• Gameleap/mw4/Content/Tables/MechChassisTable.tbl
• Gameleap/mw4/Content/Tables/MechTable.tbl

Slot/hardpoint logic

• Gameleap/code/mw4/Code/MW4/MWDamageObject.cpp
• Gameleap/code/mw4/Code/MW4/MechLab.cpp
• Gameleap/code/mw4/Code/MW4/Subsystem_Tool.cpp

Facing logic

• Gameleap/code/mw4/Code/MW4/Weapon.cpp
• Gameleap/code/mw4/Code/MW4/Weapon.hpp
• Gameleap/code/mw4/Code/MW4/Weapon_Tool.cpp
• Gameleap/code/mw4/Code/MW4/hudweapon.cpp

Build manifests

• Gameleap/mw4/Content/core.build
• Gameleap/mw4/Content/props.build
• Gameleap/mw4/Content/textures.build

Current State Summary

At the time this doc was written:

• mech_loadouts.csv includes playability, default loadout, facing, hardpoint, and notes columns
• non-playable mechs are explicitly marked No
• Templar and other mechs with rear or side mounts have facing visible in the CSV
• the file is intended to be a living audit artifact for future data cleanup and enablement work

---

MechEditor Web App — Data Sources, Fields, and Conversions (documented 2026-07-23)

The MechEditor is a single-file Python HTTP server at /home/rich/Repositories/MechEditor/mech_editor.py.
It runs at localhost:8765, parses the firestorm content tree, and presents a full mech configuration editor in the browser.
This section documents every data field it reads, every conversion it performs, and every naming rule it enforces.

---

Data Files Parsed Per Mech

All files live under Gameleap/mw4/Content/Mechs/<MechDir>/.

.data file (parse_data())

Field in file	Editor key	Notes
VehicleTonnage	tonnage	chassis base tonnage (float)
MaxVehicleTonnage	max_tonnage	max loadout tonnage (float)
TechType	tech	$(Tech_IS) ? "IS", $(Tech_Clan) ? "Clan"
MaxHeat	max_heat	heat capacity (int)
VehicleTradeValue	trade_value	C-bills
DragoonValue	dragoon	used in Power Rating bar scaling
MinMaxSpeed	min_max_speed	base speed ceiling in m/s
MaxSpeed	max_speed	absolute speed ceiling in m/s (engine upgrades may not exceed this)
FullStopTurnRate	full_stop_turn	turn rate at zero speed, in degrees/sec
TopSpeedTurnRate	top_speed_turn	turn rate at top speed, in degrees/sec
Acceleration	acceleration	forward acceleration in m/s²
Decceleration	decceleration	forward braking in m/s² — double-c spelling is canonical in the engine source
ReverseAccelerationMultiplier	rev_accel_mult	multiplier applied to Acceleration for reverse
ReverseDeccelerationMultiplier	rev_decel_mult	multiplier applied to Decceleration for reverse — double-c canonical
MinStandTransitionSpeed	not surfaced	animation threshold only — see note below
CanLoadJumpJets	can_jj	Yes/No
CanLoadECM	can_ecm	Yes/No
CanLoadBeagle	can_bap	Yes/No
CanLoadLightAmp	can_lightamp	Yes/No
CanLoadAMS	can_ams	Yes/No
CanLoadLAMS	can_lams	Yes/No
CanLoadIFF_Jammer	can_iff	Yes/No

MinStandTransitionSpeed is the speed (m/s) below which the mech switches from its walking animation to its idle/standing animation.
It is NOT a hard movement limit. It is purely an animation state machine threshold in Mech.cpp.
Code path: animStateEngine?RequestState(StandState) when currentSpeedMPS <= minStandTransitionSpeed.
Must be > 0 (validated in Vehicle_Tool.cpp). Argus = 12.631 m/s = 45.5 kph.

.instance file (parse_instance())

Field	Editor key	Notes
PowerRating	PowerRating	mechlab bar value, 0–100
ArmorRating	ArmorRating	mechlab bar value, 0–100
SpeedRating	SpeedRating	mechlab bar value, 0–100
HeatRating	HeatRating	mechlab bar value, 0–100
DoesHaveLightAmp	has_lightamp	0 or 1, default 1 — whether LightAmp is currently installed

.subsystems file (parse_subsystems())

Provides: armor type + per-zone multipliers, installed heatsinks, jump jets, engine upgrades, weapons, electronics.

Armor block:

• ArmorType= ? armor type string (Standard, FerroFiberus, Reactive, Reflective, Solarian)
• Per-zone entries: LeftArm=1.0, RightTorso=2.5, etc. — multiplier for that zone

Engine:

• EngineUpgrade blocks counted ? engine_upgrades (0–5)

Weapons — each weapon block contains:

• Model= ? weapon subsystem resource path (name extracted)
• InternalLocation= ? zone name
• Site= ? mount port name (from armature)
• GroupIndex= ? weapon group number
• WeaponFacing= ? 0=Front, 1=Rear, 2=Side (absent = Front)
• AmmoCount= ? rounds for ammo-using weapons
• EjectSite= ? optional ejection site for ammo

Electronics: ECM, Beagle (BAP), AMS, LAMS, IFF_Jammer detected by subsystem model path.

.damage file (parse_damage())

Per zone section [ZoneInternal]:

• BaseArmorValue ? starting armor (float)
• MaxArmorValue ? hard cap on armor pts for that zone
• InternalHPValue ? internal structure HP
• OmniSlots, BeamSlots, MissileSlots, ProjectileSlots ? weapon slot counts

Special zones:

• SpecialAttachedToZone= ? which body section this special zone is attached to
• DamagePropagationZone= ? where overflow damage propagates

.engine file (parse_engine())

Field	Editor key	Notes
NumHeatSinks	NumHeatSinks	free heatsinks from engine (not in subsystems)
TonsPerUpgrade	TonsPerUpgrade	tonnage cost per engine upgrade tier
MPSPerUpgrade	MPSPerUpgrade	m/s speed gain per upgrade tier

.torso file (parse_torso())

Field	Notes
TwistSpeed	torso horizontal rotation speed — may be a macro reference
PitchSpeed	torso vertical rotation speed — may be a macro reference
TwistRadius	max horizontal twist angle — may be a macro reference
PitchRadius	max vertical pitch angle — may be a macro reference
ArmRatioAngle	ratio of arm tracking vs torso rotation — may be a macro reference

All torso fields may reference macros from Content/Defines/MechTorso.defines.
The editor resolves them using a preloaded TORSO_DEFINES dict. Notable values:

NORMAL_RATIO   = 40
SNAIL_TSPEED   = 40
NORMAL_TSPEED  = 60
FAST_TSPEED    = 80
WIDE_TRADIUS   = 160
NORMAL_PRADIUS = 40

---

Calculated Ratings and Conversions

Speed (kph)

top_speed_kph = min(MinMaxSpeed + MPSPerUpgrade × engine_upgrades, MaxSpeed) × 3.6

• MinMaxSpeed and MaxSpeed from .data (m/s)
• MPSPerUpgrade from .engine (m/s per tier)
• engine_upgrades from .subsystems (0–5)
• Multiply by 3.6 to convert m/s ? kph
• Argus example: (20.28 + 1.11 × 10) × 3.6 = 113.5 kph

Speed Rating (bar)

speed_rating = (top_speed_mps / MaxSpeed) × 100   [capped at 100]

Turn Rate — degrees to radians

The .data file stores turn rates in degrees/sec. The mechlab UI label was changed to show rad/sec:

• StringResource.rc: IDS_ML_CH_TURNRATE ? "Turn Rate (Top Speed Rad/Sec):"
• Conversion: radians = degrees × ?/180 where ?/180 ? 0.017453
• Argus: FullStopTurn = 75° = 1.309 rad/sec, TopSpeedTurn = 45° = 0.785 rad/sec

Acceleration / Deceleration (m/s²)

Stored directly in .data. Reverse values are derived:

reverse_accel = Acceleration × ReverseAccelerationMultiplier
reverse_decel = Decceleration × ReverseDeccelerationMultiplier

The double-c spelling (Decceleration, ReverseDeccelerationMultiplier) is canonical — it matches the engine source. Do not "fix" the spelling.

Heat Rating (bar)

total_hs = NumHeatSinks (engine) + installed_heatsinks (subsystems)
effective_hs = total_hs × (2 if Double else 1)
heat_rating = (effective_hs / MaxHeat) × 100   [capped at 100]

Power Rating (bar)

total_damage = ? (DamageAmount × NumFire)  for each installed weapon
power_rating = (total_damage / 80) × 100   [capped at 100]

• DamageAmount and NumFire come from WeaponSubsystems/<weapon>.data following !include chains
• Parsed by load_weapon_damages() at server startup, cached in Handler.weapon_damages
• Argus example with default load: ~36.2 total damage ? 45 rating (stored = 42)

Armor Rating (bar)

for each zone:
    pts = multiplier × ARMOR_PTS_PER_TON[armor_type]
    effective = min(pts, MaxArmorValue[zone])
armor_rating = (? effective / ? MaxArmorValue) × 100

Armor pts per ton by type (from Adept/ResourceImagePool.cpp and game design):

Type	Pts/ton
Standard	32
FerroFiberus	38
Reactive	30
Reflective	30
Solarian	60

Note: FerroFiberus is the canonical internal token (not player-visible). The player sees DNL_FERROFIB = "Ferro Fibrous" via string lookup.

---

Active-in-Game Detection

Source: Gameleap/mw4/Content/Tables/MechChassisTable.tbl

Format:

DisplayKey=Mechs\DirName\FileName.data
//CommentedKey=Mechs\DirName\FileName.data   <- inactive

• Active = entry exists AND is not prefixed with //
• Currently the only inactive mech: Dasher (commented out)
• The editor shows a green ACTIVE IN GAME or red NOT IN GAME banner at top of Stats tab

---

hsh/ Image Naming Conventions

The hsh/ directory under Gameleap/mw4/ holds loose BMP files loaded at runtime (not packed into .mw4).
There are four relevant subdirectories, each with a different naming authority.

hsh/hud/ — in-game HUD damage silhouette (own mech)

hsh/MFD/ — MFD target display silhouette (target mech)

hsh/radar/hud/ — radar damage overlay

All three use identical stems sourced from huddamage.cpp texturename[] array.

Load path:

• hud/MFD: hsh\<texturename>.bmp where texturename = hud\<stem> ? file = hsh/hud/<stem>.bmp
• radar: hsh\radar\<texturename>.bmp ? file = hsh/radar/hud/<stem>.bmp

Code: render.cpp CRadar_Device::LoadRadarDamageTexture() and huddamage.cpp HUDDamage.

hsh/Mechs/ — mw4print scorecard portrait

Load path: recscore.cpp ? GetLocString(model->m_nameIndex) ? DNL_* string from StringResource.rc ? lowercased filename.
Different naming authority from the other three.

---

Complete Canonical Name Table

Key: mech directory name (case-insensitive) ? canonical stem for hsh/hud/, hsh/MFD/, hsh/radar/hud/.
Entries in bold differ from the directory name.

Directory	hud/MFD/radar stem	hsh/Mechs/ portrait filename
Annihilator	annihilator	annihilator.bmp
Archer	archer	archer.bmp
ArcticWolf	arcticwolf	arctic wolf.bmp
Ares	ares	ares.bmp
Argus	argus	argus.bmp
Assassin2	assassin2	assassin ii.bmp
Atlas	atlas	atlas.bmp
Avatar	avatar	avatar.bmp
Awesome	awesome	awesome.bmp
Battlemaster	battlemaster	battlemaster.bmp
Battlemaster2c	battlemasteriic	battlemaster iic.bmp
Behemoth	behemoth	behemoth.bmp
Behemoth2	behemothii	behemoth ii.bmp
Blackhawk	blackhawk	black hawk.bmp
Blacknight	blackknight	black knight.bmp
Blacklanner	blacklanner	black lanner.bmp
Brigand	brigand	brigand.bmp
Bushwacker	bushwacker	bushwacker.bmp
Catapult	catapult	catapult.bmp
CauldronBorn	cauldronborn	cauldronborn.bmp (table key has hyphen; DNL does not)
Chimera	chimera	chimera.bmp
Commando	commando	commando.bmp
Cougar	cougar	cougar.bmp
Cyclops	cyclops	cyclops.bmp
Daishi	daishi	daishi.bmp
Deimos	deimos	deimos.bmp
Dragon	dragon	dragon.bmp
Fafnir	fafnir	fafnir.bmp
Flea	flea	flea.bmp
Gladiator	gladiator	gladiator.bmp
Grizzly	grizzly	grizzly.bmp
Hauptmann	hauptmann	hauptmann.bmp
Hellhound	hellhound	hellhound.bmp
Hellspawn	hellspawn	hellspawn.bmp
Highlander	highlander	highlander.bmp
Hollander	hollanderii	hollander ii.bmp
Hunchback	hunchback	hunchback.bmp
Kodiak	kodiak	kodiak.bmp
Loki	loki	loki.bmp
Longbow	longbow	longbow.bmp
Madcat	madcat	mad cat.bmp
Madcat_MKII	madcat2	mad cat mkii.bmp
Masakari	masakari	masakari.bmp
Mauler	mauler	mauler.bmp
Novacat	novacat	nova cat.bmp
Osiris	osiris	osiris.bmp
Owens	owens	owens.bmp
Puma	puma	puma.bmp
Raven	raven	raven.bmp
Rifleman	rifleman	rifleman.bmp
Ryoken	ryoken	ryoken.bmp
Shadowcat	shadowcat	shadow cat.bmp
Solitaire	solitaire	solitaire.bmp
Sunder	sunder	sunder.bmp
Templar	templar	templar.bmp
Thanatos	thanatos	thanatos.bmp
Thor	thor	thor.bmp
Uller	uller	uller.bmp
Urbanmech	urbanmech	urbanmech.bmp
Uziel	uziel	uziel.bmp
Victor	victor	victor.bmp
Vulture	vulture	vulture.bmp
Warhammer	warhammer	warhammer.bmp
Wolfhound	wolfhound	wolfhound.bmp
Zeus	zeus	zeus.bmp

Critical mismatches where directory name ? hud/MFD stem (files must use the stem, not the dir name):

Directory	Wrong name (dir-based)	Correct name (stem)
Battlemaster2c	battlemaster2c.bmp	battlemasteriic.bmp
Behemoth2	behemoth2.bmp	behemothii.bmp
Blacknight	blacknight.bmp	blackknight.bmp
Hollander	hollander.bmp	hollanderii.bmp
Madcat_MKII	madcat_mkii.bmp	madcat2.bmp

Portrait mismatches for hsh/Mechs/ (table key ? DNL string):

The MechChassisTable.tbl display key and GetLocString() DNL string differ for these mechs.
mw4print uses the DNL string. The table key is NOT the correct portrait filename for these 5 mechs.

Directory	Table key (wrong for mw4print)	DNL string (correct portrait stem)
Assassin2	AssassinII ? assassinii	DNL_ASSASSIN2 "Assassin II" ? assassin ii.bmp
Battlemaster2c	BattlemasterIIC ? battlemasteriic	DNL_BATTLEMASTERIIC "Battlemaster IIc" ? battlemaster iic.bmp
Behemoth2	BehemothII ? behemothii	DNL_BEHEMOTHII "Behemoth II" ? behemoth ii.bmp
CauldronBorn	Cauldron-Born ? cauldron-born	DNL_CAULDRONBORN "Cauldronborn" ? cauldronborn.bmp
Hollander	HollanderII ? hollanderii	DNL_HOLLANDERII "Hollander II" ? hollander ii.bmp

---

MechEditor Implementation Notes

The editor encodes all of the above knowledge in two Python dicts:

MECH_HSH_STEMS (in mech_editor.py)
Maps lowercase dir name ? canonical stem for hsh/hud/, hsh/MFD/, hsh/radar/hud/.
Source: huddamage.cpp texturename[] array.

MECH_PORTRAIT_OVERRIDES (in mech_editor.py)
Maps lowercase dir name ? portrait stem for hsh/Mechs/ where the DNL string differs from the chassis table key.
Source: DNL_* entries in Gameleap/code/mw4/Code/scriptstrings/StringResource.rc.

For all other mechs, the portrait stem is derived dynamically from MechChassisTable.tbl (display key, lowercased).

The Assets tab in the editor shows all four image types. When an image is missing, it displays:

Wants: hsh/<subdir>/<expected_filename>.bmp

so the user knows exactly what to rename or create.