wow-m2

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

Overview

wow-m2 provides comprehensive support for 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.)
• ✅ Comprehensive 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.3.0"

Or use cargo add:

cargo add wow-m2

Usage

Basic Example

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

// Load a model
let data = std::fs::read("path/to/model.m2")?;
let mut cursor = std::io::Cursor::new(data);
let model = M2Model::parse(&mut cursor)?;

// 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
let output_data = converted.write_to_bytes()?;
std::fs::write("path/to/converted.m2", output_data)?;

Working with Skin Files

use wow_m2::Skin;

// Load a skin file
let data = std::fs::read("path/to/model00.skin")?;
let mut cursor = std::io::Cursor::new(data);
let skin = Skin::parse(&mut cursor)?;

// Access submesh information
for submesh in &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 model = M2Model::load("character.m2")?;

// 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 - Comprehensive guide to 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