Guide:Mod Organizer/Advanced

< Guide:Mod Organizer

Mod Organizer Advanced/Technical Guide -- by DoubleYou & the STEP Team

GUIDE FORUM THREAD
OFFICIAL SUPPORT FORUM

---

Internal Mechanics

The Virtual Filing System (VFS)

As explained in the FAQ, Mod Organizer (MO) uses mod isolation, a feature in which every mod is installed into its own directory. This provides for an untouched game data folder, void of installed mods, which is the main feature of MO. This section will not only discuss the technical details and challenges of this approach, but also its advantages and disadvantages.

It will be discussed for Skyrim but is valid for all four supported games. When Skyrim is installed it stores all its files on the file system (FS) of a disk. The same is true when you install the official DLC's. The behavior of Skyrim can be changed by installing mods and plugins.

Note: Mod managers like Nexus Mod Manager (NMM), Wrye Bash (WB) and Mod Organizer (MO) can only install files in the <Skyrim>/data directory. Hence plugins like ENB and SKSE cannot be installed by them.

Typical mod managers like NMM and WB install mods into the data directory of the game being modded. When installing mods, they keep a record of all installed files. This allows them to detect if a mod overwrites files of the original game and/or one or more existing mods. The user is given the option to overwrite such files. All files are added to the original game data directory. Hence the once empty and pristine state of the game data directory is lost. These programs have algorithms to restore files on the FS when, for example, mod B, which had overwritten files from mod A, is uninstalled. When using Profiles and changing the order in which mods were installed, these programs make changes to the windows file system by copying/deleting files on it. Depending on the performed actions this can take considerable time. If these programs work perfectly and Windows works perfectly, no harm will be done to the file system and the game continues to work. Unfortunately, this is not always the case, and problems may arise.

Mod Organizer takes a very different and revolutionary approach. It never writes files to the game data directory, but instead creates and uses a virtual filing system (VFS). It is called virtual because it does NOT exist on the regular file system and only exists when MO tells a program it exists. When the game is started by MO, it is unaware of this VFS and thinks it uses the regular Windows file system. Therefore, all installed mods are loaded and used normally. The same is true for any other program started by MO (e.g., BOSS, Boss Userlist Manager (BUM), WB, etc.).

The VFS is constructed using a technique called hooking. Hooking is not an uncommon technique and progams like SKSE, ENB, SweetFX and ENBBoost use it. In the case of MO, hooking involves intercepting the Windows system calls and injects its VFS into the file system. In other words, it 'hooks' itself into the regular Windows filing system and changes it. The hooking is performed by a dynamic link library (DLL) created by Tannin, a part of the MO program rightly called hook.dll. Other open source hook libraries exist, like EasyHook. Users interested in the technical details of 'hooking' are encouraged to read the section 'EasyHook and 64-bit support' below.

The VFS is constructed from the following:

• The regular <Skyrim/Data> directory and all its subdirectories.
• The <MO>/mods directory
• The <MO>/overwrite directory.

The section "Files and directories which are virtualised" gives a complete list of what is virtualised. The above shows in which order the VFS is constructed and what overrides each other.

Regular <Skyrim/Data> directory.
This is the base and nothing needs to be added or injected.

The <MO>/mods directory.
In MO a mod is a directory in the <MO>/mods directory. All files in each directory are injected into the VFS. The order in which files are overwritten in the virtual data directory is explained in the Priorities tab of the wiki.

The <MO>/overwrite directory.
The last files injected into the VFS are the files in the <MO>/overwrite directory. But what is this overwrite directory? Basically and simplified it contains files which are created by a mod or plugin after its installation. Examples of this are files generated by Skyproc-based programs programs such as Automatic Variants (AV), a 'Bashed patch.esp' created by WB, and log files generated by skse based mods like Elys meminfo.

IMPORTANT. MO does not know about the relationship between files in the overwrite directory and the mod which generated it. Hence it does NOT obey the priorities set for a mod in the left pane. Which means you always have to make sure the overwrite directory is empty. The overwrite directory is global for all profiles. Some users have expressed this to be a drawback. For more information about the overwrite directory and strategies how to simulate a 'local overwrite for each profile' can be found in the Overwrite tab of the wiki.

Advantages of the MO VFS approach

1. Speed. Changing the install order mods is instantaneous because no files have to be copied.
2. An untouched Skyrim/data directory, because it does not change any files on the file system for the supported games (with few exceptions).
3. Manipulating mods and the overwrite directory can be done using the default Windows Explorer.
4. Mods can be installed outside of MO, since a mod is nothing more then a directory inside the <MO>/mods directory.

Disadvantages of the MO VFS approach

1. The overwrite mechanism is confusing as it can't be made consistent for all mods/plugins.
2. There is no 'local overwrite' directory for each profile.
3. No support for 64-bit programs.
4. The hook mechanism is the Achilles' heel of MO and fragile.
5. The hook mechanism does/did not support all functions calls.
6. If it fails then no mods are loaded when the game is started.
7. Examples are Automatic Variants, NTFS hard support.

Template:Notice

EasyHook & 64-bit Support

Tannin has created his own hook library. There exist multiple hook libraries. One of them is the open source library EasyHook. For anyone interested in the details of the hook mechanism see this documentation of EasyHook. EasyHook supports both 32-bit and 64-bit programs. MO currently cannot start 64-bit programs, but Tannin is looking into alternatives to the current solution that will provide support for 64-bit applications.

Support for 64-bit programs would mean NMM could be started by MO and 64-bit Java could be used. The latter would be especially beneficial for Skyproc-based programs like Automatic Variants. Some Skyproc-based programs can use a lot of memory. Sometimes on a heavily modded setup, this can lead to a painfully slow patching process and even cause problems/errors. In general with 32-bit Java, only between 1000 and 1200 can be allocated, sometimes even less, depending on the alignment of the stars.

Virtualized Files

The data directory is the only directory-wide visualization.

Files

1. Plugins.txt
2. Loadorder.txt
3. Skyrimpref.ini
4. Skyrim.ini

Important files

categories.dat - This contains any changes to the mod category system made by the user. Please note this file will not exist if the user has not edited categories.

ModOrganizer.ini - This file controls most settings for MO. This includes:

• Game path.
• Whether or not this is the first time you have started MO.
• Currently selected profile.
• Current sort state of columns.
• Whether or not mod grouping is being used and which option if enabled.
• Whether or not the Downloads tab is in compact view.
• Nexus username and password.
• Window positioning and UI element positioning
• Whether or not the Filters pane is visible.
• The current executable selected to run.
• Whether or not disabled plugins are visible to the game when launched.
• Whether or not core files like Skyrim.esm are able to be disabled.
• The current load mechanism.
• The location of the downloads, mods, and cache directories.
• The selected style or theme.
• The log level MO is set to record when loading your game.
• Whether or not MO is set to automatically login to the Nexus when necessary.
• Offline mode.
• Whether MO uses system proxy settings or ignores them.
• The current user-agent MO is identified by on the Nexus.
• All settings related to MO plugins.
• All custom executables and settings for them.
• All known Nexus servers and which ones you may have selected as being preferred.
• Whether or not you have complete the tutorials.
• Whether or not Steam is launched when an executable is run.
• Whether or not MO will automatically extract BSAs.

nxmhandlers.ini - This file tells nxmhandler.exe how to handle nxm links. Deleting this file will NOT stop nxmhandler.exe from controlling nxm links.

Meta.ini - This file is in each folder created for every installed mod. They contain details that are mostly found in the Information dialog or displayed in the columns of the Left-hand pane: Such things included are:

• The location of the download site for that mod.
• The mod's version. For a detailed explanation of how this version number is formulated and then used, see this page.
• The newest version as shown on the Nexus site.
• The category assigned to it.
• Other details specific to each mod.

Mostly these details are filled when the download is completed, but some will only be there if the specific tab is viewed or modified.

• The Nexus Info tab will have a saved capture of the text on the description page for that mod.
• The Notes tab will only be filled if you have actually provided notes for that mod.
• The INI Tweaks will likewise only be filled if that feature is used. Note this only shows that this feature is used, the actual tweak is in its own file.

This file can be edited by any text editor and if the correct details are not provided automatically it is good practice to do so to ensure proper functionality. All care being taken to provide correct details by the user.

Maintenance

File Backup

PlaceHolder

Updating

