Adding a completely new mesh

From Battletech Modding Wiki
Jump to: navigation, search
Please note credit for this goes to SolahmaJoe on the Battletech Forums. & I in this refers to Solahma Joe.
There's still many issues and its a hugely hackish job, but SolamhaJoe was able to get PGI Rifleman artwork in the game.

(Note: These instructions were updated on September 19th, 2018 by GentlePayload to reflect new method for building assetBundles and building .json file structure for use with Battletech Mod Loader (BTML) and Roguetech Mod Loader(RTML). If you run into problems (and you will) or have questions, you can find me or BloodyDoves on Discord here: game_modding_help--GentlePayload)

Tools needed:


Build AssetBundle Script (Copy/paste into a c# script from here:

Unity Asset Bundle Extractor (

Blender 3D Modeling Software (

GIMP Image editing software (

.dds plugin for GIMP (

MS Visual Studio (Installed with Unity) or another advanced text editor.

Artwork. The PGI artwork for MWO can be export by following these instructions:

Sparkles Plugin for Blender (!RMkiXL7S!fv7QQTGMLvuMld06emFB6Zl3JSk9WPzQfGKD5EUDb-c)

General Notes:

  • I recommend saving all the files involving the asset bundle to a working directory.  Just before testing copy the current version of your asset bundle to StreamingAssets\data\assetbundles.  (Must be there for the game to find it.)
  • You can store your .json files in the standard directories or create your own folder someplace under StreamingAssets for your mod.  The paths just need to be correct in the mod.json file to properly update the version manifest.
  • Getting the meshes aligned properly takes tons of trial-and-error. Involves getting the mesh all the way into the game to check, then adjusting our source file in your 3D software, and then following long series of steps to get it into the new asset bundle.
  • There will be some fudging for the difference in hardpoints between the bundle you copy and the 'Mech you're replacing it with. Such as: I overwrote jm6_right_arm_forearm_missile10_mh1 with rfl_right_arm_forewarm_laser_eh1.
  • UABE sucks at saving the asset bundles themselves.  It’s best to save as a new file, then from Windows Explorer delete or rename the old file. Then rename the new saved file to the proper name for the StreamingAssets\data\assetbundles. Eg: I’ll open chrprfmech_fleabase-001, make changes, then save it as chrprfmech_fleabase-001new. Then I’ll rename chrprfmech_fleabase-001 to chrprfmech_fleabase-001old. Then I’ll rename chrprfmech_fleabase-001new to chrprfmech_fleabase-001. Then copy it to StreamingAssets\data\assetbundles. This maintains a backup for when things (inevitably) go wrong. Depending on the changes I might maintain 2-3 old versions.

The quick version is:

Create an new bundle:

  • Export CAB file from existing HBS bundle
  • Create new empty bundle with Unity
  • Import CAB from HBS bundle into new bundle
  • Update bundles manifest entry

Overwrite the imported models & textures:

  • Export the model from your 3D software.
  • Import models & texture into a Unity project.
  • Use Build AssetBundles menu option (created by c# script) to save it to a surrogate asset bundle
  • Open & unpack the surrogate asset bundle in Unity Asset Bundle Extractor
  • Export models and textures in RAW format. (Make sure to export the Mesh, not GameObject.)
  • Open the new asset bundle you created above.
  • Locate the matching models and textures and import the new models/texture as RAW. I.e: replace jm6_centre_torso_rear with rfl_centre_torso_rear. (Again, make sure to import over the Mesh, not GameObject.)
  • Save and and copy your new asset bundle to StreamingAssets\data\assetbundles.
  • Load the game and hope you didn't make some small typo.

Creating the new Asset Bundle

1. Create new asset bundle inside Unity

  • Open Unity. Create new project. (or open an existing project)
  • Open the folder for your project in windows explorer.
  • In the Assets folder, create 2 new folders. AssetBundles, and Editor. Verify they appear in the file structure inside Unity.
  • In Unity, open the Editor folder, right-click and select "Open C# Project."
  • Copy and Paste the Build AssetBundles script (link is in the tools section). Edit the script so that BuildPipeline.BuildAssetBundles points to your project's AssetBundles folder and ensure "BuildTarget.StandaloneWindows."


  • Save and close Visual Studio and ensure your new script appears in the Editor folder.
  • Verify script is functioning by right-clicking. Under "Open C# Project" there should be a new menu item called "Build AssetBundles."
  • Create an empty GameObject following the HBS naming scheme for asset bundles, E.g: chrPrfMech_FleaBase-001.
  • Drag the GameObject into the Project assets to create a Prefab.
  • Assign the new Prefab to a new Asset Bundle, also following the HBS naming scheme.
  • Build the bundle by going to right-clicking and selecting Build AssetBundles.
    Creating new asset bundle in Unity.png
  • Copy the new bundle from <project_folder>\AssetBundles\Windows to your working directory.

2. Export CAB from existing BattleMech asset bundle

You want to use the asset bundle from a BattleMech that has a similar size and structure (normal vs reversed legs) for the animations, and similar hardpoints in each location. This will simplify the amount of editing you will have to do later on.

Hardpoints can be overwritten and moved between locations (E.G. missile to energy/ballistic or CenterTorso to Head) easier than new ones added. Will cover more on hardpoints in a later section.

  • Open Unity Asset Bundle Extractor (UABE).
  • Open an existing HBS bundle from StreamingAssets\data\assetbundles.
  • Unpack when prompted and save as an new file (to your working directory).
  • Click on Export & save CAB file.

3. Import CAB file into your new asset bundle

  • Use UABE to open the asset bundle you created in Unity.
  • Unpack when prompted & save with a new filename (e.g.: chrprfmech_fleabase-001unpacked).
  • Import the CAB file from the HBS bundle (the contents will not appear yet).
  • Save (see general notes above), close, and reopen.
  • Click Info. Your new bundle should have the content from the HBS bundle you copied.
    New bundle contents.png

4. Update new asset bundle manifest

  • Sort info list by Type & locate the one AssetBundle entry.
  • Click Export Dump and save file to your working directory.
  • Open the file in a text editor.
  • Rename all instances of the old ‘Mechs name with the new ‘Mech and save the file.
  • Check all hardpoints. This is where hardpoints can be changed or moved. The game only recognizez the following hardpoints: ac2, ac5, ac10, ac20, gauss, mg, laser, ppc, flamer, missile2, missile4, missile5, missile6, missile10, missile15, missile20, and narc. any other hardpoint such as uac or lbx are ignored. This gives you some flexibility in remapping as you can use the ignored hardpoints to fill slots in locations where you are short a hardpoint or two.

It is important that hard points match between the AssetBundle Manifest (the file you are editing), hardpointdatadef.json, and mod.json files. Any inconsistency will result in an endlessly spinning loading wheel at some point when trying to launch in a mission. Case is also important. All paths must have matching case. For example chrprfweap_leftarm_ac5_bh1 and chrPrfWeap_leftarm_ac5_bh1 are not the same and will cause an error. There is one exception to this in the mod.json file and that is "chrPrfComp" which points to the simgame prefab. This is the single player representation of your mech and will not work unless written as above.

Renaming hardpoints.png
  • Re-import the dump into the bundle by clicking Import Dump and selecting the file.
  • Save the bundle, close and reopen.
  • Verify the prefabs were renamed properly.
    Renamed hardpoints.png

(note to self: need higher res screenshot with correct prefab name. main prefab should be chrprfmech_fleabase-001, not locust!)

  • Copy the new asset bundle to StreamingAssets\data\assetbundlea

5. Create chassisdef, mechdef, and movedef files

  • Follow instructions from here: Add Mechs
  • This 'Mech is primarily for testing. It does not need to match an actual design.
  • Only include a few weapons you'll be testing first.
  • Place the files in a directory specifically for your mod. I.e.: ...\Battletech\Mods\<modname> (see your mod'd directory structure below)

Mod Directory Structure.png

6. Create hardpointsdatadef file

  • Copy the hardpoints file from the same 'Mech you copied the asset bundle CAB file.
  • Edit the file in a text editor and rename all occurrences of the copied 'Mech to your new 'Mech's name E.g.: chrprfweap_locust_leftarm_laser_eh1 to chrprfweap_flea_leftarm_laser_eh1
  • Make sure the new hardpoint names match the prefab names in the bundle's manifest from step 4.
  • Place the file in the standard HBS directories, or a directory specifically for your mod. I.e.: StreamingAssets\Mods\<yourname>\<modname>

7. Add entries in mod.json

  • Assuming you are building your mod for use with BTML or RTML. Copy mod.json from an existing mech mod such as HotD_Maurader or GP Stormcrow.
  • Add entry for new assetbundle.

AB Path.png

  • Add entry for main prefab inside the new bundle. (Make sure the first entry matches the name of the prefab inside the new asset bundle. Second entry is Prefab. Third entry matches the full prefab entry in the new bundle. Second to last entry should be the new asset bundle name.)

Prefab path.png

  • Add entries for the weapon prefabs that you will be testing. E.g.: <assets/character/mechs/prefabs/weapons/adder/chrprfweap_adder_leftarm_missile2_mh1.prefab>

Hardpoint entry.png

  • Add entries for new chassisdef, mechdef, movedef, and hardpoint json files per usual instructions: Add Mechs

Def path.png

8. Test to make sure things are working

  • Your new asset bundle should be in mods\<mod name>\assetbundles.
  • Your json files should be in their associated folder (pictured above).
  • Make sure your entries in mod.json file entries are correct.
  • Mistakes in the mod.json file can cause LWoD in either spot though.

When you get the Loading Wheel of Death:

  • Check the output_log.txt for errors (in the same directory as the StreamingAssets folder)
  • If the LWoD is before the Skirmish configuration screen (selecting ‘Mechs) the problem is probably with the def .json files.
  • If it’s when trying to launch into the actual skirmish, the probably with the asset bundle.
  • “AssetRequest could not locate asset in bundle” is the game can’t find a Prefab entry from the VersionManifest.csv or weapon in the hardpointsdatadef file with the names the asset bundle.
  • A misplaced coma in a json can be a real pain.
  • If you get the LWoD during the “Drop Sequence” screen with no loading/reading errors in the output_log.txt it *might* be a bug. (But it could also problem with the asset bundle).  I’ve had that screen hang 2-3 time in a row, then work without actually making any changes. Usually seems to happen in my final testing when I restore my StreamingAsset directory back to a base install and then re-apply my mods and try to launch a skirmish with multiple ‘Mechs form modded asset bundles. I don't get this with a fresh unmodded install, but does start happening occationally once I start adding bundles. (Not really a bug as HBS is not specifically designing the game to be modded.)

Overwriting model & texture files

1. Export models/textures from editing software

  • Use the methods explained in this post to make importing the MWO models into blender easier. Especially helpful if you intend to do mutiple mechs.

2. Import files into Unity Editor and save to surrogate bundle

  • Import the models into Unity.  (Basically copy them into the Assets folder in your project.) If using blender, you can drop the entire .blend file and it will import complete with textures.
  • Assign them to a new “surrogate” asset bundle:
Assign to surrogate asset bundle.png
  • Rebuild the asset bundles (Assets -> AssetBundles > Build AssetBundles).
  • Copy the surrogate bundle (<unity_project_folder>\AssetBundles\Windows) to your working directory.

3. Export files from surrogate bundle (RAW format)

  • Open the “surrogate” bundle in UABE & unpack and click Info.
  • Locate the models/texutres you wish to copy over. Make sure the type is Mesh for models, and Texture2D for textures.
  • Click Export Raw and save the file to your working directory with an appropriate filename.
    Export as RWA.png
  • The standard PGI/HBS models are broken up by location: centre_torso, centre_torso_rear, left_torso, left_torso_rear, right_torso, right_torso_rear, head_cockpit, centre_torso_twist (waist), centre_pelvis, centre_torso_rear, left/right_arm_clavicle, left/right_arm_upperarm, left/right_arm_forearm, left/right_leg_hip, left/right_leg_thigh, left/right_leg_calf, left/right_leg_foot, plus toes, heels, and talons.
  • There are also damaged versions of each location.
  • You can get away with combining some models. For the Flea I did not separate the rear torso locations, but I still had to create models with no polygons to overwrite the original models.
  • Weapons are a separate models with their name based on the location name.
  • For the first move I generally copy over the main body parts: torsos, cockpit, pelvis, upperarms, forearms, thighs, calves, and feet.

4. Import RAW files into new 'Mech asset bundle

  • Open your new asset bundle in UABE (ie: chrprfmech_fleabase-001).
  • Locate the Mesh/Texture you’re going to replace and click Import Raw. Again, make sure you’re selecting a Mesh or Texture2D.
    Import RAW file.png
  • Select the RAW dat file you exported.  You should see a * in the Modified column now.
  • File > Save, then close the Info window.
  • File > Save, enter a new filename, then close UABE.
  • Rename the old copy of your bundle as a back, then rename the new bundle you just saved with the correct name for the assetbundles folder. (UABE does not overwrite files correctly, you must save as a new file, then replace the original.)
  • Copy the newly saved and renamed bundle to StreamingAssets\data\assetbundlea folder.

5. Test/Check in game

  • Relaunch the game and start a skirmish with your new 'Mech.
  • At this point you’ll probably have a mess like this:
    Broken Flea.png
  • Basically, none of the meshes are aligned properly.

6. Repeat

At this point you'll be repeating steps 1 - 5. A lot.

  1. Rotate, move, scale, and/or adjust one or more models in your 3D software and export.
  2. Import them into Unity and save them into a surrogate asset bundle.
  3. Export them from the surrogate bundle in RAW formate.
  4. Import them into your new game asset bundle.
  5. Check results inside the game.

I recommend leaving the models origin at coordinates 0, 0, 0 in your software and adjusting the actual vertices. It feels like when I move/rotate the entire object the game does not mount it the same way to it's in-game parent. I then end up chasing my own changes.

You can temporarily hide parts by importing an empty mesh that has no polygons or is really tiny. You may also have to merge two meshes. This will leave on part of the new mesh without a texture. This is where the sparkles plugin comes in. See how to fix the textures here.

The names in the asset bundle will be pulled from the object name inside your 3D software. (The names will change after you save and reopen.). So if you import the same empty model to hide multiple parts you wont be able to quickly tell them apart later but you can trace it out by looking at the weapon mesh's prefab path or another mesh's parent object in the details section within UABE.

Known issues:

  • Have to re-orient & re-position meshes in another 3d program. I tried to figure out how to do this from withing the Unity Transforms in the asset bundle but couldn't get any object to move, rotate, or scale. All the meshes are used by SkinnedMeshRenderers, which makes me think the Transforms' positions/rotations/scales are getting overridden by the animations. Or I just haven't found the correct Transform.
  • Textures need work. HBS changed the MWO textures to meet their needs (for the more worn look and for differences between CryEngine & Unity). The base albedo texture will need to be to have the black areas replaced with a light grey or the 'Mech. There's a lot of improvement that could be done to match HBS's quality.
  • HBS merged the Cockpit texture from its own file to the files for the BattleMech's body. This involves some re-working of the UVW unwrap in your 3D software to fix.