Name: mlox Version: 0.61 Copyright 2014 John Moonsugar License: MIT License (see the file: License.txt) ---------------------------------------------------------------------- mlox - the elder scrolls Mod Load Order eXpert ---------------------------------------------------------------------- This is mlox_readme.txt, which gives basic information on what mlox is and how to use it. See mlox_rules_guide.txt for a description of the rules and rule-base. See mlox_guts.txt for a discussion of mlox's inner workings. ---------------------------------------------------------------------- Contents o Features o Installation and quick start o Support o Introduction - Why mlox? o Origins of mlox o What mlox does, operational details o Note to mod Authors o On the Importance of the output warnings o Testing o Note to Wrye Mash users o Usage oo The mlox GUI o Known Issues o ChangeLog ------------------------------------------------------------ o Features - optimally reorders your load order to avoid known problems, where "optimally" is relative to the quality and coverage of the rule-base. - warns about missing pre-requisites - warns about plugin conflicts - prints notes for things you might want to know about a mod, but may have overlooked in the Readme, or things discussed in forum posts you may have missed. - mlox is customizable via a separate user rules file. - can also check someone else's load list, you can paste their load ordr into the mlox GUI, or load it from a file. - it runs on Windows or Linux! :) (Note that mlox does not tell you if you have missing Meshes or Textures, it is only a load order tool, and does not report problems with resources). ------------------------------------------------------------ o Installation and Quick Start oo Requirements - mlox.py is written using Python with wxWidgets, just like Wrye Mash. You do need to install Python and wxWidgets if you wish to run the script form of the program. You can do this in Windows if you install the following two packages: https://www.python.org/ftp/python/2.6.5/python-2.6.5.msi [install this version or newer as earlier versions only support US version of Windows and code page 437] http://downloads.sourceforge.net/wxpython/wxPython2.8-win32-ansi-2.8.7.1-py25.exe [there are later versions of wxPython but mlox needs the ANSI version] (Please note that the version of wxWidgets necessary for mlox is slightly newer than the one recommended for Mash, but will work for both applications. mlox will not work with wxPython 2.8.0.1, which is the version recommended by Mash!). - For Windows, there is a stand-alone executable that requires the Microsoft Visual C++ 2008 Redistributable Package (vcredist_x86.exe): http://www.microsoft.com/downloads/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf&displaylang=en It is important to get the right version, which the Python interpreter was compiled with. So get the above installer and not the VS2008 SP1 version. - It is STRONGLY RECOMMENDED that you install Hrnchamd's MCP ("Morrowind Code Patch"): http://www.nexusmods.com/morrowind/mods/19510 The MCP makes it safer to change your load order in an existing savegame, amongst many other wonderful fixes it does. You are also encouraged to use Wrye Mash to manage your plugins: http://wryemusings.com/Wrye%20Mash.html - mlox.py has 2 modes, GUI and command line. When executed with no command line switches it starts in GUI mode, when executed with the switch -h, it displays command line usage help. - Unpack the mlox application archive somewhere under your Morrowind game directory. If you don't have a place decided, I suggest you unpack in the Morrowind directory. A new directory called "mlox" will be created containing all the files. - The rule-base is released as a separate archive (mlox-data_.7z), unpack this archive in the mlox directory created when you unpacked the application. Version 0.59 added an automated downloader for updating the mlox rule-base. - A quick explanation of the included batch files for Windows (unless otherwise specified, run these batch files from the mlox directory): locheck - run mlox in command-line mode to check (not update). Not available for users of the standalone Windows executable version of mlox. lofix - run mlox in command-line mode to update your load order. Not available for users of the standalone Windows executable version of mlox. lo - (run this in "Data Files") just prints your current load order. - On Windows, run mlox.exe. On Linux, run: mlox.py On Windows, if you have set up files that end in ".py" to be executed by Python, then just double-clicking on mlox.py would start the GUI. - Note: On Windows 7 (and maybe Vista), if you installed Morrowind in the default location "C:\Program Files\...", you may need to turn off UAC to get mlox to recognize your activated plugins in Morrowind.ini. - mlox always assumes that the rule-base files (mlox_base.txt and optionally: mlox_user.txt) are in the current working directory (the directory where you run mlox) so you should run mlox in the directory where those two files live. ------------------------------------------------------------ o Support If you run into a problem with mlox, the best thing to do to get help is to post on the BethSoft Morrowind Mods forums: http://forums.bethsoft.com/forum/12-morrowind-mods/ You can search for the latest mlox thread by using the forum Search function. If you get a popup error window, please include the contents in your report. Please report all Windows usability problems to me. I'm not a Windows user, so as a programmer, I may make mistakes about how Windows is supposed to work. ------------------------------------------------------------ o Introduction - Why mlox? mlox runs on a little rule-based engine that takes rules from 2 input files: mlox_base.txt, which contains general community knowledge, and mlox_user.txt (if you have created one), which you can edit to contain local knowledge of your personal load order situation. You may completely ignore mlox_user.txt if you don't want to be bothered with it. It's main audience will be the "power user". Why mlox? Well, because getting your load order "sorted" (also in the sense of "working correctly") can be a tedious, error-prone job. So why not automate it? mlox can help in a variety of situations: - It's not rare that a user will post on a TES forum asking for load order help, and it is readily apparent that they have not read the Readmes for the mods they are using. For example, sometimes a Readme will say to activate only one of a set of plugins, but they have inadvertently activated them all. Then they ask why it's not working. The answer is simply: "run mlox". - There's also the situation where a power user with hundreds of mods may want to re-install from scratch, but they have so many mods, they've forgotten about some of the pre-reqs, incompatibilities and orderings, so they end up making little mistakes during the re-install. Sadly, this has happened to me :) With the mlox knowledge base, you don't have to remember these details, you just write a rule and the rule remembers for you. mlox will not forget. - If you are a modder, and you are tired of hearing people having the same installation problems over and over again with your mod, or hearing about alleged problems with your mod that are actually known conflicts with other mods, you might consider contributing rules to the mlox rule-base that describe orderings, conflicts, and dependencies for your mod. Then when people have problems, you can tell them to run mlox. So mlox is potentially for everybody. That's the theory. Of course, it will take a lot of work to add rules for the many existing mods. Currently mlox is aware of many popular mods, but there is still much more work to be done to fill out the rule-base. If mlox succeeds, it will be due to the effort of many. No one person could do it all. mlox works by matching filenames specified in rules against the plugins you actually have installed and active. If you have merged many plugins with the Construction Set, and no longer use the original plugin filenames, mlox will not know this and will not be able to order them or tell you dependencies for your merged plugins. Of course, if you like, you can write rules yourself and put them in mlox_user.txt to cover these situations. ------------------------------------------------------------ o Origins of mlox mlox is inspired by Random007's BOSS (formerly FCOMhelper) project, (see: https://boss-developers.github.io/ ). BOSS (Better Oblivion Sorting Software) is truly invaluable for Oblivion, because Oblivion is particularly susceptible to crashing if the load order isn't correct, and some mod projects, notably FCOM, require a very large and complicated load ordering that can be difficult to get right. After BOSS came along, when people post about Oblivion load order problems, the answer to them simply became: "run BOSS". Hopefully, mlox will become as useful for Morrowind. However, I decided to take a different approach in the design than the approach used in BOSS. BOSS uses a "total order" approach, every plugin in the database knows its ordering relationship with every other plugin, mlox uses a "partial order" approach, the rules specify a minimal set of orderings. If it does not matter whether 2 plugins are in a particular order, there is no ordering specified for them. BOSS also sometimes requires a second step: every time you run it, all the plugins it doesn't know about end up at the end of the order and must be re-ordered by hand. (While BOSS knows about a vast number of mods, you may use some it doesn't know about. Also, experienced users often have some home-grown plugins and patches which BOSS couldn't know about). mlox uses your current load order as a set of "pseudo-rules", so plugin orderings that are unknown by the rule-base are filled in by what mlox knows about your current order. If that's too confusing, I'll put it this way, mlox normally only has one step, and you don't need to do any manual reordering afterwards. If you don't like the order mlox produces, you can add new rules in the mlox_user.txt, but this only has to be done once, from then on it's all automatic. Finally, I wanted to have a set of rules that could easily express relationships between plugins: A depends on B, X conflicts with Y, and so on. This would require writing a simple rule-base system. Don't take this explanation of the differences as a negative view of BOSS. I have used BOSS and it really has been invaluable in setting up a working load order for Oblivion. There's a lot to be said for the simple approach it takes. For example, the BOSS rule-base is trivial to understand, while the mlox rule-base in comparison is quite complicated and that can potentially lead to errors and behavior that is not understood. So you can't really say one approach is better than the other. I just prefer to be able to write rules to customize my load order, and to be able to express dependencies and conflicts, and these are things that really need a little rule-based engine. So that's why I wrote mlox. ------------------------------------------------------------ o Note to mod Authors It is my hope that the users of your mod will benefit from using mlox, and also that maybe mlox will help reduce mod conflicts, and support questions for your mod due to misconfiguration. It is a grand goal (I hope), and there are some things we can do together to see it happen. The first thing is versioning of your mod. If mlox can tell what version of your mod the user is using, it can give more accurate advice. mlox can get the version of a plugin from its header description field (preferred), or from the plugin filename. So, if the filename stays the same from version to version, then if the description field of the plugin contains a version string: Version: 0.57 (on a line by itself) mlox will be able to use it. (Wrye Mash can report that version too, so it's just a generally useful thing to have in the description). mlox can also tell the version from the filename. So, for example, this works: Plugin_V1.0.esp The next thing is teaching mlox about your mod. If you like, you can ask for rules to be added for you, post on the Bethsoft forums and they'll be added into the next release of the rule-base. If you're adventurous and know about Subversion, you can ask for write access to the rule-base, and I'll let you make changes to the rule-base directly. The more mlox knows, the more useful it is, and people will have fewer load order problems. ------------------------------------------------------------ o On the Importance of the output warnings [REQUIRES] warnings specify missing pre-requisites, this is usually very important, and normally you can consider these "errors" that should be fixed. But in some case, they are warnings about patches that are available to make two plugins work better together. [PATCH] warnings specify mutual dependencies as in the case of a patch plugin where you'd like to know if the patch is missing or if the thing that's supposed to be patched is missing. These are usually pretty important warnings since proper functioning of a mod sometimes means getting patches properly installed. [CONFLICT] warnings specify situations where plugins conflict and generally speaking, these are "warnings". When 2 plugins conflict, the second one in the load order wins, because it overrides objects it has in common with the first. In some cases, the game will still play, but you will not see some of the content of the first plugin. In other cases, conflicts will break your game. The comments printed by the conflict rules will try to tell you how important the conflict is so you can decide which plugin to load last, or which to omit, depending on what you want to see in your game. [NOTE] warnings print information that may be of use to you. They may tell you that a particular plugin is known to have evil GMSTs, or whether or not it is a good idea to include it in "Merged Objects.esp" if you have that. They are like annotations for all your plugins. In command-line mode, you can always turn off the printing of NOTEs with the (-q) command line option if you don't want to see them. ------------------------------------------------------------ o Testing Before you start testing how mlox works on your load order, I recommend using Wrye Mash to save your current load order: In the plugin pane under Mash's "Mods" tab: right click on a column header, choose "Load" -> "Save List...", and enter a name for your saved load order so that you can revert back to it later should you decide that you do not like the results you get from mlox. mlox only updates your load order in GUI mode if you press the update button, (or in command-line mode if you use the -u switch). So you should let mlox tell you what it's going to do first, then decide whether or not you like the results before you actually let mlox update your load order. ------------------------------------------------------------ o Note to Wrye Mash users If you use the "Lock Times" feature of Wrye Mash, then you'll need to turn it off *before* you use mlox to sort your load order, otherwise Mash will just undo any load order changes mlox makes when it runs. After you have changed your load order with mlox, then you can turn "Lock Times" back on. ------------------------------------------------------------ o Usage On Windows, run mlox.exe or if you have the .py file association set-up double-click mlox.py On Linux, run the python script: mlox.py These commands will start mlox in GUI mode. If the proposed load order looks good to you, press the "Update Load Order" button. Here is the full command-line usage for mlox from "mlox -h" (You can ignore this if you only want to run mlox in GUI mode) (Note that the .exe version does not support command line mode): Usage: mlox [OPTIONS] OPTIONS -a|--all Print warnings for all plugins, otherwise warning messages are only printed for active plugins. --base-only Use this with the --explain option to exclude the current load order from the graph explanation. -c|--check Check mode, do not update the load order. -d|--debug Turn on debug output. -e|--explain plugin Print an explanation of the dependency graph for plugin this can help you understand why a plugin was moved in your load order. -f|--fromfile file1... fileN File processing mode, at least one input file must follow on command line, each file contains a list of plugins which is used instead of reading the list of plugins from the data file directory. File formats accepted: Morrowind.ini, load order output of Wrye Mash, and Reorder Mods++. -h|--help Print this help. -l|--listversions Use this to list the version numbers parsed from your plugins. The output is in 2 columns, the first is the version from the plugin filename, if present, the second is from the plugin header, if present. Naturally, many plugins do not use version numbers so results are spotty. This information can be used to write rules using the [VER] predicate. -n|--nodownload Do not automatically download and update the mlox rules. -p|--parsedebug Turn on debugging for the rules parser. (This can generate a fair amount of output). -q|--quiet Run more quietly (does not print out NOTEs). -u|--update Update mode, updates the load order. -v|--version Print version and exit. -w|--warningsonly Warnings only, do not display the new load order. when invoked with no options, mlox runs in GUI mode. mlox is intended to be run from somewhere under your game directory. mlox runs under Windows or Linux. mlox sorts your plugin load order using rules from input files (mlox_base.txt and mlox_user.txt, if it exists). A copy of the newly generated load order is saved in mlox_loadorder.out. Note: if you use Wrye Mash's "lock times" feature and you want mlox to update your load order, you need to run Mash first and turn it off. Otherwise, the next time you run Mash, it will undo all the changes in your load order made by mlox. Here's an example command line to get an explanation of why a plugin has it's position in the load order: mlox.py --explain=plugin.esp --base-only If you want to see the effect of adding in what mlox knows about your current load order, then leave off the --base-only switch. ---------------------------------------------------------------------- oo The mlox GUI The mlox GUI displays 4 text panes. The top text pane shows the rules files that have been loaded and their stats. The middle text pane shows messages and warnings. And the 2 lower panes that are side by side show the original load order on the left, and the mlox sorted load order to the right. Plugins that have moved up due to sorting are highlighted in the mlox sorted order. To update your load order to the new sorted order, simply press the button labeled: "Update Load Order". Right click on the original load order to get a context menu for advanced options. These options are: - Select All: allows you to select the text of the plugin order so you can copy and paste it somewhere. - Paste: allows you to paste a list of plugins into mlox so you can, for example, analyze the plugin list posted by someone in a forum post. Input formats can be: Morrowind.ini [Game Files] section format, the format from Wrye Mash's "Copy List" function, or the output of Reorder Mods++. NOTE: when you paste in a list of plugins, mlox assumes they are all active! Also, some of the rule functions like testing plugin size obviously won't work when you're pasting in from a list, and in these cases to be on the safe side, the rules will return a positive result, meaning that you will likely see false positives. For example, with a rule checking if you have a plugin containing GMSTs it would normally do that by checking the size of the plugin you have installed. But when you paste in from a list, mlox cannot check the size, so if it just sees the name of the plugin it will report that it may have GMSTs in it, whereas in reality it's possible that the user has cleaned that plugin, which would change its size. - Open File: this option allows you to input a list of plugins from a file, instead of from pasting them. See the Paste option above for input formats and caveats. - Debug: this will pop up a window containing a list of debugging output (and automatically copy the contents to a file: mlox_debug.out). If you run into problems with mlox, I may need you to send me this bugdump so I can figure out what happened. ---------------------------------------------------------------------- o Known Issues - Updating does not immediately refresh [mlox-base YYYY-MM-DD HH:MM:SS (UTC)] string in the top text pane, although the update is effective. - There appear to be compatiblity issues with Yacoby's Wrye Mash Standalone. If you are using Yacoby's mash.exe avoid using these options: Mlox\Sort using mlox Mlox\revert changes Instead, use: 1 - Mash\Lock times off 2 - Mlox\Launch mlox 3 - Sort mods using the mlox GUI 4 - Mash\lock times on ================================================== o ChangeLog Version 0.61 - 2015/08/01 * URI for checking and downloading new rule-base changed from Google Code to SourceForge [Dragon32] Version 0.60 - 2014/09/07 * mlox will now skip reporting an error if it fails to make a connection when downloading the rule-base [abot] * fixed potential compatibility issues caused by Python changing their function names between versions [abot] Version 0.59 - 2014/07/06 * Fix conflict with tes3cmd's resetdates and only redate files if necessary [abot] * Automatic checking for and downloading of new rule-base [abot] Version 0.58 - 2011/02/16 [Not released] * Fix for parsing [SIZE] predicate with plugin names that contain brackets * Added Melchor's workaround for problem displaying different encodings in wx. Version 0.57 - 2009/11/03 * Added a check for max progress value in the progress dialog Version 0.56 - 2009/10/29 * Use a popup error window instead of mlox.err * Logo is now a button that does a refresh * Added a progress dialog when reading the rule-base Version 0.55 - 2009/03/16 * Documentation update: DOS line endings. Version 0.54 - 2009/03/14 * Now official .esms are automagically moved to top of load order. Version 0.52 - 2009/01/08 * Implemented spoiler hiding for messages with Version 0.51 - 2009/01/08 * Fixed a few bugs in how filenames are expanded. * Small GUI presentation tweak to ensure the labels at the bottom of the load order panes don't collide when the sash is adjusted all the way down. Version 0.50 - 2009/01/06 * Beta release. Documentation has been edited to be current. No new application functionality from version 0.41.