Template:Notice by frihyland
GUIDE FORUM THREAD
This guide is designed to introduce mod authors and mod users to the concept of mod cleaning and to provide instructions on how to clean mods using TES5Edit. Clean mods are essential to the creation of a stable modded game environment in which there are minimal conflicts between the mods used.
This guide is split into two sections: the first contains the information neccessary to understand why some mods need cleaning and the cleaning process itself, while the second provides the actual instructions for cleaning mods. There is also a Glossary at the end of the guide that may be used as a quick reference if you forget what a term means.
While this guide may seem intimidating, cleaning is not hard once you understand it. Devote some time to reading through this guide and you'll be well on your way to have a squeaky-clean mod list and a fun, more stable game environment.
Many mods make unintentional or unnecessary edits to game elements. Such edits can be a problem when using multiple mods due to the "rule of one", that states that if multiple mods change the same record, only the changes from the mod loaded last will be applied.
When a mod containing unintentional or unneccessary edits (known as a "dirty mod") is used with a mod that makes an intentional edit to one or more of the same elements, this can introduce the possibility of bad things happening, from incorrect game settings to broken content and crashing to desktop (CTD). The more dirty mods you run, the more likely you are to encounter such issues.
Dirty edits occur for two reasons: the first is that a mod author changes a record's properties but then decides to undo their changes by setting the properties back to their original values instead of removing the changes entirely, and the second is due to Creation Kit bugs changing the values of properties without the mod author being aware of this occurring.
The most common type of dirty edit is an Identical To Master (ITM) edit. This is where a mod contains an edit to a record where the edited values are identical to the original values. There are other types of dirty edit, including things like automatic cell water height edits, but they are commonly also referred to as ITM edits, so the terms "dirty edit" and "ITM edit" are somewhat colloquially equivalent.
Wild edits are unintentional or misdirected edits to game elements by a mod author that cause unneccessary conflicts with other mods. They are called wild edits because they often appear to have been made hapazardly with no relation to the author's stated intentions.
One example of a wild edit would be when a container is incorrectly modified to include an item, but instead of only that one container including the item, the result is that all containers of the same type include the item. If the description of the mod states that an item is added to a specific container, then it is clear this is a wild edit and the mod should be cleaned by fixing the wild edit.
Deleted references are a common cause of crash-on-exit. This is because if one mod tries to modify a reference that another mod has deleted, then the first mod cannot find the reference, and this then leads to a crash when the game is exited.
References are generally deleted to remove them from the game world, but a practically identical effect can be achieved by undeleting the reference then disabling it and moving it to a position where it is no longer visible in the Creation Kit (TES5Edit sets the Z axis position to -30,000 units).
Cleaning very broadly defined is a process that analyzes all the changes a mod makes and determines which edits are actually supposed to be in the mod, then removes those that are not.
Cleaning can be automated when dealing with dirty edits and deleted references, but must be performed manually when dealing with wild edits. This is because while dirty edits and deleted references have clear technical definitions, identification of wild edits requires knowledge of the mod author's intent, which is not really possible for a computer to determine accurately or consistently.
Manual cleaning is a fairly advanced technique that requires those performing it without the aid of specific step-by-step instructions to know how TES5Edit works and to know a bit about how mods work. Mod users will generally not need to perform manual cleaning most of the time, and so the specifics are not covered in this guide.
Manual cleaning is all about using your judgement to decide whether an edit is a valid, intentional edit or a wild edit that should be removed. Wild edits may be obvious such as in the example below, or not obvious, such as some rocks that were accidently moved a small amount while editing a cell. Once you have judged that an edit is wild, you must then use your knowledge of modding to decide on the correct method of fixing it, and perform the fix correctly. Incorrectly judging an edit to be wild, choosing the wrong method of fixing a wild edit and performing the fix incorrectly will all lead to making the situation worse, which is why knowledge and experience are required when manually cleaning plugins.
If you don't understand the above example and the fix, you don't possess the knowledge required for manual cleaning, so don't worry about it and just stick to automated cleaning.
Automated cleaning requires knowledge of exactly which other mods the mod to be cleaned is dependent on, both implicitly and explicitly.
In automated cleaning, if cleaning dirty edits, the program analyses every record edit a mod makes and compares each one against the record without the edit, removing any edits that match the technical definitions of dirty edits.
If cleaning deleted references, the program it analyses each reference a mod edits, checking if it has been deleted or not, undeleting and disabling any deleted references encountered.
Even when performing automated cleaning, it is important to ensure everything is set up so that cleaning can be performed correctly.
It is recommended that you begin cleaning at the top of your load order and just do down the list. This will ensure that dependencies will be cleaned before the mods that are dependent on them, so long as yout load order is correct.
It is important to ensure a mod's dependencies are clean before cleaning the mod itself because the automated cleaning process will assume that the dependencies are clean. If this assumption is incorrect, it may lead to the mod being incorrectly cleaned.
The terms explicit dependency and implicit dependency are used in this section. It is important that you understand these terms, so before continuing, here are their definitions:
Having the correct load order set for your mod plugins is essential for them to be cleaned correctly. Load ordering is outside the scope of this guide, but the easiest way to get a load order that is likely to be correct is to use BOSS.
It is highly recommended that when cleaning a plugin, only the plugin itself and the plugins it depends on should be loaded. Having any other plugins loaded introduces the risk of their contents interfering with the cleaning process and leading to invalid results.
There are two absolute requirements to loading plugins for cleaning:
Due to these rules, you cannot clean more than one mod in the same TES5Edit session. If you have multiple plugins to clean, then they must each be loaded into separate TES5Edit sessions and cleaned separately.
The principle reason for the presence of dirty mods is a lack of awareness of the issues surrounding dirty mods and the importance of mod cleaning. As such, a community-wide effort is required to raise awareness and so reduce the incidence of dirty mods.
It's NOT a good idea for everyone to just go ahead and clean their full load order and then forget about it.
The problem is twofold. First, to properly clean mods usually requires an understanding of the intent of the mod author. There might be implicit dependencies on other mods which are not part of the master list. Second, and following from the first, depending on how the cleaning was done, people end up with slightly different versions of these modules, which is going to make support in case of problems a nightmare for the mod author.
Mod quality is a community-wide problem that needs to be properly addressed on a community level. Mod authors need to ensure that their mods are clean, because they only need to clean their mod once for all future users to benefit, whereas each and every user of a dirty mod would have to clean it themselves, which is hugely inefficient.
The BOSS team provides a focus for community efforts to raise awareness regarding mod cleaning, by accepting reports of dirty mods and attaching them to the relevant plugins in the BOSS masterlist as messages containing a link to this wiki page, along with any additional information supplied. This data is then extracted and displayed to the user by BOSS when it runs, and the data can also be accessed by other utilities that make use of the BOSS API. The result is a central repository of information that can be accessed by a large number of people.
For mod authors:
For mod users:
These are the actual instructions for the automated cleaning of plugins using TES5Edit:
This glossary contains definitions for the general modding terms and cleaning-specific terms used in this guide.
Mod: A modification for Skyrim. Can be player-made or official DLC.
Plugin: A file with a .esp or .esm file extension (well, it's what's inside the file that matters, but the file extension is a pretty good clue).
Record: A data structure inside a plugin that holds the information on one element of the game. For example, each type of weapon, each race, each potion, etc. have different records.
Rule of One: Only one plugin's changes to a record can be applied by the game. If multiple plugins change the same record, then the changes from the last of those plugins in the load order will be applied. There are a few exemptions, eg. if multiple plugins put things into the same cell, then all those things will be seen in-game, but in general the rule holds for non-complex record types (and complex record types are beyond the scope of this guide).
Load order: The order in which plugins are loaded.
Dirty mod: A mod that contains dirty edits, wild edits, deleted references or any combination of them.
Dirty edit: An edit made which is unnecessary, often caused by Creation Kit bugs or authors making unintended edits then undoing them incorrectly. Such edits can be cleaned automatically.
Identical To Master edit: A type of dirty edit made where the edited value(s) is/are identical to the value(s) without the edit.
Wild edit: An edit made which is not consistent with the intent of the mod, often caused by authors accidently making small edits or trying to perform an edit in the wrong way. Such edits must be cleaned manually.
Deleted reference: A reference to a record that has been deleted. For example, placing a Silver Sword into the game world creates a Silver Sword reference there, which may then be removed by deleting it.
Dependency: A plugin upon which another plugin relies. For example, Skyrim.esm is a dependency for most mods.
Explicit dependency: A dependency that is recorded within the dependent plugin, such that the game cannot be loaded without the dependency being satisfied.
Implicit dependency: A dependency for which there is no indication given within the dependent plugin, and which can only be determined by considering author intent.
This guide has been adapted from the TES4Edit Cleaning Guide. Much of the content of that guide has been removed for this guide, with all lists of mods being absent: this is partly because there are as yet no mods to list, but mainly because such lists belong on a separate wiki page from the guide. The special cleaning instructions section is also missing for the same reason, and the tips on avoiding dirty mods section is missing because I felt it was counter to the topic of the guide. I also left out the review of key concepts because I felt that having such a section would cause many readers to skip the rest of the information, and so put them in a position of false confidence from where they could do significant harm to their modded game.
I have also created a [Dirty_Plugins_List|Dirty Plugins List] page for the listing of any plugins that need cleaning, plugins that should not be cleaned, and plugins for which manual cleaning instructions are required.
Many thanks go to the various authors of and contributors to that article, including but not limited to: Brumbek, Arthmoor, Vorians, ElminsterEU and dev_akm.
Thanks also go to ElminsterEU, Sharlikran, Zilav and Leandro Conde for their work in getting TES5Edit released.
Finally, thanks go to the BOSS team members responsible for Skyrim's masterlist, for their efforts in collating dirty mod reports.
Still to do: