Mod Cleaning Tutorial

Oh no! I've been working on my mod for months, pouring my life's blood, sweat, and tears into this thing, and I just realized that two weeks ago I:

• deleted a quest/NPC/widget that's essential to the main story
• accidentally hit "Recompile All" in the script editor
• moved something in a cell I was looking at for inspiration
• touched a bunch of dialogue records that I shouldn't have
• somehow screwed up something really important in the stock game

I don't have a recent backup, and every time I try to fix the problem by copying/pasting the removed resource back into my mod, it just makes things worse! Have I ruined three months of work? Will I have to start all over? Has life as I know it come to an end?

Relax. Sit back. Take a deep breath. Now, read on and learn all about your dirty mod, and how to fix it.

What's A Dirty Mod?

To get a thorough understanding of this concept you first need to know what a mod is. A mod is basically a list instructions telling Oblivion what to change in the vanilla game to create a desired effect. A mod can make changes to npcs, quests, items, buildings, etc. These changes are then saved and stored in a plugin file.

The problem with dirty mods arises from the fact that Oblivion allows the player to use more than one mod at a time. One mod may add a building to a city. Another mod may create an NPC or move an NPC from one location to another. A player can download and install a great number of mods as you probably know. But what if two or more mods attempt to make a change to the exact same object? Which mod wins? The answer is the last mod loaded by the game.

Let's say in the process of creating your mod you accidentally move an NPC. Wanting to be a responsible modder you promptly move the NPC right back to where they were. Maybe you put the NPC back in its exact same spot - and maybe not. But you figure the NPC is close enough. Thinking nothing more of it you save your mod. Here is where dirty mods are born. When you saved your mod the CS also recorded the fact that you moved the NPC. The NPC might be in the exact same spot you found it. Still, when your mod is loaded Oblivion is going to read and act on the instructions you gave it, and the NPC will be moved to the precise location you specified - even though it was an accident. A person playing your mod could have another mod that loads before yours which moves the NPC in question to a new and specific location in Cyrodiil. The new location of this NPC may be a critical feature of this other mod. Still, when Oblivion gets to your mod in the load order the NPC will be moved to the exact spot your mod specified. Even though you didn't intend any changes to the NPC, your accidental "nudge" broke a mod someone else created. This is called a mod conflict. And fixing these types of "mistakes" is what Mod Cleaning is all about.

A dirty mod is any mod in which you, the modder, accidentally touched something in stock Oblivion that you didn't mean to. Many times, you might not have even noticed. Perhaps you were just looking at a dungeon and accidentally nudged a rock out of place. Or maybe you were browsing through the quest editor one day poking check-boxes to see how things worked, then forgot all about it and saved your mod anyway. Or maybe you made the classic mistake of doing a "Recompile All" in the script editor, and suddenly your mod just grew by 2MB and you now have a copy of every script in the game.

Often, a dirty mod is benign. You probably didn't even know it was dirty until some user asked why your mod conflicts with some other mod, and you can't for the life of you figure out what they have in common. Or maybe you noticed right away after you accidentally deleted Martin from the main quest line, but you just don't know how to set things right.

Use The Details, Luke

Luckily, the solution to all these problems (and more!) is the Details button. The Details button can be found on the open screen, where you load your mod, right beside the "Set Active File" button.

The Details button in the open dialog.

Clicking the details button reveals the guts of your mod. It shows a list of your mod's records, which are the instructions that tell Oblivion how to change the master Oblivion.esm file. Anything you do in your mod, every change you make, adds new records to this list. Even deleting a stock Oblivion object adds a new record to your mod that instructs Oblivion to remove that item from the player's world. Basically your mod is just one huge changeset being applied to Oblivion.esm, and the Details tab lets you see every one of these changes up close and personal.

There's a reason we don't do our everyday modding through the details editor, because it's not exactly the easiest thing to understand.

However, the basic concept is quite simple. The record type lists what kind of thing is being changed. This could be a reference (REFR), a dialogue entry (DIAL), something about a worldspace (WRLD) or a cell (CELL), or any number of other things. Often, these records are nested. So changing an external cell also "touches" the worldspace containing that cell, and you will see both records in the details list. You know when something is nested because it will be preceded by a GRUP record that cannot be modified. The thing before the GRUP record is what this record is nested under. So, for instance, modifying a cell would cause you to have a WRLD record, followed by a GRUP record, followed by a CELL record.

The detailed file record list.

The other bits of information are quite straight forward. The 'D' column is a flag that indicates that the record is deleting the referenced item, rather than changing it. The 'I' column is a flag you can set to ignore that record. The final column is the identifier for the record, which can be all sorts of different things, depending on the record type. Usually you can figure out what's what based on the record type and identifier.

Cleaning the Mod

The real power in this screen comes from the ability to ignore records. To ignore a record, select it and hit the "delete" key. To unignore an ignored record, select it and hit the "delete" key again.

Ignoring records is how you clean a mod. Simply search through the list of records in your mods to find the item that corresponds to your accidental change. If you deleted an NPC, you'll probably see an NPC_ or REFR record with the 'D' column flagged. If you accidentally moved a rock somewhere, you'll see a CELL record for the cell you touched, followed by a GRUP record, followed by several REFR records for the things you accidentally moved. Of course, each case is unique, but a little bit of digging and common-sense should enable you to figure out which are the records you need to get rid of.

The only caveat is to make sure you truly find everything you touched. Because of nesting, moving an object in a cell will potentially touch that object REFR, the owning CELL record, and the containing WRLD record, all at the same time. To clean this properly you would have to ignore all three of these records (assuming there was nothing else in that cell/world space that you meant to change).

Finally, ignore the unwanted records by hitting "delete". Load the mod, then save it, and those changes will disappear forever from your mod. Cells you didn't mean to touch will no longer flag as being modified. NPCs you accidentally deleted will be right back where you left them. Mysterious conflicts will suddenly disappear. Your users will rejoice, and you can breathe a sigh of relief!

Using an External Utility

There are several utilities that can make it a lot easier to remove things from a plugin.

TES4Edit

TES4Edit makes it very easy to examine the details of a mod's record structure, compare it with other mods in your load order, and tweak any of them to clean out problem records.

By far the best way to do this is to perform a thorough examination of your mod looking for unintentional or problematic changes. The huge advantage here is that you can tell exactly what changes were made to each record, which lets you make an informed decision about whether the record should be removed or not. In other words, you can verify your work by examining the plugin record structure in TES4Edit and removing any records that are not intentional changes.

To remove a single record or range of records in TES4Edit, select them and right-click->Remove.

You can also use TES4Edit's "Remove identical to master records" function, which automates the process for any records that are unchanged from the master. This doesn't catch records which have minor accidental changes, but it can still help. When you do this, make a copy of your mod, use TES4Edit's "Remove identical to master records" on it, then load your original "dirty" mod and use TES4Edit's "Compare to" function to compare it with the cleaned copy.

There are several good tutorials on the subject of mod cleaning with TES4Edit, but the TES4Edit Cleaning Guide is by far the most comprehensive. Other guides can be found here and here.

Wiki link:TES4Edit

TESsnip

TESsnip allows you to view more details than the "Details..." button. You can also save changes to a new .ESP in case you delete something you shouldn't have.

After using it you will still want to open it in the CS so it can correct the header/index. When you've deleted stuff with the utility the CS will complain that the .ESP has fewer things than it expected. Just let it fix it.

Wiki link:TESsnip

TESsnip website

TES4Gecko

Recent versions of TES4Gecko include a feature called Clean Plugin, which automatically removes any records from your plugin that are not actually changed from the original master.

It also now includes a Compare Plugins feature that can help you easily distinguish between records that have changed and those that have not.

In cases where you need to remove accidental changes, TES4Gecko includes a feature called "Display/Copy Plugin Records" that does a lot more than its name would suggest.

When you load up a plugin file with TES4Gecko using the "Display/Copy Plugin Records" function, it lets you browse a tree structure of the records in a plugin. Records are grouped neatly into branches by type so you can quickly drill down to the things you want to look at by expanding the appropriate branch.

The major advantage here is that problem records are easy to see and you can quickly remove an entire branch of records by marking Ignore on the parent group.

For example, if you have accidentally changed a default container, you can easily spot this under the Container branch because you'll see a container record there with a FormID starting with 00 (records starting with 00 are always from Oblivion.esm, while records starting with 01 are new things added by your plugin).

File:TES4GeckoContainer.jpg

Marking Ignore on several dirty container records.

To remove these dirty container records, expand the Containers branch, select the dirty records (Ctrl-Click to get multiple records), click the Ignore button, then click Save Plugin.

If your mod contains several dirty creature records, the process is the same:

File:TES4GeckoCreature.jpg

Marking Ignore on several dirty creature records.

To remove these dirty container records, expand the Creatures branch, select the records you want to remove (Ctrl-Click to get multiple records), click the Ignore button, then click Save Plugin.

TES4Gecko automatically adjusts the record count for the plugin after you make changes this way, but it's still a good idea to open it up in the CS to check your changes.

Wiki link:TES4Gecko