Guide:Plugins Files

This guide will walk you through various level of understanding of the "plugins files" used by Skyrim and other recent Bethesda titles, from their definition/content to the interaction they have with each other, and their result in-game. -- by the S.T.E.P. Team and contributing members

GUIDE FORUM THREAD
SUPPORT FORUM

---

WIP

This page is incomplete but all info is relevant!

• The original author isn't a native English speaker. This page need orthographic, grammatical, and syntactic review

Global game architecture

Skyrim is firstly its executable, the actual program that run the game. It is located in the installation folder, and goes by the name of TESV.exe

Most of what will actually be seen and used in game isn't included in the executable itself, but in the Data folder placed under it. The Data folder is where the original Skyrim content is defined, and where mods are usually installed to add their own content.

Files found under the data folder can be sorted into 5 categories :

• Plugins Files, the object of this guide. They have the .esp or .esm file extension, and are the files read by the executable.
• Resource files, which can be either "loose", or packed in a Bethesda-specific archive format named BSA, with the .bsa extension. Resources files aren't accessed/read first-hand by the executable, instead they're "pointed to" by plugins. (Or used by an other resource, which is in turn pointed by a plugin). There would be a lot to say about all of this, but this is out of this guide's scope.
• Hard-coded resource files, read directly by the executable without being pointed to by plugins. This is the case of the intro video (the Bethesda logo).
• Non-relevant files, either put there by user-mistake, or here to serve development purpose (such as source files, used to create scripts).
• Plugin-linked files, those are used when the relevant plugin is loaded without being pointed directly. This is the case of INI files and localization files.

Basics

This part will cover some of the basic concept of plugins files.

If you're looking for more technical information, refer to the UESP Wiki

This first part is intended to be read "as is", without prior knowledge or third-party visualization tool that could alter the understanding of the following.

Definitions

Here are several definitions that need to be properly understood for understanding the rest of the guide

Form: A form is an "object" (in the programming-sense of the term) used by the game engine. There are multiple types of forms, such as NPCs, weapons, weathers, quests, cell, visual effect, etc... there are a bit more than a hundred different types of forms used in Skyrim.

FormID: A FormID is an 8-digit number in hexadecimal identifying a form. Each formID is unique to the form it defines. A FormID is completely independent of the type of the form defined.

Record: A record is a set of data defining a form. A record is stored in a plugin.

NOTE:

There are actually some specific records which are just in the plugin for technical reasons that don't define a form. See other definitions for more info.

Run-time : This is the game-launching process. Among several other things, part of this process involve reading records stored in plugins to generate the forms that'll be used in game.

Group: A group is a collection of records (or of other sub-groups), optimizing the way records are stored/accessed inside a plugin.

NOTE:

A group is actually a record itself, one of those which doesn't define a form.

Top-Group: A top-group is a group containing a complete family of records defining the same type of forms. If not for an oddity in the vanilla files, one could say that a top-group define a family of form.

NOTE:

It is technically possible that two top-groups defining the same type of forms exist in the same file, which is one reason why "top-group" isn't simply defined as "category of form". However, this situation isn't expected and and will be regarded as potential plugin's corruption.

NOTE:

Empty top-groups exists. Left-over from previous Bethesda titles, or unimplemented projects, there are 6 of them (7 with the empty duplicated top-group).

Sub-Group: A sub-group is a group contained in a top-group or another sub-group, dividing its parents "family" into "sub-family", used to further optimize complex set of records.

NOTE:

Sub-groups aren't very common, they're only used to organize world-spaces/cells and their content into logical blocks, and to regroup dialogues info under a same dialogue topic

Signature: A signature is the ID-card of a record. A record's signature represent which kind of form this record will define, and thus, which top-group it belongs to and what kind of data it should contain. A signature is a 4-character word.

NOTE:

Groups all have the generic GRUP signature

Field: A field is a data from a record. Records are a collection of fields. The number and the nature of those fields depends on the record's type (and thus, signature). Like records, fields also have a signature, though its meaning depends of which kind of record this field belong to. Field are also commonly designated as sub-records.

