Skyrim Mod:Mod File Format

Mod files (Plugin files) are collections of records, which are further divided into fields.

Records generally correspond to objects (e.g., a creature, a game setting, a dialog entry), with the fine details of the object (e.g., health of a creature, a dialog entry test) being handled by the fields of the record. Records themselves are organized into groups.

At the highest grouping level, a plugin file is generally:

• A single TES4 record (plugin information).
• A collection of top groups.

Mod Plugin Types

Mod files take the form of a plugin file in one of the three below formats:

• Elder Scrolls Master (ESM, .esm)
• Elder Scrolls Plugin (ESP, .esp)
• Elder Scrolls Light Master (ESL, .esl)

Elder Scrolls Master and Elder Scrolls Plugin files are similar to each other, except for the difference in that ESMs are pinned to the top of the load order, taking precedence over all non-flagged ESP and ESL plugin files. Elder Scrolls Light Master plugins are unique in that they do not conform to the load order specification of either ESM or ESP plugins, and as such, up to 4096 ESL plugins can exist in the load order, rather than the maximum of 254 plugins when only non-flagged ESM and ESP plugin files are used. The primary limitation of ESL plugins are that they only allow up to 4096 Form ID records whereas ESM and ESP plugins have a significantly higher record limit. Since v1.6.1130, ESL plugins can hold up to 4096 records. Before, the form ID range 0x0000 to range 0x07FF was reserved, resulting in a 2048 record limit.

ESL plugins were introduced with the addition of Creation Club content known as Creations in update 1.5 of the Special Edition, and are therefore only available for use starting from this update and future updates and versions, including the Anniversary Edition. Due to this, they will not load or be detected in either the Legendary Edition or earlier versions of the Special Edition prior to update 1.5.

ESM and ESP plugins can be flagged as an ESL if the maximum number of records in the plugin conforms to the 4096 form ID limit and that their form ID records are compacted prior to the flagging of them as an ESL. They can additionally be given the ESM flag to pin them to the top of the load order, similar to the default behaviour of non-flagged ESM files.

The position in the load order depends on the file extension (.esm, .esl, or .esp), so what is functionally an ESL file can be given an ESP extension to allow placing them towards the bottom of the load order.

Note that ESP files (which are not flagged as ESL) have a special behavior in which all references they contain are treated as permanent, even if they are temporary references. This means that these references are always loaded and actively processed, regardless of which cells they are in, and they always count towards the maximum reference cap in the engine. For this reason, plain ESP files should be avoided and mods should preferably be released as ESL (or ESL-flagged ESP) if possible, or ESM otherwise.

Record Types

Type Data Object AACT Action ACHR Actor Reference ACTI Activator ADDN Addon Node ALCH Potion AMMO Ammo ANIO Animation Object APPA Apparatus (probably unused) ARMA Armor Addon (Model) ARMO Armor ARTO Art Object ASPC Acoustic Space ASTP Association Type AVIF Actor Values/Perk Tree Graphics BOOK Book BPTD Body Part Data CAMS Camera Shot CELL Cell CLAS Class CLFM Color CLMT Climate COBJ Constructible Object (recipes) COLL Collision Layer CONT Container CPTH Camera Path CSTY Combat Style DEBR Debris DIAL Dialog Topic DLBR Dialog Branch DLVW Dialog View DOBJ Default Object Manager

Type Data Object DOOR Door DUAL Dual Cast Data (possibly unused) ECZN Encounter Zone EFSH Effect Shader ENCH Enchantment EQUP Equip Slot (flag-type values) EXPL Explosion EYES Eyes FACT Faction FLOR Flora FLST Form List (non-leveled list) FSTP Footstep FSTS Footstep Set FURN Furniture GLOB Global Variable GMST Game Setting GRAS Grass GRUP Form Group HAZD Hazard HDPT Head Part IDLE Idle Animation IDLM Idle Marker IMAD Image Space Modifier IMGS Image Space INFO Dialog Topic Info INGR Ingredient IPCT Impact Data IPDS Impact Data Set KEYM Key KYWD Keyword LAND Landscape

Type Data Object LCRT Location Reference Type LCTN Location LGTM Lighting Template LIGH Light LSCR Load Screen LTEX Land Texture LVLI Leveled Item LVLN Leveled Actor LVSP Leveled Spell MATO Material Object MATT Material Type MESG Message MGEF Magic Effect MISC Misc. Object MOVT Movement Type MSTT Movable Static MUSC Music Type MUST Music Track NAVI Navigation (master data) NAVM NavMesh NOTE Note NPC_ Actor (NPC, Creature) OTFT Outfit PACK AI Package PERK Perk PGRE Placed grenade PHZD Placed hazard PROJ Projectile QUST Quest RACE Race / Creature type REFR Object Reference

