Category:Data Files

This is an introduction to mod files: their uses, differences, and importance both to using and making mods. Understanding how mod files work is fundamentally important to understanding how to mod.

• Note: This page does not cover the use of assets such as mesh and texture files. See BSA Files for more information.

Master Files (*.esm) and Plugins (*.esp)

Master Files (files with .esm - ie, Fallout3.esm) and Plugin files ("TES files" or "mods" for short - files with .esp - ie, Fallout3mod.esp) are the core data files of Fallout 3. A master file acts as a database of all of the data for the world, including object data, dialogue, gameplay settings, object placements, AI settings, landscape, script commands, cells, etc. The GECK is the tool we use to view and edit master files and plugins.

Master files and plugins are largely identical in format, but have some important distinctions in practice. The main practical difference is that ESPs automatically make all REFs persistent which keeps them all in RAM and increases save bloat, as a result they are a poor choice for most mods.

In order to create new .esms, you can use The GECK and when saving your file add ".esm" to the end of your file name. This will create an ESM instead of an ESP with the proper extension and flag applied on the file header. Additionally FOMM or XEdit can be used to convert an ESP or create a new blank ESM.

To load multiple .esms in the GECK, you need to edit or add this setting in the GECKCustom.ini file: bAllowMultipleMasterLoads=1 (Under the [General] category)

This file is found in the user folders under:

• My Documents/My Games/Fallout 3
• My Documents/My Games/FalloutNV

Further this file typically can not be found under a normal search in windows.

Notes

• If any plugin contained in the masterlist of another plugin is missing, the game will crash.
• A mod which adds or modifies navmesh should be ESM. Navmesh overrides will stop working when dying and reloading a game when in an ESP due to how navinfo works.
• All references in ESP's are persistent and always loaded in memory. In ESM's, only records explicitly flagged as persistent are treated as persistent, as well as records in the ONAM. Persistent records use memory and increase save file size.
• Editing ESM files in GECK will not create all ONAM required for overrides. To create ONAM, open the ESM in xEdit. Then right-click the plugin in the left panel, and select Mark Modified. For a larger mod this may take several seconds. Monitor the output on the right panel. When Mark Modified is complete, save the file in xEdit.
• Changing non-persistent refs to persistent in an ESM as an override of another ESM will create dirty edits (ITM) in any mod using the ESM as a master.
• Editing NPC base records inside ESM files causes NPCs to become white in game as a result of losing face textures, See Export NPC Face Textures for information on how to fix this.

Dependencies

Master files, plugins and savegames are usually dependent on other master files or plugins (the exception being the original master file that shipped with the game - that master file has no dependencies, and runs on its own). Typically, a Fallout 3 mod will be dependent on the original Fallout 3 master file. The masters of a given mod or savegame is simply the list of "parent" mods that the mod or savegame depends on. The masters of a mod can be seen in the GECK details view.

Masters lists are important because they help identify where objects in a mod or a savegame come from. I.e. when a savegame remembers an object, it essentially remembers it as something like "the 2,034th object defined in my fourth master". If the master list were somehow to be erased, then the savegame would lose the ability to match the object in the player's inventory with original object defined in the mod.

In regular gameplay, it's not really necessary to know about masters, but modders need to understand them, since gameplay debugging often requires working with FormIDs, and FormIDs are the way the game encodes information like "the 2,034th object defined by my fourth master".

Records and Overrides

As mentioned before, a mod file (master file or plugin) is basically a database of all the objects in the gameworld. To be more specific, the mod file is a collection of records. The records in a given mod are mixture of 1) new records, and 2) modifications of existing records (i.e. of records defined by the mod's masters). E.g. "Cool Guns.esp" might introduce three new guns, as well as modify two existing guns defined by Fallout3.esm. Each of these guns is represented by a single weapon record (so 3+2 = 5 records in total).

The important thing about records is that each record is a single indivisable object as far as GECK and the game engine are concerned. Thinks of the game world as a table with stacks of playing cards. You can add a new card, or you can override an existing card by putting a new card on top of it. So, in the example above, the three new guns form three new stacks, and the two modified guns go on top of existing stacks overriding the original cards/guns/records

Now, suppose that there's a second mod "Heavy Guns" which adds two new guns and redefines four guns from Fallout3 to be more "heavy". Suppose that of these four overridden guns, one conflicts with an override done by "Cool Guns" -- i.e. they both try to change the same gun.

Again, this is just like the card game. The two new guns form two new stacks, and the four redefined guns go on top of existing cards, overriding them. But in this case, one of those cards goes on top of the card added by Cool Guns -- thus overriding its changes as well as as original Fallout3.esm gun/card. Note in particular, that they changes are not merged. Each newly added card/record completely replaces the card/record under it.

Load Order

The card game above is why load order is important. Load order determines the order in which mods lay their cards down on the table. Fallout3 goes first, then the next mod in load order, up to the last mod. Whenever two mods conflict, the later loading mod will win.

So the following load rules exist:

• ESM plugins always load before non-ESM plugins
• Plugins listed in a masterlist of another plugin always load before said plugin
• ESM plugins always load before non-ESM plugins. Then within each groups, files are ordered by modified date

In case there are no conflicts between multiple plugins editing the same record in different ways that need attention, load order will not matter. If there are conflicts, the best way to compare changes is to use xEdit (With some exceptions such as scripts, navmeshing, worldspace/cell edits)

Summary

Remember the the game engine is effectively playing a game of stacked cards. And when you create a mod, you're simply creating a hand of cards that will be played in that game. From that ending table, with its various stacks of cards, arises the gameworld that the player enters and lives in.

ONAM Records

ONAM data is a list of overridden CELL, LAND, NAVM and REFR/ACHR records in ESM.

The difference between ESM and ESP is that in ESP all records are loaded into memory (they all are treated as persistent), but ESM loads only persistent records and records from ONAM. If LAND is modified in ESM but it is not in ONAM list, it is not loaded by the game.

xEdit generates proper ONAM list when plugin with ESM flag in TES4 header is saved.