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

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
4.5 Supports the altfiles descriptor in OFFICIAL headers
5.0 Supports the requireddlc descriptor to require specific DLC(s) to be installed before mod will install
5.1 Supports the additionaldeploymentfolders descriptor to allow inclusion of additional folders that are not specifically installed

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 updates. Required for mod deployment and use of the updater service. 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

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.

[UPDATES] Supported Descriptors
Descriptor Value Purpose & Notes Required Supported Versions
serverfolder Unquoted String Path to your server storage area. Typically this is 3rdparty/<username>/modname. This is only used when generating the manifest. Required for Updater Service, Not used for Deployment All
blacklistedfiles Unquoted Semicolon Separated List (String) Relative file paths here from the mod's root directory will be deleted upon update. This is used to delete old files that may have fallen out of the scope of the mod folders. For example, I used to ship a .cmd file with SP Controller Support, which I blacklisted to ensure it was deleted on update so it would no longer be used. Optional for Updater Service, Not used for Deployment 4.2+
sideloadonly Unquoted Semicolon Separated List (String) Relative file paths in this list will be marked as sideload only. This can be used if you are shipping a very large update which is too large to be used on the updater service. When building the manifest, files marked as sideload only will be packaged into a file that then must be imported as a sideload package when dropped onto the Mod Manager interface. This is a very advanced feature only used in very rare circumstances. Requires sideloadurl. Optional for Updater Service, Not used for Deployment 4.2+
sideloadurl Unquoted Semicolon Separated List (String) URL to download the sideload package from. This is a static link, typically through something like DropBox or Google Drive. Requires sideloadonly. Optional for Updater Service, Not used for Deployment 4.2+
additionaldeploymentfolders Unquoted Semicolon Separated List (String) Folders specified here will be included in mod staging for deployments, and transitively for mods in the updater service. Note you can only specify top level folders with this descriptor, not files or subdirectories. Optional for Updater Service, Optional for Deployment 5.1+

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+
BALANCE_CHANGES See below notes 4.3+

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:

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+
requireddlc Unquoted Semicolon Separated List (String) List of DLC foldernames that are required to be installed before this mod can be installed. For example, if your mod depends on Extended Cut, you would put DLC_CON_END. You can also require multiple DLC to be installed. No 5.0+

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.

altdlc 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_ANY_DLC_PRESENT - any items in the ConditionalDLC list are present. The ConditionalDLC parameter is a list when this condition is used.
  • COND_ALL_DLC_NOT_PRESENT - all items in the ConditionalDLC list are not 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 combined with the ConditionalDLC is checked against the user's current DLC folder when being 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
ModAltDLC Relative Path To Alternate Directory (Unquoted String) This variable points to the folder that the Mod Operation will be performed on. For example, if you were detecting that a specific mod was installed and you had patch files in a subdirectory Patches\CompatPatches, you would use the value of Patches\CompatPatchesc. It should point directly to the root of the files if you are adding all files, if you are adding a CUSTOMDLC you should point to the root of the DLC such as DLC_MOD_PATCHDLC. Yes
ModDestDLC Relative Folder Installation Path (Unquoted String) Points to the destination you will be copying the ModAltDLC item to. The value you use changes depending on what your operation is:
  • OP_ADD_CUSTOMDLC - The destination foldername in the DLC folder. Typically this will be the same as the DLC name itself, e.g. DLC_MOD_PATCHDLC.
  • OP_ADD_FOLDERFILES_TO_CUSTOMDLC - Relative path from the DLC directory to where the files will be installed to. For example, if I was adding files to part of this mod's DLC_MOD_SuperCompatPatch directory, I would specify DLC_MOD_SuperCompatPatch/CookedPCConsole. Files from within the ModAltDLC folder path will be copied into DLC_MOD_SuperCompatPatch/CookedPCConsole at install time in the DLC directory.
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. Recommended