ESM, ESP: understanding master files and plugin files

[This page is outdated! See instead this page on the Project Tamriel wiki: https://wiki.project-tamriel.com/wiki/Content_File_Guidelines]

  • What is it?
  • What's the difference?
  • Load order
  • Auto-loading
  • Editing
  • Merging
  • Parenting
  • Plugins modifying plugins
  • Plugins modifying masters
  • Cleaning
  • What does it mean for TR mods?
  • What does it mean for TR devs?


 
What is it?
Elder Scrolls Master (.esm) and Elder Scrolls Plugin (.esp) are the content file formats of Morrowind. The original game files are .esm files. Mods can be .esm or .esp files. Public releases of TR's playable content (TR_Mainland) use the esm format; internal versions of the file use the esp format.
File with .esm extension: master file
File with .esp extension: plugin file


What's the difference?
ESM and ESP files are identical except for a single byte in the header of the file. Wrye Mash and tes3cmd can instantly turn a master into a plugin, or the other way around.
The difference is how the game and the CS (Construction Set) treat the files.


Load order
Vanilla engine: Load order is defined by modified date and oldest files are loaded first, but master files are loaded before all plugin files.
*OpenMW: Load order is explicit or by default alphabetical, master files aren't loaded before all plugins on principle, but are loaded before plugins that depend on them.


Auto-loading
If a file is listed as a "Parent master" for a file that is being loaded, the game will load the parent master automatically, and fail if it isn't found. This is called a dependency.
The CS will also properly load at most four Parent masters automatically when loading a plugin (Morrowind.esm, Tribunal.esm, Bloodmoon.esm, +Tamriel_Data.esm will load on their own if a file has them for parents) but will fail to load with five or more masters if they haven't been manually selected.
The game and the CS will give a warning if the master file is different from the one that was recorded as parent. (see below in "Parenting")


Editing
Master files cannot be set as "Active file" in the CS, so the CS will only directly edit plugin files. To edit a master file in the CS, turn it into ESP with Wrye Mash or tes3cmd, edit it, then turn it back into ESM.


Merging
The CS can only merge all ESP plugins together, excluding masters. See [Tutorial] How to merge into section files


Parenting
When a plugin file is saved in the CS, any master file (ESM) that was loaded with it is added to its "Parent master" list. A plugin file (ESP) can be listed as a parent through other means, but the CS will remove this dependency when the active file is saved.
If the master dependency is not wanted, it can be removed in Wrye Mash by ticking off the square left of the parent's name and saving, or by using the Esp-QuickEditor.
The "Parent master" dependency list includes the parent file's size. If the size is different from what was recorded, the game or the CS will give a warning: "One or more plugins could not find the correct versions of the master files they depend on". That's because some of the things a plugin can do don't work correctly if the parent master file isn't the version it was made with (see below in "Plugins modifying masters"). The warning will always be given even if there are no issues. The dependency list can be updated to the current master file's size with Wrye Mash to remove this warning. Updating to a new version of Tamriel_Data, for example, usually shouldn't create issues for plugins that depend on it, and simply updating the dependency to remove the warning is fine.


Plugins modifying plugins
An object record is the definition of an object, for example the ID and properties of "Imperial Guard".
An instance record is a specific placement of an object in a CELL. For example, a specific guard in Seyda Neen is an instance of the "Imperial Guard" object.
As a rule of thumb*, a plugin ESP can:
- refer to and create instances of objects defined in its parent master (ESM) or in another plugin (ESP), as long as the plugin is loaded before it
- edit the objects of its parent master (ESM) or of another plugin (ESP)
- edit, move or delete the instances of its parent master (ESM)
But normally a plugin ESP can not: - edit, move or delete the instances of another plugin (ESP).

 


 
Plugins modifying masters
As explained above, a plugin can't edit, move or delete instances of another file unless that file is its parent master. It must also be the version of the parent master the plugin was made for. Every time a master file is updated (modified in the CS), any plugin that edits its instances will need to be updated, otherwise the edits will not happen or happen to the wrong instances. This is the process for updating plugins automatically with WryeMash. The updating process is reliable for cells that haven't been modified between new versions of the master; cells that have had objects removed in the master between versions? remain to be tested.
Expand for details:

 

 

 


 
Cleaning
If you create an instance of an object that comes from another plugin (ESP), the CS will automatically dirty (overwrite the definition of) the object in your plugin. This doesn't happen if the object was defined in a master (ESM).
Dirty objects from plugins won't be detected by tes3cmd. tes3cmd will clean dirty edits from a plugin only if the original records are found in its parent masters. The CS automatically dirties certain cells from the exteriors of loaded files, called "junk cells", when merging plugins or randomly(?) when editing exteriors. Junk cells from vanilla master files or TR_Mainland.esm will be detected automatically.

 
What does it mean for TR mods?
TR's public releases are ESM files for the playable area TR_Mainland. If you make a mod for TR_Mainland and edit/move/delete instances, the mod will only work for that version of the ESM, and you will need to update it (as explained above) with each new TR release or give users of your mod instructions to update it themselves.
If no instances are edited, the mod will still give a warning with future versions of the ESM unless the parent list is updated with Wrye Mash. Only adding objects to TR_Mainland cells will not create instance indexing issues with future versions of the ESM. Like when making mods for the base game, keep in mind that adding objects to a cell will overwrite the properties of the cell (for an interior: fog, light, sleep...; for an exterior, cell name can be overwritten too), so adding objects to TR_Preview.esp is more likely to create incompatibilities with later releases, since these areas are in active development.

What does it mean for TR devs?
Internal TR files for Mainland and sections are ESP plugins, so your claim files can change the definitions of objects or place new objects in existing cells, but they can't edit/move/delete existing instances (see "Plugins modifying plugins" above). If you need something removed from a cell, or to add ownership to an object, or want an existing door to be opened by a new key, add it to the list of things that need to be done when the claim is merged.
Cleaning: If you're placing objects from an internal Data add-on and that add-on is a plugin (ESP), the objects will probably be dirtied in your file.
Cleaning: For junk cells, if exterior files from plugins (the internal Mainland plugin or TR_Preview/section files) are loaded with your file, any junk cells from these plugins won't be detected automatically by current utilities. You'll have to look for empty cells and delete them yourself. You can find empty cells in tes3cmd with tes3cmd dump --exterior --no-match "FRMR" MyPlugin.esp > MyPluginEmptyCells.txt