About

ceres-mpq is a pure-Rust implementation of a reader/writer for Blizzard's proprietary MoPaQ (MPQ) archive format.

The intended use-case for this library is to be used for reading and writing Warcraft III map files, which in themselves are MPQ archives. Since Warcraft III only uses Version 1 of the format, no effort is made here to support newer features found in MPQ files in other games.

For more details and the list of supported/unsupported features, please refer to the top-level library documentation.

Command-line

There is a command-line utility for reading, viewing, and writing MPQ files, which you can find here: ceres-mpqtool

lib.rs:

A library for reading and writing Blizzard's proprietary MoPaQ archive format.

Currently, ceres-mpq only supports reading and writing Version 1 MoPaQ archives, as this is the only version of the format still actively encountered in the wild, used by Warcraft III custom maps.

For this reason, no effort was made to support features found in newer versions of the format, though this may change in the future if there is a need for this.

ceres-mpq provides no support to edit existing archives yet, thought it may in the future.

Supported features

Not the whole range of MPQ features is supported yet for reading archives. Notably:

• IMA ADPCM compression is unsupported. This is usually present on .wav files.
• Huffman coding compression is unsupported. This is usually present on .wav files.
• PKWare DCL compression is unsupported. However, I haven't seen any WC3 maps that use it.
• Single-unit files are unsupported.
• Checksums and file attributes are not checked or read.

Additionally, for writing archives:

• You cannot choose which compression type to use for added files in Creator. DEFLATE is used by default.

Protected MPQs

In Warcraft III, it is not uncommon to encounter so-called "protected maps" which use various obfuscations and hacks that are designed in such a manner that they can be read by WC3's built-in MPQ implementation, but will trip up other implementations.

No effort is made to work around those "protections" in ceres-mpq. In particular, ceres-mpq is likely to fail when trying to read a protected MPQ which has explicitly subverted the MPQ archive structure in some manner.

If you need a library with good support for reading protected maps, please refer to StormLib.

Example

let buf: Vec<u8> = Vec::new();
let mut cursor = Cursor::new(buf);

// creating an archive
let mut creator = Creator::default();
creator.add_file("hello.txt", "hello world!",
    FileOptions {
        encrypt: false,
        compress: true,
        adjust_key: false
    }
);
creator.write(&mut cursor)?;

cursor.seek(SeekFrom::Start(0))?;

// reading an archive
let mut archive = Archive::open(&mut cursor)?;
let file = archive.read_file("hello.txt")?;

assert_eq!(file.as_slice(), b"hello world!");