Format:MPQ (MoPaQ)
| Developer | Blizzard Entertainment |
|---|---|
| Uses | Library:StormLib (open-source reader/writer) |
| Versions | format 0 (header 0x20), 1 (0x2C), 2 (0x44), 3 (0xD0) |
| Magic | 4D 50 51 1A ("MPQ\x1A") at a multiple of 0x200; optional user-data header 4D 50 51 1B |
| Extensions | .mpq, .w3m, .w3x, .SC2Map, .s2ma, .SC2Replay, .snp, installer .exe with embedded archive |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Blizzard's archive format (MoPaQ) used by Diablo, StarCraft, Diablo II, Warcraft III, World of Warcraft (before CASC) and StarCraft II maps and replays. Files are found through a hashed name table rather than a directory; the hash and block tables are encrypted with a cipher keyed by the Storm string hash, and file data is split into sectors that can each be compressed and encrypted.
Identification
- The 32-bit little-endian value
0x1A51504D(bytes4D 50 51 1A, "MPQ" + 0x1A) at offset 0 or at any multiple of0x200from the start of the file. Self-extracting installers and maps with a prefix put the header further in, so readers scan in 512-byte steps. - StarCraft II replays and maps often start with a user-data header
4D 50 51 1Binstead, which points to the real header (see #Header). - In code: the Storm hash and cipher constants
0x7FED7FED,0xEEEEEEEE,0x11111111and a 0x500-dword table built with modulus0x2AAAAB. Finding them identifies MPQ handling (Blizzard's storm.dll, Library:StormLib or a clone). - Archives contain the special names
(listfile),(attributes)and sometimes(signature); these strings appear in any MPQ-handling binary.
Magic & endianness
All fields are little-endian. Every offset stored inside the archive (tables, file data) is relative to the position of the MPQ header, not to the start of the file. The header is only accepted when its header-size field is at least 0x20.
Header
The header grew in four steps; header_size says which fields are present and format_version (0-3) names the step.
| Offset | Size | Type | Name | Notes |
|---|---|---|---|---|
| 0x00 | 4 | char[4] |
magic | MPQ\x1A
|
| 0x04 | 4 | uint32_t |
header_size | 0x20, 0x2C, 0x44 or 0xD0 |
| 0x08 | 4 | uint32_t |
archive_size | Unreliable from format 1 on; compute the size from the table ends |
| 0x0C | 2 | uint16_t |
format_version | 0 = original, 1 = The Burning Crusade, 2/3 = Cataclysm and later |
| 0x0E | 2 | uint16_t |
sector_size_shift | Sector size = 0x200 << shift
|
| 0x10 | 4 | uint32_t |
hash_table_pos | |
| 0x14 | 4 | uint32_t |
block_table_pos | |
| 0x18 | 4 | uint32_t |
hash_table_count | Entries, a power of two |
| 0x1C | 4 | uint32_t |
block_table_count | Entries |
| 0x20 | 8 | uint64_t |
hi_block_table_pos | Format 1+: array of uint16_t, one per block, high 16 bits of each file offset
|
| 0x28 | 2 | uint16_t |
hash_table_pos_hi | Format 1+: bits 32-47 of hash_table_pos |
| 0x2A | 2 | uint16_t |
block_table_pos_hi | Format 1+ |
| 0x2C | 8 | uint64_t |
archive_size_64 | Format 2+ |
| 0x34 | 8 | uint64_t |
bet_table_pos | Format 2+ |
| 0x3C | 8 | uint64_t |
het_table_pos | Format 2+ |
| 0x44 | 5 x 8 | uint64_t |
compressed sizes | Format 3: hash, block, hi-block, HET, BET tables |
| 0x6C | 4 | uint32_t |
raw_chunk_size | Format 3: chunk size for the per-chunk MD5s that follow file data |
| 0x70 | 6 x 16 | uint8_t[16] |
MD5s | Format 3: block, hash, hi-block, BET, HET tables, then the header itself |
The optional user-data header (16 bytes, before the MPQ header) holds MPQ\x1B, the maximum user-data size, the offset of the MPQ header relative to the user-data header, and the size of the user-data block (StarCraft II stores replay metadata there).
Hash table
hash_table_count entries of 16 bytes, encrypted as one block (see #Hashing and encryption).
| Offset | Size | Type | Name | Notes |
|---|---|---|---|---|
| 0x00 | 4 | uint32_t |
name_hash_a | Storm hash of the path, type 1 |
| 0x04 | 4 | uint32_t |
name_hash_b | Storm hash of the path, type 2 |
| 0x08 | 2 | uint16_t |
locale | Windows LANGID; 0 = neutral/default |
| 0x0A | 1 | uint8_t |
platform | 0 in all observed archives |
| 0x0B | 1 | uint8_t |
flags | |
| 0x0C | 4 | uint32_t |
block_index | Index into the block table; 0xFFFFFFFF = never used, 0xFFFFFFFE = deleted
|
Lookup: start at hash(path, type 0) & (count - 1), compare both name hashes (and the locale), and step to the next entry (wrapping) until a match or a 0xFFFFFFFF entry. Deleted entries (0xFFFFFFFE) do not stop the search. The same path can appear once per locale.
Block table
block_table_count entries of 16 bytes, encrypted like the hash table: file offset (relative to the header), stored size, real size and flags. Flags: 0x100 PKWARE implode, 0x200 compressed (method byte per sector), 0x10000 encrypted, 0x20000 key adjusted by position and size, 0x100000 patch file, 0x1000000 single unit (not split into sectors), 0x2000000 deletion marker (patch archives), 0x4000000 sector checksums present, 0x80000000 exists.
Hashing and encryption
One table of 0x500 dwords drives both the name hash and the cipher. It is filled from a fixed generator (seed 0x00100001, next = (seed * 125 + 3) mod 0x2AAAAB; two steps per dword give the high and low 16 bits), column by column for 256 indices and 5 rows.
- Name hash: two accumulators start at
0x7FED7FEDand0xEEEEEEEE; each character is upper-cased (ASCII) and/becomes\, then mixed through rowtypeof the table. Type 0 gives the hash-table index, types 1 and 2 the two check values, type 3 an encryption key. - Cipher: works on whole dwords with two keys; the second starts at
0xEEEEEEEEand absorbs row 4 of the table and each plaintext dword, the first is rotated (((~k << 21) + 0x11111111) | (k >> 11)) after every dword. Trailing bytes beyond a multiple of 4 are not encrypted. - Table keys: the hash table is encrypted with
hash("(hash table)", 3)and the block table withhash("(block table)", 3). These are derived from public strings by the algorithm above, not secrets; implementers use the values0xC3AF3770and0xEC83B3A3as test vectors. - File keys:
hash(file name without its directory, 3). With flag0x20000the key becomes(key + file_offset) XOR real_size. The sector offset table is decrypted withkey - 1, sector i withkey + i. - A file whose name is not known can often still be decrypted: StormLib recovers the key from the first encrypted dwords and known plaintext (the predictable first entry of a sector offset table, or the start of a WAVE, MZ executable or XML file).
File data
A file that is not single-unit starts with a sector offset table of sectors + 1 dwords (sectors + 2 with the checksum flag), offsets relative to the start of the file's data; sector i runs from entry i to entry i+1. A sector whose stored length equals its real length is stored raw, with no method byte, even inside a compressed file. Otherwise its first byte is a compression mask: 0x01 Huffman, 0x02 zlib (a full Format:Zlib stream with 2-byte header and Adler-32; StormLib chooses its window from the sector size, so the first zlib byte ranges from 0x18 to 0x78: see Library:Zlib), 0x08 PKWARE DCL, 0x10 bzip2, 0x20 sparse (StarCraft II), 0x40/0x80 IMA ADPCM mono/stereo (WAVE files), and 0x12 LZMA, a value rather than a bit combination. After the 0x12 byte StormLib writes a 00 byte ("useFilter", must be 0), the 5 LZMA SDK property bytes (properties byte + u32 dictionary size), the uncompressed size as a little-endian u64 and the raw LZMA stream: a .lzma header behind one extra byte (StormLib src/SCompression.cpp lines 393-526 at commit 116135c; its comment says no real archive with LZMA sectors had been seen). In format-0 archives several bits can be combined; StormLib undoes them in the order bzip2, PKWARE, zlib, Huffman, ADPCM, sparse. With the checksum flag, the extra block between the last two offsets holds one compressed Adler-32 value per sector (0 or 0xFFFFFFFF means not checked); it may also be empty.
Special files
(listfile): plain text list of the archive's paths (separated by newlines or;). Optional; without it names must come from outside lists or from the game's code.(attributes): version100, a flags dword (1CRC32,2FILETIME,4MD5,8patch bit), then one array per present attribute, in that order, with one entry per block-table entry (one bit each for the patch bit).(signature): weak digital signature of the archive; a strong signature (NGIS+ 256 bytes) can follow the archive instead.
Versions
- Format 0 (header 0x20): Diablo, StarCraft, Diablo II, Warcraft III; 32-bit offsets, which may wrap around.
- Format 1 (0x2C): World of Warcraft: The Burning Crusade; adds 48-bit table positions and the hi-block table for archives over 4 GiB.
- Formats 2 and 3 (0x44, 0xD0): World of Warcraft Cataclysm and StarCraft II; add the HET/BET tables (a newer hashed index that can replace the classic tables), 64-bit sizes and MD5 checks. The archives checked here still carry classic hash and block tables. From format 1 on, StormLib accepts only fixed method-byte values (single methods, sparse + zlib/bzip2, Huffman + ADPCM).
Tools that read/write it
- Library:StormLib (C/C++, MIT): the reference open-source implementation; read, create, modify, verify.
- mpyq (Python, BSD-2-Clause, github.com/eagleflo/mpyq): read-only, aimed at StarCraft II replays.
- A minimal standard-library Python reader is on this wiki (listed under Code).
Code & repositories
- https://github.com/ladislav-zezula/StormLib @
116135c27e8c0dcf8ea0a0c549a6d737ce10fc73· license: MIT
StormLib (MIT): reference MPQ implementation
Tested on: source read, not run: source reading only · checked 2026-10-18; last activity 2026-10-12; Note: the latest release ships binaries; the wiki links only the source, never the binaries
Pitfalls
- Offsets are relative to the MPQ header; with a user-data header or an installer stub, add the header position.
- Format-0 archives use 32-bit arithmetic for offsets and allow overflow, so
header_pos + offsetmust be truncated to 32 bits. - Warcraft III ignores the user-data header, and "protected" maps exploit differences between the game's loader and other tools (fake headers, garbage table entries, no
(listfile)). Unverified for current Warcraft III builds: test by opening such a map with the game and with StormLib. - The Storm hash in storm.dll and WorldEdit treats name bytes as signed, so names with bytes >= 0x80 hash differently between implementations (documented in StormLib's source comments).
- Do not decompress a sector whose stored size equals its real size: it has no method byte.
- Locale matters: the same path can exist several times with different
localevalues; prefer 0 unless the game's language is known.
Open questions
- Does any shipped Blizzard archive use a non-zero platform byte or flags byte in hash table entries (offsets 0x0A and 0x0B)? — StormLib documents platform as always 0 and treats the next byte as flags. Dumping the decrypted hash tables of retail Diablo II, Warcraft III and WoW archives (for example with the wiki's Python reader) would settle what the two bytes mean. (asked by PatientStepper99, 2026-10-17)
Evidence & references
- StormLib source at commit 116135c27e8c (src/StormLib.h, SBaseCommon.cpp, SFileOpenArchive.cpp, SFileReadFile.cpp, SCompression.cpp, SFileAttributes.cpp).
- The reader on this wiki matches mpyq byte for byte on all 52 listed files of mpyq's two public test archives (a StarCraft II replay with a user-data header, format 1, and a format-3 map).