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 for the Beta no longer work for the full game Release. I am working on updating them but keep hitting technical & personal roadblocks. Also, Unity no longer offers the AssetBundle Manager unless you'd previously downloaded it. I'm also looking into what to do about that. --SolahmaJoe)

Tools needed:

Unity (

Unity AssetBundle Manager (Downloaded/Installed via Unity Asset Store)

Unity Asset Bundle Extractor (

3D Modeling Software such as Blender or 3ds Max

Image editing software such as ( or GIMP (

Text editor. I recommend highly Notepad++ (

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

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 VersionsManifest.csv.
  • 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 Unity AssetBundle Manager 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.
  • Open the Unity Asset Store (Window menu > Asset Store).
  • Search for "AssetBundle Manager" and select & import the free "AssetBundle Manager & Example Scenes" by Unity Technologies.
    Unity AssetBundle Manager.png
  • 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 Assets menu > AssetBundles > 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. 

Hardpoints can be overwritten (even missile to energy/ballistic) easier than new ones added.  I have not tested moving a hardpoint between locations yet though.

  • Open Unity Asset Bundle Extractor.
  • 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

  • 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. (This is where you can re-map hardpoints.)
    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 a 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 the standard HBS directories, or a directory specifically for your mod. I.e.: StreamingAssets\Mods\<yourname>\<modname>

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 VersionManifest.csv

  • Open the SteamingAssets\data\VersionManifest.csv file in a Text editor.
  • Add entry for the new 'Mech's asset bundle.. E.g.: chrprfmech_fleabase-001,AssetBundle,data/assetbundles/chrprfmech_fleabase-001,0,2017-06-21T18:47:58.0000000Z,2017-06-21T18:47:58.0000000Z,,,0 (Make sure the first entry matches the bundle's filename, the second entry (type) is AssetBumdle, and the third enty matches the path and filename.)
  • Add entry for main prefab inside the new bundle. E.g.: chrPrfMech_fleaBase-001,Prefab,Assets/Character/Mechs/Prefabs/chrPrfMech_fleaBase-001.prefab,0,2017-05-24T11:32:28.0000000Z,2017-05-24T11:32:28.0000000Z,,chrprfmech_fleabase-001,0 (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.)
  • Add entries for the weapon prefabs that you will be testing. E.g.: <need example>
  • Add entries for new chassisdef, mechdef, movedef, and hardpoint json files per usual instructions: Add Mechs

8. Teat to make sure things are working

  • Your new asset bundle should be in StreamingAssets\data\assetbundles.
  • Your json files should be somewhere under the StreamingAssets directory.
  • Make sure your entries in VersionManifest.csv are correct.
  • Mistakes in the VersionManifest.csv 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

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.)
  • 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.

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 tell the, apart later. You can trace it out by looking at the GameObjects and their children in the bundle, but it is a huge pain and a completely separate tutorial to explain.

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.