Mod Manager Mod Format (moddesc.ini)

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. Mods are defined as folders in the mods/ directory, which is in the same folder as ME3CMM.exe. Inside of these mod folders 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 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. If you want to use this service, you can contact me at my me3tweaks email address (in the help menu) 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

Below is a quick and easy template you can use 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 (zip/rar/7z is supported) 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). 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 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.

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.

Note: The documentation here was written against Mod Manager 4.4.1. As Mod Manager evolved, new headers could be parsed by older moddesc versions, but old versions of Mod Manager won't support those new headers. This is a side effect of how the list of headers was updated. Again this should never be an issue for you as a mod developer.


Moddesc.ini's 3 main components

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

[ModInfo] Header

The [ModInfo] 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.

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

Moddesc features by version
cmmver Version Release highlights
1.0/1.1 Basic Coalesced.bin swapping only.
2.0 Supports modifying SOME of the official game DLC (see headers table below)
3.0 Supports modifing the basegame and TESTPATCH DLC
3.1/4.0 Supports installation of Custom DLC mods
4.1 Supports adding and removing files from the game
4.2 Supports the altfiles descriptor for CustomDLC, supports sideloading, blacklisting, and manifest building tags
4.3 Supports marking added files as read only, supports modding balance changes
4.4 Supports the altdlc and outdatedcustomdlc descriptors for CustomDLC

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.

[ModInfo] Supported Descriptors
Descriptor Value Purpose & Notes Required Supported Versions
modname Unquoted String Mod name displayed in Mod Manager Yes All
moddesc Unquoted String Mod description shown on Mod Manager. Newlines can be inserted by adding <br> where you want the newline. Yes All
modver Floating Point Number Mod version, as shown in Mod Manager. This value is also used to detect udpates. No All
moddev Unquoted String Mod developer(s). Shown in the mod description panel. No All
modcoal Integer Number Any value other than zero indicates that there is a coalesced swap job for Mod Manager 2.0 mods. A file named Coalesced.bin must be in the same folder as moddesc.ini. This variable only works with moddesc targeting version 2.0. Moddesc 1.0 only does coalesced swap, and Moddesc 3.0 and above is done by adding a [BASEGAME] header with a replacement of /BIOGame/CookedPCConsole/Coalesced.bin. No 2.0 only
modmp Unquoted String Text to show if the mod affects MP. This descriptor has been deprecated and may stop being parsed by Mod Manager in the future. No All
modsite Unquoted String (URL) If present, a clickable link anchored at the bottom of the mod description panel will go to this URL. You should put the page that users can go to for support as this is the main reason they will go there. No All
modid Integer Number ModMaker Mod ID. Should not be manually added to any mods. Value is shown in the mod description panel and used for checking for updates. No All
updatecode Integer Number ME3Tweaks Updater Service update code. This is used to get the manifest from ME3Tweaks for classic mods. If you don't have an update code assigned from ME3Tweaks, don't use this descriptor. No All

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.

Official DLC Headers
Header name DLC Folder Supported Versions
BASEGAME BIOGame/CookedPCConsole 3.0+
RESURGENCE BIOGame/DLC/DLC_CON_MP1 2.0+
REBELLION BIOGame/DLC/DLC_CON_MP2 2.0+
EARTH BIOGame/DLC/DLC_CON_MP3 2.0+
RETALIATION BIOGame/DLC/DLC_CON_MP4 2.0+
RECKONING BIOGame/DLC/DLC_CON_MP5 2.0+
PATCH1 BIOGame/DLC/DLC_UPD_Patch01 2.0+
PATCH2 BIOGame/DLC/DLC_UPD_Patch02 2.0+
FROM_ASHES BIOGame/DLC/DLC_HEN_PR 2.0+
EXTENDED_CUT BIOGame/DLC/DLC_CON_END 2.0+
LEVIATHAN BIOGame/DLC/DLC_EXP_Pack001 2.0+
OMEGA BIOGame/DLC/DLC_EXP_Pack002 2.0+
CITADEL BIOGame/DLC/DLC_EXP_Pack003 2.0+
CITADEL_BASE BIOGame/DLC/DLC_EXP_Pack003_Base 2.0+
APPEARANCE BIOGame/DLC/DLC_CON_APP01 2.0+
FIREFIGHT BIOGame/DLC/DLC_CON_GUN01 2.0+
GROUNDSIDE BIOGame/DLC/DLC_CON_GUN02 2.0+
GENESIS2 BIOGame/DLC/DLC_CON_DH1 2.0+
COLLECTORS_EDITION BIOGame/DLC/DLC_OnlinePassHidCE 2.0+
TESTPATCH BIOGame/Patches/PCConsole 3.0+

