blizzardry

Blizzardry

JavaScript library for mastering the wizardry that is Blizzard's game files.

The current version of Blizzardry focusses on Wrath of the Lich King game content.

Licensed under the MIT license, see LICENSE for more information.

Installation

Blizzardry is available via npm:

npm install blizzardry

Or for usage in the browser, soon™.

Usage

ADT

Map tiles containing terrain and object information.

A map tile consists of 16 by 16 map chunks.

r = require('blizzardry/lib/restructure');
ADT = require('blizzardry/lib/adt');

io = fs.readFileSync('Azeroth_31_39.adt');
stream = new r.DecodeStream(io);

adt = ADT.decode(stream);
adt.version // 18
adt.flags   // 0

adt.MTEX.filenames // ['Tileset\\Wetlands\\Wetlandsdirt01.blp', ...]
adt.MMDX.filenames // ['WORLD\\AZEROTH\\ELWYNN\\PASSIVEDOODADS\\BUSH\\ELWYNNBUSH09.M2', ...]

adt.MCNKs.forEach(function(chunk) {
  chunk.areaID   // 2365
  chunk.position // { x: -3733.33, y: 533.33, z: -462.37 }
  chunk.indexX   // 0
  chunk.indexY   // 0
});

BLP

Texture format holding up to 16 pre-rendered mipmaps.

Blizzardry uses BLPConverter to process BLPs.

OSX

Install using Homebrew:

brew install --HEAD https://raw.githubusercontent.com/timkurvers/homebrew-games/formula/blp-converter/blp-converter.rb

Windows

Download BLPConverter and generate the project using CMake:

cmake -DWITH_LIBRARY=YES CMakeLists.txt

Build the DLL using Visual Studio 2013 in release mode, rename it to libblp.dll and ensure the library ends up on the load path.

Other platforms

Compile from source and ensure the library ends up on the load path.

BLP = require('blizzardry/lib/blp');

BLP.open('RabbitSkin.blp', function(blp) {
  blp.version     // 2
  blp.mipmapCount // 8

  blp.largest.width  // 128
  blp.largest.height // 128
  blp.largest.data   // <Buffer a2 a2 a2 dd a2 ...>

  blp.smallest.width  // 1
  blp.smallest.height // 1
  blp.smallest.data   // <Buffer 7e 98 af ee>

  // Or directly:
  blp.mipmaps[3].width  // 16
  blp.mipmaps[3].height // 16
});

// Or alternatively:
var blp = BLP.open('RabbitSkin.blp');
// ...
blp.close();

CASC

Generic archive format, used in recent Blizzard games. Supersedes MPQ.

Blizzardry will use CascLib to handle CASC storage containers.

Support to be added soon™.

DBC

Client database format, containing data on items, NPCs, environments and more.

r = require('blizzardry/lib/restructure');
DBC = require('blizzardry/lib/dbc');

io = fs.readFileSync('Faction.dbc');
stream = new r.DecodeStream(io);

dbc = DBC.decode(stream);
dbc.signature   // 'WDBC'
dbc.recordCount // 396
dbc.records[0]  // <Buffer 01 00 00 00 ff ff ff ff ...>

To avoid parsing records manually, use one of the pre-defined DBC entities:

Faction = require('blizzardry/lib/dbc/entities/faction');

dbc = Faction.dbc.decode(stream);
dbc.records.forEach(function(record) {
  record.id          // 576
  record.parentID    // 1118
  record.name        // 'Timbermaw Hold'
  record.description // 'As the last uncorrupted furbolg tribe ...'
});

M2

3D model format for player characters, NPCs and doodads, among others.

r = require('blizzardry/lib/restructure');
M2 = require('blizzardry/lib/m2');

io = fs.readFileSync('Rabbit.m2');
stream = new r.DecodeStream(io);

m2 = M2.decode(stream);
m2.signature // 'MD20'
m2.name      // 'Rabbit'
m2.vertices[0].position // [ -0.2735.., -0.0035.., 0.3579.. ]

MPQ

Generic archive format, used in most Blizzard games. Superseded by CASC.

Blizzardry uses StormLib to handle MPQ archives.

OSX

Install using Homebrew:

brew tap homebrew/games
brew install stormlib

Windows

Download StormLib and generate the project using CMake:

cmake -DWITH_LIBRARY=YES CMakeLists.txt

Build the DLL using Visual Studio 2013 in release mode, rename it to libstorm.dll and ensure it ends up on the load path.

Other platforms

Compile from source and ensure the library ends up on the load path.

MPQ = require('blizzardry/lib/mpq');

MPQ.open('common.MPQ', function(mpq) {
  mpq.files.contains('Creature\\Illidan\\Illidan.m2') // true

  // Extract to local filesystem
  mpq.files.extract('Creature\\Illidan\\Illidan.m2', '~/Illidan.m2');

  // Iterate over all entries
  mpq.files.all.forEach(function(result) {
    result.filename // 'SPELLS\\ArcaneBomb_Missle.M2'
    result.name     // 'ArcaneBomb_Missle.M2'
    result.filesize // 28928
  });

  // Search for entries (supports wildcards)
  mpq.files.find('*Illidan*');

  // Accessing file data
  file = mpq.files.get('Creature\\Illidan\\Illidan.m2');
  file.name // 'Creature\\Illidan\\Illidan.m2'
  file.size // 1888368
  file.data // <Buffer 4d 44 32 30 08 01 00 00 ...>
});

// Or alternatively:
var mpq = MPQ.open('common.MPQ');
// ...
mpq.close();

WDT

World definition file specifying which map tiles are present.

A map consists of 64 by 64 map tiles.

r = require('blizzardry/lib/restructure');
WDT = require('blizzardry/lib/wdt');

io = fs.readFileSync('Azeroth.wdt');
stream = new r.DecodeStream(io);

wdt = WDT.decode(stream);
wdt.version // 18
wdt.flags   // 0
wdt.tiles[30 * 64 + 24] // 0
wdt.tiles[30 * 64 + 25] // 1

WMO

Root world map definition file listing textures, doodads and orientation.

Actual model data is stored in group files.

r = require('blizzardry/lib/restructure');
WMO = require('blizzardry/lib/wmo');

io = fs.readFileSync('trolltent.wmo');
stream = new r.DecodeStream(io);

wmo = WMO.decode(stream);
wmo.version    // 17
wmo.flags      // 1
wmo.groupCount // 1

wmo.MOTX.filenames // ['DUNGEONS\\TEXTURES\\ROOF\\BM_TROLL_KOTOSKIN01.BLP', ...]

WMO Group

For a root file named trolltent.wmo, its group files are named trolltent_000.wmo, trolltent_001.wmo and so forth.

The amount of groups is exposed as groupCount in the root file (see above).

r = require('blizzardry/lib/restructure');
WMOGroup = require('blizzardry/lib/wmo/group');

io = fs.readFileSync('trolltent_000.wmo');
stream = new r.DecodeStream(io);

group = WMOGroup.decode(stream);
group.version // 17
group.flags   // 1
group.MOVT.vertices[0] // [ 3.1721.., 10.4109.., 5.7666.. ]

Development & Contribution

Blizzardry is written in ES2015, compiled by Babel, developed with Gulp and tested through Mocha.

Getting this toolchain up and running, is easy and straight-forward:

1. Get the code:

   git clone git://github.com/timkurvers/blizzardry.git
   

2. Download and install Node.js (includes npm) for your platform.

3. Install dependencies:

   npm install
   

4. Install BLPConverter and StormLib as outlined above.

5. Run npm run gulp which will automatically build and test the project when source files change.

When contributing, please:

• Fork the repository
• Accompany each logical unit of operation with at least one test
• Open a pull request

Changelog

v0.2.6 - September 26, 2015

• Supports floats compressed in 16 bits as Quat16Float.

• Corrects M2.Bone#rotation decoding as Quat16Floats.

• Exposes following on M2.Skin:

  • boneCount
  • boneIndices
  • signature
  • submeshes
  • textureUnits

• M2.Bone#subMeshID is now M2.Bone#submeshID.

• ADT#soundEmittersCount is now ADT#soundEmitterCount.

• Deals with incorrect MCAL and MCSH sizes in ADT.

• Decodes MCSE only when sound emitters are present in ADT.

• Exposes ADT#MDDF.

• Exposes M2#textures and M2#renderFlags.