Content File Guidelines

This page details the idiosyncrasies of dealing with Morrowind's two content file types: .esm and .esp. Most of this information was written by Rot.

Developers starting out with the Construction Set will only directly edit .esp files, but will still need to load .esm files, rearrange load orders, and clean plugins. Senior developers will additionally benefit from knowing how to merge claims either with each other or into master files.

ESP and ESM Basics

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 Tamriel Rebuilt's and Project Tamriel's playable content (e.g., TR_Mainland) and corresponding in-development main and section files use the .esm format; while individual claim files use the .esp one.

• File with .esm extension: master file
• File with .esp extension: plugin file

Note: Previously, Project Tamriel and Tamriel Rebuilt kept their in-development main files as .esp, too. However, we are now trialling the merge-to-master workflow, wherein in-development main and section files are .esm, instead.

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 Construction Set treat the files.

Load Order

If two content files edit the same reference, the latest one in the load order overrides the former one. Likewise, if a plugin references an object added in another plugin or master file, the latter will have the loaded before the former.

• 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: Currently, load order is explicit or, by default, alphabetical per data directory. Master files aren't loaded before all plugins on principle, but are loaded before plugins that depend on them. When restarting the launcher, all unticked plugins will be sorted alphabetically, again.
  • Note: There have been talks on adding simple topological sorting of master files and remembering the order of unloaded files, but these improvements are not yet implemented in OpenMW.

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 vanilla Construction Set 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 have not been manually selected. This issue is fixed by CSSE.

The game and the Construction Set will give a warning if the master file is different from the one that was recorded as parent (see below in "Parenting").

Editing

Plugins can be edited with the Construction Set or with various other tools, like tes3cmd, Esp-QuickEditor, Wrye Mash, TESAME, and many others.

Converting a plugin into a .json file using tes3conv additionally allows you to use the innumerable JSON-handling programs to make batch changes. You will need to be really careful about what and how you modify – the guide for this is currently out of scope for this page. However, many new tools being developed to modify Morrowind content files rely on .json files produced by tes3conv.

Master files cannot be set as "Active file" in the Construction Set, so the Construction Set will only directly edit plugin files. To edit a master file in the Construction Set, turn it into .esp with Wrye Mash or tes3cmd, edit it, then turn it back into .esm. However, consider instead making your changes in a dependent .esp file and using the Merge to Master process – this will preserve compatibility with other plugins editing the same master (see "Plugins Modifying Masters" below).

Parenting

When a plugin file is saved in the Construction Set, 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 Construction Set 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 Construction Set will give a warning: "One or more plugins could not find the correct versions of the master files they depend on." That is because some of the things a plugin can do do not work correctly if the parent master file is not 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 should not 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 cannot:

• edit, move or delete the instances of another plugin (.esp).

The above rules-of-thumb also apply to .esm files, not just to .esp files.

The rules-of-thumb come with exceptions:

• A plugin actually defines a whole new object with the same ID and overwrites the first plugin's definition, when it "edits the objects of another plugin (.esp)." In other words, it cannot modify some aspects of the object and leave the rest unmodified; it can only define and overwrite the whole object (CELL records are the only partial exception, since new instances can be added to existing instances, but the CELL's properties will always be overwritten).
  • Note: This also means that the second plugin is technically independent from the first plugin it "modifies" and can be used without it, as the new definition does not refer to any records from the first plugin. However, it can refer to records from the first plugin, without redefining them itself: for instance if the first plugin contained object records for TR_ImperialSkirt clothes and a TR_ImperialGuard NPC, the second plugin can modify/redefine the TR_ImperialGuard record and add TR_ImperialSkirt to its inventory, without containing a definition of TR_ImperialSkirt. This second plugin will only work correctly if the first pugin is loaded before it. If it's loaded in the Construction Set without the first plugin, or with the first plugin loaded after it with a newer date, the Construction Set will give an error message about the missing object (assuming you haven't skipped all warnings yet) and will remove it from the guard's inventory.

