Description:
//=====================================================================================================
This script automates the process of combining multiple Bethesda Plugin/Master Files
(.esp/.esm) into a single plugin file. I have perfected this process through extensive
user-assisted experimentation and testing to take into account a massive number of variables.
We have come a very long way from the manual merging method that was known 2 years ago.

The script is extremely easy to use, just select the mods you want to merge in xEdit, run the
script, type in a name, and presto! Your mods are now in a single clean package!



Version 1.8:
//=====================================================================================================
After extensive beta testing and development, Merge Plugins v1.8 has been publicly released.
A lot has changed since v1.7, so it is extremely important for you to read the summary below.
You can also check out the change log.


TES5Edit version checking:
The script will terminate and print messages to xEdit's internal message log if you aren't using
xEdit version 3.0.33 or newer. Because there isn't a way for me to check the svn of xEdit, you
will pass this test even if you're using an old xEdit 3.0.33 svn. For this reason, I recommend
that when you download version 1.8 you download the latest version of xEdit as well. Currently,
the latest version is available on Nexus Mods (version 3.1.0).  Having the latest xEdit version
is absolutely essential for the script to run properly.


Advanced options:
The GUI has received a massive overhaul. The settings that dictate how a merge is performed
have been moved to a separate window, which you can open by clicking the gear icon in the
lower right corner of the main Merge Plugins window. This "Advanced Options" window will
automatically open the first time you run the script. You cannot perform a merge until you have
set your settings in this window. Settings will be saved to "Edit Scripts\mp\config.ini", and
reloaded each time you run the script in the future. Every control in the Advanced Options
Window has detailed Hint text which will appear if you mouse over it. Hints that say LEGACY
OPTION correspond to options you shouldn't use unless you're doing experimentation.


Mod Organizer options:
If you're using Mod Organizer, you need to the check the "I'm using Mod Organizer" checkbox
and then make sure the script knows where Mod Organizer is installed. If you click the Detect
button the script will attempt to find Mod Organizer by searching standard installation
directories. You can also enter the path manually or click on the folder icon to browse for it.
The path here should be a full path to the directory holding ModOrganizer.exe. E.g.
"C:\Program Files (x86)\Mod Organizer\"

There is a new option here called Copy general assets. This option only works with Mod
Organizer, and has the script copy assets from the "Mod Organizer\mods\*\" folders
corresponding to the ESPs you're merging. I highly recommend you use this option if you're
using Mod Organizer.


Renumbering options:
A new option called "Renumber conflicting FormIDs" has been added. This is the best of two
worlds in that it only renumbers the records that need to be renumbered to avoid fatal conflicts
(duplicate FormIDs), but doesn't renumber everything so esoteric issues relating to renumbering
FormIDs are mitigated. You should always use this option, resorting to "Renumber all FormIDs"
only if merging with "Renumber conflicting FormIDs" isn't creating a functioning merged plugin.

You should never use "Don't renumber FormIDs" unless you know what you're doing and are
prepared to face the issues associated with duplicate FormIDs.


Copying options:
You should always use "Copy Intelligently" unless you're doing experimentation.


Second pass copying options:
Second pass copying used to be necessary to create functioning merged plugins with certain
records (NAVM, NAVI). Recent xEdit updates may have made it unnecessary. To be safe,
you can use the "Second pass same as first" option, though this will extend the time spent
merging. The default option is "No second pass", which I have determined works for mods
that used to require a second pass.


Other options:
The "Asset destination directory" is the directory where the script will copy assets to. If you're
using Mod Organizer this should be Mod Organizer's overwrite folder. This will automatically be
set if the script successfully detects Mod Organizer after you click the Detect button. You can
also enter the path manually or click on the folder icon to browse for a destination folder. If
you're using NMM your destination folder could be either Skyrim's data folder or a different
folder which you plan on making into a mod package to install into Nexus Mod Manager later.

The "Extract BSAs" option will extract all BSAs associated with the plugins being merged to the
"Asset destination directory". This is only necessary if you're using NMM, as Mod Organizer will
load all assets from available BSAs automatically regardless of whether or not there's an ESP
with a matching file name. Also note that, when copying file-specific assets like FaceGenData,
Voices, and MCM Translation files the script will check inside available BSAs as well as your
data directory, so you no longer need to extract BSAs before merging for that purpose anymore.

