Add Mechs

From Battletech Modding Wiki
Jump to: navigation, search


Dingers Youtube Tutorial, is a great example of how to make a new variant of a mech and also how to trouble shoot some of the problems that you might run into while doing so!

If you don't want to watch the you tube tutorial here is precise instructions on how to Add Grand Dragon.


To add Mechs or edit existing mechs you need to understand that each Battlemech and it's Variants are defined in a set of 3 files + the bundled Model files. At the current time we can Not edit the model files.

The three files that define the mech are .json files and are:

  1. the mechdef file under SteamLibrary\SteamApps\common\BattleTech - Private Beta\BattleTech_Data\StreamingAssets\data\mech\
  2. the chassisdef file under SteamLibrary\SteamApps\common\BattleTech - Private Beta\BattleTech_Data\StreamingAssets\data\chassis\
  3. the movedef file under SteamLibrary\SteamApps\common\BattleTech - Private Beta\BattleTech_Data\StreamingAssets\data\movement\

The files generally have the name of the mech in them, like chassisdef_atlas_AS7-D.json for ease of understanding though the name is not required.


  • The mechdef file contains general info about the Name, ID, Icon, cost and rarity of the mech and if they can be purchased.
  • It also contains the link to the chassisdef file and mechtags that describe the role of the mech. It is important that the tags include "unit_release_ksbeta" or the mech will not be available in the game.
