Mod Support Readme Documentation

[HBS_Mouse]

BATTLETECH MOD SUPPORT (v 1.9.1)

Hello, and thank you for playing BATTLETECH! This document is meant to offer a basic primer on how to successfully manage mods within the game. Mod creation is still a fan driven effort, and while we have included some resources to get you started, the game itself provides no built-in resources to generate modded content.

The mods themselves must be compatible with the latest version of BattleTech, and even then there is always a chance that combining mods can create a non-functional game! In general, mod at your own risk. As mods are created externally to the game, not all mods are guaranteed to work.

1. Mod Management
The Mod Management screen is accessible from the main menu. When the mod system is enabled, it builds a list of all the installed mods and displays them here. On this screen you can enable/disable the mod system as a whole, or toggle on or off individual mods. Enabling a mod that has a dependency on other mods will automatically enable any dependent mod. And disabling a mod will also automatically disable any mods that depend on it.

1.1 How to install a mod into BattleTech

1. Find a mod you’re interested in. You can start with some common modding communities, listed below.

https://www.nexusmods.com/battletech
https://www.reddit.com/r/BattleTechMods/
​

2. Once you’ve identified and downloaded a mod, place the mod contents into a named folder inside the same folder where this document is located.

• WIN: C:\Users\user_name\MyDocuments\MyGames\BattleTech\mods
• LIN: /home/user_name/MyGames/BattleTech/mods
• OSX: /Users/user_name/MyGames/BattleTech/mods

3. Launch the game, then click the ‘Mods’ button at the bottom left of the main menu
4. You should now see your new mod in the list. If so, it’s installed and ready to go!

Note that the first time you install mods, it may take some time to load the mod.

1.2 How to uninstall a mod
1. Delete the mod you inserted into the BattleTech/mods folder in step 2 of installation
2. Launch BattleTech, and the mod should now be removed from the list!

PLEASE NOTE - Mods affect saves. If you save your game with mods installed, those saves will no longer be loadable if you uninstall the required mods.

1.3 How to change the mod installation directory
1. The game expects a file named “modFolderRedirect.txt” to be placed in the root of its persistent data folder. Depending on your system, this may be in different places:

• WIN: %userprofile%\AppData\LocalLow\Harebrained Schemes\BATTLETECH
• LIN: $XDG_CONFIG_HOME/unity3d/Harebrained Schemes/BATTLETECH
• OSX: Unity scans multiple folders. If you find multiple directories, know that Unity favors the oldest timestamp.
  • ~/Library/Application Support/Harebrained Schemes/BATTLETECH
  • ~/Library/Application Support/unity.Harebrained Schemes.BATTLETECH
  • ~/Library/Caches (This is unlikely)

2. The entire contents of this folder should be an absolute path to the folder you want to use; e.g. C:\BTMods. Please note that when redirecting mods, the BattleTech sub folder is not created.


3. If the file, and the path it specifies exist and are accessible to the current user, mods will be loaded from this folder.

OSX Note: To create a plain text file using TextEdit, use the following steps:

1. Launch Text Edit
2. Create a new file (File > New)
3. Change it to plain text format (Format > Make Plain Text)
4. Set your absolute path as desired in this file
5. Save as modFolderRedirect.txt in the appropriate directory

1.4 Enabling and disabling mods
Mods are enabled when they are installed by default. However, they can be disabled after they are installed, in case you want to play without your installed mods active. (See above note in 1.2 about save compatibility)

When mods are active they will be marked “Enabled” in the status bar:

To disable mods, check the box next to the mod, and it will be marked “disabled”:

If a mod is enabled but fails to load (such as in cases where the mod version is outdated), it will be grayed out and marked as “mod failed to load”. As long as the mod remains enabled, the game will try to load the mod on each pass. However, if the mod json is unparsable (such as having bad json), then the mod will not show up in the list at all.

If you want to disable all mods, uncheck the “Mods enabled” in the top right corner. This will put an overlay over all existing mods, disabling the ability to interact with them.

Disabling the mod loader via the “mods enabled” checkbox respects the last known status of the existing mods. This means that the next time you load the game, mods will not be loaded, but their previous status will be retained should you re-enable mods. Changes to installed/uninstalled mods will not be reflected until the “mods enabled” checkbox is enabled and the game rebooted.

As a reminder, ModLoader will show the last known status of mods, but is not designed to verify whether a mod will work. Mods are external to the loader, so mod at your own risk

You will need to restart the game for changes to take effect!

1.5 Modding Gotchas

1. Whenever mods are enabled or disabled, the game must be restarted in order for the changes to take effect. You will be prompted to restart the game if you make changes from the Mod management screen.
2. Once the game is modded, any Game Save produced will contain modded data and the mods you have installed are now required to load that save game. The save system is mod aware, and will lock out saves that include modded data, if those mods are not enabled in the mod manager.
3. If you alter the contents of the Mods folder on disk while the game is running, you will have to relaunch BattleTech for changes to be detected.
4. It is highly recommended that when playing multiplayer and using mods, that both users have the same mods installed. Not having the same mods installed will create a disconnect between game clients and prevent users from launching multiplayer matches.
5. It is possible for mods to break a BattleTech install. If you believe your game is in an unrecoverable state, do a clean reinstall of BattleTech to restore the game back to it's previously unmodded state.

2. Getting Started with Modding
2.1 Basic Concepts
Mods are made up of a JSON file that describes them, and a collection of assets. Sometimes those assets are a DLL that is patched into the game at runtime, and sometimes they are actual game assets that overwrite existing assets, or add new ones. This document primarily describes the Mod JSON Format, and the difference between System Mods and Game Mods.

2.2. Mod Types
Mods come in two flavors. There are System Mods and Game Mods. The only way that the ModLoader knows the difference between the two is from the name of the .json file used to load them. Without a “systemMod.json” or a “mod.json” the game will have nothing to point it towards the files it should load.

2.3 Mod JSON Format
{

"Name": "MyLoggerSystemMod",
"Enabled": true,

"Version": "0.1.01a",
"Description": "A system mod to add new logs to ModLoader",
"Author": "",
"Website": "https://wewantedmoreloggers.com/morelogs",
"Contact": "loggermail@wewantedmoreloggers.com",

"DLL": "MyLoggerSystemMod.dll",
"DLLEntryPoint": "MyLoggerNamespace.MyFlanelClass.MyAxeMethod",

//Game Mods Only
"Manifest": [ { “Type”: “MechDef”, “Path”: “NewMechDefPath” }, ],​

}

2.3.1 Information
These are optional fields that are used to fill out some of the information located in the Mod Manager Screen. The rest is potentially good information for mod users if you are looking to have feedback directed somewhere.

Information Sample
{

"Name": "MyLoggerSystemMod",
"Enabled": true,
"Version": "0.1.0",
"Description": "A system mod to add new logs to ModLoader",
"Author": "",
"Website": "wewantedmoreloggers.com/morelogs",
"Contact": "loggermail@wewantedmoreloggers.com",
"PackagedOn": "2020-02-02T00:22:02Z"​

}

2.3.2 Enabled
The enabled field will tell the ModLoader to either load your mod or to ignore it. If the Enabled field is missing, the ModLoader defaults to trying to load the mod. Whether or not the field has been set, the user will be able to toggle a Mod on and off from the Mod Manager Screen.

Setting whether or not a mod is enabled through the Mod Manager Screen does not write the new value to the Mod Json. Instead, this is stored in the game data as part of the Mod Status. If the Mod Json does not match the stored data, the file setting wins.

Please note that if other mods are dependent on a mod, they will also be disabled if their dependency is disabled or fails to load.

Enabled Sample:
{

"Name": "MyAwesomeMod",
"Enabled": true​

}

2.3.3 Dependencies
These fields determine if Modloader should load your mod based on the other installed mods, and what order they should be loaded in. It should be noted that Game Mods and System Mods can depend on other System Mods. However System Mods cannot be dependent on Game Mods. This is due to System Mods completing their load process before Game Mods are loaded.

Dependencies will also be indicated in Mod Manager Screen when hovering over the info icon. This can be used as an indicator for why a mod may or may not have loaded depending on what you have installed or enabled.

Dependency Sample
{

"Name": "MyLoggerSystemMod",
"Enabled": true,

"DependsOn": [ "Dependency", "Dependency2" ],
"ConflictsWith": [ "PotentialConflict" ],
"OptionallyDependsOn": [ "OptionalDependency", "OptionalDependency2" ]​

}

With dependencies, you can create a situation where Mod A depends on B, B depends on C, and C depends on A. When we detect a circular dependency, none of the mods can load. If there’s a circular Optional dependency, it loads them in an unspecified order. The modloader.log file should report any problems that it finds. There may exist some strange combination of optional dependencies vs regular dependencies that confuse the ModLoader. Use dependencies responsibly.

2.3.4 DLL
The DLL field points to the packaged DLL that the mod is intended to load and patch into the game. This is optional in regards to Game Mods but required for System Mods. Without a DLL a System Mod cannot really do anything.

DLL Sample
{

"DLL": "MyLoggerSystemMod.dll",
//Optional
"DLLEntryPoint": "MyLoggerNamespace.MyFlanelClass.MyAxeMethod",​

}

3. ModLoader Patching
The ModLoader may be patched using System Mods. System Mods are a type of mod that are loaded prior to the standard Game Mod. Because of this, they can go so far as to patch how Game Mods will be loaded. System Mods, unlike Game Mods, are exclusively a compiled DLL paired with the SystemMod.json that points the game to it. A writeup on how to get started working on DLL based mods can be found in the “Additional Resources” section at the end of this document.

3.1 System Mods
Mods can be made up of a Game Mod, a System Mod, or both! System Mods load and patch before Game Mods have started loading, so they can have an effect on that process. System Mods do not have a Manifest as they are intended to be DLL only mods and not introduce new assets or content. Otherwise, SystemMod.json is formatted and loads very similarly to mod.json.

Things that can potentially be done with System Mods:

• Add new logs to the Game Mod load flow
• Manipulate how ModLoader loads Game Mods

4. ModLoader Configuration
When you disable mods, it keeps a cache of what was installed and enabled at that time. Any changes to installed mods won’t be reflected until the mods system is reenabled. This is kept in mod_status.json and system_mod_status.json files in the mods\HBS\Cache directory.

There are also a few settings in the settings.json file that will be useful for modders. This can be found in your BattleTech installation directory.

For OSX users, navigate to your BattleTech application folder. Then right-click the BattleTech application and select “Show Package Contents.” From here you can navigate the rest of the way to the settings.json

WIN: BATTLETECH\BattleTech_Data\StreamingAssets\data\debug\settings.json
MAC: BATTLETECH\Contents\Resources\Data\StreamingAssets\debug\settings.json

"modLoggerLogLevel": "Error",
"alwaysClearModCache": false,
"disableSplashScreens": false,
"disableIntroMovie": false,​

• modLoggerLevel - defaults to Error, and determines what types of things are exported to the logs. Valid options are Debug, Log, Warning, and Error.
• alwaysClearModCache - defaults to false - The modcache system exists to speed up subsequent playthroughs for modded games. While developing mods, you might find it useful to have the cache always be cleared to prevent stale data.
• disableSplashScreens, disableIntroMovie - both default to false - to improve iteration times when developing mods, turn these off so you don’t have to wait before the mods start loading

4.1 Clearing the mod cache
There’s a setting in settings.json alwaysClearModCache which is off by default. When developing/debugging mods, it might be useful to turn this back on by setting the value to true.

The ModCache will be cleared if installed mods go missing, new mods get installed, if the version of the game changes, or if the alwaysClearModCache setting is enabled.


5. Additional resources
5.1 Popular Mods
Nexusmods is a common resource for Battletech mods.
https://www.nexusmods.com/battletech?tab=popular+(all+time)

5.2 Mod Communities
There are several communities where you can talk about mods and modding, including recommendations and troubleshooting. The Paradox forums also link to various external communities (such as Discord channels) that you can join for further conversations.
https://forum.paradoxplaza.com/forum/index.php?forums/battletech-mod-forum.1012/