Template:Notice The official upgrade instructions by Tannin for a regular release are:

1. Click on the upgrade button in MO.

Alternatively:

1. Download the installer version of the upgrade.
2. Run the installer and install to your ModOrganizer directory.

Another alternative:

1. Download the latest archive version.
2. Extract to your ModOrganizer directory, overwriting all.

For Beta versions:

1. Unpack the newest "main" file into your ModOrganizer directory, overwriting all.
2. Unpack any update and optional files as necessary into your ModOrganizer directory, overwriting all.

A fail-safe method for situations where...

1. An update broke something due to an outdated file remaining intact from a previous version.
2. You want to start with a fresh install of Mod Organizer.

The workflow is as follows:

1. Delete the following in your current ModOrganizer directory:
   • All files EXCEPT ModOrganizer.ini, nxmhandlers.ini, and categories.dat
   • All directories EXCEPT downloads, mods, overwrite, and profiles
2. Now download the latest archive(s) (There may be important optionals you need to install, so read the instructions.)
3. Copy the contents of the latest archive(s) into your ModOrganizer folder, overwriting all.

Fixing NXM Issues

2014/04/17 Update. This is an updated process to fix the NXM association or to perform upon removal of Mod Organizer. If you are going to stop using MO for another mod manager that handles nxm files you need to do this before you remove MO. Go into the ModOrganizer directory and look for a file called nxmhandler.exe and double click on it to run the program. When the window opens look for a references to the games that MO supports. Click on each one and delete it. When finished right click in the now empty window and select add. In the resulting dialog select the game you want to use and in the binary section browse to where NMM is installed. When there select NexusClient.exe and close the window.

The data below is being left in place as it has information on the different load mechanisms used in MO.

By courtesy of GSDFan who created the article and which was moved here. The information provided here is from my poking around in MO and from various posts on the Skyrim Nexus forum and as such may not be totally accurate. Only Tannin42 knows the internal workings of MO and his advice, if provided, should be considered over mine. The information is accurate as I see it for Mod Organizer v1.05 RC6.

On 29 September 2013, a user asked:

“I want to uninstall MO, What do I need to do?

Tannin provided this answer in the FAQ section of the Mod Organizer landing page.

Q: I want to uninstall MO, what do I do?

A: First, inside MO, go to settings and select Mod Organizer for the load mechanism. Close MO and then just stop using it.

You can delete the Mod Organizer directory if you're sure you need nothing from it anymore (like mod archives, savegames). Beyond that, no un-installation is necessary. MO does not write to the registry or into any directory besides its own ^{1, 2}.

Let’s break this down a little further - There are three ways to launch Skyrim or load mechanisms:

Method one: Mod Organizer, which should be the used as the main way to launch the game. Provides to the game through hook.dll the Virtual File System or VFS. When MO is no longer required, the load mechanism has to be set back to Mod Organizer in the Options, workarounds tab and Load Mechanism. Then just stop using MO.

Method two: SKSE plug in. MO will install two files, hook.dll and mo_path.txt, to the vanilla Skyrim directory in data/skse/plugins. If this is the method being used for launching the game and MO is no longer required, the load mechanism has to be set back to Mod Organizer. If MO has already been uninstalled, then delete hook.dll and mo_path.txt from skyrim/data/skse/plugins.

Method three: Proxy DLL. Tannin has advised not to use this method to launch the game. In this method MO copies steam_api.dll to steam_api.dll.orig and writes a new steam_api.dll. Again if this is the method being used to launch the game and MO is no longer required, the load mechanism has to be set to Mod Organizer in options. If MO has already been removed, then the following has to be done. Go to the skyrim directory and look for a steam_api.dll, which should less than 50kb in size and a steam_api.dll.orig which should be 118kb in size. Delete steam_api.dll, then rename steam_api.dll.orig to steam_api.dll.

Sometime around version 0.99.XX. Tannin removed the internal browser from Mod Organizer and replaced with a mechanism that mimics what NMM does. Downloading mods via the system default web browser, as the default action.

To accomplish this, an association between MO and the web browser needs to be set up. This is done by pressing the globe icon, the second icon on the top left toolbar, to make the link automatically. After this is done, pressing the green “Download with Manager” button will use the NXM link and determine where the file will go.

¹ If MO is set up to handle nxm links that is written to the registry. url or file associations aren't uninstalled and they can't be reverted, they can only be overwritten by an application that is still installed. This means that if you switch (back) from MO to NMM and want NMM to handle links then start NMM as an administrator and navigate to settings/ general tab and toggle the “Associate with NXM URLs” option and click OK. This will re-establish the link to NMM. Another method to change the association is to type file association in the Windows start menu search box to bring up the Windows Set association dialog. Once that is open look for “.nxm” and Double click on it or press the Change program button on the upper right of the window. This will bring up a dialog where Nexus Mod Manager can be specified. Once that is done click the close button, the next time the green download with manager button is pressed NMM will be used for the download.

² I was made aware that the Qt library creates a few registry entries as a cache but please note that all other qt applications I've come across like nifskope, calibre, teamspeak, ... don't remove these either. Technically they belong to Qt, not to MO.

Using MO to Manage Multiple Games

Posted by Tannin42 in the Nexus MO forum on 04 June 2013 - 07:34 AM.

You can't add multiple games to one MO installation but you can have multiple separate MO installations. Simply install MO again and point it at FNV on the first start up.

Optimal Install Locations

In principle Mod Organizer can be installed anywhere on the filing system, which means there a two options

• Install MO inside the game folder of the supported games.
• Install MO outside the game folder of the supported games.

Path to the Mod Organizer Program is for the Steam Version:
…\Steam\SteamApps\Common\Fallout 3\ModOrganizer\ModOrganizer.exe
…\Steam\SteamApps\Common\Fallout 3 GotY\ModOrganizer\ModOrganizer.exe
…\Steam\SteamApps\Common\Fallout New Vegas\ModOrganizer\ModOrganizer.exe
…\Steam\SteamApps\Common\Morrowind\ModOrganizer\ModOrganizer.exe
…\Steam\SteamApps\Common\Oblivion\ModOrganizer\ModOrganizer.exe
…\Steam\SteamApps\Common\Skyrim\ModOrganizer\ModOrganizer.exe

The benefit of having Mod Organizer installed in these locations is ease of finding it or the other folders/files it references.

If you dont want to have ModOrganizer in the actual game folder another option would be, but only use outside actual Games folder.
…\ModOrganizer\Fallout 3\ModOrganizer.exe
…\ModOrganizer\Fallout 3 GotY\ModOrganizer.exe
…\ModOrganizer\Fallout New Vegas\ModOrganizer.exe
…\ModOrganizer\Morrowind\ModOrganizer.exe
…\ModOrganizer\Oblivion\ModOrganizer.exe
…\ModOrganizer\Skyrim\ModOrganizer.exe

Other valid directory structure are for example:
…\ModOrganizer\Mod Organizer Fallout 3\ModOrganizer.exe
…\ModOrganizer\MO FO3\ModOrganizer.exe
…\ModOrganizer\Fallout 3 MO\ModOrganizer.exe
…\MO\Fallout 3\ModOrganizer.exe
…\MO\FO3\ModOrganizer.exe

The benefit of installing Mod Organizer away from your game installation is it's also away from any folders that might be under Windows' UAC.
This is a very good reason to install in these types of locations.

Finally to be absolutely clear All the other Mod Organizer Files and Folders should be with ModOrganizer.exe when first installed for each game.
Template:Notice

Exceptions

ModOrganizer has path settings for three folders which can be changed using the Advanced Pane on the General Tab of Settings Window. This is always disabled by default and requires activating using the provided tick box. Enabling relocation of the following:

Download Directory

Mod Directory

Cache Directory

These are the only Folders and Contents that can be located anywhere except with ModOrganizer.exe for each game, but only if the path is set here.

The Download Directory is the most obvious candidate for relocation, when using SSD's, as nothing is gained by Downloads being on a SSD. Downloads are always an Archive and only used to install the Mod into the Mod Directory, the Archive just occupies valuable SSD space.

Keeping Archives is essential, for many reasons:

Removal from Nexus and Internet

Authors only keeping the latest version on Nexus and Internet.

Reinstalling an old Character using older versions of the Mods.

Requirement Changes to Mod that are unacceptable.

Requirement Changes to Mod that are incompatible with other Mods used.

