This guide covers two related topics for anyone working with custom BattleTech content in MegaMek (MM), MegaMekLab (MML), and MekHQ:

1. Building custom units with MegaMekLab
2. Storing custom units (and other custom content) using a Custom User Data Directory — the current recommended approach

Our recommended way of building custom units is with [MegaMekLab](https://github.com/MegaMek/megameklab/releases). The program is kept current with the game system and can build the following unit types:

• Meks (Normal, Industrial, Tripod, Super Heavy, LAMs, QuadVee) — Building and printing (except handheld weapons)
• Combat Vehicles — Building and printing (including Naval units)
• Battle Armor — Building and printing
• Aerospace Fighters — Building and printing
• Conventional Fighters — Building and printing
• DropShips — Building and printing
• Infantry — Building and printing
• JumpShips — Building and printing
• WarShips — Building and printing
• Space Stations — Building and printing
• ProtoMechs — Building and printing
• Support Vehicles (standard support vehicles from Total Warfare/Tech Manual, except Airships, but including Rail) — Building
• Handheld Weapons for Meks

Not yet supported (TBD):

• Support Vehicles from Tactical Operations (satellite, large naval, and airship)
• Mobile Structures

Units are constructed and validated against the current construction rules. Refer to the CGL Tech Manual, Tactical Operations, Strategic Operations, and Interstellar Operations for the underlying rules — these books/PDFs are available from DriveThruRPG or the Catalyst Game Labs store. MegaMekLab isn't designed to explain what equipment does or how special abilities work; it references the relevant book and page number for each piece of equipment instead.

We can't guarantee that builders other than MegaMekLab will produce files that work correctly with MegaMek. MegaMek is under constant development, and while we try to maintain backward compatibility, other building programs may not keep pace with our naming systems or file formats. Files from other builders may fail to load or, in rare cases, cause crashes.

If you run into trouble with a unit built elsewhere, we're happy to help — but our first recommendation will usually be to rebuild and save the unit from MegaMekLab.

Once you've built your custom units, you need somewhere to store them. The current recommended method is setting up a Custom User Data Directory, which works across MM, MML, and MekHQ alike.

The user data directory lets you store units, camos, fonts, and other supported file types in a folder of your choosing — completely separate from any specific MegaMek installation.

• Consistency: Keep all your custom files in one place, accessible to all your MM, MML, and MekHQ installations.
• Flexibility: Choose any directory location that suits you, e.g. D:/myMMStuff.
• Ease of upgrade: When you install a new version of MM, MML, or MekHQ, just point it at your existing user folder in Client Settings — no need to move files around.

Note: The user directory works with cloud-based drives like OneDrive, Dropbox, and Google Drive, but all files must be saved locally (not stream-only/online-only).

1. MegaMek: Set the path in Client Settings (part of the ClientPreferences configuration).
2. MegaMekLab: Set the path in the Options menu.
3. MekHQ: Go to Options → Misc Options and set the path there.

Changes typically take effect after restarting the application. Point the setting at the top-level folder — the same level that would contain a data folder.

To work correctly, your custom user data directory needs to follow this structure:

• Fonts: Place font files (.ttf) anywhere within the user directory.
• Units: Store unit files (.mtf, .blk) anywhere in the user directory. Only put custom units here — if a unit also exists in your local install, you'll get duplicate entries in the mek selector.
• Images: Place images in these subdirectories:
  • data/images/camo/ — camo images
  • data/images/portraits/ — portrait images
  • data/images/fluff/<unit type>/ — unit fluff images (check /data/images/fluff/ in your MegaMek install for the exact subfolder names)
• Skins: Skin definition files (.xml) can go anywhere in the user directory.
• Rank Systems: Store rank definition files at data/universe/ranks.xml.
• Awards: Save award definition files (.xml) in data/universe/awards/.

Note: Some data types — Boards, for example — can't be used with the user directory due to how the programs load that data. The list above is complete as of the time this feature was implemented (Dec 26, 2023).

D:/myMMStuff
    ├── Oxanium.ttf
    ├── Exo.ttf
    ├── campaign_units/
    │   └── Atlas AS8-XT.mtf
    ├── data/
    │   ├── Jura.ttf
    │   ├── MyMMSkin.xml
    │   ├── images/
    │   │   ├── camo/
    │   │   │   ├── myForceCamo.png
    │   │   │   └── oldcamo/
    │   │   │       ├── camo1.png
    │   │   │       └── camo2.png
    │   │   ├── portraits/
    │   │   │   └── minscandboo.png
    │   │   └── fluff/
    │   │       ├── Mek/
    │   │       │   └── Atlas.png
    │   │       └── DropShip/
    │   │           └── Colossus.png
    └── universe/
        ├── ranks.xml
        └── awards/
            ├── MyAwards.xml
            └── AuriganAwards.xml

Before the Custom User Data Directory feature existed, the standard advice was to create a folder called Customs inside \Megamek\data\mechfiles\ and keep all custom units there:

1. Create a folder called Customs in the data/mechfiles folder.
2. Copy your custom units into the Customs folder.
3. Delete the units.cache file in the mechfiles folder.
4. Start MegaMek/MegaMekLab/MekHQ.
5. Make sure the game's year/tech level are set to what you need.
6. Double-check that "Canon units only" isn't checked.

This method still works, but it ties your customs to a single installation and doesn't share cleanly across MM, MML, and MekHQ or across version upgrades. New users should use the Custom User Data Directory method above instead.