• Any file can technically "edit, move or delete the instances of another plugin (.esp)" if that plugin is treated as a parent master, which the Construction Set itself does not let you do. Instead, one has to turn the parent into an .esm before using it in the Construction Set, then edit the name of the master to .esp in the dependency list of the final plugin using another editor. Even so, that plugin is subjected to the below caveats as other plugins modifying masters when it changes.

Plugins Modifying Masters

As explained above, a plugin cannot edit, move or delete instances of another file unless that file is its parent master. There is another caveat if the master file has been modified, depending on how the modification was made:

1. If the parent .esm was modified by turning it into an .esp, modifying it in the Construction Set, then turning it back into an .esm, any plugin that edits its instances will need to be updated, otherwise the edits will not happen or happen to the wrong instances. Wrye Mash will do the requisite updates when you edit masters automatically. The updating process is reliable for cells that have not been modified between new versions of the master; cells that have had objects removed in the master between versions remain to be tested.
2. If the parent .esm file has been modified only by using the Merge to Master option in the Construction Set, the plugin should still work, as long as the prior merged plugins did not change the specific instances that your new plugin refers to.

The first option above breaks reliant plugins because the Construction Set assigns new Object indexes to all instances in an .esp file every time you save the file. To understand what that means, you need to know that to edit a master's (.esm file's) instance, the CELL instance subrecord in your .esp file needs the correct Master index and Object index. In the below example, a guard in Tamriel Rebuilt 1807's .esm release was moved and the modification was saved as a plugin (.esp file). Below are the plugin's contents dumped with tes3cmd. Note the two bolded values, and the position of the master:

Record: TES3 "()" Flags:0x0000 ()
  HEDR:   Version:1.3  Is_Master:False  Author:""
  Description:""
  N_Records:1
*MAST: Master:Morrowind.esm
  DATA: Length:79837557
*MAST: Master:Tribunal.esm
  DATA: Length:4565686
*MAST: Master:Bloodmoon.esm
  DATA: Length:9631798
*MAST: Master:Tamriel_Data.esm
  DATA: Length:7344508
*MAST: Master:TR_Mainland.esm
  DATA: Length:110297847

Record: CELL "gorne (40, -30)" Flags:0x0000 ()
  NAME: Name:Gorne
  DATA: (Exterior) Coordinates: (40, -30)  Flags:0x0006 (Has_Water, Illegal_To_Sleep_Here)
  RGNN: Region:Nedothril Region
*FRMR: ObjIdx:34155  MastIdx:5
  NAME: Name:TR_ind_guard
  DATA: X:335775.313  Y:-239378.016  Z:627.054  X_Angle:0.0000  Y_Angle:0.0000  Z_Angle:3.1000

The Master index specifies which of the masters is modified, using its number in the masters list. TR_Mainland.esm is the 5th master in this file's parents list.

• Note: when loading this plugin in the Construction Set, TR_Mainland must be the 5th master file that is loaded. If an additional master, like a patch for vanilla bugs, is loaded with a date between the Tamriel_Data and TR_Mainland files, the plugin will fail to apply the correct instance modification in the Construction Set. There is no such issue if masters are loaded in a different order in the game, only in the Construction Set.

The Object index specifies which instance is modified. For this guard in TR_Mainland.esm version 1807, the index is 34155.

A dump of the Gorne record in TR_Mainland.esm version 1807 shows you the guard has the correct index value:

Record: CELL "gorne (40, -30)" Flags:0x0000 ()
  NAME: Name:Gorne
  DATA: (Exterior) Coordinates: (40, -30)  Flags:0x0006 (Has_Water, Illegal_To_Sleep_Here)
  RGNN: Region:Nedothril Region
 *FRMR: ObjIdx:34155  MastIdx:0
  NAME: Name:TR_ind_guard
  DATA: X:335734.313  Y:-239223.234  Z:627.054  X_Angle:0.0000  Y_Angle:0.0000  Z_Angle:0.0000

Now look at the same dump from TR_Mainland.esm version 1709, an earlier version of the master file. The index value was not the same:

Record: CELL "gorne (40, -30)" Flags:0x0000 ()
   NAME: Name:Gorne
   DATA: (Exterior) Coordinates: (40, -30)  Flags:0x0006 (Has_Water, Illegal_To_Sleep_Here)
   RGNN: Region:Nedothril Region
  *FRMR: ObjIdx:29510  MastIdx:0
   NAME: Name:TR_ind_guard
   DATA: X:335734.313  Y:-239223.234  Z:627.054  X_Angle:0.0000  Y_Angle:0.0000  Z_Angle:0.0000

This is because in earlier Tamriel Rebuilt development, the main release files used to be updated using the first option above – i.e., the in-development master file was kept as an .esp, modified in the Construction Set and saved, then turned into an .esm only for public releases. Every time TR_Mainland.esp was modified, the Object indexes were randomly reassigned, meaning that all plugins made to modify TR_Mainland records now referred to the wrong Object indexes.

Wrye Mash is able to automatically update index values, and that is why it was needed when updating masters. Without updating the index, the instance that will be moved when loading the plugin with the version 1709 .esm would not be the guard, but instead an instance of flora_tree_ai_02 which happens to use that index value. If the plugin was instead made with the version 1709 .esm in the Construction Set, then loaded with the version 1807 .esm, the index would find no object to move, because there does not happen to be any with the index 29510.

This issue should largely be defunct, now that TR_Mainland, Sky_Main, and PC_Main are kept as .esm files, and plugins modifying these files should largely work across different versions (except for instances that are explicitly changed between different versions of the master files).

Merging

The Construction set provides two main ways of merging the game modifications from different content files into one file, both detailed below. In addition, other Morrowind content file modifying programs may offer additional ways.

Merging Plugins

• 

  The relevant Construction Set menu item.

• 

  You will need to temporarily convert .esp files that you do not want to merge into .esm files using Wrye Mash.

• 

  The load order when merging a claim .esp into Tamriel Rebuilt's Lake Andaram section file. Notice how the newly created temporary TR_Update.esm is loaded instead of the TR_Update.esp that you would get from the release files tracker.

• 

  Untick the temporary .esm files from the newly created merged plugin, then click Save. Here, the TR_Mainland.esm dependency is removed (back when our main project files were maintained as .esp files).

This process is used to merge two plugins (.esp files) together, for example when merging a claim into a section file. In previous years, it was also used for merging section files and claims into project main files (e.g., TR_Mainland, Sky_Main), but this is no longer done.

In order to merge plugins, simply load all the files needed for the claim that you want to merge in the Construction Set, then go to the File menu, and select Combine Loaded Plugins.

However, note that this will merge all loaded .esp files! This means that in most cases, when you are merging claim .esp files to .esp section files, you will need to do more steps to ensure that only the files you intend to merge are merged:

1. Convert all .esp files in your load order that you do not want to merge into .esm files. For this, use Wrye Mash: right-click on the respective .esp and select Copy to Esm. Most often, you will have to do this to the project main file update .esp (i.e., TR_Update.esp, which acts as the update file to TR_Mainland.esm).
2. Load your plugins in the Construction Set in the normal order, but replace the relevant .esp file(s) that you do not want to merge with the .esm file(s) you just created.
3. Click on File->Combine Loaded Plugins and name the new merged plugin file.
4. Remove the merged plugin's dependencies on the newly-created temporary .esm files. For that, go to Wrye Mash again, select the newly created merged plugin, deselect the relevant parent masters from the lower-right-hand-side list, and click Save.

The merged plugin file will now contain all records from the .esp files that were loaded while merging.

Note: If you are working on the project main file update .esp (i.e. TR_Update.esp), then you can ignore the above caveat, since you do want to merge the update .esp itself.

Merge to Master

This is the new, preferred workflow for merging claims and section files into the in-development main files, which will eventually be released to players.

The primary advantage of this approach is that object indexes of older content do not change in the process, so that dependent third-party mods do not break (previously, when in-development TR_Mainland or Sky_Main were still .esp files, every public update would break every dependent mod due to the CS assigning new random indexes each time an .esp is saved; see above in the "Plugins Modifying Masters" section). Another advantage is that plugin files can directly remove or edit references in master files, meaning that "Merge notes", i.e. claim-related work needing to be done directly in TR_Mainland.esp/.esm, are no longer needed for many claims.