The "Disable label coloring" option is for users that can't see the colored labels in the main
"Merge Plugins" window. An alternative to using this option is to enable Windows Aero.

The "Batch copy assets" option will copy all assets after merging via a batch (.bat) script. This
option is valuable when performing large merges, as Delphi's internal CopyFile function operates
asynchronously, which leads to massive memory and CPU usage, and will often lead to xEdit
running out of available memory. You should always have this option enabled, but take note of
the fact that it will open a visible Command Prompt (cmd.exe) window at the end of the merge
for asset copying. You must not close TES5Edit or this window during the copying operation if you
want asset copying to be performed correctly.


Asset destination helper:
With the introduction of the "Asset destination directory" feature, I also implemented a check
which makes certain the asset destination directory is empty before performing any operations
for the merge.  If it's not empty, a window will appear alerting you that it's not empty, giving
you the options to proceed with the merge, open the directory in explorer, or cancel the merge.
This should help you avoid the mistake of including files in the merged mod that aren't needed.
If you're using the data directory as the asset destination directory when you first run the script,
you will be notified that using it will make your data directory messy over time, and isn't
recommended.



Installation:
//=====================================================================================================
Before installing and using this script you need xEdit 3.0.33 svn1898 or newer.
xEdit is an alternative editing program to the Creation Kit. While xEdit may not have some
of the cool features the Creation Kit has, it runs faster and allows for the execution of pascal
scripts.

You can get xEdit 3.1.0 here.

Once you have downloaded and installed xEdit you simply need to copy the contents of the
included "Edit Scripts" folder into xEdit's "Edit Scripts" folder. This folder is located in the
directory where TES5Edit.exe is.



Tutorial:
//=====================================================================================================
Merging Plugins with Mod Organizer:
1. Set up the plugins you plan on merging so they're all in adjacent load order slots. Test to
make sure the plugins create the desired behavior in the game before merging.
2. Run xEdit through Mod Organizer and load the mods you want to merge.
3. Use "Check For errors" on files to be merged and fix any errors xEdit finds. See the FAQ
for more information on errors and how to fix them.
4. Hold control and click on each of the mods you want to merge so they're highlighted.
5. Right-click on one of the mods and click "Apply Script".
6. Choose "Merge Plugins v1.8" from the drop-down menu and click OK.
7. If it's your first time running Merge Plugins v1.8 you will be taken to the Advanced Options window.
When here, check the "I'm using Mod Organizer" checkbox and set Mod Organizer's directory (you can
use the Detect button to have the script try to find it for you). Check "Copy General Assets", and
set the Asset destination directory to Mod Organizer's overwrite folder, then click "Save".
8. Verify the mods you want to merge are checked, and that no other mods are checked, then click OK.
9. Choose -- CREATE NEW FILE -- and click OK.
10. Enter the filename you wish to use for the merged plugin.
11. Wait for merging to complete. If an error occurs (highly unlikely) the script will stop, display the
log, and alert you that an error occurred. Post this log on Nexus Mods to receive assistance.
12. Once merging is completed, close xEdit saving ONLY the new merged plugin you just created.
13. Right click on the Overwrite mod in Mod Organizer and click "Create Mod...". Name the mod,
activate it, and then deactivate the mods you merged.
14. Start the game and test to see if the merged plugin is working as intended.


Merging Plugins with Nexus Mod Manager:
1. Set up the plugins you plan on merging so they're all in adjacent load order slots. Test to
make sure the plugins create the desired behavior in the game before merging.
2. Run xEdit and load the mods you want to merge.
3. Use "Check For errors" on files to be merged and fix any errors xEdit finds. See the FAQ
for more information on errors and how to fix them.
4. Hold control and click on each of the mods you want to merge so they're highlighted.
5. Right-click on one of the mods and click "Apply Script".
6. Choose "Merge Plugins v1.8" from the drop-down menu and click OK.
7. If it's your first time running Merge Plugins v1.8 you will be taken to the Advanced Options window.
When here, check "Extract BSAs", and set the Asset destination directory to a folder on your desktop
(or somewhere else) for the Merged Plugin you're making.
8. Verify the mods you want to merge are checked, and that no other mods are checked, then click OK.
9. Choose -- CREATE NEW FILE -- and click OK.
10. Enter the filename you wish to use for the merged plugin.
11. Wait for merging to complete. If an error occurs (highly unlikely) the script will stop, display the
log, and alert you that an error occurred. Post this log on Nexus Mods to receive assistance.
12. Once merging is completed, close xEdit saving ONLY the new merged plugin you just created.
13. Open your Skyrim data directory and move the Merged Plugin ESP file from it to the folder on
your desktop. Add the folder on your desktop to a .zip, .rar, or .7z archive, then install it in
Nexus Mod Manager. Activate it and deactivate the plugins of the mods you merged from your
load order.
14. Start the game and test to see if the merged plugin is working as intended.


