Tes4Mod:Save File Format/REFR

A REFR Change Record (change record type 49) describes changes to the objects placed in cells (REFR mod file records).  Although it is the most common type of change record, the complexity of the record format has made it impossible, so far, to fully predict the locations of all subrecords, let alone understand the subrecord contents.  It seems likely that to properly process a REFR change record, it is first necessary to read the original information for the record.  In other words, the exact details of which records appear may be controlled not only by data provided in the save file, but also by information from the Oblivion.esm (or other relevant .esm files). Nevertheless, it is possible to fairly reliably scan the entire REFR record, and it is also possible to reliably extract the data likely to be of most interest.

The REFR change record shares many similarities with the even more complicated ACRE and ACHR change records.

Names of Subrecords
The first difficulty in interpreting a REFR change record is that the record's overall Flags do not provide a simple guide to the record's contents.  The following table lists the name assigned to each flag value (using the names providing in text file dumps).  It also summarizes what subrecord(s) may appear when that flag is set:
"Standard subrecord" means that a single subrecord appears in a fixed location whenever the corresponding byte is set.
In many cases, the data appears in the Properties structure.  This structure has its own system of flags which are used to identify the specific properties contained in the structure.  These properties can appear in any order within the structure, and the properties that appear are only loosely related to the record's overall Flags.
In other cases, the data may appear in the Miscellaneous section.  The contents of the Miscellaneous section are not fully understood: they appear to all be optional, for unknown reasons.
Yellow rows are ones that are also found (with the same meaning) in ACHR and ACRE change records.

Summary information about the location and size of the associated subrecords is listed in the next section.



Locations of Subrecords
This table summarizes the best current understanding of what data appears in a REFR change record, in what order, and when.
Yellow rows are ones that are also found (with the same meaning) in ACHR and ACRE change records.



 

 

 

Properties
A properties section appears in a REFR change record only if one or more of the following bytes are set in the record's overall Flags:
5, 6, 7, 10, 20, 21, 24, 25, 26, 28
Within this section, the individual properties can appear in any order -- each property is preceded by a flag identifying its contents.  The full list of possible property flags and the format associated with each flag is documented on a separate Properties article.

Miscellaneous
This section of the record is not yet properly understood.  It does not always appear; when present, it can contain one or more subrecords, each of variable length.  All of the subrecords in this section follow the same format, and the meaning of the data within the subrecords is unknown, making it very difficult to differentiate between the subrecords.  Given that the contents of the Miscellaneous section are so uncertain, the easiest way to handle it is to simply skip past the section.

Data that is known to appear in this section (based on the subrecord sizes in text dump files) include:
Animation (byte 24)
Movement Extra (byte 25)
Havok Moved (byte 3)
Other subrecords that are believed to appear in this section are:
Had Havok Move Flag (byte 11)
Empty Flag (byte 16)
Furniture Markers (22)
Door Default State (18)
However, these additional subrecords are always empty (contain 2 0x00 bytes), or are subrecords that only appear in records identified as NOT LOADED in the text dump savefiles, and whose data length is therefore unknown.  This prevents a size-based analysis of the subrecords' presence and relative location.

Within the section are a series of subrecords, all with the following format:


The number of such sections to appear in a Miscellaneous section is difficult to  predict. Existing theories (discussed below) work in some cases, but overpredict the number of subrecords in other cases.  What can be more reliably deduced from the record's overall flags is where the miscellaneous section ends, essentially by working backwards from the end of the REFR change record.  Specifically:
If byte 4 (Scale) is not set, the section ends at the end of the REFR change record.
If byte 4 is set, the section ends 4 bytes before the end of the REFR change record.

The most reliable way to process the Miscellaneous Section is:
# Determine the end of the section
# Read subrecords until the end of the section is reached

