Crate ceres_mpq

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!");

Structs

Archive	Implementation of a MoPaQ archive viewer.
Creator	Creator capable of creating MPQ Version 1 archives.
FileOptions	Represents various options that can be used when adding a file to an archive.

Enums

Error