Plugin: A plugin is a collection of records organized in groups, each of them defining a form.

Header: There is exactly one header per plugin. The header is a special record that doesn't belong to any top-group, and doesn't define a form. It contain technical information related to the plugin, along with its author's name and a description.

NOTE:

The header record have the TES4 signature.

Referencing record: A referencing record is a record that use one (or several) other records in one or more of its fields.

Referenced record: A record referenced by an other one.

Base object: A record defining a form that can be placed in the world.

Reference: A reference (not to be confused with a referenced record) is a record defining an instance of a Base Object in the world. The base object is referenced by this reference (yes, English sometime sound a bit weird in this context). Reference are always under a CELL sub-group.

Interpretation

With what has been defined so far, you should now be able to visualize the content of a plugin like a main folder containing :

• A kind of "readme" (header) and several other folders (top-groups).
• Each of those folders contain either : Sub-folders (sub-groups), or files (records).
• Each of those files have a unique name (formID), and an extension depending on which folder it is placed in (signature).
• Those files contains multiple lines of information (fields), each line starting with a signature as well. Some lines are a path to an other of those files (referencing records to referenced records).

That's it, you can now visualize a complex game's file architecture as a simple folder on your desktop. This is the first towards understanding how the game work.

Masters

There is a little bit more into FormID than just 8 hexadecimals numbers. FormIDs are actually constituted of two parts:
The first 2 digits, called "index", and the 6 last digits, which doesn't have a specific name. Here is an other definition :
FormID's Index : Or Index for short, the first two digits of a FormID. An other technical name you might encounter for this is leading byte

In order to prevent multiple plugins to randomly "overlap" each other in the FormID they use, and cause critical issues, the FormID index won't be used as it is saved in the plugin. It will be interpreted at run-time to be constrained to a specific value. The value depending on the masters of the plugin, and the index itself.

Plugins can have masters. Most plugins for Skyrim actually have at least Skyrim.esm as master, including the official DLCs. Masters of a plugin are listed in its header, and this list of master is sorted. Which give us some more definitions :

Master File: A plugin listed in the list of masters of an other plugin.

Master's index: The place of a master in the masters' list of a plugin (starting to "0", up to "number_of_masters - 1")

The number of masters, and their index in the master list, will determine how the actual FormID's index will be interpreted at run-time :

• If the formID's index is equal to the number of masters, the form with this formID is considered as "defined in the plugin"
• If the formID's index is superior to the number of masters, it'll be "clamped", i.e. treated as if it was equal.
• If the formID's index is inferior to the number of masters : then it match one of the master's index. The form with this formID is considered as defined in the matching master.

Then again, there is two scenarios:

• The form is actually defined in the master, in this case the record in the master is overridden.
• The form doesn't exist. The record will be considered as "injected".

Which give us 3 new definitions:

New record: A record with a formID's index equal or superior to the number of master. This record defines a new form to be used by the game.

Override: A record with a formID's index equal to one of the master's index, if the master also has a record with this formID. This record modifies a form already defined by an other plugin.

Injected record : A record with a local formID's index equal to one of the master's index, but the master does not have a record with this formID. This record also defines a new form to be used by the game.

In a less abstract fashion:
We've now learned how a new form is created (by defining a new record), and how we can modify an already existing form (by overriding its record in the master it's defined into). We also learned that it's possible to create "injected" records, though the purpose of this remain unclear.

Because definitions are so practical when it come to understanding things in depth, we can extrapolate a little bit and give a few more to carve our knowledge in stone :

Master record: A new record in a plugin that is later referenced into an other.

Multiple overrides: A scenario where two or more plugins would override the same master record.

