Convert Command Testing Results

Date: 2026-01-11

Summary

Testing of all warcraft-rs convert subcommands using real game data from WoW clients (1.12.1 Vanilla, 3.3.5a WotLK).

Detailed Results

BLP Convert

Status: Working

Tested conversions:

• BLP1 (1.12.1) -> PNG: Success
• BLP2 (3.3.5a) -> PNG: Success
• PNG -> BLP1 RAW1: Success
• PNG -> BLP1 JPEG: Success (alpha stripped with warning)
• PNG -> BLP2 DXT1: Success (auto-selects 1-bit alpha for RGBA input)
• PNG -> BLP2 DXT3: Success (auto-selects 8-bit alpha for RGBA input)
• PNG -> BLP2 DXT5: Success (auto-selects 8-bit alpha for RGBA input)

Features:

• Alpha bits are auto-detected from input image if not specified
• JPEG format now works with RGBA images (alpha is stripped with a warning)
• DXT1 auto-selects 1-bit alpha for images with transparency
• DXT3/DXT5/JPEG auto-select 8-bit alpha for images with transparency
• Raw1/Raw3 auto-select 8-bit alpha for full quality

Note: BLP JPEG format stores RGB in the JPEG stream. Alpha (if requested) would be stored separately, but this is a limitation of the current BLP format. For images requiring alpha, DXT5 or Raw1 formats are recommended.

M2 Convert

Status: Working - All versions parse and roundtrip correctly

The M2 converter preserves all animation data including bone animations, particle emitter animations, ribbon emitter animations, texture animations, color animations, transparency animations, event track data, attachment animations, camera animations, light animations, and embedded skin data through roundtrip and version conversion for all supported versions.

Working:

• Full model roundtrip (Vanilla, TBC, WotLK, Cataclysm, MoP)
• Version conversion between any supported versions
• Bone animation keyframes (timestamps, values, ranges) preserved
• Particle emitter animations (10 track types) preserved with offset relocation
• Ribbon emitter animations (4 track types) preserved with offset relocation
• Texture animations (5 track types) preserved with offset relocation
• Color animations (2 track types: RGB color, alpha) preserved with offset relocation
• Transparency animations (1 track type: alpha) preserved with offset relocation
• Event track data (simple M2Array timestamps) preserved with offset relocation
• Attachment animations (1 track type: scale) preserved with offset relocation
• Camera animations (3 track types: position, target position, roll) preserved with offset relocation
• Light animations (5 track types: ambient color, diffuse color, attenuation start/end, visibility) preserved with offset relocation
• Pre-WotLK embedded skin data preserved (ModelView, indices, triangles, submeshes, batches)
• Header fields correctly handle version-specific differences:
  • playable_animation_lookup (Vanilla/TBC only, versions 256-263)
  • texture_flipbooks (pre-WotLK only, versions <= 263)
  • views vs num_skin_profiles (M2Array pre-WotLK, u32 for WotLK+)
• Vertex data preserved (48-byte format for all versions)
• Bone structure and animation tracks preserved with offset relocation

Test results with DwarfMale.m2 (vanilla 1.12.1):

Original:                2,124,656 bytes (version 256, embedded skins)
Vanilla roundtrip:       1,496,389 bytes (version 256, 4 skins, 138 bone anims, 34 attachment anims)
Converted to WotLK:      1,259,407 bytes (version 264, external skins)

Previous (before fix):     173,965 bytes (animation data was zeroed)

Note: Roundtrip file is smaller than original because we don’t preserve padding/alignment from the original file. The output contains all data needed to display and animate the model.

The converter preserves:

• Magic (MD20) and version
• Vertices and geometry (3246 vertices)
• Bones with animation tracks (110 bones, 138 animation data entries)
• Materials and textures (3 textures)
• Embedded skins for pre-WotLK (4 skin profiles)
• All animation sequences (135 animations)
• Particle emitter animations (emission speed, gravity, lifespan, etc.)
• Ribbon emitter animations (color, alpha, height)
• Texture animations (translation U/V, rotation, scale U/V)
• Color animations (RGB color, alpha)
• Transparency animations (alpha/texture weight)
• Event track timestamps (timeline triggers for sounds, effects)
• Attachment scale animations (weapon/effect attach points)
• Camera animations (position, target position, roll)
• Light animations (ambient/diffuse color, attenuation, visibility)