Verifying your Merged ESP:
You should also re-open the merged ESP in xEdit after merging and use Check For Errors to make
sure everything is functional.


Removing Plugins from a Merged Plugin:
As of v1.7, you can remove plugins from a merged plugin. This will only work on plugins made with
Merge Plugins v1.7 or newer. Note: this is an experimental feature and results may vary.

1. Load your merged plugin in TES5Edit.
2. Right click on the merged plugin, and click "Apply Script".
3. Choose "Merged Plugin Manager v1.1" from the drop-down menu and click OK.
4. Check the plugins you want to remove, then click "Remove".
5. Close the Merged Plugin Manager and then exit TES5Edit, saving the merged plugin.


Generating and Submitting Reports:
As of v1.7, you can generate reports on the merge-ability of plugins. This can be done with a Merged
Plugin or with the ESP files you merged.

1. Load your merged plugin in TES5Edit.
2. Right click on the merged plugin, and click "Apply Script".
3. Choose "Merged Plugin Manager v1.1" from the drop-down menu and click OK.
4. Check the plugins you want to generate reports on, then click "Report".
5. Enter the information you want to submit for each report. You won't be able to generate the
report if you leave one or more fields blank or at their default values.
6. Once you've generated your reports, go to your Edit Scripts folder and open the "mp" folder.
7. Run "Merge Plugins Report Client.jar", enter a username you want to have associated with
your report, and click "Login".
8. Click "Send Reports" to send all reports you have generated to the remote server to be
incorporated with the Dictionary file.
9. Click "Logout".

NOTE: If you're found to be abusing the report submission system your IP will be blacklisted and
you will no longer be able to submit reports or get updated dictionary files through the client.


Updating your Dictionary File:
Updating your dictionary file will give you all the latest definitions from reports submitted by
users. I recommend you try to update your dictionary file before merging, and at most once
a week.

1. Go to your Edit Scripts folder and open the "mp" folder.
2. Run "Merge Plugins Report Client.jar", enter a username, and click "Login".
3. Click "Get Dictionary".
4. Click "Logout".



Merge Logs:
//=====================================================================================================
As of v1.8, the script uses an internal log instead of using the message log built-in to
xEdit. This was done because there is a demonstratable performance hit when printing many
messages to the xEdit log. To maximize the speed gained by not using a visible log, you
should not click the "Show Details" button while the merge is being performed.

The script's internal log will be saved to a file "Edit Scripts\mp\logs\merge_<date>_<time>.txt"
after the script finishes executing. If you experience problems you must copy the messages
from the log file associated with the merge and post them here or on pastebin if you wish
to recieve assistance. Without a log file I can only really take shots in the dark as to what
went wrong with your merge. With a log file, I can determine within 30 seconds what went
wrong with a merge and respond immediately. Please, show me that you value both my
time and your own time by posting a log when you have an issue. It's really easy to do and
makes a world of difference.



Popular Mods:
//=====================================================================================================
This is a short list of some popular mods that been made using the Merge Plugins script. 
These mods serve as proof of the Merge Plugins Script's success, effectiveness, and usefulness
to the Skyrim Modding community.  If you know of more popular mods that have been merged
and distributed by the author using my script, let me know and I'll add them to this list!

• Static Mesh Improvement Mod
• Realistic Needs and Diseases
• SkyFalls and SkyMills
• JK's Skyrim
• Immersive College of Winterhold
• Relighting Skyrim
• Northern Cardinal
• Unique Border Gates
• Jaxonz Utilities
  

Thanks:
//=====================================================================================================
There are a lot of people who have helped make Merging Plugins into what it is today. Here
I will show my appreciation for their contributions, which have been invaluable to the
development of this tool. If you see them in the comments section or on the forums, make
sure you thank them too!

zilav: The guy behind the machine. Zilav is one of the lead programmers of xEdit, and
has been working with me since I first started doing xEdit scripting. This guy has made
everything I do possible and far more. All hail zilav!

