wc3
wc3 is a Rust library for working with Warcraft III assets. It reads, edits,
and writes models in binary MDX and text MDL, and textures in BLP1
and BLP2 containers.
Models share one typed representation across MDX and MDL, with layouts for Classic and Reforged versions. Texture APIs can inspect and rewrite encoded BLP data without decoding pixels, or decode and encode images with optional features.
Getting started
The library crate is wc3. Add the latest published version to your project:
Enable both BLP image operations with
cargo add wc3 --features blp-decode,blp-encode. You can enable either feature
on its own. Add a direct image = "0.25" dependency if you use image types in
your code, as the examples below do.
| API | Cargo feature |
|---|---|
| MDX and MDL models; BLP container reading, editing, and writing | None |
BLP mipmap decoding to RGBA pixels; image::ImageDecoder adapter |
blp-decode |
BLP image encoding from RGBA pixels; image::ImageEncoder adapter |
blp-encode |
Models: read, edit, and write
Model types live under wc3::model. Import the relevant mdx::Read /
mdx::Write and mdl::Read / mdl::Write traits as _ to enable their
methods.
use ;
use ;
use Write as _;
Use Model<V> when you know the version. DynamicModel selects the version
from an MDL file or an MDX VERS chunk; MDX reading takes a fallback version
for files without that chunk. Supported versions are 800, 900, 1000, 1100,
1200, 1300, 1400, 1600, and 1800.
MDX preserves chunk order and opaque data. MDL writes canonical text and
reports data it cannot faithfully represent. MDL readers accept Warcraft III
and Hive Workshop spellings; writers use Warcraft III syntax by default.
See the model and
mdl module docs for editing
collections, dialects, and field-level coverage.
Textures: inspect, decode, and encode
BlpRef borrows encoded mipmaps from the input buffer. Convert it to an owned
Blp to edit container fields, then write it back:
use ;
Writing recalculates mipmap offsets and discards source padding. With
blp-decode, decode any BLP1 or BLP2 mipmap to an image::RgbaImage:
use BlpRef;
With blp-encode, encode an RGBA image to BLP JPEG, indexed colour with 0, 1,
4, or 8-bit alpha, DXT1/3/5, or uncompressed BGRA:
use ;
Blp::encode_image generates mipmaps; Blp::encode_mipmaps accepts authored
mipmaps. See the blp module docs for
the image crate adapters, options, and container behavior.
Version conversion
Model::convert builds a model for another version and returns a report,
leaving the source intact. Strict conversion rejects unsupported nondefault
data; ConversionOptions::lossy() permits discarding it. Unknown chunks have
a separate preserve or drop policy. Conversion cannot translate every feature
between Classic and Reforged layouts and does not guarantee identical game
rendering. See the model module
docs for the conversion example and editing guidance.
API documentation
The mdx and
mdl modules document their
Read and Write traits, format behavior, and lower-level codecs. Build all
workspace API docs locally with: