blizzardry

Blizzardry

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

Blizzardry currently 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.

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

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

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

adt.MTEX.filenames // ['Tileset\\Wetlands\\Wetlandsdirt01.blp', ...]
adt.MMDX.filenames // ['WORLD\\AZEROTH\\ELWYNN\\PASS...\\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 in Release mode, rename blp.dll to libblp.dll and ensure it ends up on the load PATH.

By default, node-gyp compiles ffi for x64 so make sure libblp.dll matches this architecture.

Other platforms

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

var 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

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.

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

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

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

Use pre-defined DBC entities for convenience:

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

var 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.

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

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

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

MPQ

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 build the DLL in Release mode using StormLib_dll.vcproj (Visual Studio), rename StormLib.dll to libstorm.dll and ensure it ends up on the load PATH.

By default, node-gyp compiles ffi for x64 so make sure libstorm.dll matches this architecture.

Other platforms

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

var 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
  var 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.

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

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

var 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.

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

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

var 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).

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

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

var 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/wowserhq/blizzardry.git
   

2. Download and install Node.js – including 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.4.0 - June 14, 2016

• Breaking changes in M2:

  • renderFlags renamed to materials
  • textureUnits renamed to textureMappings
  • transparencies renamed to transparencyAnimations
  • colors renamed to vertexColorAnimations

• Breaking changes in M2.AnimationBlock:

  • track.keyframes is removed
  • track.timestamps is added
  • track.values is added
  • isAnimated flag renamed to animated
  • isEmpty flag renamed to empty

• Breaking changes in M2.Skin:

  • textureUnits renamed to batches

• Breaking changes in M2.Skin.Submesh:

  • id renamed to partID

• Breaking changes in M2.Skin.Batch:

  • colorIndex renamed to vertexColorIndex
  • renderFlagsIndex renamed to materialIndex
  • textureUnitNumber renamed to layer
  • textureIndex renamed to textureLookup
  • textureUnitNumber2 renamed to textureMappingIndex
  • transparencyIndex renamed to transparencyLookup
  • textureAnimIndex renamed to uvAnimationLookup

• Additions to M2:

  • boneLookups (bone lookup table)
  • uvAnimations (texture coordinate animations)
  • blendingOverrides (used in computing M2.Skin.Batch.shader_id)
  • overrideBlending (boolean flag)

• Additions to M2.Bone:

  • billboardType (parsed from bone flags)
  • billboarded (boolean flag)

• Additions to WMO:

  • MOPV (portal vertices)
  • MOPT (portal entries)
  • MOPR (portal references)

• Additions to WMO.Group:

  • MOCV (vertex colors)
  • MODR (doodad references)

• Fixes to ADT:

  • Chunk holes are 16-bit, not 32-bit

• Fixes to WMO:

  • Correct optional chunk ordering

• Other:

  • Simpler / more consistent custom types
  • Uses Babel 6
  • Supports Node 6