5.3 Mod Creation
Want to learn how to make mods? Talk to the communities linked above, and check out these articles on different ways to make mods:
https://github.com/BattletechModders/ModTek/wiki/The-mod.json-Format
https://github.com/BattletechModders/ModTek/wiki/Writing-ModTek-DLL-mods
https://github.com/BattletechModders
https://github.com/BattletechModders/ModTek

5.4 DLC Design Data
If you want to see how we do things under the hood, HBS hosts DLC design data here:
https://github.com/caardappel-hbs/bt-dlc-designdata

 

[gh0s7]

Great post, it's really helpful to get the directions to where to place the mods and so on. Thank you!

 

[Zolotaya]

Thank you for posting this.

Hopefully, I can use all the resources you linked to accomplish my simple goal.

 

[starscream]

mech mods are not working with 1.8 at the moment probably something to do with the btperformancefix needing updated

 

[Vonbek]

@HBS_Mouse , am I being needlessly overthinking or does this make things like Crystal Clear UI and the various Badge mods as simple as drop in and enable in game with no Modtek/BMM needed any more?

Obviously things like RT/CXE will likely still have various dependencies sttill attached, but are the other "cosmetic" addons really now that simple?

If so, thanks.

 

[ronhatch]

This is the most excited I've been since the original release of the game!

Tons of testing to do, to explore the boundaries of what features may have broken or not been included... but regardless, this is wonderful.

 

[Prussian Havoc]

This is the most excited I've been since the original release of the game!

Tons of testing to do, to explore the boundaries of what features may have broken or not been included... but regardless, this is wonderful.

Plus there’s this...

No more (UNSUPPORTED)! : )

 

[naphouse]

Is there a way to change the default mod directory? It seems the directory chosen follows a Windows convention, but on OSX the convention is to put these support files in ~/Library/Application Support.

 

[Timaeus]

@HBS_Mouse Can that Discord link be updated? It's either expired or bad. Though I suppose it's possible I've also already joined it and that's why i'm having issues.

 

[Ironbar Sinister]

Is there a way to change the default mod directory? It seems the directory chosen follows a Windows convention, but on OSX the convention is to put these support files in ~/Library/Application Support.

Simply make a mods folder in your BattleTech folder - where ever it may be. That's all there is to it.

Edit: Oooooh snap! I spoke too soon.
Yah, do not like - Mods folder in my user profile? Ugh.

 

[starscream]

modloader is utterly broken

Its not just roguetech its nearly all mods the modding guys over on discord are trying to work this one out
[Mod edit: merged. Don't spam duplicate posts ]
HBS pls release a patch for the mod loader its very broken

the mod loader is not loading mods properly the modding guys on discord are at this moment trying to find a work around

 

[Crackshots]

Hey, some mods save their games in different locations, like "..../myGames/mods/modsaves/...." these cannot be loaded now ingame, which makes it kinda pointless to play with these kind of mods .. any solutions?

i guess for example "roguetech" is one of these mods

 

[Crackshots]

Ok, thanks, i just thought i maybe overlooked something since "roguetech" is even mentioned in the first post as a reference.

the "blackscreen" issue is with btml and modtek, these are not needed anymore (and wont work - injecting btml and modtek results in main menu not loading) it seems, since you can load mods now directly.

problem is some mods have a different save-path, and cannot save anymore
the mods itself seem to work ON FIRST GLANCE, i havent played much, obviously, since i cannot save anything

 

[Lynx7725]

If you are using the more complex mods out there, there might be some issues. But if you are using simple JSON mods, then the official mod loader does work.

Things to note:

1. Mods now go in your user profile, not in the game files directory.
2. it's mod.json, not the older file name. got to change.
3. Watch the path. It's "/" not "\" (if you're on Windows), and paths don't start with "/". Directory-based hoovering works.
4. If you have previously done ammo def/ ammo box defs, you may need to rework those. Seems to be some issues there.

Good to see the Mechs back in the Skirmish Mech Bay.

