wow-m2

A Rust library for parsing, validating, and converting World of Warcraft M2 model files.

Overview

wow-m2 supports M2 model files across all World of Warcraft expansions from Classic (1.12.1) through The War Within (11.x). The library handles:

• M2 Models (.m2/.mdx) - 3D character, creature, and object models
• Skin Files (.skin) - Level-of-detail and submesh information
• Animation Files (.anim) - External animation sequences
• BLP Texture References - Re-exports BLP support from the wow-blp crate

Features

• Parse and validate M2 models from all WoW versions
• Convert models between different game versions
• Coordinate system transformations for Blender, Unity, Unreal Engine
• Support for all chunk types (bones, animations, textures, etc.)
• Error handling with detailed context
• Zero-copy parsing where possible for performance
• Optional serde support for serialization

Installation

Add to your Cargo.toml:

[dependencies]
wow-m2 = "0.6"

Or use cargo add:

cargo add wow-m2

Usage

Basic Example

use wow_m2::{M2Model, M2Version, M2Converter};

// Load a model (returns M2Format enum with Legacy or Chunked variant)
let format = M2Model::load("path/to/model.m2")?;
let model = format.model(); // get the inner M2Model

// Print basic information
println!("Model version: {:?}", model.header.version());
println!("Vertices: {}", model.vertices.len());
println!("Bones: {}", model.bones.len());

// Convert to a different version
let converter = M2Converter::new();
let converted = converter.convert(model, M2Version::WotLK)?;
// Save the converted model
converted.save("path/to/converted.m2")?;

Working with Skin Files

use wow_m2::{SkinFile, load_skin};

// Load a skin file
let skin_file = SkinFile::load("path/to/model00.skin")?;

// Access submesh information
for submesh in &skin_file.skin.submeshes {
    println!("Submesh {}: {} vertices, {} triangles",
        submesh.id, submesh.vertex_count, submesh.triangle_count);
}

Coordinate System Transformations

Transform WoW models for use in common 3D applications:

use wow_m2::{M2Model, CoordinateSystem, CoordinateTransformer, transform_position};

// Load a model
let format = M2Model::load("character.m2")?;
let model = format.model();

// Transform for Blender (right-handed: X=right, Y=forward, Z=up)
let transformer = CoordinateTransformer::new(CoordinateSystem::Blender);
for vertex in &model.vertices {
    let blender_pos = transformer.transform_position(vertex.position);
    println!("WoW: {:?} → Blender: {:?}", vertex.position, blender_pos);
}

// Or transform individual coordinates
let wow_pos = model.vertices[0].position;
let unity_pos = transform_position(wow_pos, CoordinateSystem::Unity);
let unreal_pos = transform_position(wow_pos, CoordinateSystem::UnrealEngine);

Why coordinate transformation is needed: WoW uses X=North, Y=West, Z=Up, which differs from standard 3D applications. Without transformation, models appear rotated or mirrored.

Version Support

The library supports parsing versions by both numeric format and expansion names:

use wow_m2::M2Version;

// Using version numbers
let version = M2Version::from_string("3.3.5a")?;  // WotLK

// Using expansion names
let version = M2Version::from_expansion_name("wotlk")?;
let version = M2Version::from_expansion_name("MoP")?;

Supported Versions

Examples

See the examples/ directory for more detailed examples:

• convert_model.rs - Convert models between versions
• analyze_model.rs - Analyze model structure and contents
• validate_model.rs - Validate model integrity

Documentation

• Coordinate Systems Guide - WoW coordinate systems and transformations
• API Documentation - Complete API reference

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Contributing

See CONTRIBUTING.md for guidelines.

References

• WoWDev.wiki M2 Format
• WoWDev.wiki SKIN Format