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](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