Critical conflict: A world-end scenario, where a plugin override a record in an uncommon fashion, using its formID to re-define something completely different instead of simply altering it (typically, the override doesn't have the same signature as the master record).

The exhaustive list of overrides contained in a plugin is saved directly in its header, under the ONAM field.

Load Order

Since there are multiple plugins, they have to be loaded in a specific order. This order is stored in the %LocalAppData%/Skyrim/plugins.txt file, and can be adjusted manually from here. The official game's launcher and several modding utilities offer more convenient means to alter the load order.
Note that contrary to popular belief, the loadorder.txt file that can be found in the same folder isn't an "official" file, but is generated/used by the loadorder utility LOOT (and its predecessor BOSS). This file is commonly used by popular modding utilities such as TES5Edit as reference for the load order if present, in place of the actual plugins.txt.*

Load Order: The order in which plugins are read at run-time.

Load Order Index : Sometime just index for short, when talking about a plugin. The position of a plugin in the load order. Not to be confused with the formID index definition from the previous chapter. A load order index will usually be written between square brackets like this : [01]

Priority: Non-quantitative term to qualify a plugin's index in the load order. A plugin with low priority has a small index and will be loaded before most of the others. Essentially used to compare two plugins : "A has a higher priority than B" = "The index of A is higher than the index of B".

The index of Skyrim.esm in the load order is hard-coded, its index will always be [00]. Other plugins, including official patches and DLCs are loaded in the order they appear in plugins.txt, and their index attributed accordingly : starting from [01] for the first plugin of the list, and up to [FE] if there is 255 plugins listed.

At run-time, the engine will interpret the formID's index we've been talking about in the previous chapter, in order to attribute them to their respective plugin : New records will have their FormID's index set equal to their plugin's index. Overrides and injected records will have their FormID's index set to the corresponding master's index.

Atop of that, if one plugin's master is missing, the game will crash to desktop after the official Bethesda logo. We now know enough to understand that this is because it is trying to find a master in order to attribute some formID's a proper index, but cannot.
To prevent any critical bug, the game shut itself down.

Furthermore, it is now clear that a form, with its unique formID, is only defined once (by a master record), but can be altered by records in plugins dependent on the master. Thus, for the next part of this guide, we will, for the most part, ignore the subtlety of the interpreted formID's index, and consider talking about a "record's formID", designating the formID of the record post-interpretation.

We also know enough to understand that it would be possible for a plugin to be loaded before its master (overrides would just have a higher index than new records in the same plugin). While the game is actually able to load, and some overrides will behave as expected, several others might output the expected result, and scenarios of multiple overrides will lead to random results.
Atop of that, such disordered load order is extremely difficult for a human or a basic algorithm to be read, thus it is highly recommended that the load order is... in order, i.e. that any plugin having masters should be loaded after all of them.
Utilities such as LOOT and NMM will automatically modify the load order in order to have this behavior. Others, such as MO or WB will warn about miss-ordered load order. TES5Edit will refuse to launch with an error message explaining that the load order is unexpected.

More about dependency

There are several reasons why plugins have a master, and thus various types of "dependency".

Explicit dependency: When a plugin needs its master records in order to function. The master is in the masters' list of the plugin. There are two reasons for an explicit dependency :

• The dependent plugin is overriding one or more of its master's records in order to make its modifications.
• One or more of the master's records are referenced by records in the dependent plugin.

Implicit dependency: An implicit dependency is when a plugin doesn't reference a master, but is designed expecting this master to be present. Typical examples includes :

• A mod needing an other mod's resources, but none of its records.
• A mod expecting bug fixes/alterations to be in place to function properly.

Forced dependency: Same as an implicit dependency, but the expected master has been forced as explicit master (added to the masters' list of this plugin even if not technically required).
There are several reasons where a forced dependency makes sense, especially in the case of patches or mods with specific version designed with compatibility in mind.

Obsolete dependency: Same as a forced dependency, a plugin has been added to the list of masters while not technically required. However the mod doesn't necessarily expect the other mod to be installed at all, not even implicitly. This is usually an error on the modder's end that happens when loading unnecessary master files in the creation kit alongside the plugin worked on.

More about Master Files

A common misunderstanding in the modding community is that master files are files with a .esm extension, and .esp files are regular plugins. This is wrong on several levels. The file extension is just a convention supposed to identify them, but has no technical meaning.

A master file is a plugin which has the "ESM" flag set in its header. Whether it have a .esp or .esm extension doesn't matter, only the flag is to be taken into consideration. And this is the only actual difference between a master file and a regular plugin. (A plugin with the "ESM" flag set, but which still has the .esp extensions is usually referred to as an "esmyfied plugin").
The game engine has no consideration for this file, nor for the file's extensions. No matter if the "ESM" flag is set, as long as the plugin has either the .esp or .esm extension and is listed in Plugins.txt, it'll be loaded at its index.
.esm files and/or files with the ESM flag set doesn't necessarily need to be loaded before any regular files. This is only a convention followed by the majority of the community.
A regular plugin file (with the .esm extension, and without the "ESM" flag set) can be a master as much as any other plugins, this isn't a limitation.

The only difference between files that have the flag, and those that don't, is the way the Creation Kit, or another official editing tool, is handling them, because it can only edit one plugin at a time. If a file with a master is loaded in the Creation Kit:

• If the master has the "ESM" flag : the modder will be able to edit his plugin without modifying anything in the master(s) file(s). No matter if the plugin needs records from the loaded master files, all of them will be added in its masters' list (this is how obsolete dependency happens)
• If not, then the CK will simply not be able to determine which file(s) it is supposed to edit (since none have the "ESM" flag), and thus break the dependency in order to work on them "separately". This will result in completely corrupted plugins, as every referencing record pointing to a record in the master file will now point to the void.

Dynamically created forms and savegames

In addition to all the forms defined by records, "created forms" are also used in-game. A created form isn't defined by any record, and only exists in memory (while playing) and the savegame (upon exiting the game).
Their formID index is always FF. The behavior of those forms is similar to references, in the sense that they are instances of base objects (base objects which are regular forms generated from records), but have been created dynamically by the game. This is the case of any "spawned" items or actors which haven't been hand-placed by a modder/developer.

A way to visualize this concept it is to see the savegame as an additional plugin that would always be loaded at index [FF], and only contains:

• Overrides of forms that have been altered in-game (typically via script).
• New records of references only (typically spawned items/NPCs).

WARNING:

This is only a way to represent the content and impact of the savegame in the context of plugins. There is much more to savegames than just this.

Conflicts

This chapter will walk you through the basic concept of conflicts detection, understanding, and resolution.

The rule of one

For the sake of accuracy

---

As discussed in the previous chapter, there is a technical difference between winning override and override loaded last, as it is technically possible to load plugins before their master and still have their overrides take precedence in game.
However, the un-reliability of this behavior, and the fact that it makes any consistent analysis of the load order near-impossible for a human brain, we will consider during the whole guide that the load order is always sorted with masters loaded before plugins dependent on them. Thus, we can negate the distinction between override loaded last in the load order, and winning override.

The rule of one is the community-given name to the way records are processed (or with our brand new fancy vocabulary, how forms are generated for the game based on the records defined in the plugins and their load order).

Rule of One: In case of multiple overrides on the same record, only the winning override is taken in consideration to generate the form used in-game.

Which gives us some more definitions:

Conflict : A case of multiple override where two overrides on a same master record make different changes.

Winning Override: Also designated as "Conflict Winner, the override used to create the form.

Loosing Override: Also designated as "Conflict Loser, An override which doesn't affect the game because it is overridden by a record in a plugin with higher priority.

As we've seen, records are considered "as a whole". Each field from the master is copied into the override, but only some are modified. All of the non-modified fields are thus identical to the fields in their masters.

This behavior wouldn't be an issue if a record was only one piece of information at a time. However, records are a collection of fields, each field carrying different information. When two different plugins edit the same record for a different purpose, they don't edit the same field. However, the rule of one implies that only the winning override see its changes taken into consideration, the change(s) to the other(s) field(s) from the conflict loser are "ignored", instead, the fields identical to their master's are used.

ITM records

ITM stand for "Identical To Master". An ITM record is a case where an override is present in a plugin, but each of its fields is identical to the one in its master. Such records is usually designated by the sole "ITM" acronym.
Such records serve no purpose (the form generated by the record will be the same, whether or not this override is here). However, this override can present a conflict with an other one in an other plugin, preventing its change to take effect if its plugin have a higher priority.

ITMs are in most case the result of careless manipulations in the Creation Kit by the mod author. The truth is that the Creation Kit is extremely sensitive, and that any record opened and then closed, even if not modified, will be saved as ITM in the plugin if it have been closed by clicking "OK" instead of "Cancel". ITMs exist even in the official DLCs, sometimes preventing modifications from another DLC to take effect.

There are cases where ITMs can be intended.

• To prevent a specific change from an other plugin to take effect on purpose (for consistency reason, or to fix an issue introduced by the change). However, plugins designed for such purpose are supposed to have the plugin they're reverting the changes from added as a forced dependency, in order for the record to "not be an ITM", since there would be an other master differing from the record.
• To make sure the data contained in these records are the vanilla ones. This case is however never completely consistent (mods usually require only some fields to be vanilla's, not the whole record), and is essentially pointless, since the load order could just lead to this ITM being overridden anyway.

The global conclusion is that ITMs records are unnecessary and will essentially lead to broken load order and malfunctioning mods.

Resolving conflicts

There are several approaches to conflict resolution. The most common way is to create a patch, containing the changes to any fields from every override to the same record into an other override. This process will be detailed in the following paragraph.

The most convenient tool to create such patch is TES5Edit. Now that most of the information it will display has been defined and explained, it might be a good time to open it up and look at some content, or even reproduce and solve the following example by yourself.

Conflicts arise when two plugins override the same master record. For a simple use case example, let's say:

• Skyrim.esm is the master file, and the master record the infamous Iron Sword.
• ModA.esp references Skyrim.esm as master, and overrides the Iron Sword record in order to change its gold value from 25 to 70.
• ModB.esp references Skyrim.esm as master, and overrides the Iron Sword record as well, but instead changes its Damage from 7 to 5.

NOTE:

if you're trying to reproduce this case in TES5Edit, the FormID of the Iron Sword is 00012eb7. Invoke the **Context menu** with a right click on it on the left pane and look for the "Copy as override into...". You should now have enough knowledge to figure out what will next happen by yourself ;) Look at the xEdit guide if you aren't confident enough about where you should click

The "rule of one" implies that only the winning override will have its changes applied. So:

• If only ModA.esp is loaded, the Iron Sword will have a gold value of 70 instead of 25. This is a case of "override without conflict". The original record from Skyrim.esm isn't used, but this is considered as the expected behavior, because ModA.esp is referencing it as a master.
• If both ModB.esp and ModA.esp are loaded, and ModB.esp has a higher priority than ModA.esp, thus the Iron Sword will have a damage of 5, but will still be at the vanilla gold value of 25. The Iron Sword isn't using the information from the record in ModA.esp at all.

In case this wasn't clear enough in the previous paragraph: this isn't using the record from Skyrim.esm either. Data, other than the damage, are identical to those in Skyrim.esm only because they've been copied "as is" in ModB.esp

We now have a conflict. There are multiple approaches to solving it:

• Creating a custom patch. This would be a 3rd plugin, Patch.esp for instance, that would modify both the gold value to 60, and the damage to 5. To make things "clean", our patch would have both ModA.esp and ModB.esp as masters. While having those masters is not technically required in this case, it'll help you remember why this patch has been created in the first place (one reason to have forced dependencies). By loading Patch.esp after ModA.esp and ModB.esp, we would have changes from both mods. This is what common conflict-resolution is about : Copying all the changes from conflicting records into an additional patch to have all the changes taking effect.
• On the other hand, since ModA.esp and ModB.esp don't do anything else, we could just create the same plugin as we just did, but not add the forced dependencies and just use it instead of the other two. In such case we're not talking about "patching", but recreating a mod from scratch including the features from two others. Although this seems like the best solution in this example, such practice is quickly limited when dealing with actual large-scale mods.
• We could also consider that this is ok to "lose" the change from ModA.esp : since ModB.esp is reducing the effectiveness of the sword, it'd make sense that it isn't worth more than the original value. In which case, ModA.esp is obsolete and be removed. However, if ModA.esp was a larger-scale mod (for instance, overhauling the gold value of any weapons in the game), it might be better to just keep the conflict and bear with it.
• Trying to be smart: This is usually something that should be done on the modder's end, but as a power user, you could figure out that ModA.esp's purpose is to set the gold value to 10xDamage. So, with the damages reduced to 5 in ModB.esp, following ModA.esp pattern, a proper "ModB - A Edition.esp" would have its damage set to 5, and its gold value to 50.

So much blabla for such a simple thing you think... and you'd be right. Hopefully, this little example gave you enough to think about how a proper and complete conflict-resolution procedure can be hair-pulling on an actual load order. We've just been analyzing the consistency between gold value and damages on a single basic weapon.

Records merged at runtime

I mentioned exceptions to the rule of one. Those are known as "records that merge at runtime". Some records are excluded from the "rule of one" behavior, they are automatically "conflict-resolved" when the game kick-in.

For references, those records are listed on the AFKMods KnowledgeBase

Note that it is possible that only a handful of fields are merged at runtime, and not the whole record.

Some specifics records will be reviewed in an other chapter of this guide.

Advanced notions

This chapter will introduce advanced notions on the content of plugins, especially what can be found in the various fields and its meaning.

Records analysis

This chapter will focus on the analysis of some specific records, groups, or fields which present interesting behavior and should be known of anyone willing to manage a complex load order.

Worldspaces, Cells, Blocks and sub-blocks

This is an edited copy of an original post by Zilav explaining blocks and sub-blocks for Worldspaces/Cells. You'll find an accessible copy the original post on the STEP Forum
Note that the original post on the nexus forum was aimed at the FNV community so references are made to the Fallout New Vegas files instead of the Skyrim's ones. The technical explanations still stand for Skyrim.

Blocks and Sub-Blocks are actual GRUP records stored in plugins, the game use them to quickly find temporary exterior cells when the player travels around. Their numbers depend on cell's X,Y coordinates, actually cells are placed into those groups depending on their X,Y. Blocks and Sub-Blocks numbers for a cell record are calculated this way, assuming (CellX, CellY) are the cell's coordinates stored in XCLC sub-record.

SubBlockX = (int) CellX / 8
if (CellX < 0) and ((CellX %   8 != 0) SubBlockX = SubBlockX - 1
 
BlockX = (int) SubBlockX / 4
if (SubBlockX < 0) and ((SubBlockX % 4) != 0) BlockX = BlockX - 1

The same for Y.

So each Sub-Block holds a grid of 8x8 cells, and each Block 4x4 Sub-Blocks, or 32x32 cells. This is a WastelandNV map with overlayed blocks, sub-blocks and cell coordinates of bottom left corner of each sub-block to give you the overview. You can view it yourself in FNVEdit pressing Alt+F3 for any worldspace, including your own (just select opacity to overlay grid).

The only exception is a single persistent CELL having <0,0> as coordinates which holds all persistent references in the worldspace. It is a direct child of WRLD record and the game load all those references regardless of the position of player, hence the name "persistent".

Interior cells use groups too under top CELL top-group, but they are determined differently. Cells can be only temporary, they hold both temporary and persistent references. Hexadecimal FormID number of a CELL record is converted to the integer value excluding the leading byte which is load order and changes dynamically depending on the position of plugin. The last decimal number determines Block number, the previous one is Sub-Block. Lets take this cell as an example NovacMotelRoomTwin2 "Motel Room" [CELL:000CD3E1] Hex value 0CD3E1 converted to integer is 840673, so the physical location of that cell inside a plugin file is FalloutNV.esm / Cell / Block 3 / Sub-Block 7 / 000CD3E1 <NovacMotelRoomTwin2> (as FNVEdit shows you).