Oblivion Mod:Save File Format/Inventory

This page summarizes the Inventory subrecord, which is common to ACHR, ACRE, and REFR change records. The page is designed to be included in those pages, but the information has been collected in one place to ensure that future updates are added to all appropriate places.

Inventory

The Inventory subrecord is present when byte 27 (0x08000000) is set in an ACHR/ACRE/REFR change record's overall Flags. Its length is variable. The parameters controlling its length are well-understood but complex: it consists of a specified number (itemNum) of entries, each of which is documented by a structure of variable length. You need to decode the entire Inventory subrecord in order to determine the total size of the subrecord. The subrecord details the items that the character, creature or containers (drawers, chests, etc.) currently possess -- and those that are no longer possessed.

Because this is a change record, the inventory lists changes relative to that specified in the ESM/ESP files, both additions and substractions. For example: at the start of the game, your character receives "royal jewelry" a.k.a. wrist irons. If you never drop or sell them they are not listed in your character's Inventory subrecord, because you are still carrying them. On the other hand, if you do drop the wrist irons, then they are listed in the Inventory, with stackedItemsNum=-1. Therefore, if you want get a complete list of the inventory contents, you need to read first the listing provided by the ESM and ESP files. Then you can read the save file's contents and add or remove items, yielding the inventory's final list.

A minimal inventory item entry provides the item's iref (ulong), item count (StackedItemsNum, ulong), and count of extra information (changedEntriesNum, ulong). If changedEntriesNum is 0, then no further data is provided for that item -- the total size of that item's entry is 12 bytes. However, many items include extra information, documenting changes to the item's properties (e.g., whether the item is equipped by the player, the item's health, the available charge of an enchanted weapon, etc.). The structure and data length for this extra information depends upon the number and type of the changed properties.

The extra information count, changedEntriesNum, does not list the number of changed properties, but rather the number of sets of changed properties. Each set of changed properties (each changedEntries structure) applies to one subset of the item stack. Multiple changedEntries information sets are provided if a stack of multiple items contains items with a range of properties; conversely, an inventory entry documenting a single item will only have one changedEntries set. For example, if the player is carrying 12 Iron Longswords (base health 140), 1 of which is equipped and damaged to 10% health and 4 of which have been repaired to 125% health (leaving 7 "unchanged" swords at 100% health), the inventory listing will consist of:

• iref (4 bytes; value differs for every save game)
• stackedItemsNum=12 (4 bytes)
• changedEntriesNum=2 (4 bytes)
• The first changedEntries set, describing the equipped but damaged sword (8 bytes total):
  • propertiesNum=2 (2 bytes)
    • itemHealth property: flag=0x2b; value=14.0 (5 bytes total)
    • equipped property: flag=0x1b; value=empty (1 byte total)
• The second changedEntries set, describing the 4 expert-improved swords (10 bytes total):
  • propertiesNum=2 (2 bytes)
    • itemHealth property: flag=0x2b, value=175.0 (5 bytes total)
    • affectedItemsNum propery: flag=0x2a, value=4 (3 bytes total)

(Note that in earlier documentation of the inventory record, the structure and meaning of this extra information was inaccurate; the earlier documentation would only work for relatively simple sets of changed properties).

Name	Type/Size	Info
itemNum	ushort	Number of items in inventory.
item	struct[itemNum]	Items in characters inventory.
iref	ulong	Points to the FormId's location in the FormIdArray (unless iref>0xFF000000, in which case it is the FormId of an item in the createdData array).
stackedItemsNum	ulong	Number of items added to (or removed from) stack by the change record.
changedEntriesNum	ulong	Number of entries listing changed properties (e.g. equipped, used, damaged etc) If changedEntriesNum is 0, this is the end of the item's data
changedEntries	struct[changedEntriesNum]	Each listing in changedEntries is a collection of properties describing one or more of the items in the stack. If the properties apply to more than one item, then one of the properties entries will be affectedItemsNum; conversely, if affectedItemsNum does not appear, then the properties describe only one item. Since these are changed properties, any properties that are not specified have default values.
propertiesNum	short	Number of properties changed for this subset of items
property	struct[propertiesNum]	Structure detailing an individual property change.
Flag	byte	Changed property indicator. The properties page documents all known values for this flag.
-Value	different	Changed property value, The type of value and its length depends upon the flag; see properties. (Value is not present for flags with zero-length values)