wow-mpq-web

Read and write World of Warcraft MPQ archives in the browser and Node.js — WebAssembly bindings for the wow-mpq Rust crate. Everything happens in memory: bytes in (Uint8Array), bytes out. No filesystem access needed.

Getting the package

Install from npm (recommended for JS/TS):

npm install wow-mpq-web

Or download wow-mpq-web-<version>-web.tar.gz from the GitHub releases and unpack it (tar xzf ... creates ./pkg/), or build it yourself:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

cargo build --release -p wow-mpq-web --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir wrappers/wow-mpq-web/pkg \
  target/wasm32-unknown-unknown/release/wow_mpq_web.wasm

Usage

import init, { MpqArchive } from "wow-mpq-web";
// If you downloaded the tarball or built locally, use:
// import init, { MpqArchive } from "./pkg/wow_mpq_web.js";
await init();

// Reading: open an archive from a <input type="file">, fetch(), etc.
const archive = new MpqArchive(new Uint8Array(await file.arrayBuffer()));
console.log(archive.list());                    // [{name, size, compressedSize, flags, ...}, ...]
const data = archive.readFile("patch.m2");      // Uint8Array

// Writing: stage changes, then export a brand-new archive
archive.addFile("hello.txt", new TextEncoder().encode("hi"));
archive.removeFile("old-file.txt");
const modified = archive.export();              // Uint8Array — save/download it

// Creating from scratch
const fresh = MpqArchive.create(1);             // MPQ format version 1–4
console.log(fresh.fileCount());                 // 0

API

| Method | Description | | ------ | ----------- | | new MpqArchive(bytes) | Open an existing archive from its bytes | | MpqArchive.create(version?) | Create a new empty archive (format version 1–4, default 1) | | list() | Array of { name, size, compressed_size, flags, compressed, encrypted, single_unit, exists } | | readFile(name) | Uint8Array with the (decompressed) file contents | | addFile(name, bytes) | Stage a file for addition/replacement (applied on export()) | | removeFile(name) | Stage a file for removal (applied on export()) | | export() | Rebuild the archive with staged changes; returns Uint8Array | | fileCount() | Number of currently visible files |

Streaming / large-archive support

For multi-gigabyte archives (e.g. browsing an entire WoW Data folder from the File System Access API), loading the whole archive into a Uint8Array will run out of wasm memory. Use the streaming class instead:

import init, { MpqStreamingArchive } from "wow-mpq-web";
await init();

const file = await fileHandle.getFile();

function readRange(file, offset, length) {
  const reader = new FileReaderSync();
  const blob = file.slice(offset, offset + length);
  return new Uint8Array(reader.readAsArrayBuffer(blob));
}

const archive = new MpqStreamingArchive(file, readRange);
console.log(archive.list());              // entries without loading the whole archive
console.log(archive.listfile());          // parsed (listfile) paths, or null
const data = archive.readFile("patch.m2"); // read a specific file

MpqStreamingArchive is read-only and only keeps the MPQ header and index tables in memory. The actual file bytes stay on disk and are fetched on demand through the synchronous read callback.

Note: MPQ uses \ as path separator; MPQ-internal special files ((listfile), (attributes), (signature)) are regenerated by the builder on export().