In cases analyzed to date, 0 to 3 subrecords have been found in the Miscellaneous Section.  The best guess at the order to use when assigning those subrecords is:
# Movement Extra (if byte 24 is set)
# Animation (if byte 25 is set)
# Havok Moved (if byte 3 is set)
# Had Havok Move Flag (if byte 11 is set)
# Empty Flag (if byte 16 is set)
# Furniture Markers (if byte 22 is set)
# Door Default State (if byte 18 is set)

Presumably, Bethesda's algorithm for processing records does not require first calculating where the section ends.  However, a pattern identifying which subrecords will appear has not yet been identified.  For example, if both bytes 24 and 25 are set, sometimes only one subrecord appears in the Miscellaneous Section; other times, two subrecords are clearly present.

The following sections summarize some of the statistics used to reach the previous conclusions.  The most important tool used in determining the subrecords present in the Miscellaneous Section is the sizes listed for loaded records in text file dumps.  However, those sizes cannot be used to differentiate between two-byte subrecords; there are clearly inaccuracies in the listed sizes; and, Had Havok Move Flag subrecords never appear in loaded records.  Therefore, in many cases, the analysis comes down to whether the entries in the Miscellaneous Section are two-byte entries (0x00,0x00) or multi-byte entries (more than two bytes in size).  Several of the subrecords are assumed to be at most two bytes in size (namely, Empty Flag, Furniture Markers, and Door Default State), and therefore cannot be paired up with multi-byte entrie.

Movement Extra
The Movement Extra subrecord may be present in the Miscellaneous Section when byte 24 (0x01000000) is set in a REFR change record's overall Flags.  This data is in addition to any that may appear in the Properties section, under property 0x4b.  The meaning of the Movement Extra data is unknown.

In loaded records listed in text file dumps, sizes ranging from 15 to 5137 are reported for the Movement Extra subrecord.  After deleting the size of any data found in the Properties section, the remaining sizes range from 2 to 5096 bytes.  When seen in loaded records, the remaining size of the Movement Extra subrecord always matches the size of the first entry in the Miscellaneous Section.

Animation
The Animation subrecord may be present in the Miscellaneous Section when byte 25 (0x02000000) is set in a REFR change record's overall Flags.  This data is in addition to any that may appear in the Properties section, under property 0x4a.  The meaning of the Animation data is unknown.

In loaded records listed in text file dumps, sizes ranging from 4 to 179 are reported for the Animation subrecord.  After deleting the size of any data found in the Properties section, the remaining sizes range from 2 to 179 bytes (the property entries were 6-14 bytes in size, and were always the only Animation data present in the change record).

Havok Moved
The Havok Moved subrecord may be present in the Miscellaneous Section when byte 3 (0x00000008) is set in a REFR change record's overall Flags.  This data is in addition to any that may appear in place of the Moved subrecord.  The meaning of the Havok Moved data is unknown.

In loaded records listed in text file dumps, sizes ranging from 2 to 33 are reported for the Havok Moved subrecord.  After deleting the size of any data found earlier in the subrecord, and deleting any superfluous data (the total of the text file dump sizes is frequently 28 bytes too large when the Havok Moved subrecord is present), the remaining sizes range from 2 to 5 bytes.  However, in NOT LOADED records, larger sizes are frequently inferred; also, in ACHR/ACRE change records, where the Havok Moved subrecord seems better-behaved, its size can also be much larger than 5 bytes.

Had Havok Move Flag
The Had Havok Move Flag subrecord may be present in the Miscellaneous Section when byte 11 (0x00000800) is set in a REFR change record's overall Flags.  This subrecord is only seen in unloaded records in text file dumps, so no information is available about its expected size.  It is also never seen in records with the Havok Moved subrecord.

However, it seems likely that the Had Havok Move Flag can have data sizes of more than 2 bytes.  Overall, the inferred sizes for the Had Havok Move Flag subrecord are very similar to those for the Havok Moved subrecord -- suggesting that the Had Havok Move Flag essentially inherits the Havok Moved data.  In other words, this flag may indicate that the Havok Moved data is all obsolete and needs to be purged from the record the next time the record is loaded, but in the meantime the data is still there and needs to be taken into account when processing the record's data.  

