Mod Manager Mod Format (moddesc.ini)

This information is deprecated and is only applicable to Mod Manager 5.x and below. If you're writing mods for Mod Manager 6 (ME3Tweaks Mod Manager) use the information from its documentation pages.

Mod Manager allows users to organize mods as well as deploy them into the game. It is designed to be friendly for users and powerful for developers - as a developer, you do not need to worry about users not installing the binkw32 bypass or manually running AutoTOC - Mod Manager takes care of this all in the background for users. You can focus on developing your mods and my program will take care of the user side of things.

Mod Manager mods are defined as folders in the mods/ directory, which is a directory right next to ME3CMM.exe. Inside of the mods folder are individual folders for different mods. In each mod folder, there is a moddesc.ini file, along with the modded files and folders that make up the mod. The moddesc.ini file describes the mod and what features of Mod Manager the mod will use for both displaying the mod and its options to the user, as well as how the mod is installed. .

Targetting different versions indicates which versions of Mod Manager can use your mod and what features/mod operations you can describe in your moddesc file. For the most part it is best to use the latest version, as the automatic updater in Mod Manager brings most users to the latest version. If you are making simple mods, sometimes using an older moddesc format is easier.

ModMaker mods are compiled against the most recently supported version of moddesc that the compiling Mod Manager version supports, which is typically the base number (e.g. 4.4.1 compiles against moddesc 4.4). ModMaker mods are designed on ME3Tweaks Modmaker, so you won't need to worry about anything ModMaker related when building a moddesc.ini file.

Using the ME3Tweaks Mod Update Service

Mod Manager has a mod updating mechanism for ModMaker mods as well as "Classic" mods that are not created on ModMaker. This allows all users to update their mods without having to manually have them do it. I have surveyed some end users and many say this is one of the best features of Mod Manager.

If you want to use this service, you can contact me on the ME3Tweaks Discord and we can discuss using the service for your mod. All mods that are on the updater service must be Mod Manager mods (because it's the only way they can do so) and will be listed on the mods page. The main download does not need to be hosted on ME3Tweaks. This service is free as long as your mod is a reasonable size (and my web host doesn't complain).

Creating a mod for Mod Manager

To create a mod for Mod Manager, you will need to know what kind you are making. Most users will be creating a singleplayer-only CustomDLC, which can be very easily created with Mod Manager's Starter Kit. You can create a fully working, blank DLC mod by going to Tools > Developer tools > Custom DLC Starter Kit.

If you wish to make one manually, you can do so using this quick and easy template if you want to deploy a CustomDLC mod (mod that adds only a DLC to the game). Edit the variable names as necessary and save as moddesc.ini next to your mod's DLC folder. Zip it up (7z is recommended) and your mod should be ready for Mod Manager.

[ModManager]
cmmver = 4.4

[ModInfo]
modname = Your Mod Name Here
moddev = Your Name Here
modver = 1.0
moddesc = Set your description that will show in Mod Manager here. The description must be done on a single line as ini files are parsed per linebreak. You can use the <br> tag to force a newline in the description in Mod Manager.
modsite = http://example.com

[CUSTOMDLC]
sourcedirs = DLC_YOUR_NAME_HERE
destdirs = DLC_YOUR_NAME_HERE

Modver should be a decimal number (1.2, 1.33) and the modsite value will be a clickable link in the description panel of the mod, so users can go directly to your mod's page (e.g. nexusmods page). If you don't know the NexusMods URL, you can find the base of it once you start creating your mod page. I have found that using 7zip to compress mods with 384MB dictionary size on the highest compression settings can yield very good compressed sizes. Mod Manager will do all of this for you with the Deploy Mod feature.

Mod Manager Advanced Moddesc Format

Headers and Descriptors

Mod Manager mods are defined by their moddesc.ini files which are located in the mod folder. The folder, mod files and this moddesc.ini file make a Mod Manager Mod. The moddesc.ini format has 2 key terms: Headers and descriptors. Headers are items in brackets like [ModManager] or [CUSTOMDLC]. Under these headers are descriptors, which describe items for the header above it, such as sourcedirs and serverfolder. Descriptors will apply to the most recently listed header in the file. Both of these items are case sensitive.

Version Targetting

Mod Manager is fully backwards compatible with mods targetting older versions of moddesc, but upgrading a mod's moddesc version without upgrading the contents of the file may not work properly as different moddesc versions are parsed differently. Mod Manager can load mods targetting newer versions, but theres a good chance it won't support the new features from that moddesc version. This is rarely an issue as Mod Manager's automatic updater prompts users for updates on startup.

Moddesc.ini's 4 main components

Moddesc.ini's file format has 4 main components: The [ModManager] header, which contains the targetting information, the [ModInfo] header, which contains display information and information about the mod, the [UPDATES] header which contains deployment and updater service information, and then the actual mod task headers themselves such as [CUSTOMDLC] or [RETALIATION].

[ModManager] Header

The [ModManager] header is a required header for all moddesc.ini files. It supports a single descriptor, cmmver, which is set to a specific version to tell Mod Manager how to parse the file. You can do this to ensure forwards compatibilty, in the event I have to change how moddesc parsing works - I will always strive to ensure a version targetting a previous version will remain usable in the future. If you are building a mod, I suggest targeting at least 5.0, which is last version 32-bit Mod Manager supported. Otherwise use whatever the latest version is, as deployment support typically is built around the latest version.

Valid values are listed below with the main highlights of that release:

If a cmmver descriptor is not set, the default 1.0 value will be used.

[ModInfo] Header

The [ModInfo] Header is used for the description, version, and other information about the mod that the user will see in Mod Manager. It also houses the ME3Tweaks Updater Service information.

Note that at some point I may move updatecode to the [UPDATES] section, however I will keep backwards compatibility. I may have Mod Manager automatically move it to the correct section.

[UPDATES] Header

The UPDATES header is used when deploying your mod as well as information about how it is stored on the ME3Tweaks Updater service, if you choose to use it.

Official DLC Task Headers

Mod Manager 2.0 and above added support for modding offical game DLC. The following headers are supported, with their supported descriptors in the table below. BASEGAME is technically not a DLC (vanilla game) but keeps the same format.

BALANCE_CHANGES is special in that it is an additional job that supports all of normal features, but additional code is run when this task is processed to ensure the balance changes replacer ASI is installed. You should only ever use this header to target balance changes, such as follows:

[BALANCE_CHANGES]
moddir = BALANCE_CHANGES
newfiles = ServerCoalesced.bin
replacefiles = \Binaries\win32\asi\ServerCoalesced.bin

The above headers support the following descriptors:

[CUSTOMDLC] Header

The [CUSTOMDLC] header is likely the most important header for mod developers. It allows Mod Manager to add a Custom DLC folder to the game, such as DLC_MOD_EGM. This header has some advanced optional descriptors that allow you to add compatibility shims and packs automatically when the mod loads in Mod Manager. This header is supported starting with Moddesc 3.1.

The following descriptors are supported by this header. They are explained in more detail below the table.

altfiles specification

The altfiles descriptor allows you to substitute, add, or remove files from your Custom DLC job based on the existence, or non existence, of a DLC. It uses a list of parenthesis objects. Below is a substition done in SP Controller Support for example, which is targeting ModDesc 5.0.

[CUSTOMDLC]
sourcedirs = DLC_CON_XBX
destdirs = DLC_CON_XBX
altfiles=((Condition=COND_DLC_PRESENT, ConditionalDLC=GENESIS2, ModOperation=OP_SUBSTITUTE, ModFile=DLC_CON_XBX/CookedPCConsole/BioP_Char.pcc, AltFile=GENESIS2/BioP_Char.pcc, Description="Enables Genesis 2 DLC to work in character creation"))

The altfiles descriptor takes a list of structs in parenthesis. The entire list is also encapsulated in parenthesis, as shown in the above example by the first and last parenthesis encapsulating a single object that is also in parenthesis. This object is a list of comma separated values in the format of Variable=Value. Value is sometimes in quotes (for some strings) and other times not (if the string cannot have spaces). The table below shows what variables are accepted in this struct and how they work. All operations are transparently applied at mod loading time unless they use COND_MANUAL.

altdlc specification

altdlc allows you to add a folder of files to a CustomDLC based on the installed game state. You can alternatively add an entire Custom DLC folder to the game using this specification. This is useful for automatically applying compatibility packs if your mod has known incompatibilities with another, as you can detect that and automatically reconfigure your mod to work around it. You can also have manual options to allow users to add their own developer-provided options, like lower resolution asset files.