The above headers support the following descriptors:

Official DLC Descriptors
Descriptor Value Purpose & Notes Required Supported Versions
moddir Unquoted String Directory that houses the new files that will be installed into the game. This is relative to the mod folder. For example, a value of MP1 would mean that files in the MP1 folder belong to this mod task. if adding or replacing files 2.0+
newfiles Unquoted Semicolon Separated List (String) List of filenames in the moddir that are files that will be installed into this DLC. if using replacefiles 2.0+
replacefiles Unquoted Semicolon Separated List (String) File targets that will be replaced in this DLC. The paths should be relative to the base Mass Effect 3 folder. For example, you could put in /BIOGame/DLC/DLC_CON_MP1/CookedPCConsole/Asari_Commando_MP.pcc. The order of these files to replace MUST match the newfiles list or they will install to the wrong place. if using newfiles 2.0+
addfiles Unquoted Semicolon Separated List (String) List of filenames in the moddir that that will be added to this DLC. if using addfilestargets 4.1+
addfilestargets Unquoted Semicolon Separated List (String) File targets that will be added to this DLC. The paths should be relative to the base Mass Effect 3 folder. For example, you could put in /BIOGame/DLC/DLC_CON_MP4/CookedPCConsole/SFXPawn_ChubbyHusk.pcc. The order of these files to replace MUST match the addfiles list or they will install to the wrong place. if using addfiles 4.1+
addfilesreadonlytargets Unquoted Semicolon Separated List (String) File targets that should be set to read only on installation. This only works on files you are adding, not replacing. The paths should be relative to the base Mass Effect 3 folder and match items from addfilestargets exactly. The order does not matter. Making files read only makes it more difficult for users to modify them as programs will say they can't modify it, however it does not stop users from modifying them. This is useful to protect files that are used by the exec command. No 4.3+
removefilestargets Semicolon separated list (String) File targets that will be deleted from this DLC. The paths should be relative to the base Mass Effect 3 folder. For example, you could put in /BIOGame/DLC/DLC_HEN_PR/CookedPCConsole/SFXWeapon_Prothean.pcc. Unpacked and basegame files that are deleted are automatically backed up by Mod Manager. This descriptor should be used with extreme caution. No 4.1+

