TES4Edit Cleaning Guide

Introduction

This tutorial is designed to teach modders and mod users how to use TES4Edit to clean mods. Cleaning mods is critical to the development of compatibility in the modding community and for creating a stable modded game environment, but TES4Edit is not a simple utility and care must be taken not to damage the mods in the process. This tutorial should help explain everything that you need to know to clean mods correctly.

This guide is split into two sections. The first section is meant to convey general knowledge and understanding about the entire cleaning process. The second section contains the *actual* instructions on how to clean your mods. You could skip to the second section but it is highly advisable that you read this entire document from start to finish in order to greatly improve your success rate in the cleaning endeavor.

There is also a Glossary at the end of this guide. Several terms I use are community wide terms, but a number of other are ones I’ve sort of invented to help explain things. You may wish to skip to the glossary now to get a rough idea of key terms I’ll be using.

Section #1: General Knowledge and Theory Behind Cleaning

Section #1 has three parts:

1. Why Clean?: This part explains why many mods need to be cleaned

1. What is Cleaning?: This part explains what it means to ‘clean’ a mod

1. How to Clean: This part explains the theory about how to clean your mods properly and safely

Please read through this guide entirely at least once before attempting to clean your mods. Throughout the guide, Key Concepts will be given. These are sort of big picture ideas that you need to learn and apply in order to successfully clean your mods. I repeat, you MUST understand these concepts or you are likely to get into trouble.

Part #1: Why Clean?

Short answer: Because some mods have ‘dirty edits’ which cause bad things to happen, ranging from incorrect game settings, disabling content, broken quests, and crashing to desktop (CTD). If you run a lot of mods (subjective amount but perhaps 100 or more) the chance of dirty mods causing problems rises exponentially.

Longer answer: When a mod is created, certain unnecessary edits can occur and be stored in the mod. Unnecessary means the edits do not in any way add to the purpose of the mod and are, in fact, improper edits, which have become known as ‘dirty edits.’ This is a problem because Oblivion uses the ‘override’ system which means that if a certain mod changes a specific game element (game setting, stats, characters, towns, buildings, wilderness, ect), that mod will override changes to the same game element that any prior mods make. Whatever mod loads last, that mods settings will take precedence over all prior mods that alter the same settings.

'Example 1: Quest mod overwriting Sneak mod'

To illustrate the problem, say you have a quest mod loaded in the middle of your load order after some other mod that alters how sneaking works in Oblivion. Say the quest mod creator originally was going to change the sneak elements in Oblivion to fit his quest mod. However, after editing the settings, the creator decided the original unmodified (called ‘vanilla’) sneak settings were fine, so he changed them back to the original values. In this case, the earlier loaded sneak mod that changed the sneak elements will be overridden by the quest mod, even though the sneak edits in the quest mod were changed back to Oblivion values. Incidentally, the correct thing the quest mod creator should have done was to actually delete the sneak edits completely from his mod rather than simply change them back to Oblivion values.

Hopefully you can see that the end result of the above example is that your super-cool sneak mod that changes all sneak attack multipliers to 1,000 times more damage will be overridden by the quest mod and you’ll get lame vanilla sneak attack multipliers. This type of dirty edit is fairly mild in its negative effect, but it still is undesirable.

The solution is to clean the quest mod. By cleaning the quest mod, the sneak attack changes will be completely removed so that now the earlier sneak mod will be able to change the settings without the later quest mod overriding it.

Please note: this description of ‘Why Clean?’ is a non-technical description and there is much more to say about it, but for our purposes we only need to know that dirty edits are nasty creatures that need to be vanquished by the shining light of truth that is mod cleaning, poetically speaking.

Part #2: What is Cleaning?

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.

There are two ways to clean: manual and automated. I differentiate between undesirable edits and unnecessary edits just to help understand these concepts. Undesirable edits require manual cleaning. Unnecessary edits can be removed using automated cleaning.

This guide is ONLY giving detailed instructions for automated cleaning. However, the next section will give some broad information about manual cleaning in order to increase your understanding of both manual and automated cleaning.

Method 1: Manual Cleaning

It should be said that manual cleaning is an advanced technique that most users don’t have the knowledge or need to engage in most of the time. Automated cleaning is effective for removing most dirty edits from a mod, usually.