I'd need to apply the "copy to DB" option and then test my career/ campaign game to make sure they didn't break, then figure out what to do about my mod given the free mechs and recent DLC. But the mod loader works for basic stuff.

 

[starscream]

I am just trying to get mech mods to work so far they don't show up in the mech bay

 

[HBS_Mouse]

@HBS_Mouse , am I being needlessly overthinking or does this make things like Crystal Clear UI and the various Badge mods as simple as drop in and enable in game with no Modtek/BMM needed any more?

Obviously things like RT/CXE will likely still have various dependencies sttill attached, but are the other "cosmetic" addons really now that simple?

If so, thanks.

Yup! The intent would be that if the mod was dependent on ModTek for loading, it should work by dropping it into the mods folder. Note that this doesn't account for changes the mod itself may need in order to be compatible with the updated version of the game though.

 

[starscream]

the modloader is deactivating the battletech performancefix which is required for mech mods

 

[Lynx7725]

Ok, what I can say after most of a day of debugging JSON files and cleaning out commas where they don't belong and adding them where they should is that:

1. The current mod loader at least work for basic JSON work -- mech, chassis, movement, hardpoint, equipment, works. There might be a bit of tightening on loading fussiness, so it'd be good to validate your JSONs before loading.

2. The one specific case that it doesn't work for me is in ammunition. The net effect is that you can't declare new ammunition type in JSON now. In addition, internally there appears to be some changes in handling that defaults all ammunition boxes to predefined types. So even if you fake an AMS ammo to become MRM ammo, your MRM launchers will now reach for the default AMS ammo bins.

This isn't as bad as it sounds... with one caveat. Ammo category has moved over to enumeration already, the caveat is currently that enumeration is not opened up for easy access via mod.json. If and when that happens, you will be able to define ammo categories --> ammo --> ammo bins, and then from there your fancy new Naval Autocannon will feed fine. Just not now.

3, From (2), if you have mechs that uses custom ammo bins, you'd need to rework them, because you can't declare ammunition, so you will end up with a null pointer for your ammo bins, and your mech configs will point to non-existent ammo bins. This can pass the Skirmish Mechlab load test, but will fail the Skirmish SP load test.

So yeah. Things "kind of" work. Not great, I hope HBS can add the ammo category enumeration in quick/ soon/ yesterday, but I still can get some stuff out.

EDIT: Hmm musing out loud. The issue with not being able to put in non-generic Ammo Boxes is a bit more insidious then I initially thought. For one, harder to have different ammo per ton. Autocannons (ACs, LBX, UAC, LAC, RAC) don't suffer from this too badly since per ton they are consistent (45/20/10/5 going from *AC2 to *AC20), but Gauss straight away hits a problem, as Light Gauss has 16 per ton, but normal Gauss (which is in game) is 8.

There are some tricks to get around this problem (in the Gauss' case, just up per-ton to 16 and implement normal Gauss that sucks 2 rounds per shot.. wonky, but evens out). But when you get to missiles... oh boy. MRMs are a bit maths heavy to work out to share ammo with LRMs.

And that leads to the second problem -- if you use default bins, you can end up with situation where a Mech mounts LRMs and MRMs (which is set to use LRM ammo) and just share one bin across all launchers. Can get to some brokeness this way.

Best to hope AmmoCategory enum comes in soon.

 

[Vonbek]

cheers @HBS_Mouse , time to drop the cosmetics ( company emblems ) and Clear UI back in then.

As said, CXE will wait till Don and the guys get it stable and then back to Yuki Onna's day 600 or so career save.

 

[WhiteHawke]

@HBS_Mouse Can that Discord link be updated? It's either expired or bad. Though I suppose it's possible I've also already joined it and that's why i'm having issues.

It's not just you. The Discord link is expired. I'm trying to figure out how to do Advanced JSON merging on the new mechs (can do them on Marauder/Warhammer and base game mechs, can't do them on others even after downloading the HBS chassis files from the design data link on this page) and I was hoping someone in the Discord would be able to help, but obviously I can't join with an expired link.