To merge an .esp into an .esm, you need to enable the Merge to Masters button in the Construction Set. This is a straightforward Morrowind.ini file tweak (you can find this file in your main Morrowind install directory). Once enabled, the button can be found in the Data Files pop-up window of the Construction Set.

WhoCanMerge

The Merge to Masters button located between Set as Active File and Details...

Open Morrowind.ini and find [WhoCanMerge]. If this is not present in the file, add it to a new line. This section defines a list of Windows users who can use the Construciton Set to merge to master. The syntax for each line is username=1 where username is the name of the Windows user who can merge. So if your username is "EE", the section would look as follows:

[WhoCanMerge]
EE=1

Merge Button

Open the Data Files menu and check the .esm you want to merge into, its master files, and the .esp you want to merge into it, just as you would if you wanted to load them for regular editing/viewing. Note that the .esp to be merged should be set as the active file. Proceed to click the Merge to Masters button. You will be shown a file selection menu. Select the .esm you want to merge into and press Save. Your .esp should now be part of your .esm. Be aware that doing this overwrites your original .esm and deletes your .esp. Making a backup of both prior to merging is advisable.

Cleaning

Cleaning a content file refers to the process of pruning accidental or "junk" edits from the files. Files containing such edits are called "dirty." Cleaning your plugins is supremely important in avoiding hard-to-troubleshoot errors and ensuring mod compatibility. All developers who work in the Construction Set must be familiar with this process.

Any of three programs are typically used for cleaning plugins: TESAME, tes3cmd, or Esp-QuickEditor (refer to the prior links on how to use these programs for cleaning a plugin). A few things (mainly dialogue) are also best to clean directly in the Construction Set.

Object definitions

If you create an instance of an object that comes from another plugin (.esp), the Construction Set will automatically dirty (overwrite the definition of) the object in your plugin. This does not happen if the object was defined in a master (.esm). Note that these dirty objects from plugins will not be detected by tes3cmd. tes3cmd will clean dirty edits from a plugin only if the original records are found in its parent masters.

Exterior Cells

It is especially important to clean dirty exterior cells, because they can cause missing landscape in adjacent cells. Dirty cells include anything outside the bounds of your claim or mod.

TESAME is relatively inconvenient to use for cleaning dirty exterior edits, since TESAME does not display cell coordinates. It is much easier to use tes3cmd or Esp-QuickEditor. Alternatively, you can name every cell in your claim while it is in development so as to recognize which ones to keep in TESAME.

Aside from accidental edits by the Construction Set user, there are also some common junk cells. These are cells that the Construction Set will automatically dirty from the exteriors of loaded files, either when merging plugins or randomly(?) when editing or even viewing exteriors. For these, it is convenient to use tes3cmd:

• Junk cells from vanilla master files or TR_Mainland.esm will be detected automatically by tes3cmd.
  • Note: The highly recommended Construction Set Extender will automatically delete the known junk cells from vanilla .esm files in your plugin.
• Junk cells from dependent .esp files won't be detected, so you will have to look for empty cells and delete them yourself. You can find empty cells in tes3cmd with the below script:

tes3cmd dump --exterior --no-match "FRMR" MyPlugin.esp > MyPluginEmptyCells.txt

Dialogue

How marking "edge cases" in the Construction Set will allow you to more easily identify them in the TESAME later, and clean them out.

In the Construction Set, whenever you insert dialogue entries next to ones not from your plugin, the entries above and below are dirtied. This is indicated by an asterik (*), though one does not immediately appear on the entry above. These two "edge cases" should always be cleaned. To track them down easily, you can edit the response to say something like "CLEAN ME", as shown in the image to the side.

When cleaning dialogue with TESAME, do not delete dialogue entries you added yourself if they have neighboring entries you also added. The remaining entries may lose their order or fall to the bottom of the topic by referencing the deleted entry. The best practice is to only remove Info/Responce records that originate from a master file or dependency and use the Construction Set for your own dialogue.

Construction Set Tip: Jump to the first edited line in the dialogue list by typing an asterisk. Follow it with a space and additional letters to search your edited lines.