Type Data Object REGN Region (Audio/Weather) RELA Relationship REVB Reverb Parameters RFCT Visual Effect SCEN Scene SCRL Scroll SHOU Shout SLGM Soul Gem SMBN Story Manager Branch Node SMEN Story Manager Event Node SMQN Story Manager Quest Node SNCT Sound Category SNDR Sound Reference SOPM Sound Output Model SOUN Sound SPEL Spell SPGD Shader Particle Geometry STAT Static TACT Talking Activator TES4 Plugin info / Header TREE Tree TXST Texture Set VTYP Voice Type WATR Water Type WEAP Weapon WOOP Word Of Power WRLD Worldspace WTHR Weather

Groups

GRUPs are collections of records, and are used to improve scanning of files to make it easier to skip over records that the reading program is not interested in. In addition to this, subgroups for WRLD and CELLS provide some useful structural information (e.g., the division of cell data into persistent and non-persistent references).

File Format

Type/Size	Info
char[4]	Record type (always "GRUP")
uint32	Size of the entire group, including the group header (24 bytes). This is in contrast to records and fields, whose sizes do not include their header sizes.
uint8[4]	Label. Format depends on group type (see next field). In the CK Details view, you can mark a group as ignored, but the CK ignores this setting and reads the group anyway. The ignore flag interferes with what should ordinarily be in the label field (e.g., "HAIR" becomes "HQIR"). This mislabeling has no effect on record loading. In short, the label field of a group is not reliable. If you subsequently save, the group will be written without the ignore markings.
int32	Group type: Type Info Label Type Description 0 Top (Type) char[4] Record type 1 World Children formid Parent (WRLD) 2 Interior Cell Block int32 Block number 3 Interior Cell Sub-Block int32 Sub-block number 4 Exterior Cell Block int16[2] Grid Y, X (Note the reverse order) 5 Exterior Cell Sub-Block int16[2] Grid Y, X (Note the reverse order) 6 Cell Children formid Parent (CELL) 7 Topic Children formid Parent (DIAL) 8 Cell Persistent Childen formid Parent (CELL) 9 Cell Temporary Children formid Parent (CELL)
uint16	Timestamp Skyrim: The low byte is the day of the month and the high byte is a combined value representing the month number and last digit of the year times 12. That value is offset, however, so the range is nominally 13-132, representing dates from January 20x4 through December 20x3. Lower values can be seen in Skyrim.esm, likely corresponding to older records held over from Oblivion where values of 1-12 represented 2003 (see the Oblivion version of this page for specifics). To derive the correct values, use the following formulae, where Y is the single-digit year, M is the month number, and HB is the high byte of the value: Y = ((HB - 1) / 12 + 3) MOD 10 M = ((HB - 1) MOD 12) + 1 HB = (((Y - 4) MOD 10) + 1) * 12 + M Skyrim SE: Bits are used to represent each part, with a two-digit year: 0bYYYYYYYMMMMDDDDD. Thus, January 25, 2021 would be (spaces added for clarity): 0b 0010101 0001 11001 or 0x2A39.
uint16	Version Control Info The low byte is the user id that last had the form checked out. The high byte is the user id (if any) that currently has the form checked out.
uint32	Unknown. The values stored here are significantly different than those used in records and appear to be a 32-bit value rather than two 16-bit values. Values break out by group type: All top-level groups have a 0 here, with the exception of CELL, which can have a 1 in some add-ons. Topic children have single-byte values or 0xCCCCCCCC. Interior cells have a value of either 0 or 0xCCCCCCCC. Some add-ons have a value of 1. Other cell/world-related groups have a wide array of small to large values that are not Form IDs. Again, 0xCCCCCCCC is a possible value.
uint8[groupSize-24]	Records and subgroups.

Top Groups

In Skyrim.esm, the top, or highest level groups are stored in the following order:

GMST, KYWD, LCRT, AACT, TXST, GLOB, CLAS, FACT, HDPT, HAIR, EYES, RACE, SOUN, ASPC, MGEF, SCPT, LTEX, ENCH, SPEL, SCRL, ACTI, TACT, ARMO, BOOK, CONT, DOOR, INGR, LIGH, MISC, APPA, STAT, SCOL, MSTT, PWAT, GRAS, TREE, CLDC, FLOR, FURN, WEAP, AMMO, NPC_, LVLN, KEYM, ALCH, IDLM, COBJ, PROJ, HAZD, SLGM, LVLI, WTHR, CLMT, SPGD, RFCT, REGN, NAVI, CELL, WRLD, DIAL, QUST, IDLE, PACK, CSTY, LSCR, LVSP, ANIO, WATR, EFSH, EXPL, DEBR, IMGS, IMAD, FLST, PERK, BPTD, ADDN, AVIF, CAMS, CPTH, VTYP, MATT, IPCT, IPDS, ARMA, ECZN, LCTN, MESG, RGDL, DOBJ, LGTM, MUSC, FSTP, FSTS, SMBN, SMQN, SMEN, DLBR, MUST, DLVW, WOOP, SHOU, EQUP, RELA, SCEN, ASTP, OTFT, ARTO, MATO, MOVT, HAZD, SNDR, DUAL, SNCT, SOPM, COLL, CLFM, REVB