Empty Flag
The Empty Flag subrecord may be present in the Miscellaneous Section when byte 16 (0x00010000) is set in a REFR change record's overall Flags.  The flag is always seen for REFR records whose base object is a plant (FLOR record), so it is possible this flag keeps track of whether or not a plant has been harvested (i.e., has been emptied of ingredients).

In loaded records listed in text file dumps, the size of the Empty Flag subrecord is always listed as two bytes, and therefore it has been assumed that the Empty Flag subrecord is never more than two bytes in size.  However, the resulting conclusion is that the relative position of the Empty Flag data varies depending upon which set of subrecords are present.  Specifically:
In several combinations, Empty Flag (16) comes after the Havok subrecords (3, 11).  Namely: 25-11-16, 25-3-16
In other combinations, the Empty Flag must come before the Havok subrecords.  Namely: 16-11, 16-3
The size statistics for more complex combinations are inconclusive (no multi-byte records could be associated with any of 3, 11, or 16).

Furniture Markers
The Furniture Markers subrecord may be present in the Miscellaneous Section when byte 22 (0x00400000) is set in a REFR change record's overall Flags.  The meaning of the flag is unknown.

In loaded records listed in text file dumps, the size of the Furniture Markers subrecord is always listed as two bytes.  In cases where Furniture Markers is the only possible subrecord in the Miscellaneous Section, the Miscellaneous Section almost always contains a single 2-byte entry -- confirming that the Furniture Markers subrecord does appear in this section.  However, when seen in combination with other Miscellaneous subrecords, the Miscellaneous Section often contains only multi-byte entries -- so presumably the Furniture Markers subrecord is frequently dropped.  Therefore, the Furniture Markers subrecord appears near the end of the list of possible subrecords.

Door Default State
The Door Default State subrecord may be present in the Miscellaneous Section when byte 18 (0x00040000) is set in a REFR change record's overall Flags -- although it seems more likely that in fact no data is added when this byte is set.  As described in more detail under Door State, this subrecord appears related to the use of the   command.

In loaded records listed in text file dumps, the size of the Door Default State subrecord is always listed as two bytes.  However, it seems likely that no data is actually added to the REFR change record.  The sum of the subrecord sizes is always larger than the total record size by two (or more) bytes when byte 18 is set.  Furthermore, byte 18 has only been seen simultaneously with bytes 24 and 25; in all such cases, only one 2-byte (0x00,0x00) entry is present in the Miscellaneous Section.  There is no way to definitively identify the correct subrecord for this entry, but byte 24 seems the most probable (there are 4 missing bytes for byte 24, plus byte 24 is known to have data in the Miscellaneous Section).

Scale
The Scale subrecord is present when byte 4 (0x00000010) is set in an ACHR/ACRE/REFR change record's overall Flags. Its length is a constant 4 bytes, and provides the size of this particular object relative to the standard object size.

In a REFR change record, Scale is always located at the end of the subrecord.

Note that there is also a Scale property (property flag 0x37), but the property is only found in Inventories, not in REFR property sections.



Dropped Item Flag
"Dropped Item Flag" is true when byte 17 (0x00020000) is set in a REFR record's overall Flags.  No subrecords or data are added to the record when this flag is set.



Door State
"Door State" is true when byte 19 (0x00080000) is set in a REFR record's overall Flags.  No subrecords or data are added to the record when this flag is set.

Note that there is also a "Door Default State" subrecord (triggered by byte 18) that appears in the Miscellaneous section.  In one test using the console, both bytes 18 and 19 were set when the command   was run; however, neither byte was set when the command   was run.  However, this test involved REFRs to STAT records, not REFRs to DOOR records, so it might not be representative.