# Diablo II Item Bitstream Specification (.d2s / D2Common)

> **Gold Standard Reference**: `D2Common!6FD77180` (Packing / Serialization) and `D2Common!6FD592C4` (Unpacking / Deserialization).  
> **Target Version**: Diablo II 1.10 / 1.13c Lord of Destruction character save (`.d2s`) item list.

---

## 1. Overview and Architecture

Diablo II stores item data inside character save files (`.d2s`), network packets, and memory structures as a **variable-length, bit-aligned stream**. Unlike byte-aligned structures, fields in the item stream are packed tightly with arbitrary bit widths (e.g. 1 bit, 3 bits, 7 bits, 9 bits, 11 bits, 12 bits) without byte padding between fields.

### 1.1 Bitstream Conventions
- **Byte and Bit Ordering**: Little-endian bitstream. Bits are read from lowest to highest within each byte (LSB first: bit 0 of byte 0, bit 1 of byte 0, ..., bit 7 of byte 0, bit 0 of byte 1, etc.).
- **String Encoding**:
  - Item base code (4 bytes / 32 bits): 4 ASCII characters right-padded with ASCII spaces (`0x20`), stored in byte order.
  - Personalized and Ear names: Null-terminated strings using 7-bit ASCII characters (`0x00` terminator is 7 zero bits).
- **Two Major Modes**:
  1. **Simple / Compact Item**: Items with the `Simple` flag (bit 11) set (potions, scrolls, gold, gems, runes, keys, simple quest items). Serialization terminates immediately after the item base code and socket count.
  2. **Extended Item**: Items with the `Simple` flag cleared (weapons, armor, jewelry, charms, complex items). Includes full fingerprint, ilvl, quality branch, defense/durability, sockets, and stat list blocks.

---

## 2. Complete Bitstream Layout

The table below outlines the sequential bitstream order executed by `D2Common!6FD592C4` (unpack) and `D2Common!6FD77180` (pack):

| Bit Offset (Rel) | Bit Width | Field Name | Type | Condition / Presence | Description |
|---|---|---|---|---|---|
| `0` | 16 | `magic` | ASCII | Always | `"JM"` header magic (`0x4A`, `0x4D`) |
| `16` | 32 | `dwFlags` | Bitmask | Always | Header flags (see §3 for bitmask breakdown) |
| `48` | 10 | `version` | uint | Always | Item format version (`0` or `101` for 1.10+) |
| `58` | 3 | `mode` | uint | Always | Location mode (0: Stored, 1: Equipped, 2: Belt, 3: Ground, 4: Cursor, 5: Dropping, 6: Socketed) |
| `61` | 32 or 15 | **Position Data** | Branch | Always | Dependent on `mode` (see §2.1 below) |
| — | 32 | `itemCode` | ASCII[4] | Always (except Ear) | 4 ASCII characters right-padded with space (e.g. `"swd "`, `"gld "`) |
| — | 3 | `socketedCount` | uint | Always (except Ear) | Number of gems/runes/jewels socketed inside this item (0..7) |
| *CUTOFF* | — | *Simple Item End* | — | `dwFlags.Simple == 1` | **If Simple Item flag is set, serialization STOPS here.** |
| — | 32 | `uniqueId` | uint32 | Extended item | Item GUID / seed (`dwInitSeed`, item fingerprint) |
| — | 7 | `ilvl` | uint | Extended item | Item level (0..127) |
| — | 4 | `quality` | uint | Extended item | Item quality tier (1..8, see §4) |
| — | 1 | `hasGraphic` | bool | Extended item | 1 if graphic variation index is present |
| — | 3 | `graphic` | uint | `hasGraphic == 1` | Graphic variant index (0..7) |
| — | 1 | `hasAutoAffix` | bool | Extended item | 1 if class auto-affix (Automagic) is present |
| — | 11 | `autoAffixId` | uint | `hasAutoAffix == 1` | Automagic affix ID (from `AutoMagic.txt`) |
| — | Variable | **Quality Data** | Branch | Extended item | Dependent on `quality` (see §4) |
| — | 16 | `runewordData` | uint | `dwFlags.Runeword == 1` | 12-bit Runeword ID (`Runes.txt`) + 4-bit parameter |
| — | Variable | `personalizedName`| String | `dwFlags.Personalized == 1`| 7-bit ASCII characters terminated by `0b0000000` (max 15 chars) |
| — | 5 | `tomeId` | uint | Code == `"ibk "` or `"tbk "` | Tome ID (5 bits) |
| — | 1 + 96 | `realmData` | Bytes | Extended item | 1 bit flag; if set, followed by 96 bits of realm data |
| — | 11 | `defense` | uint | Item kind is Armor | Current armor defense (value - 10 + `Armor.minac`) |
| — | 8 (+8) | `durability` | uint | Item has Durability | `maxDurability` (8 bits); if max > 0: `currentDurability` (8 bits) |
| — | 9 | `quantity` | uint | Item is Stackable | Current stack count (e.g. javelins, keys, arrows) |
| — | 4 | `totalSockets` | uint | `dwFlags.Socketed == 1` | Total number of sockets on the item (1..6) |
| — | Variable | **Set Bonuses** | Branch | `quality == 5` (Set) | 5 bits property list count; active set bonus stat lists (each terminated by `0x1FF`) |
| — | Variable | **Base Stat List** | StatList | Extended item | Stat modifier list (9-bit statId + params/values), terminated by `0x1FF` |
| — | Variable | **Runeword Stats** | StatList | `dwFlags.Runeword == 1` | Extra runeword stat list, terminated by `0x1FF` |