Whether the game engine expects this order is unknown, but it's probably safer to use this order than not.

All top groups contain records matching their label (e.g., the GMST top group contains GMST records). For most top groups, only the matching record types are present. However, in the CELL, WRLD and DIAL top groups, each main record can be followed by one or more child groups which contain additional records of a different type. Unlike Oblivion, WRLD groups in Skyrim no longer contain ROAD records.

Notes:

• 6 record types have a GRUP but no records: CLDC, HAIR, RGDL, SCPT, SCOL, PWAT.
• There are 2 HAZD groups, the second one has no records.

Dawnguard The following had field order changes and updates. Also pre-existing or new records were added.

• LCTN, INFO, NPC_, RACE, NAVI, QUST, REFR, WRLD

New Fields:

• LCTN added: ACID, ACSR, ACUN, ACEC, ACEP, RCPR
• NAVI added: NVSI
• REFR added: XATR

Subgroups

The following groups are only found in subgroups of other records:

REFR, ACHR, NAVM, PGRE, PHZD, LAND, INFO

Records

Type/Size	Info
char[4]	Type
uint32	Size of data field
uint32	Flags Flag Meaning 0x00000001 (TES4) Master (ESM) file 0x00000010 Deleted Group (bugged, see Groups) 0x00000020 Deleted Record 0x00000040 (GLOB) Constant (REFR) Hidden From Local Map (Needs Confirmation: Related to shields) 0x00000080 (TES4) Localized - this will make Skyrim load the .STRINGS, .DLSTRINGS, and .ILSTRINGS files associated with the mod. If this flag is not set, lstrings are treated as zstrings. 0x00000100 Must Update Anims (REFR) Inaccessible 0x00000200 (TES4) Light Master (ESL) File. Data File (REFR) Hidden from local map (ACHR) Starts dead (REFR) MotionBlurCastsShadows 0x00000400 Quest item Persistent reference (LSCR) Displays in Main Menu 0x00000800 Initially disabled 0x00001000 Ignored 0x00008000 Visible when distant 0x00010000 (ACTI) Random Animation Start 0x00020000 (ACTI) Dangerous Off limits (Interior cell) Dangerous Can't be set without Ignore Object Interaction 0x00040000 Data is compressed 0x00080000 Can't wait 0x00100000 (ACTI) Ignore Object Interaction Ignore Object Interaction Sets Dangerous Automatically 0x00800000 Is Marker 0x02000000 (ACTI) Obstacle (REFR) No AI Acquire 0x04000000 NavMesh Gen - Filter 0x08000000 NavMesh Gen - Bounding Box 0x10000000 (FURN) Must Exit to Talk (REFR) Reflected By Auto Water 0x20000000 (FURN/IDLM) Child Can Use (REFR) Don't Havok Settle 0x40000000 NavMesh Gen - Ground (REFR) NoRespawn 0x80000000 (REFR) MultiBound
uint32	Record (form) identifier
uint16	Timestamp (see the same field in Groups)
uint16	Version Control Info (see the same field in Groups)
uint16	The internal version of the record. This can be used to distinguish certain records that have different field layouts or sizes.
uint16	Unknown. Values range between 0-15.
uint8[dataSize]	Data For uncompressed records, this is a sequence of fields. Compressed data is the same, except that the fields are compressed using ZLIB, and stored into the data field like so... Type/Size Info uint32 Size of decompressed data uint8[dataSize-4] Compressed collection of fields

Fields

Type/Size	Info
char[4]	Field type.
uint16	Size of data field. †
uint8[dataSize]	Data. Format depends on record and field type.

^†If the preceding field has the type XXXX, then dataSize will be 0 and the size of the data is in fact the 32 bit quantity stored in the XXXX field. This feature is commonly used to store large navmesh fields in Skyrim.esm.

Commonly used fields and their definitions can be found here. Many records allow for object bounds (OBND) and scripting (VMAD) fields, but ignore them. It's unclear why. Only those records to which they actually apply will have these fields listed.

See Also

• Raw Data: a dump of all records/fields in Skyrim.esm and their associated counts/sizes.
• Raw Function Data: a dump of all script/console functions and events in TESV.exe.