[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.

[CUSTOMDLC] Descriptors
Descriptor Value Purpose & Notes Required Supported Versions
sourcedirs Unquoted Semicolon Separated List (String) List of directory names in this mod folder that will be installed into the game's DLC folder. Yes 3.1+
destdirs Unquoted Semicolon Separated List (String) List of directory names that will be created in the game's DLC folder. The corresponding folder in the sourcedirs list will be placed here. Typically the destdirs and sourcedirs list are identical, but they can be different if you prefer a different naming scheme. Yes 3.1+
altfiles Unquoted Comma Separated List (AltFile) List of AltFile structs that define an alternative set of files to install (or not install). You can make these alternate files automatically part of the mod (such as substituting a file if a DLC exists) or have them be manually chosen by the user, like game files that use lower resolution. See the AltFile struct information below. No 4.2+
altdlc Unquoted Comma Separated List (AltDLC) List of AltDLC structs that define an alternative set of Custom DLC to install (or not install). You can make these alternate dlcs automatically part of the mod (such as adding a DLC if another DLC is not present) or have them be manually chosen by the user, like adding more squadmates to a mod. You can also add files to an existing Custom DLC that you are going to install if you want to have a modular style CustomDLC that is customized for every user. See the AltDLC struct information below. No 4.4+
outdatedcustomdlc Unquoted Semicolon Separated List (String) List of foldernames that should not be present in the game's DLC folder after installation. You can use this descriptor to have Mod Manager delete old versions of the mod (if you renamed it), remove outdated compatibility packs, and remove known incompatible mods. The user is prompted to delete the folders if any exist. No 4.4+

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.

[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, ModAltFile=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.

altfiles struct variables
Variable Name Value Purpose & Notes Required
Condition Unquoted String Specifies what operation to perform if the condition for the conditional DLC is true. Valid values are as follows:
  • COND_DLC_PRESENT - listed ConditionalDLC is installed
  • COND_DLC_NOT_PRESENT - listed ConditionalDLC is not installed
  • COND_MANUAL - user must manually choose this alternate file from the mod utils menu
Yes
ConditionalDLC ModDesc Header or DLC Folder Name (Unquoted String) Conditional DLC to check for. This can be a ModDesc header (as listed above) or a DLC folder name like DLC_CON_BackOff. If using a header it will be resolved to the DLC folder name. The condition is checked against this DLC in the game's DLC folder and will cause this alt file to be applied or not applied when the mod is installed. if any condition except COND_MANUAL
ModOperation Unquoted String Specifies what operation to perform if the condition for the conditional DLC is true. Valid values are as follows:
  • OP_SUBSTITUTE - change a file that is being installed
  • OP_INSTALL - add a file to the Custom DLC (will autotoc after install)
  • OP_NOINSTALL - remove a file from the Custom Dlc (will autotoc after install)
These operations are applied at install time and do not modify anything in the mod's folder in Mod Manager.
Yes
ModFile Relative Replacement File Path (Unquoted String) This variable points to the file that the Mod Operation will be performed on. Its use changes a bit depending on the condition:
  • OP_SUBSTITUTE or OP_INSTALL - relative file path from the mod's folder to the file to perform on (e.g. DLC_CON_XBX/CookedPCConsole/BioP_Char.pcc). The file path listed by ModFile will be installed to this file in the game's DLC folder.
  • OP_INSTALL - points to a a new, unused file path that will be added to the job (e.g. DLC_CON_XBX/CookedPCConsole/FileAddedToDLC.pcc).
if using OP_INSTALL or OP_SUBSTITUTE
ModAltFile Relative DLC Installation Path (Unquoted String) Points to a replacement file or a new file that will be substituted or added to the game. This is an unquoted path to your new file, relative to the mod's folder in Mod Manager. In the above example, the alt file that will be used is in the GENESIS2 folder, named BioP_Char.pcc. Yes
Description Quoted String This variable sets the description of the operation that is shown in Mod Manager's Mod Utils list in 4.4.1 and above. In previous versions of Mod Manager this variable was not displayed. If this variable is not present, Mod Manager automatically generates a description of the operation, which is fairly ugly (and does not convey its purpose) to the user. No

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.

altfiles struct variables
Variable Name Value Purpose & Notes Required
Condition Unquoted String Specifies what operation to perform if the condition for the conditional DLC is true. Valid values are as follows:
  • COND_DLC_PRESENT - listed ConditionalDLC is installed
  • COND_DLC_NOT_PRESENT - listed ConditionalDLC is not installed
  • COND_ANY_DLC_NOT_PRESENT - any of the items in the ConditionalDLC list are not present. The ConditionalDLC parameter is a list when this condition is used.
  • COND_ALL_DLC_PRESENT - all items in the ConditionalDLC list are present. The ConditionalDLC parameter is a list when this condition is used.
  • COND_MANUAL - user must manually choose this alternate file from the mod utils menu
Yes
ConditionalDLC List or Singular ModDesc Header or DLC Folder Name (Unquoted String) Conditional DLC to check for. The format of this parameter changes depending on which Condition is used.
  • Singular: ConditionalDLC=CITADEL
  • List: ConditionalDLC=(CITADEL;LEVIATHAN;OMEGA)
This can be a ModDesc header (as listed above) or a DLC folder name like DLC_CON_BackOff. If using a header it will be resolved to the DLC folder name. The condition is checked against this DLC in the game's DLC folder and will cause this alt dlc to be applied or not applied when the mod is installed.
if any condition except COND_MANUAL
ModOperation Unquoted String Specifies what operation to perform if the condition for the conditional DLC is true. Valid values are as follows:
  • OP_ADD_CUSTOMDLC - adds a CustomDLC folder to the mod when installing.
  • OP_ADD_FOLDERFILES_TO_CUSTOMDLC - adds the contents of a folder to the destination Custom DLC directory.
These operations are applied at install time and do not modify anything in the mod's folder in Mod Manager.
Yes
ModFile Relative Replacement File Path (Unquoted String) This variable points to the file that the Mod Operation will be performed on. Its use changes a bit depending on the condition:
  • OP_SUBSTITUTE or OP_INSTALL - relative file path from the mod's folder to the file to perform on (e.g. DLC_CON_XBX/CookedPCConsole/BioP_Char.pcc). The file path listed by ModFile will be installed to this file in the game's DLC folder.
  • OP_INSTALL - points to a a new, unused file path that will be added to the job (e.g. DLC_CON_XBX/CookedPCConsole/FileAddedToDLC.pcc).
if using OP_INSTALL or OP_SUBSTITUTE
ModAltFile Relative DLC Installation Path (Unquoted String) Points to a replacement file or a new file that will be substituted or added to the game. This is an unquoted path to your new file, relative to the mod's folder in Mod Manager. In the above example, the alt file that will be used is in the GENESIS2 folder, named BioP_Char.pcc. Yes
Description Quoted String This variable sets the description of the operation that is shown in Mod Manager's Mod Utils list in 4.4.1 and above. In previous versions of Mod Manager this variable was not displayed. If this variable is not present, Mod Manager automatically generates a description of the operation, which is fairly ugly (and does not convey its purpose) to the user. No