However, there are certain mods that require manually cleaning because the mod contains dirty edits that are undesirable based on a human judgment call. Automated cleaning will not remove these edits because the program computer cannot determine what the original author’s intent was and what is desirable. To quote the Governator from Terminator 3: ‘I am a machine, desire is irrelevant.’

Let us here from one expert, Vorians (display name is already in use) regarding manual cleaning:

The other type of dirty records - those which TES4Edit cannot automatically detect and remove (but will color-code them so you can track them down) are typically accidental edits by the mod creator, for example unintentionally clicking on a rock and moving it a tiny amount when they meant to click on something else. Don't try to manually fix these without first gaining some good understanding of both how TES4Edit works and what the purpose and scope of a mod is - you need to be able to tell whether such an edit is a mistake, or in fact intentional.

A mod changes the Silver Sword so that it is now the Super Sword of Slaying, and adds many powerful abilities to the weapon, then places it once at the bottom of a new dungeon. Every single placement of the Silver Sword in the game, including those by any other mod, will now be the Super Sword of Slaying. Changing the Form ID from 00###### to 01###### and updating the single valid reference will ensure that Silver Swords are all Silver Swords, while the one and only Super Sword of Slaying is still the Super Sword of Slaying. [If you don’t understand this Form ID talk, don’t worry and just stick with automated cleaning. -Brumbek]

It's all a matter of understanding what the mod is MEANT to do, to ensure you can tell a valid edit from a dirty edit.

Regarding undesirable edits, let’s quote another expert, Arthmoor:

TES4Edit will highlight in bright yellow wild edits, but it won't automatically remove them as they aren't identical to masters, but these are edits that should not be made. They're fairly obvious with their bright yellow highlights. Knowing what a location should reasonably edit is key to removing these safely [manually].

'Example #2: Old Dungeon mod Ruins of Tarnesia alters unrelated locations'

Ruins of Tarnesia is a great mod but it does make some random edits to unrelated things, whether accidentally or because of CS bugs. Another mod that loads earlier that also edits one of these unrelated (to Ruins of Tarnesia) locations, will have its edits overridden by Ruins of Tarnesia. Automated cleaning will not detect and delete these incorrect changes in Ruins of Tarnesia because technically the edits differ from vanilla Oblivion and are therefore not considered unnecessary (identical to master Oblivion.esm).

It should also be mentioned that Ruins of Tarnesia also contains a LOT of edits that will be removed by Automated cleaning (out of 6304 records, 4440 are redundant and unnecessary). So here is an example of a mod that you would have to use automated cleaning and ALSO manual clean out all dirty edits. For the record, most users just shouldn’t use this mod given how much it changes, sadly.

In conclusion, regarding manual editing, the only way to remove dirty edits would be to load the mod in TES4Edit and to have enough knowledge to identify edits that are spurious and do not support the true purpose and scope of the mod. Before engaging in manual editing, you should also have an understanding of how every edit a mod makes effects the game.

Method 2: Automated Cleaning

Automated cleaning analyzes every edit a mod makes and compares each one to the default Oblivion environment (by comparing the mod to Oblivion.esm) and removes any edits in that mod that are identical to vanilla Oblivion. Again, the purpose of automated cleaning is to make sure no unnecessary edits exist in a mod. Remember, undesirable edits can STILL exist, but at least the mod will be cleaner than previously and possibly entirely clean.

For the record, it should also be stated that just because a mod has some dirty edits, this is not always the mod creator’s fault. The CS is known to produce certain dirty edits incorrectly. Certain dirty edits are due to modder lack of skill, however, other dirty edits can happen to the best modders. Vorians says:

The majority of dirty edits which can be removed by TES4Edit automatically exist in the .ESP due to the bugs in the CS. The more cells an .ESP edits, the more dirty records there are likely to be.

Mart's Monster Mod - City Defences.ESP edits cells in every city (except Kvatch and the Imperial City), all around the wall tops, both in the city worldspaces and in the main Tamriel worldspace. That's a lot of edited cells, and thus the reason for so many dirty records. And such dirty records exist through no fault of the mod creator!

Part #3: How to Clean

The number one most important thing you must know before cleaning a mod is what other mods the mod to be cleaned depends upon. I will explain what this means, but here’s the key concept:

Key Concept #1: Automated cleaning requires knowledge of exactly which other mods a certain mod relies upon (is dependant upon), both explicitly and implicitly.

Vorians repeats many times that when cleaning the user must be sure they are ‘doing it right.’ What does this mean? Key concept #2 tell us:

Key Concept #2: The very essence of ‘doing it right’ is to make sure you load into TES4Edit all files (.esp and/or .esm), in the right load order, that the mod your cleaning relies upon, both explicitly and implicitly.

I know want to explain four terms to help you understand the details: explicit dependency, implicit dependency, simple mod, and complex mod.

An explicit dependency is very easy to discern because you can easily check what files it relies upon in Wrye Bash. Moreover, TES4Edit will automatically load any explicit dependencies (can be either .esm or .esp files) when you select a mod with explicit dependencies. The only time it won’t do this is if you don’t have a mod installed that the other mod is dependent upon. This would be a major mistake you’ve made. For instance, if you download a patch to fix landscape issues with, say, Verona House Bloodlines, you better have Verona House Bloodlines installed!

An implicit dependency is more tricky because you won’t see the required files listed in Wrye Bash. The most common implicit dependency is when dealing with the many landscape patches by Vorians and some by Arthmoor. The only way to know what implicit dependencies a mod has is to know what the mod does, which can discovered by reading its readme usually. Here again is where understand what a mod does is crucial. Specifically, you must understand which mods a patch mod is designed to patch!

A simple .esp is one that relies solely on Oblivion.esm and possibly a master. esm from the mod itself, which would be distributed with the mod itself and be obvious. A simple mod has only explicit dependencies, so TES4Edit will always load the necessary master files when loading the mod.

A complex .esp is one that mods another mod and is meant to be used with one or more other mods. This can also be called a ‘patch’ mod. A complex .esp has both explicit and implicit dependencies, so you MUST by yourself determine and load the implicit dependencies into TES4Edit.

Complex .esp’s can be broken down into two more types:

A basic complex .esp usually edits two other mods in a minor way. Landscape patch mods are the most common examples of this.

An advanced complex .esp must attempt to patch many mods together in a very in-depth way.

The perfect example of an advanced complex group of .esps is FCOM. It is not recommended to clean FCOM not because it *can’t* be safely cleaned but because to safely clean it you need a LOT of knowledge about the inner workings of FCOM, and nobody but dev_akm is qualified here.

Moreover, dev_akm cleans his stuff well enough already. To prove it dev_akm says:

All recent versions of FCOM were created almost completely with TES4Edit to begin with, so every record override includes some important change to one of the masters. You may find a very small number of override records that do not actually change anything in the master, but this usually only happens in cases where the master was later updated to match a change first made in the FCOM plugins (this happens a lot).

So everyone should stop worrying about FCOM and just not clean it. Instead, you should worry about nuclear war (or the absence of it?) or something.

'Example #3: A simple .esp – KvatchRebuilt.esp'

KvatchRebuilt.esp is a simple .esp because it depends only upon Oblivion.esm and KvatchRebuilt.esm. You would be able to tick KvatchRebuilt.esp in TES4Edit only and have TES4Edit load both the aforementioned .esm files properly, and cleaning would be perfectly safe and simple.

'Example #4: A complex mod – Landscape patches like the Baddy patch for Entius Gorge'

Let us quote Vorians regarding cleaning patch files. His note has been verified as correct by ElminsterEU, the creator of TES4Edit.

It should be perfectly safe to clean a patch as long as you ensure that every ESP that the patch relates to is also loaded in TES4Edit. And I mean all of them, not just those which have to be loaded because the patch is dependent on them. So for example one of my Unique Landscape compatibility patches is only [explicitly] dependent on Oblivion.esm but is for one Unique Landscape mod and one other mod. You must load into TES4Edit the Unique Landscape mod and that other mod (in the correct load order!) before attempting to clean the patch.

And here is an actual example of what Vorians means using his Unique Landscape compatibility patch for Baddy and Unique Landscape Entius Gorge:

This patch is dependent on Baddy.esp, so if you wanted to auto-clean this ESP, TES4Edit will load ‘Baddy.esp’ when you load ‘Baddy-EntiusGorge patch.esp’. It won't however load ‘xulEntiusGorge.esp’ as the patch is not [explicitly] dependent on the Unique Landscape ESP. [So the user MUST be sure to tick the UL ESP themselves, when first loading TES4Edit. If you forget to tick the UL ESP, you run the risk of removing IMPORTANT edits when automatically cleaning the mod.]

So, the patch has ‘Baddy.esp’ as a master, making the patch explicitly dependent on ‘Baddy.esp’. The filename, readme and entire purpose of the mod makes it clear that ‘xulEntiusGorge.esp’ is fairly important for the patch to work correctly. So it is implicit that the mod is dependent on ‘xulEntiusGorge.esp’ even though there is no master entry in the header record.

This means that it is obvious to anyone who is actually intelligent enough to be safe using TES4Edit in the first place (did I say that out loud?!) that to do it right, you need to have both ‘Baddy.esp’ and ‘xulEntiusGorge.esp’ loaded into TES4Edit (and in the correct load order!) for the automated cleaning to be reliable [not mess things up].

Therefore…there is no valid reason to not clean a patch where it is blatantly obvious which other mods it was designed to patch.}}

'Example #5: Another Illustration of the Importance of Loading Implicit Dependencies'

DuggeDank provides the following example. Assume Mod A is a great mod but it regrettably makes a few silly changes. For instance, Mod A changes the name of the NPC Baurus to JohnnyBoy but does a lot of other really cool things. So Mod B is created in order to fix (patch) Mod A. Therefore, Mod B changes the name of the NPC Baurus back to Baurus in order to get all the changes from Mod A except the name change.

If you were to only load Mod B without also loading Mod A into TES4Edit, then TES4Edit would notice that Mod B's record of for Baurus is identical to its master Oblivion.esm. Hence, automated cleaning would remove the name change in Mod B because it appears to be unnecessary. This would be bad because now you’d have JohnnyBoy running around in game again.

This is why it is critically important that you load both Mod B AND Mod A into TES4Edit in the proper order (Mod B loads after Mod A since it modifies Mod A).

But as ElminsterEU points out:

This problem [the JohnnyBoy issue] only happens if you load JUST Mod B and not Mod A into TES4Edit at the time you do the [automated] cleaning.

If both Mod A and B are loaded, then that record in Mod B would be marked as ‘identical to master but conflict winner,’ in which case the cleaning should not touch it.

To prevent the possibility of Mod B being loaded without Mod A being loaded, Mod B should list Mod A in its master list in which case trying to load Mod B into TES4Edit will always load Mod A as well.}}

Elminster’s final point is aimed toward mod creators. It is best and safest that any time you release a mod that modifies or relies upon another mod(s), you should list the other mod(s) as a master in the header of your mod.

Lastly regarding Example #5, the much preferred solution to this whole problem would be for the original mod creator of Mod A to delete the JohnnyBoy edit. But this may not happen because for many reasons such as the mod author is long gone, likes the JohnnyBoy change, and/or is criminally insane. This is why sometimes a patch needs to contain typically unnecessary edits to counter the undesirable edits.

Load Order Notes

Besides loading all explicit and implicit mods into TES4Edit in the right load order, the mod you are cleaning should 'always be' the last mod loading in TES4Edit. This is 'crucial'. Never, ever, ever clean a mod that has other mods loaded into TES4Edit after it! This means you cannot load groups of mods together into TES4Edit and clean them in the same TES4Edit session. You must load the proper files as discussed above and clean only the last mod. Then you MUST close TES4Edit and start over with whatever next mod you want to clean. This is why cleaning many mods takes 'a long time'. It is recommended you set aside many hours when you will clean your mods.

Vorians sums up with another ElminsterEU verified statement saying:

Best practice [what you should ''''always do'''' and never do anything different!] when cleaning an ESP is to ''''always'''' only ever load into TES4Edit the files necessary to carry out the cleaning. This means there should be zero files loading after the file you are cleaning.

Now here are some hard and fast rules by the man, ElminsterEU, himself. These rules NEVER change and ALWAYS apply to cleaning.

• The module you are cleaning should be the last in the load order

• All modules (which can be both esm's and esp's) that the to be cleaned module depends on (no matter if they are in the master list or if the dependency is implicit and indirect as e.g. with some of the FCOM modules) must be loaded in the correct load order

Note that to have the correct load order, you set your order to usual way as if you were playing. So as long as you already have the correct load order (you do, don’t you?), then you don’t need to do anything different for using TES4Edit. Load ordering is not within the scope of this document, but the easiest way to get the correct (mostly) load order is to use Better Oblivion Sorting Software (BOSS).

What Order to Clean Mods In?

It is recommended that you begin cleaning at the top of your load list and just do down the list. This means start with your earliest loading mods (top of the TES4Edit box that appears when you open TES4Edit).

Arthmoor also says to clean the ESM first when you have an ESP dependent upon it. This will happen anyway if you simple start at the top of your load list (the ESM’s will be cleaned first).

Section #2: Actual Cleaning Instructions

Why have I spent so much time on cleaning philosophy instead of actual cleaning instructions? The reason is because the majority of problems you can cause by cleaning come from a lack of deep understanding rather than mistakes in the actual cleaning process. Also, the actual cleaning process is very simple (but tedious). And here enters our last Key Concept.

Key Concept #3: The true challenge in cleaning is not the logistics of cleaning but the knowledge required to know what files to load into TES4Edit.

And now, at last, the actual instructions:

Coming Soon!

Review of Key Concepts

Key Concept #1: Automated cleaning requires knowledge of exactly which other mods a certain mod relies upon (is dependent upon), both explicitly and implicitly.

Key Concept #2: The very essence of ‘doing it right’ is to make sure you load into TES4Edit all files (.esp and/or .esm), in the right load order, that the mod your cleaning relies upon, both explicitly and implicitly.

Key Concept #3: The true challenge in cleaning is not the logistics of cleaning but the knowledge required to know what files to load into TES4Edit.

The astute reader will realize all three key concepts are actually saying the exact same thing.

Quick List of What Mods to Clean

• Do NOT clean any FCOM files that come in the FCOM archive.
• Do NOT clean any of the unofficial patches (UOP, USIP, UMP).
• Do NOT clean SM Plugin Refurbish…unless you really understood this guide.
• Do clean WarCry & Bob’s Armory.
• Do clean the official DLC.
• Do clean just about everything else…

List of Mods Needing Cleaning

This list is NOT comprehensive. It is merely here to point out some mods that definitely need cleaning. Any mod not on this list and not on the Clean list may need cleaning.

24HrArenaAliveV2.esp
300_White Stallion 4
Addendum - Diabloblivion.esp
Adonnays Elven Weaponry.esp
AlchemistsCave-COBL.esp
Aliyah.esp
ArmamentariumArtifacts.esp
Atmospheric Oblivion.esp
Auriel's Books.esp
AyleidArrows.esp
bartholm.esp
Benirus Manor Remade.esp
Blood&Mud.esp
cf_Improved_Barter_Gold.esp
Choices and Consequences - MMM.esp
Choices and Consequences.esp
ClocksOfCyrodiil.esp
Cobl_Glue.esp
Crowded Roads Advanced less crowded.esp
Cyrodiil transportation network 1.3 WZ.esp
DLCBattlehornCastle.esp
DLCFrostcrag.esp
DLCHorseArmor.esp
DLCMehrunesRazor - Unofficial Patch.esp
DLCMehrunesRazor.esp
DLCOrrery.esp
DLCSpellTomes.esp
DLCTheivesDen.esp
DLCVileLair.esp
Echo_ChapelChant.esp
Enhanced Quest Roleplaying.esp
eyja.esp
GlenvarCastle.esp
GTAesgaard.esp
hackdirtabyss.esp
HeartOftheDead.esp
Ivellon.esp
Knights.esp
Living Economy - Items.esp
LostSwordOfTheAylied.esp
Lynges_Thieves_Highway-10256.esp
Malevolent.esp
MannimarcoComplete.esp
MannimarcoRevisited.esp
Mart's Monster Mod - City Defences.esp
Mart's Monster Mod - Gems & Gem Dust.esp
Mart's Monster Mod - Hunting & Crafting.esp
MD Saddlebags v3.0.esp
Mighty Umbra.esp
MIS.esp
NakedNord.esp
Nanaelas Heartbreak.esp
New_Sheoth_Palace_LOD_fix-10076.esp
noDem's City Life.esp
Oblivion WarCry EV.esp
OBSE-Storms & Sound SI.esp
Origin of the Mages Guild.esp
Rainbows.esp
Reznod_Mannequin.esp
Roleplaying Dialogues.esp
RTT.esp
Ruin.esp
SentientWeapon.esp
ShiveringIsleTravellers.esp
sir_balin_mod.esp
Slof's Horses Base.esp
SM Plugin Refurbish - Battlehorn.esp
SM Plugin Refurbish - ThievesDen.esp
Sonia.esp
StarX Vanilla Vampires Revised.esp
sunk ships.esp
T.I.E4MODS.esp
T.I.E4MODSOOO+FCOM.esp
TamrielTravellers4OOO.esp
The Lost Spires.esp
TheElderCouncil_TempleOfTheOne.esp
TheForgottenShields.esp
theivery.esp
TheStorytellersBrotherQuest.esp
Thieves Arsenal.esp
TOTF.esp
Ungarion1TheWelkyndSword.esp
Valley_View_Estate.esp
VaultsofCyrodiil.esp
VHBloodlines 1.2.esp v12
Visually Enhanced Arena.esp
WeaponsOfTheNine.esp
Your_Personal_Museum_Updated-9300.esp

List of Mods Already Clean

Unoffical patches
More coming soon...

Glossary

Vanilla Oblivion: This refers to the default Oblivion experience (settings, locations, items, ect) when running no mods at all.

Dirty edit: Any edit that should not be in a mod, either due to it being unnecessary or undesirable.

Undesirable edit: This edit is different than vanilla Oblivion, but the change is not consistent with the purpose and intent of the mod in question. This edit is the result of a judgment call based on studying the mod creator’s purpose and intent. Automated cleaning will not remove this type of dirty edit.

Unnecessary edit: This edit is identical to vanilla Oblivion and is not part of a patch-type mod, and is therefore totally unnecessary. This edit can be empirical proven to be a dirty edit. Automated cleaning will remove this type of dirty edit.

Explicit dependency: This is another .esm or .esp file that the mod in question lists as a master in its header. All you need to know for cleaning purposes is that TES4Edit will always load the explicit dependencies for you.

Implicit dependency: This is another .esm or .esp that the mod in question doesn’t list as a master in the header but nonetheless is required for the mod in question to do its job. You must know enough about the mod in question to know which mods it implicitly requires.

Simple .esp: An .esp that relies solely on Oblivion.esm and possibly a master. esm from the mod itself, which would be distributed with the mod itself and be obvious. A simple mod has only explicit dependencies, so TES4Edit will always load the necessary master files when loading the mod.

Complex .esp: An .esp that mods another mod and is meant to be used with one or more other mods. This can also be called a ‘patch’ mod. A complex has both explicit and implicit dependencies, so you MUST determine and load the implicit dependencies into TES4Edit.

Basic Complex .esp: An .esp that usually edits two other mods in a minor way. Landscape patch mods are the most common examples of this.

Advanced Complex .esp: To fit this category an .esp must attempt to patch many mods together in a very in-depth way. This would be FCOM. It is not recommended to clean FCOM not because it *can’t* be safely cleaned but because to safely clean it you need a LOT of knowledge about the inner workings of FCOM, and nobody but dev_akm is qualified here. Plus dev_akm cleans his stuff well enough already.

Do it right: Making sure you load all files (.esp or .esm) into TES4Edit in the correct load order that the mod your cleaning relies upon, both explicit dependency and implicit dependency.

Correct cleaning load order: The same load order that is correct for playing the game. The file you are cleaning must ALWAYS be the last file loaded in TES4Edit, and all other required files must be loaded in the same optimal order you use for playing.

Closing Remarks

You actually read all of this? +5 to OCD for you.

But seriously, none of this would be possible without ElminsterEU, who has put an enormous chunk of his personal spare time into the making of this wonderful program. All kudos should go to him. And if you are in position of doing so, don't forget to rate the download (a perfect 10 of course!) at TESNexus.

I also want to think all the other contributors to this, specifically Vorians, Arthmoor, dev_akm, and many others. I also want to thank all the little people I stepped on in order to become Master of the Universe.