Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:MPQ (MoPaQ)

From ReverseEngineering.wiki
Format
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 (bytes 4D 50 51 1A, "MPQ" + 0x1A) at offset 0 or at any multiple of 0x200 from 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 1B instead, which points to the real header (see #Header).
  • In code: the Storm hash and cipher constants 0x7FED7FED, 0xEEEEEEEE, 0x11111111 and a 0x500-dword table built with modulus 0x2AAAAB. 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 0x7FED7FED and 0xEEEEEEEE; each character is upper-cased (ASCII) and / becomes \, then mixed through row type of 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 0xEEEEEEEE and 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 with hash("(block table)", 3). These are derived from public strings by the algorithm above, not secrets; implementers use the values 0xC3AF3770 and 0xEC83B3A3 as test vectors.
  • File keys: hash(file name without its directory, 3). With flag 0x20000 the key becomes (key + file_offset) XOR real_size. The sector offset table is decrypted with key - 1, sector i with key + 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): version 100, a flags dword (1 CRC32, 2 FILETIME, 4 MD5, 8 patch 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 + offset must 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 locale values; 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).