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.
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).
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 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.
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 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].
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.
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|
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|
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+|
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.
|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+|
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 parenthsis. 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.
|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:
|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:
|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:
||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|
More to come...