Setting Up a Custom User Data Directory for MegaMek, MegaMekLab, and MekHQ

Setting Up a Custom User Data Directory for MegaMek, MegaMekLab, and MekHQ

Overview

This guide explains how to set up and use a custom user data directory for MegaMek (MM), MegaMekLab (MML), and MekHQ (MekHQ). The user directory lets you store units, camos, fonts, and the files listed below in a directory of your choice, outside any specific MegaMek installation. This way, you can easily share resources across different installations or versions without the 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.

Benefits of Using a Custom User Data Directory

• Consistency: Keep all your custom files in one location, accessible to all MM, MML, and MekHQ installations.
• Flexibility: Choose any directory location that suits your organizational needs, such as D:/myMMStuff.
• Ease of Upgrade: Simplifies the process of upgrading to new versions of MM, MML, or MekHQ, as all your custom content remains in a fixed location. When you install a new version, simply point the new install in the Client Settings to the location of the user folder.

Configuring the User Data Directory

Setting the Directory Path

1. MegaMek: Set the user data directory path in the Client settings. This is part of the ClientPreferences configuration.
2. MegaMekLab: Configure the path in the Options menu.
3. MekHQ: Go to Options → Misc Options and set the path for the user data directory.

Note: Changes to the user directory setting typically take effect after a restart of the application.

This should point to the location and show the data folder level.

Directory Structure

To ensure that the custom user data directory functions correctly, maintain the following directory structure:

• Fonts: Place font files (e.g., .ttf) anywhere within the user directory.
• Units: Store unit files (.mtf, .blk) anywhere in the user directory.
  Note: Only custom units should be stored in the user directory to avoid duplicate entries in the mech selector if files are also present in the local directory.
• Images: Place images in the following subdirectories:
  • data/images/camo/ for camo images
  • data/images/portraits/ for portrait images
  • data/images/fluff/<unit type>/ for unit fluff images. To find the exact subfolder names, refer to the /data/images/fluff/ directory in your MegaMek installation.
• Skins: Skin definition files (.xml) can be placed anywhere in the user directory.
• Rank Systems: Store rank definition files in data/universe/ranks.xml.
• Awards: Save award definition files (.xml) in data/universe/awards/.

Note: You’ll notice some data file types are missing, like Boards, for example. Due to how the programs use and load data, some folders just can’t be used with the User folders. The list above is considered complete as of the time of implementation (Dec 26, 2023).

Example Directory Layout

Below is an example of a suitable directory structure with some example files:

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/
    │   │       ├── Mech/
    │   │       │   └── Atlas.png
    │   │       └── DropShip/
    │   │           └── Colossus.png
    └── universe/
        ├── ranks.xml
        └── awards/
            ├── MyAwards.xml
            └── AuriganAwards.xml