"MechTags": {
 "items": [
"tagSetSourceFile": "" 
  • The last and largest part of the mechdef is the inventory, this is a list of all items installed in the mech and the location they occupy. Here weapons, ammo and HS can be swapped, added and removed. The names are case sensitive and some items might not work.


  • The chassisdef file general data about the chassis, line name, icon, descriptions, but also many modifiers and values used in game, like melee damage. The heatsinks are set to 0 in all chassis, as none have more than the standard 10 free HS defined in the game constants (the Free 10 for the Fusion Reactor) And the rest are assigned in the MechDef.
  • Also found in the chassis file are the values for the internal structure, armor and hardpoints in each section, including the type of hardpoint. The file also contains the line to the movedef file (MovementCapDefID).
  • Remember that 'Chassis' are just that the Chassis that the 'Variants' are built on, eg the 'Atlas' is all built on the ASD chassis.


  • The movedef contains the walk and sprint max distances and speed/acceleration info that is most likely used by the game engine during animation.
  • A big thing to remember with the Movement Def is that 'Walk' is walk+run (read the Wiki Entry it explains things better!).

Linking of the files.

  • The 3 files are linked using the assigned IDs, not filenames.
  • This means the "Id": fields and names are important..
    • Your MechDef will look for your ChassisID
    • Your ChassisID will look for your MoveDef with MovementCapDefID:

Mech Legality.

  • The game currently does not verify if a mech is mechlab legal, so most things can be changed.

Editing Existing Mechs

To just change a mech it is sufficient to just change the files, after making a backup.

There is also K1ttykat's tool

Creating New Variants

Step 1: Clone your source Mech,

Copy your new files to the mod structure. So grab the existing Items and move them into your own folder structure as described here you are going to want 2 files presuming you are not planning on adjusting the speed of the mech in this example we will follow sterlings great one with some minor modifications.

  • Copy mechdef_thunderbolt_TDR-5BS.json from the exiting mech folder and put it into Mods\<yourmod>\Mechs then rename it to what you need.
  • Copy chassisdef_thunderbolt_TDR-5BS.json from the existing chassis folder and put it into Mods\<yourmod>\Chassis then rename it to what you need.
  • if you are planning on adjusting movement copy movedef_thunderbolt_TDR-5BS.json from the existing movement folder and put it into Mods\<yourmod>\Movement

Step 2: Assign New ID's,

you need to open up each of the new files and give them unique ID's we recommend Notepad++, but any text editor will work.

  • In the new movedef we want to find the line that begins like this "Id" : "movedef_thunderbolt_TDR-5BS" and we want to change it to read "movedef_ournewmech_ABC-123" and remember what we name this.
  • In the new chassisdef we want to find the line "Id" : "chassisdef_thunderbolt_TDR-5BS", and give it a unique name, we also want to find the line "MovementCapDefID": "movedef_thunderbolt_TDR-5BS" and change it to read what we set in the movedef file.
  • In the new MechDef we want to find the line ID: "mechdef_thunderbolt_TDR-5BS" and again give it a unique name, we also want to update the "ChassisID": to point to the new chassis def Id.
    • We also want to make certain we have in the:
      • "MechTags": { "items": [ "unit_mech", "unit_assault", "unit_release_ksbeta", "unit_ready", "unit_role_brawler" ], "tagSetSourceFile": "" },
        • "unit_mech"
        • "unit_<class>" (Replace <class> with light, medium, heavy, assault)
        • "unit_release_ksbeta" (This is important with out it in Beta 1 the mech will NOT show up).
        • "unit_ready"
        • "unit_role_<role>" (replace the role with one of the useable roles or simply remove this line or leave it as is)
  • Modify these files to make your mech, the Chassis defines the overall base chassis, the mech defines the weapons etc on that mech and the movement the movement of the mech. Read the fileformat documents for more information or look at existing files.

Step 3: Assign New Tags

This is possibly one of the hardest steps and for the skirmish game mode is not required. However, if you want to have your new Mech dynamically pulled in to lances used for campaign contracts, it needs tags and an entry in the database. To do this at the moment you need an SQLite editor or BMIT: you can get one for free from here. Once you have it, first backup your MetaDatabase.db file, then open it in the editor and:

  • Navigate to the TagSet table.
  • The TagSetID requires a Unique version 1 UUID (or GUID). You can generate one here
  • Add a new Entry: in the TagSetID Column enter the same UUID you generated above. In the TagSetTypeID field enter 5 (for mechdef). This step must be done first, before adding your unit definition and TagSetTag entries.
    • If you're using a different tool, or can't get the GUI interface to add a record successfully, the SQL command to use is: INSERT INTO TagSet('TagSetID','TagSetTypeID') VALUES ('YourGenerated UUID',5);
  • Save your work: Click the Write Changes button. You have to save here, otherwise the following steps will fail. Mechdefs cannot be added with a UUID that does not already exist in the TagSet table.
  • Navigate to the UnitDef table, and add a new entry for your new mech. In the "UnitDefID" column enter the ID as it is listed in the ID tag of the the MechDef file (eg "mechdef_thunderbolt_TDR-5BS"). in the FriendlyName column add the English friendly name (eg "Thunderbolt"). If your Mech is a variant of an existing Mech, set the IconID column to the appropriate icon. For our Thunderbolt example, that would be uixTxrIcon_thunderbolt. Enter 1 for the UnitTypeID field. (1 is BattleMech, 2 is Vehicle, 4 is Turret, 8 is Building). Next, for TagSetID, put in the ID you generated in the first step and added to the TagSet table. Finally, in cost, put an integer value that equals the cost of the mech in Cbills. Eg 1500000 would be 1.5 million cbills.
    • The SQL statement for this section is: INSERT INTO UnitDef('UnitDefID','FriendlyName','IconID','UnitTypeID','TagSetID','Cost') VALUES ('ID_from_mechdef','Name_from_mechdef','Icon_from_mech_def',1,'UUID_from_step_one',Cost_from_mech_def);
  • Save your Work.
  • Now, navigate to the TagSetTag table
  • These are the the tags that lets the campaign game look up and pull in Mechs as needed for dynamic lances. When a lance calls for a Mech with a tag for unit_medium and unit_assassin, it checks these tags to find the eligible units before reading the details from the corresponding json files. You need to add a line for every tag in your mechdef file. The first column, TagSetID, is always going to be the UUID you generated in the first step. The second column, TagName, is the exact name of the tags from your Mechdef file. So for the Thunderbolt-5SS, we'd add a record each for:
    • unit_mech
    • unit_heavy
    • unit_lance_tank
    • unit_role_brawler
    • unit_release
      • The SQL statement for this section is: INSERT INTO TagSetTag('TagSetID','TagName') VALUES ('UUID_From_Step_one','MechTag_From_Mechdef');

Step 4: Package your mod with ModTek

ModTek is tool for packaging Battletech mods and loading them. It doesn't require dealing with the VersionManifest.csv. Writing a ModTek mod is not hard, but the ModTek documentation is at the ModTek link.

Step 4 (Deprecated): Assign Entries in VersionManifest.csv

If you don't want to use ModTek, you will need to add the 3 definition files into it to do this you need to open the VersionManifest.csv file (located at teamLibrary\SteamApps\common\BattleTech - Private Beta\BattleTech_Data\StreamingAssets\data\VersionManifest.csv) and add the 3 entries for your new files at the end it will look something like this:

  • Please note this example is an OpenBeta manifest you will need to update the manifest to match the NEWEST formats see VersionManifest for more information.

Step 5: Show time

Fire up the game so long as you did everything right you have a brand new mech to play with!