Diablo II items, etc · d2itemreader

File Structures

Diablo II items, etc Diablo II Save Files (.d2s) PlugY Save Files (.sss/.d2x) ATMA Stash Files (.d2x)

Item List Data Format

Byte Offset	Size (bytes)	Description
0x00	2	Header. Must be `"JM"` (`0x4D4A` when read as a 16 bit unsigned integer).
0x02	2	Number of items in the list as a 16 bit unsigned integer. Note: This number only counts 'root' items, i.e. it does not include items that have been inserted into the sockets of the 'root' items. That is, an item list with 1 item that has 2 socketed items inside it will have a value of 1 in this field, even though the full data will have 3 items in it. In other words, the items in the sockets should be considered part of the item that they're contained in.
0x04	...	Beginning of contiguous Item data

Item Data Format

Byte/Bit Order

Bytes are saved as little-endian (least significant byte first). However, when reading bit fields, bits should be interpretted from 'left-to-right', or least-significant-bit to most-significant-bit (i.e. the reverse of how bytes are typically represented) while also acounting for the fact that bits can span across byte boundaries.

The following is a diagram attempting to illustrate how the item code bits should be interpretted. The bytes shown are those that contain the 32 bits used store an item's code (which starts at bit offset 76; every 8 bits contains an ASCII character).

Bit offset               ...   76    80    84    88    92    96   100   104   108  ...
Char boundaries           |    |-----1-----|-----2-----|-----3-----|-----4-----|    |
Bits in byte order         0010 1010   0001 0111   0001 0011   0000 0011   0000 0010
Bits in bit field order    0101 0100   1110 1000   1100 1000   1100 0000   0100 0000
Char bits in byte order         0111   0010 0011   0001 0011   0001 0010   0000
Hex vals of char bits               7 2         3 1         3 1         2 0
Char val of char bits               'r'         '1'         '1'         ' '

In C, the following macro can be used to read an arbitrary bit field as described above (code is originally from here):

#define read_bits(start,size) \
    ((*((unsigned long *) &data[(start) / 8]) >> ((start) & 7)) & ((1 << (size)) - 1))

And here's the adapted version that d2itemreader uses, which includes data as an argument and reads a uint64_t:

#define read_bits(data,start,size) \
    ((*((uint64_t*) &(data)[(start) / 8]) >> ((start) & 7)) & (((uint64_t)1 << (size)) - 1))

To test a bit field reader implementation, the following checks can be performed while using this file as the test data:

char c1 = (char)read_bits(data, 76, 8);
char c2 = (char)read_bits(data, 84, 8);
char c3 = (char)read_bits(data, 92, 8);
char c4 = (char)read_bits(data, 100, 8);
assert(c1 == 'r' && c2 == '1' && c3 == '1' && c4 == ' ');

Format

Bit Offset	Size (bits)	Description
0	16	Header. Must be `"JM"` (`0x4D4A` when read as a 16 bit unsigned integer).
16	4	Unknown
20	1	Item is identified (bool)
21	6	Unknown
27	1	Item is socketed (bool)
28	1	Unknown
29	1	Item is new (picked up since the last time the game was saved)
30	2	Unknown
32	1	Item is an ear (bool)
33	1	Item is a starting item (was given to the player at the time of character creation)
34	3	Unknown
37	1	Item is simple (only contains 111 bits of data)
38	1	Item is ethereal
39	1	Unknown
40	1	Item is personalized
41	1	Unknown
42	1	Item has been given a runeword
43	5	Unknown
48	8	Version of the item. See the `version` field of the `d2item` struct.
56	2	Unknown
58	3	Item location. See the `locationID` field of the `d2item` struct.
61	4	Item equipped location. See the `equippedID` field of the `d2item` struct.
65	4	Item position X coordinate
69	4	Item position Y coordinate
73	3	Panel containing the item. See the `panelID` field of the `d2item` struct.
76	...	If the item is an ear (bit offset 32), then see "Ear", otherwise skip to "Non-Ear"

Ear

Bit Offset	Size (bits)	Description
76	3	Class of the ear's former owner
79	7	Level of the ear's former owner
86	Varies	Name of the ear's former owner as a null-terminated string. Each character is 7 bits wide, up to a maximum of 15 characters.
-	...	After the terminating null character of the ear's player name, the item has been fully read and any remaining bits up to the next byte boundary will be padded with 0's.

Non-Ear

Bit Offset	Size (bits)	Description
76	32	Item code as 4 8-bit-wide characters, where a space character (0x20) should be treated as a null terminator. Note: Item codes can be 4 characters long.
108	3	The number of items socketed within this item
111	...	If this is a simple item (bit offset 37), then this item has been fully read and the remaining bits up to the next byte boundary are padded with 0's. Otherwise, see "Advanced"