All M2 animation data types are now preserved through roundtrip conversion.

M2 Skin Convert

Status: Working

Tested conversions:

• WotLK old format -> MoP new format: Success
• MoP new format -> WotLK old format: Success

The skin file converter correctly maintains all data (indices, triangles, bone indices, submeshes, batches) across format changes.

M2 Anim Convert

Status: Working

Tested conversion:

• Legacy format -> MoP: Success (no actual conversion needed for legacy format)

WMO Convert

Status: Partial - Root files work; group files pending

Tested conversions:

• Classic root -> WotLK: Success
• Classic root -> Cataclysm: Success

The WMO root file converter works using expansion names (WotLK, Cataclysm, MoP) instead of raw version numbers. Uses WmoParser -> WmoConverter -> WmoWriter pipeline.

Working:

• Root file conversion between any supported versions
• Materials, groups, portals, lights, doodads preserved
• Header flags converted appropriately for target version

Not yet implemented:

• Group file conversion (requires bridging parser types to core types)

Group files (*_000.wmo, *_001.wmo, etc.) return an informative error explaining that conversion is not yet supported due to internal type system differences.

ADT Convert

Status: Working - Root ADT files convert and roundtrip correctly

Tested conversions:

• Vanilla root -> WotLK: Success (roundtrip verified)
• Vanilla root -> MoP: Success (roundtrip verified)
• TBC root -> WotLK: Success (roundtrip verified)
• TBC root -> Classic: Success (roundtrip verified, strips MFBO)
• WotLK root -> MoP: Success (adds MFBO flight bounds for TBC+)

The ADT root file converter works using expansion names (classic, tbc, wotlk, cataclysm, mop). Uses ParsedAdt → BuiltAdt.from_root_adt() → write_to_file() pipeline.

Working:

• Parsing all ADT versions (Vanilla through MoP) - 256/256 MCNK chunks
• Conversion between any supported versions (up and down)
• Version-specific chunk handling (MFBO for TBC+, MH2O for WotLK+, MAMP for Cataclysm+, MTXP for MoP+)
• Terrain heights, normals, shadow maps, alpha maps, and vertex colors preserved
• Textures, models, WMOs, and placements preserved
• Fixed: MCAL/MCSH subchunk parsing now uses header size fields instead of corrupted subchunk sizes
• Fixed: has_shadow()/has_layer() now check offset/size instead of flags for Vanilla compatibility
• Fixed: MCNK serializer clears stale offsets to prevent invalid pointer references

Not yet supported:

• Split ADT files (_tex0, _obj0, _lod) from Cataclysm+

WDT Convert

Status: Working

Tested conversions:

• Classic -> WotLK: Success (no changes needed)
• WotLK -> MoP: Success (adds 0x0040 flag, updates MODF values)

The converter correctly:

• Adds the universal flag (0x0040) for Cataclysm+ versions
• Updates MODF scale values from 0 to 1024
• Updates MODF unique IDs from 0xFFFFFFFF to 0x00000000

Output verified by wdt info and the converted file is readable.

WDL Convert

Status: Working

Tested conversion:

• Classic -> MoP: Success

Output validated successfully with wdl validate.

DBC Export

Status: Working (with caveats)

JSON and CSV export work correctly when provided with a valid schema file.

Caveats:

• Requires a YAML schema file - no built-in schemas
• Schema must use type_name field (not type)
• Field order matters for matching record structure

DBC Discover

Status: Working

The schema discovery command analyzes DBC files and generates field type information.

Features:

• Correctly identifies String, Int32, UInt32, Float32, and Bool field types
• Validates string references point to actual string starts (not middle of strings)
• Detects localized string (locstring) patterns: 8 locale strings + 1 flags field
• Shows locale names (enUS, koKR, frFR, deDE, zhCN, zhTW, esES, esMX) for locstrings
• Identifies potential key fields
• Improved float detection: small integers (< 65536) no longer misdetected as floats

For AreaTable.dbc (21 fields, 84 bytes per record):

Field  0: Int32    (confidence: Low)     ⚷ Key candidate
Field  1: Int32    (confidence: Low)
...
Field 11: String   (confidence: High)    🌐 Locstring (enUS)
Field 12: String   (confidence: Medium)  🌐 Locstring (koKR)
...
Field 19: Int32    (confidence: Low)     🌐 Locstring (flags)
Field 20: Int32    (confidence: Low)

For SpellRadius.dbc (actual float values correctly detected):

Field  0: Int32    (confidence: Low)     ⚷ Key candidate
Field  1: Float32  (confidence: Medium)  <- actual float (1.0, 2.0, 5.0, etc.)
Field  2: Bool     (confidence: High)
Field  3: Float32  (confidence: Medium)  <- actual float

Limitations:

• Field naming is generic (Float_1, Value_2, etc.) - use WoWDBDefs for accurate names

Test Data Locations

Test files extracted to /tmp/warcraft-rs-test/:

1.12.1 (Vanilla)

• FacialLowerHair00_00.blp - BLP1 texture
• DwarfMale.m2 - Character model (version 256)
• AltarOfStorms.wmo - WMO root (version 17)
• Azeroth_32_48.adt - Terrain tile
• Azeroth.wdt - Map definition
• Azeroth.wdl - World lod
• AreaTable.dbc - Database table

3.3.5a (WotLK)

• HAIR00_00.BLP - BLP2 texture
• IceTrollMale.m2 - Character model (version 264)
• IceTrollMale00.skin - Skin file (old format)
• IceTrollMale0060-00.anim - Animation file (legacy)
• Duskwood_MageTowerPurple.wmo - WMO root
• BlackTemple_28_28.adt - Terrain tile
• AuchindounDemon.wdt - WMO-only map
• AuchindounDemon.wdl - World lod

Recommendations

1. Implement WMO group file conversion - Root files work but group files need type bridging between parser and converter/writer types.

2. Implement ADT split file conversion - Root ADT files work but Cataclysm+ split files (_tex0, _obj0, _lod) require additional support.

Test Commands Reference

# BLP conversion (alpha bits auto-detected from input)
cargo run -p warcraft-rs -- blp convert input.blp output.png
cargo run -p warcraft-rs -- blp convert input.png output.blp --blp-version blp2 --blp-format dxt5
cargo run -p warcraft-rs -- blp convert input.png output.blp --blp-version blp1 --blp-format jpeg
# Explicit alpha bits (optional)
cargo run -p warcraft-rs -- blp convert input.png output.blp --blp-version blp2 --blp-format dxt1 --alpha-bits 0

# M2 conversion (all animation types and embedded skins preserved)
cargo run -p warcraft-rs -- m2 convert input.m2 output.m2 --version WotLK

# Pre-WotLK roundtrip test
cargo run --example test_vanilla_roundtrip -p wow-m2 -- input.m2 [output.m2]

# Skin conversion
cargo run -p warcraft-rs -- m2 skin-convert input.skin output.skin --version MoP

# Anim conversion
cargo run -p warcraft-rs -- m2 anim-convert input.anim output.anim --version MoP

# WMO conversion (root files only)
cargo run -p warcraft-rs -- wmo convert input.wmo output.wmo --version WotLK

# ADT conversion (root files only)
cargo run -p warcraft-rs -- adt convert input.adt output.adt --to WotLK

# WDT conversion
cargo run -p warcraft-rs -- wdt convert input.wdt output.wdt --from-version Classic --to-version MoP

# WDL conversion
cargo run -p warcraft-rs -- wdl convert input.wdl output.wdl --to MoP

# DBC export
cargo run -p warcraft-rs -- dbc export input.dbc --schema schema.yaml -f json

# DBC schema discovery
cargo run -p warcraft-rs -- dbc discover input.dbc