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?

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.

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