For all the Above reasons and the many others that will occur, deleting Archives is never a good idea. Moving the Download Directory, to an ordinary HDD, is very highly recommended.

The Mod Directory needs to be on the SSD, Mods are game files and all game files benefit, immensely, from the speed increase of SSD's So never move the Mod Directory off the SSD, a shorter file path length, can benefit Windows Explorer, due to it's 256 Character Name/Path Limit.

Mod Organizer has no such limit and for manual manipulation of files and folders, Free Commander or 7-Zip's File Manager can be used. Both have no Character Limit, it's not essential, but Mod Organizer can be in the Game Folder and the Mod Directory can use a shorter path.

The Cache Directory is ModOrganizer's Web Cache, it uses very little SSD space, it can be moved if space is very limited. If it has any affect on actual browsing/download speed or not, the gains and/or losses of moving these are small to nonexistant.

Keeping <Skyrim> Directory Clean

Placeholder. TODO.

Explain here how you can use Link Shell Extension to have for example a real pristine <Skyrim> folder. As in being able to see which files/directory belong to a virgin Skyrim install and which were added manually when installing for for example ENB, Skyrim script dragon, SKSE. This is possible because the 'symlinks' you create have a Overlay Icon which are different then the standard icons shown in windows explorer.

Adjusting Steam App ID

MO fills in the Steam App ID based on the managed game:

• Skyrim: 72850
• Fallout NV: 22380
• Fallout 3: 22300
• Oblivion: 22330

If the game or Steam tool does not launch correctly, you may need to adjust the Steam App ID. This is rare. To locate the correct Steam App ID:

1. Open Steam and go to the Library.
2. Right-click on the game and choose Properties.
3. On the General tab click the CREATE DESKTOP SHORTCUT button and select OK at the prompt.
4. On the desktop, right-click the shortcut and select Properties.
5. The URL field will say something like steam://rungameid/202480. The number is the SteamAppID (the number example here is for the Creation Kit).

Notes:

• The Fallout 3 Game of the Year version's Steam App ID is 22370. This may fix crashing on Fallout 3 if you are using the that version.
• Skyrim's Creation Kit's Steam App ID is 202480. If the Steam App ID is not set in the Configure Executables window with Overwrite Steam AppID checked with the value of 202480, the Creation Kit will not be able to see your mods.
• Extensive info on Steam App IDs can be found in this thread: The Elder Scrolls Series and Fallout Series App ID's (By Uhuru).

Left Pane Separators

In the current version of MO it is not possible to create with the MO UI separators like horizontal lines or separators which look like "----------- STEP 2.2.7 Section 3.A. Technical Tips ------------". There is a ticket for it though in the issue tracker. Its Enhancement Request #422.

There is a valid workaround however. Due to MO's mod isolation feature a 'mod' is nothing more then a directory in the <MO>/mods directory. For details see the Advanced tab section "The virtual filing system". Upon starting MO or hitting the refresh button in the left pane of MO, it (re)reads this directory and detects all mods. You can take advantage of that.

1. Create a new directory with the desired name in the <MO>/mods directory.
2. Create a new directory with the desired name in the <MO>mods directory AND create an empty 'textures' directory inside it.

Start MO or hit the refresh button when MO is already started and now you have you have a separator with the chosen name in the left pane.

Note in case of (1) you will get a red warning icon and as warning 'no valid game data'. To correct this, select the separator 'mod', right click and select 'ignore missing data'. The warning will now disappear. In fact, MO has creates an empty textures directory in the mod. The same as was explained in (2).

Migrating Other Mod Managers

Migrating from NMM

The information below is valid for all the games supported by Mod Organizer. The explanation below is done for Skyrim.

Basically there two ways to do this

1. Use the NMM importer plugin of Mod Organizer.
2. Migrate from NMM to MO manually

At this moment, the 8th of November 2013 the first method for most users will not be an option.

The main obstacles is that 'overwritten' files are currently not handled correctly. The problem arises with mods which have files which are overwritten when they were installed with NMM . Those overwritten files are not copied correctly to Mod Organizer when using the NMM import function. When there are no overwritten files it seems that the NMM importer can be used successfully. For details see Bug report ticket #435 in the issue tracker and **** thread in the official MO support forum. It also contains a method to check if their exists overwritten files.

This at least is the conclusion of a user who has tested the NMM importer three times. Each time after a new version of MO was released which contained bugfixes for the NMM importer. The conclusion is valid for MO 1.07, which is also called release 1.0 release candidate 8 (1.0 RC8).

Template:Notice Small The reason for this is that there is the possibility that even after uninstalling all mods with NMM that there are files left behind which can cause problems. If NMM works perfectly and windows works perfectly after uninstalling them the <Skyrim>/data should be in the same state as after a fresh install. Unfortunately this is not a perfect world. And if mods were installed manually NMM can't uninstall them anyway.

The procedure for migrating from NMM to MO manually is the following:

1. Lookup in the MO wiki every unknown word/function which is described below.
2. Install Mod Organizer.
3. Copy the download directory of NMM to the downloads directory of MO.
4. Perform a 'query info' action on every file in the downloads tab in the right pane.
5. Install a mod with MO.
6. Uninstall that mod in NMM.
7. Repeat step 5 and 6 until all mods are installed with MO and uninstalled in NMM.

Not all mods have to be migrated at once. This can be done in phases.

Reason: MO uses a virtual filing system which is explained in the Advanced tab of the wiki, section 'The virtual filing system'. The mods installed with MO override virtually in the VFS the files which exists in the regular <skyrim>/data directory. When a lot of mods are installed with NMM its almost certain files were overwritten. Assume mod B has overwritten files of an already installed mod A. When in MO mod B is installed first and then Mod A the order of override is different which can lead to serious problems, especially if it concerns script. Of course in MO the installation order can be changed using for drag&drop but as long as not all mods are migrated there is no way to know what will happen when Skyrim is started.

Unfortunately NMM does NOT show in the UI the order in which mods were installed. It can however found using the following steps.

Start NMM. Select the 'Open Folder' button and select 'Open NMM's Install Info Folder'. Open the installog.xml file. The <ModList>...</ModList> section contains a list of installed mods. The first installed mod is at the top after the <ModList> tag. The last installed mod is before the </ModList> tag. Each mod is represented by a <mod> .. </mod> tag. It contains amongst other things the name used to install the mod. The easiest way to install a certain mod is to go to the downloads tab in the right pane and use the search function to search for that filename. This is much easier then having to scroll through the list of downloaded mods.

Related Video(s):

• Mod Organizer #6 - Beyond Nexus Mod Manager (by Gopher)

Migrating from Wrye Bash

The information below is valid for all the games supported by Mod Organizer. The explanation below is done for Skyrim.

There is no Wrye Bash importer plugin which means the mods have to be migrated from Wrye Bash (WB) to MO manually.

Template:Notice Small The reason for this is that there is the possibility that even after uninstalling all mods with WB that there are files left behind which can cause problems. If WB works perfectly and windows works perfectly after uninstalling the <Skyrim>/data should be in the same state as after a fresh install. Unfortunately this is not a perfect world. And if mods were installed manually WB can't uninstall them anyway.

The procedure for migrating from WB to MO manually is the following:

1. Lookup in the MO wiki every unknown word/function which is described below.
2. Install Mod Organizer.
3. Copy the contents of the download directory of WB to the downloads directory of MO.
4. Perform a 'query info' action on every file in the downloads tab in the right pane.
5. Install a mod with MO.
6. Uninstall that mod in WB.
7. Repeat step 5 and 6 until all mods are installed with MO and uninstalled in WB.

Not all mods have to be migrated at once. This can be done in phases.

Reason: MO uses a virtual filing system which is explained in the Advanced tab of the wiki, section 'The virtual filing system'. The mods installed with MO override virtually in the VFS the files which exists in the regular <skyrim>/data directory. When a lot of mods are installed with WB its almost certain files were overwritten. Assume mod B has overwritten files of an already installed mod A. When in MO mod B is installed first and then Mod A the order of override is different which can lead to serious problems, especially if it concerns script. Of course in MO the installation order can be changed using for drag&drop but as long as not all mods are migrated there is no way to know what will happen when Skyrim is started.

To find out in which order the mods were installed in WB do the following.

1. Go to the installers tab in WB.
2. Select the "order" view

Shown now is in which order the mods were in installed in WB.