Advanced

Bit Offset	Size (bits)	Description
111	32	Unique identifier. Typically interpretted as an unsigned 32 bit integer and displayed using the printf format string "%08X"
143	7	Item level
150	4	Item rarity ID. See the `rarity` field of the `d2item` struct

From here on out, bit offsets begin to vary depending on the values of the fields, so they will no longer be shown.

Size (bits)	Description
1	Item has multiple pictures
3	*Only exists when the item has multiple pictures* ID of the picture used for this item (out of the available pictures for the item type)
1	Item is class specific
11	*Only exists when the item is class specific* ID of the class-specific automagic affix the item has (see the `automagicID` field of the `d2item` struct)
3	*Only exists when the item's rarity is low quality* ID of the low quality type of the item (see the `lowQualityID` field of the `d2item` struct)
3	*Only exists when the item's rarity is superior/high quality* ID of the superior type of the item (see the `superiorID` field of the `d2item` struct)
11	*Only exists when the item's rarity is magic* ID of the prefix type of the item (see the `magicPrefix` field of the `d2item` struct)
11	*Only exists when the item's rarity is magic* ID of the suffix type of the item (see the `magicSuffix` field of the `d2item` struct)
12	*Only exists when the item's rarity is set* ID of the set type of the item (see the `setID` field of the `d2item` struct)
12	*Only exists when the item's rarity is unique* ID of the unique type of the item (see the `uniqueID` field of the `d2item` struct)
8	*Only exists when the item's rarity is rare or crafted* ID of the first name of the item (see the `nameID1` field of the `d2item` struct)
8	*Only exists when the item's rarity is rare or crafted* ID of the second name of the item (see the `nameID2` field of the `d2item` struct)
Varies	*Only exists when the item's rarity is rare or crafted* Rare/crafted affixes. Each affix has a 1-bit-wide field denoting whether or not an 11-bit-wide affix ID field follows (`hasAffix`). If `hasAffix` is 1, then an 11-bit-wide field containing the ID of the affix follows. Otherwise, another 1-bit-wide `hasAffix` field follows. There are a total of 6 of these affixes, where the affixes switch off between prefixes and suffixes, starting with prefix.
16	*Only exists when the item has a runeword given to it* 12-bit-wide field followed by 4 unknown bits. The 12-bit-wide field is some sort of index into Diablo II's localization string table that contains the name of the runeword of the item, used only for displaying the runeword name of the item. Note: this should not be used to determine what runeword an item is, and instead that should be determined by the order of the runes socketed in the item.
Varies	*Only exists when the item is personalized* The name of the character that personalized the item as a null-terminated string of 7-bit-wide characters.
5	*Only exists if the item is a tome (of identify or town portal)* Unknown Note: It is untested whether or not custom tomes would have this field or not
1	Unknown (denoted as 'timestamp' in various places)
11	*Only exists if the item is an armor (i.e. the item code is found in Armor.txt)* Defense of the armor. Subtract this value by 10 to get the true armor value (note: this -10 matches the "Save Add" column in ItemStatCost.txt for the armor stat).
8	*Only exists if the item is an armor or a weapon (i.e. the item code is found in Armor.txt or Weapons.txt)* Max durability of the item.
9	*Only exists if the item's max durability is greater than zero* The first 8 bits are the item's current durability. The last bit is unknown.
9	*Only exists if the item is stackable (i.e. the item code is found in Weapons.txt or Miscs.txt and the "stackable" column is 1)* Quantity of the item
4	*Only exists if the item is socketed* Total number of sockets in the item (both filled and/or unfilled)
5	*Only exists if the item's rarity is set* Set properties bit field, used later for reading the set property lists of the item
Varies	List of magical properties of the item. See Property Lists
Varies	*Only exists if the set properties bit field of the item is not zero* List of set property lists of the item. These properties are the green bonuses that get applied per-item, not the overall set bonuses. These property lists will exist even if the bonuses are not currently active. Repeat the following 5 times (once for each bit of the set properties bit field): Check that the property list exists by verifying that the bit of the set properties bit field cooresponding to this list is set. That is, if you are starting at index 0, then `bitfield & (1 << index)` needs to be 1. If the coorespoding bit is set, then read a Property List
Varies	*Only exists if the item has a runeword given to it* A property list containing the properties of the item that come from the runeword.
...	This item has been fully read and the remaining bits up to the next byte boundary are padded with 0's

Property Lists

TODO