Private Beta Testers:
keithinhanoi
noobzor
mindw0rk2
steve25469
Teabag86
Thalioden
bla08

Public Beta Testers:
Draco856
karios525
ChiefZigZag
icecreamassassin
hishutup
...
etc.

Thank you everyone for your contributions!
And thanks to everyone who has submitted reports to the dictionary!



Frequently Asked Questions:
//=====================================================================================================
Q: Does this do conflict resolution?  That is, if I have two mods that modify the same record, will
merging those plugins combine the edits from those records into a single record?
A: No, absolutely not.  Merging plugins combines the records in the mods being merged in the
same way as the mods would behave if left separate in your load order.  That means the winning
override will be used.  If you want to combine multiple edits to the same records you need to 
make a compatibility patch which overrides those records with the edits you want to use.  There
are numerous tools out there that can do at least some of this for you, including Wrye Bash, the
TES5Edit Merged Patch, and Mator Smash.

Q: In previous versions of this script certain plugins didn't merge well. Is this still the case?
A: Based on 2791 reports submitted as of 02/12/2015, 97.56% of plugins merge well.
Considering how v1.8 has a large number of bugfixes and improvements over v1.7, this
percentage will only be getting higher.

Q: Will <insert mod here> work?
A: Based on user-submitted reports, there's a 97.56% likelihood it will work. Those are
some pretty good odds.

Q: How do merge plugins behave with BOSS/LOOT?
A: BOSS and LOOT don't know how to place merged plugins in your load order. You have to
manually place them at the highest load order position of the mods you merged with respect
to masters. (Viz., not above a file that is a master for the merged plugin.)

Q: Can I merge merged files?
A: Yes, just not during the same run of xEdit (save and quit before each new merge). This shouldn't
introduce new problems, just remember to backup so if you merge something bad you can undo it
and keep the merged file you've been working on.

Q: What can I do about errors in plugins I want to merge?
A: Well that depends on what the error is.  If its a "<Record> marked as deleted..." error
you can clean the plugin using xEdit's "Apply Filter for Cleaning" and "Undelete and Disable
References" options.  Other errors can be more complicated.  Invalid or out of order subrecord
errors often can't be fixed, but you can try opening these mods in the Creation Kit as the active file
and then resaving them.  "< Error: Could not be resolved >" FormIDs can be fixed by entering a
valid FormID in their place or by removing the subrecord that holds them (right click -> Remove).
NOTE: Fixing errors asides from UDRs can be a tricky business.  Make sure you keep backups
of the plugins you plan on fixing errors for in case you accidentally break one of them!

Q: Can mods with MCM menus be merged?
A: As of v1.7 MCM translation files are handled properly, so MCMs should merge perfectly.

Q: Can I merge ESP patches with their master file?
A: Yes.

Q: Can I merge a mod's patches together?
A: Yes.

Q: What are the benefits of merging?
A: Merging reduces ESP clutter allowing for more mods. It also makes your data directory
more manageable, so you no longer have to rip your hair out trying to find that ONE ESP
which is causing you problems. It also improves performance, load times, and reduces
CTDs. It's basically the panacea for DMS: Disorganized Modder Syndrome.

Q: SkyRe? AutomaticVariants? SUM?
A: Don't merge plugins that were made or are in any way related to these mods. SkyRe was
made with TESVSnip, and is a giant mess of corrupted data. In addition, all third party
patchers will create corrupted data, which will lead to CTDs if copied in TES5Edit.

Q: Can I use SUM/AutomaticVariants/the Reproccer on a merged plugin?
A: Yes. A merged plugin is a plugin just like any other plugin is a plugin. A merged plugin is
just a single plugin with data that used to be spread out between multiple plugins.

Q: Right clicking isn't doing anything!
A: Wait for the background loader to finish loading the mods.

Q: I'm getting CTDs, why?
A: If you didn't check for errors in xEdit you may have merged mods with errors which, can
lead to CTDs.

Q: Will this make my game explode?
A: Just make sure you only save the merged ESP and disable the ESPs you merged from your
load order when testing the merged file. If things don't work for some reason, active your old
ESPs and delete the merged file and voila, everything's back to the way it was! No harm done.

Q: Where should I put the merged file in my load order?
A: At the spot where the highest mod you merged was/should be. So if you merge mods at
positions #10, #26, and #100 you want to put the merged ESP at position #10, with respect
to masters.

Q: Copy Intelligently? Copy Records? Copy Groups? What are these things!?
A: Just use copy intelligently. The other two are old merging methods that advanced users
can choose to use if they so wish. You don't need to worry about them.

Q: What is corrupted data and can I fix it?
A: Mods with invalid/out of order subrecords may have corrupted data. Or, at least, data
that xEdit can't interpret properly. Opening these mods in the Creation Kit as the active file
and then saving them MAY fix this problem, or it may not. If you merge mods with these errors
the result is Skyrim CTDing when it starts.

Q: My hair's gone?! My armor's gone?! My weapons are gone?! My face is gone?!?! WHAT?!?!
A: When you merge plugins many records are being moved to new FormIDs to prevent conflicts.
That means all save games with references to the items from the mods you merged may have the
items/objects removed. This is just the way the game works, there's nothing I can do about it.
So say you merge your hair mods and you load a save game where you had a hair from one of those
mods. You will be bald. It's no biggie though, just use showracemenu, find the hair, and save once
you've fixed your depilation dilemma. Armors: add them back. Weapons/items: add them back.
Face: uhh... o_o'? Generally speaking, however, it's probably best to start on a new save after
merging hair/object/Leveled List/NPC outfit altering mods.

Q: Should I check for errors before merging?
A: Yes.

Q: Should I check for errors after merging?
A: Yes.

Q: Can I merge my entire load order into a single ESP?
A: Theoretically, if all those mods didn't have problems with merging, yeah you could. It's probably
best to just merge by mod groups though.

Q: Should I submit user reports?
A: Please do. It takes you all of a few minutes and may be very helpful to other users.

Q: I'm unable to select the Merge Plugins script from the Apply Script window/which script do I select?
A: When you right-click and choose apply script the window that comes up should have a
drop-down menu from which you must select Merge Plugins v1.8. DO NOT USE "Merge plugins",
this is a WIP non-functional script created by Zilav. If you do not see Merge Plugins v1.8 in the
window you're doing one of a few things wrong:

• You're starting xEdit from a shortcut, which is starting it in a directory where it doesn't
  have access to "Edit Scripts/Merge Plugins v1.8.pas". Try starting xEdit directly from
  the executable located in the directory as the Edit scripts folder you installed my Merge
  Plugins script into.
• You didn't install my Merge Plugins script correctly. See the installation section.
  

Q: Can I remove an ESP from a merged plugin?
A: Yes! As of v1.7 you can do this with the Merged Plugin Manager! Note: this is an experimental
feature, your results may vary.

Q: mteFunctions.pas is included in both AutomationTools and the Merge Plugins script, which should I use?
A: Use the one in the Merge Plugins script. If you really want to be certain you're using
the most up to date version (all versions are backwards compatible) you can grab that from
my GitHub.

Q: TES5Edit has to be in its own folder?
A: That's how I like to organize things. This is no longer required as of version 1.7.

Q: When do merged plugins cause problems?
A: Merged plugins fail/cause problems when data isn't properly copied to them by xEdit or
when assets aren't properly made available to them. Merged plugins are plugins just like all
other plugins are plugins.

Q: Can I merge ESM files?
A: If the ESM files are used by any other files in your load order you should not merge them.
If they aren't used by any other files in your load order, you can merge them. Alternatively you
can open the master file and all the files that use it as a master and merge them all together.

Q: Can older merged plugins I made continue to work with new versions of TES5Edit/the script?
A: Yes. You don't need to re-merge things whenever there is an update to TES5Edit/the
Merge Plugins script. If the merge is working, it's working. However, you won't be able
to use the features of the Merged Plugin manager on Merged Plugins that were made in
versions prior to 1.7.

Q: I'm getting grey faces still... why?
A: Shouldn't happen in v1.8 unless you didn't set your Asset destination directory
correctly.

Q: I got "Error in unit 'mteFuntions'...", why?
A: You installed an older version of mteFunctions.pas. Reinstall the latest version of the
merge plugins script and make sure you replace your current mteFunctions.pas with the one
in v1.8.

Q: Is it OK to rename merged plugins after merging?
A: No.  Renaming the merged plugin will break the association of various assets with it.

Q: How much can this reduce my load order?
A: I've heard reports of ~70% plugin reduction in load orders (insaneplumber, 357 to 104
plugins). It all depends on the mods you're using.