{"id":20363985,"url":"https://github.com/wowserhq/blizzardry","last_synced_at":"2025-12-17T00:47:56.612Z","repository":{"id":15303832,"uuid":"18033628","full_name":"wowserhq/blizzardry","owner":"wowserhq","description":"JavaScript library for mastering the wizardry that is Blizzard's game files","archived":false,"fork":false,"pushed_at":"2023-04-15T18:27:37.000Z","size":1490,"stargazers_count":54,"open_issues_count":39,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-09T12:48:04.719Z","etag":null,"topics":["blizzard","blizzard-games","javascript","mpq","stormlib","warcraft","wow"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wowserhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-23T13:09:51.000Z","updated_at":"2024-08-19T10:23:45.000Z","dependencies_parsed_at":"2024-06-19T09:17:18.875Z","dependency_job_id":"2681ebcf-5814-4763-9b25-b0216ca0da1d","html_url":"https://github.com/wowserhq/blizzardry","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowserhq%2Fblizzardry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowserhq%2Fblizzardry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowserhq%2Fblizzardry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wowserhq%2Fblizzardry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wowserhq","download_url":"https://codeload.github.com/wowserhq/blizzardry/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248517417,"owners_count":21117449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blizzard","blizzard-games","javascript","mpq","stormlib","warcraft","wow"],"created_at":"2024-11-15T00:09:12.139Z","updated_at":"2025-12-17T00:47:56.551Z","avatar_url":"https://github.com/wowserhq.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blizzardry\n\n[![Version](https://badgen.net/npm/v/blizzardry)](https://www.npmjs.com/package/blizzardry)\n![Node Version](https://badgen.net/badge/node/10+/green)\n[![Join Community](https://img.shields.io/badge/discord-join_community-blue.svg?style=flat)](https://discord.gg/DeVVKVg)\n[![CI](https://github.com/wowserhq/blizzardry/workflows/CI/badge.svg)](https://github.com/wowserhq/blizzardry/actions/workflows/ci.yml)\n\nJavaScript library for mastering the wizardry that is [Blizzard]'s game files.\n\nBlizzardry currently focusses on [Wrath of the Lich King] game content.\n\nLicensed under the [**MIT** license](LICENSE).\n\n## Installation\n\nBlizzardry is available via [npm]:\n\n```shell\nnpm install blizzardry\n```\n\nOr for usage in the browser, [soon™].\n\n## Usage\n\n### [ADT](src/lib/adt)\n\nMap tiles containing terrain and object information.\n\nA map tile consists of 16 by 16 map chunks.\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar ADT = require('blizzardry/lib/adt');\n\nvar io = fs.readFileSync('Azeroth_31_39.adt');\nvar stream = new r.DecodeStream(io);\n\nvar adt = ADT.decode(stream);\nadt.version // 18\nadt.flags   // 0\n\nadt.MTEX.filenames // ['Tileset\\\\Wetlands\\\\Wetlandsdirt01.blp', ...]\nadt.MMDX.filenames // ['WORLD\\\\AZEROTH\\\\ELWYNN\\\\PASS...\\\\ELWYNNBUSH09.M2', ...]\n\nadt.MCNKs.forEach(function(chunk) {\n  chunk.areaID   // 2365\n  chunk.position // { x: -3733.33, y: 533.33, z: -462.37 }\n  chunk.indexX   // 0\n  chunk.indexY   // 0\n});\n```\n\n### [BLP](src/lib/blp)\n\nTexture format holding up to 16 pre-rendered [mipmaps].\n\nBlizzardry uses [BLPConverter] to process BLPs.\n\n#### OSX\n\nInstall using [Homebrew]:\n\n```shell\nbrew install --HEAD https://raw.githubusercontent.com/timkurvers/homebrew-games/formula/blp-converter/blp-converter.rb\n```\n\n#### Windows\n\nDownload [BLPConverter] and generate the project using [CMake]:\n\n```shell\ncmake -DWITH_LIBRARY=YES CMakeLists.txt\n```\n\nBuild the DLL using Visual Studio in Release mode, rename `blp.dll`\nto `libblp.dll` and ensure it ends up on the load PATH.\n\nBy default, node-gyp compiles ffi for x64 so make sure `libblp.dll`\nmatches this architecture.\n\n#### Ubuntu, Debian\n\n```shell\nsudo apt-get install cmake git gcc\ngit clone git://github.com/Kanma/BLPConverter.git\ncd BLPConverter\ncmake CMakeLists.txt -DWITH_LIBRARY=YES\nsudo make install\nsudo ldconfig\n```\n\n#### Other platforms\n\nCompile from source and ensure the library ends up on the load path.\n\n```javascript\nvar BLP = require('blizzardry/lib/blp');\n\nBLP.open('RabbitSkin.blp', function(blp) {\n  blp.version     // 2\n  blp.mipmapCount // 8\n\n  blp.largest.width  // 128\n  blp.largest.height // 128\n  blp.largest.data   // \u003cBuffer a2 a2 a2 dd a2 ...\u003e\n\n  blp.smallest.width  // 1\n  blp.smallest.height // 1\n  blp.smallest.data   // \u003cBuffer 7e 98 af ee\u003e\n\n  // Or directly:\n  blp.mipmaps[3].width  // 16\n  blp.mipmaps[3].height // 16\n});\n\n// Or alternatively:\nvar blp = BLP.open('RabbitSkin.blp');\n// ...\nblp.close();\n```\n\n### CASC\n\nArchive format, used in [recent Blizzard games]. Supersedes [MPQ](#mpq).\n\nBlizzardry will use [CascLib] to handle CASC storage containers.\n\nSupport to be added [soon™].\n\n### [DBC](src/lib/dbc)\n\nClient database format, containing data on items, NPCs, environments and more.\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar DBC = require('blizzardry/lib/dbc');\n\nvar io = fs.readFileSync('Faction.dbc');\nvar stream = new r.DecodeStream(io);\n\nvar dbc = DBC.decode(stream);\ndbc.signature   // 'WDBC'\ndbc.recordCount // 396\ndbc.records[0]  // \u003cBuffer 01 00 00 00 ff ff ff ff ...\u003e\n```\n\nUse [pre-defined DBC entities](src/lib/dbc/entities) for convenience:\n\n```javascript\nvar Faction = require('blizzardry/lib/dbc/entities/faction');\n\nvar dbc = Faction.dbc.decode(stream);\ndbc.records.forEach(function(record) {\n  record.id          // 576\n  record.parentID    // 1118\n  record.name        // 'Timbermaw Hold'\n  record.description // 'As the last uncorrupted furbolg tribe ...'\n});\n```\n\n### [M2](src/lib/m2)\n\n3D model format for player characters, NPCs and doodads, among others.\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar M2 = require('blizzardry/lib/m2');\n\nvar io = fs.readFileSync('Rabbit.m2');\nvar stream = new r.DecodeStream(io);\n\nvar m2 = M2.decode(stream);\nm2.signature // 'MD20'\nm2.name      // 'Rabbit'\nm2.vertices[0].position // [ -0.2735.., -0.0035.., 0.3579.. ]\n```\n\n### [MPQ](src/lib/mpq)\n\nArchive format, used in [most Blizzard games]. Superseded by [CASC](#casc).\n\nBlizzardry uses [StormLib] to handle MPQ archives.\n\n#### OSX\n\nInstall using [Homebrew]:\n\n```shell\nbrew tap homebrew/games\nbrew install stormlib\n```\n\n#### Windows\n\nDownload [StormLib] and build the DLL in Release mode using `StormLib_dll.vcproj` (Visual Studio),\nrename `StormLib.dll` to `libstorm.dll` and ensure it ends up on the load PATH.\n\nBy default, node-gyp compiles ffi for x64 so make sure `libstorm.dll`\nmatches this architecture.\n\n#### Ubuntu, Debian\n\n```shell\nsudo apt-get install cmake git gcc zlib1g-dev\ngit clone git://github.com/ladislav-zezula/StormLib.git\ncd StormLib\ncmake CMakeLists.txt -DBUILD_SHARED_LIBS=ON\nsudo make install\nsudo ldconfig\n```\n\n#### Other platforms\n\nCompile from source and ensure the library ends up on the load path.\n\n```javascript\nvar MPQ = require('blizzardry/lib/mpq');\n\nMPQ.open('common.MPQ', function(mpq) {\n  mpq.files.contains('Creature\\\\Illidan\\\\Illidan.m2') // true\n\n  // Extract to local filesystem\n  mpq.files.extract('Creature\\\\Illidan\\\\Illidan.m2', '~/Illidan.m2');\n\n  // Iterate over all entries\n  mpq.files.all.forEach(function(result) {\n    result.filename // 'SPELLS\\\\ArcaneBomb_Missle.M2'\n    result.name     // 'ArcaneBomb_Missle.M2'\n    result.filesize // 28928\n  });\n\n  // Search for entries (supports wildcards)\n  mpq.files.find('*Illidan*');\n\n  // Accessing file data\n  var file = mpq.files.get('Creature\\\\Illidan\\\\Illidan.m2');\n  file.name // 'Creature\\\\Illidan\\\\Illidan.m2'\n  file.size // 1888368\n  file.data // \u003cBuffer 4d 44 32 30 08 01 00 00 ...\u003e\n});\n\n// Or alternatively:\nvar mpq = MPQ.open('common.MPQ');\n// ...\nmpq.close();\n```\n\n### [WDT](src/lib/wdt)\n\nWorld definition file specifying which map tiles are present.\n\nA map consists of 64 by 64 [map tiles](#adt).\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar WDT = require('blizzardry/lib/wdt');\n\nvar io = fs.readFileSync('Azeroth.wdt');\nvar stream = new r.DecodeStream(io);\n\nvar wdt = WDT.decode(stream);\nwdt.version // 18\nwdt.flags   // 0\nwdt.tiles[30 * 64 + 24] // 0\nwdt.tiles[30 * 64 + 25] // 1\n```\n\n### [WMO](src/lib/wmo)\n\nRoot world map definition file listing textures, doodads and orientation.\n\nActual model data is stored in [group files](#wmo-group).\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar WMO = require('blizzardry/lib/wmo');\n\nvar io = fs.readFileSync('trolltent.wmo');\nvar stream = new r.DecodeStream(io);\n\nvar wmo = WMO.decode(stream);\nwmo.version    // 17\nwmo.flags      // 1\nwmo.groupCount // 1\n\nwmo.MOTX.filenames // ['DUNGEONS\\\\TEXTURES\\\\ROOF\\\\BM_TROLL_KOTOSKIN01.BLP', ...]\n```\n\n#### [WMO Group](src/lib/wmo/group.js)\n\nFor a root file named `trolltent.wmo`, its group files are named `trolltent_000.wmo`,\n`trolltent_001.wmo` and so forth.\n\nThe amount of groups is exposed as `groupCount` in the root file (see above).\n\n```javascript\nvar r = require('blizzardry/lib/restructure');\nvar WMOGroup = require('blizzardry/lib/wmo/group');\n\nvar io = fs.readFileSync('trolltent_000.wmo');\nvar stream = new r.DecodeStream(io);\n\nvar group = WMOGroup.decode(stream);\ngroup.version // 17\ngroup.flags   // 1\ngroup.MOVT.vertices[0] // [ 3.1721.., 10.4109.., 5.7666.. ]\n```\n\n## Development \u0026 Contribution\n\nBlizzardry is written in [ES2015], compiled by [Babel], developed with [Gulp]\nand tested through [Mocha].\n\nGetting this toolchain up and running, is easy and straight-forward:\n\n1. Get the code:\n\n   ```shell\n   git clone git://github.com/wowserhq/blizzardry.git\n   ```\n\n2. Download and install [Node.js] – including `npm` – for your platform.\n\n3. Install dependencies:\n\n   ```shell\n   npm install\n   ```\n\n4. Install [BLPConverter](#blp) and [StormLib](#mpq) as outlined above.\n\n5. Run `npm run gulp` which will automatically build and test the project when\n   source files change.\n\nWhen contributing, please:\n\n- Fork the repository\n- Accompany each logical unit of operation with at least one test\n- Open a pull request\n\n[Babel]: https://babeljs.io/\n[Blizzard]: http://blizzard.com\n[BLPConverter]: https://github.com/Kanma/BLPConverter\n[CascLib]: https://github.com/ladislav-zezula/CascLib\n[CMake]: http://www.cmake.org\n[ES2015]: https://babeljs.io/docs/learn-es2015/\n[Gulp]: http://gulpjs.com/\n[Homebrew]: http://brew.sh/\n[Mocha]: http://mochajs.org/\n[Node.js]: http://nodejs.org/#download\n[StormLib]: https://github.com/ladislav-zezula/StormLib\n[Wrath of the Lich King]: http://us.blizzard.com/en-us/games/wrath/\n[mipmaps]: https://en.wikipedia.org/wiki/Mipmap\n[npm]: https://www.npmjs.com/\n[most Blizzard games]: http://en.wikipedia.org/wiki/MPQ#Usage_in_gaming\n[recent Blizzard games]: http://en.wikipedia.org/wiki/MPQ#Replacement:_CASC\n[soon™]: http://www.wowwiki.com/Soon\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwowserhq%2Fblizzardry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwowserhq%2Fblizzardry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwowserhq%2Fblizzardry/lists"}