---

### 2.1 Positioning Branch (Offset 61)

The position encoding branches on `mode`:

1. **Ground / Dropping Mode (`mode == 3` or `mode == 5`)**:
   - `worldX`: 16 bits (World coordinate X)
   - `worldY`: 16 bits (World coordinate Y)
   - *Total*: 32 bits

2. **Equipped, Belt, Stored, Cursor, Socketed Mode (`mode != 3` and `mode != 5`)**:
   - `equippedSlot`: 4 bits (Equipped body slot index)
     - `0`: None
     - `1`: Head (Helm)
     - `2`: Neck (Amulet)
     - `3`: Torso (Armor)
     - `4`: Right Hand (Primary Weapon / Shield)
     - `5`: Left Hand (Secondary Weapon / Shield)
     - `6`: Right Finger (Ring)
     - `7`: Left Finger (Ring)
     - `8`: Waist (Belt)
     - `9`: Feet (Boots)
     - `10`: Hands (Gloves)
     - `11`: Alt Right Hand (Weapon swap)
     - `12`: Alt Left Hand (Weapon swap)
   - `gridX`: 4 bits (Inventory column `0..9`, Belt column `0..3`)
   - `gridY`: 4 bits (Inventory row `0..9`, Belt row `0..3`)
   - `storagePage`: 3 bits:
     - `0`: Inventory
     - `1`: Equipped (Body)
     - `2`: Belt
     - `4`: Horadric Cube
     - `5`: Stash
   - *Total*: 15 bits

---

## 3. Header Flags Bitmask (`dwFlags`, 32 bits)

The 32-bit integer at bit offset 16 controls item state and conditional decoding:

| Bit | Hex Value | Name | Description |
|---|---|---|---|
| `0` | `0x00000001` | `Identified` | `1` = Item is identified; `0` = Unidentified |
| `1` | `0x00000002` | `Unk1` | Reserved / unused |
| `2` | `0x00000004` | `Unk2` | Reserved / unused |
| `3` | `0x00000008` | `Socketed` | `1` = Item has sockets (and socket count field present) |
| `4` | `0x00000010` | `NewItem` | `1` = Item picked up or generated since game start |
| `5` | `0x00000020` | `Unk5` | Reserved / unused |
| `6` | `0x00000040` | `Unk6` | Reserved / unused |
| `7` | `0x00000080` | `IsEar` | `1` = Item is a player Ear |
| `8` | `0x00000100` | `StarterItem` | `1` = Starter / beginner equipment (e.g. cracked sash) |
| `9` | `0x00000200` | `Unk9` | Reserved / unused |
| `10` | `0x00000400` | `Unk10` | Reserved / unused |
| `11` | `0x00000800` | `Simple` | `1` = Compact item (stops after socketed count); `0` = Extended item |
| `12` | `0x00001000` | `Ethereal` | `1` = Ethereal (cannot be repaired, translucent art, stat bonus) |
| `13` | `0x00002000` | `Any` | Internal personalization / save flag |
| `14` | `0x00004000` | `Personalized` | `1` = Personalized name present (Anya quest reward) |
| `15` | `0x00008000` | `Gamble` | Gambling item flag |
| `16` | `0x00010000` | `Runeword` | `1` = Active Runeword (runeword data and stats present) |
| `17..31` | `0xFFFE0000` | `Reserved` | Engine and server internal flags |

---

## 4. Quality Field and Branches (4 bits)

The 4-bit `quality` field dictates the affix and identity layout:

| Value | Quality Tier | Encoded Fields |
|---|---|---|
| `1` | **Low Quality** | `qualitySubtype` (3 bits: `0` crude, `1` cracked, `2` damaged, `3` low quality) |
| `2` | **Normal** | None (standard base item) |
| `3` | **Superior** | `superiorSubtype` (3 bits: attack rating, defense, durability, etc.) |
| `4` | **Magic** | `prefixId` (11 bits, `MagicPrefix.txt`), `suffixId` (11 bits, `MagicSuffix.txt`) |
| `5` | **Set** | `setId` (12 bits, index into `SetItems.txt`) |
| `6` | **Rare** | `rareName1` (8 bits), `rareName2` (8 bits), followed by 6 affix slots (each 1 bit present + 11-bit id) |
| `7` | **Unique** | `uniqueId` (12 bits, index into `UniqueItems.txt`) |
| `8` | **Crafted** | `rareName1` (8 bits), `rareName2` (8 bits), followed by 6 affix slots (each 1 bit present + 11-bit id) |
| `9` | **Tempered** | Rare-style affix structure (expansion prototype remnant) |

### 4.1 Rare & Crafted Affix Slots (6 Slots)
Rare (6) and Crafted (8) items carry exactly 6 affix slots. For each slot `i = 0..5`:
1. Read `present` (1 bit).
2. If `present == 1`: read `affixId` (11 bits, index into `MagicPrefix.txt` or `MagicSuffix.txt`).
3. If `present == 0`: move to next slot.

---

## 5. Stat Lists and `ItemStatCost.txt` Bit Alignment

Diablo II encodes magical bonuses and base stats as an open-ended list of properties, terminated by the 9-bit sentinel `0x1FF` (decimal `511`).

### 5.1 Stat Entry Encoding Loop
1. Read `statId` (9 bits).
2. If `statId == 0x1FF`: **End of Stat List**.
3. Lookup `statId` in `ItemStatCost.txt`:
   - `CSvParam` / `Save Param Bits`: If non-zero, read `param` (`CSvParam` bits). Used for skill ID, character class ID, elemental masteries, or charges.
   - `CSvBits` / `Save Bits`: Read unsigned integer of length `CSvBits`.
   - `CSvSigned`: Indicates signed or unsigned interpretation.
   - `Save Add`: Value offset. `finalValue = rawValue - SaveAdd`.
4. Store `{ statId, statName, param, value }` in item's stat list.
5. Repeat from Step 1.

### 5.2 Multiple Stat Blocks
Extended items can contain multiple stat list blocks in sequence:
- **Base Stats Block**: Always present on extended items; ends with `0x1FF`.
- **Set Item Bonuses**: For Set items, 5 bits indicate bonus properties; each active set bonus tier has its own stat list ending with `0x1FF`.
- **Runeword Bonuses**: For Runewords (`dwFlags.Runeword == 1`), a dedicated runeword bonus stat list follows, ending with `0x1FF`.

---

## 6. Player Ear Items (`dwFlags.IsEar == 1`)

If bit 7 of `dwFlags` is set:
- Item code is `"ear "`.
- Followed by:
  - `classIndex`: 3 bits (0: Amazon, 1: Sorceress, 2: Necromancer, 3: Paladin, 4: Barbarian, 5: Druid, 6: Assassin).
  - `level`: 7 bits (Player level at time of death).
  - `playerName`: 7-bit ASCII characters terminated by `0b0000000`.
- Ear decoding terminates here; no extended stats or durability are encoded.

---

## 7. Lossless Round-Trip and Preservation Guarantee

To ensure perfect interoperability between this engine, official Diablo II binaries, and third-party save editors (e.g. Hero Editor, Gomule):

1. **`rawFlags: number`**: The raw 32-bit flags integer is preserved verbatim so unknown, reserved, or engine-specific flag bits are never stripped or shifted.
2. **`unknownBits?: Uint8Array`**: Any trailing padding bits, vendor/realm payloads, or unparsed bitstream extensions are retained alongside the structured fields.
3. **Deterministic Serialization**: When re-packing to bitstream via `D2Common!6FD77180`, fields are written back in the identical sequence and bit alignments specified in this document.