Behind the scenes at, we are avid gamers. Heroes of the Storm is a game we are quite fond of and have put a bit of time into, both on the play aspect as well as game analysis. Being able to automate specific analysis, whether it is general stats or individual gameplay, is a topic many gamers in the software-development industry subscribe to.

With the release of Blizzard's heroprotocol scripts in 2015, we are able to parse *.StormReplay files. As we are primarily JavaScript developers, we had a need to parse a replay file and use the data from NodeJS. Thus, we wrote heroprotocol-node. There were a couple of existing Node ports of the heroprotocol library. However, we had a few goals we wanted to accomplish with heroprotocol-node:

  • Expose the parsing API as a NodeJS module
  • Guarantee future compatibility
  • Minimize maintenance
  • Closely match the official Heroes of the Storm release cycle

heroprotocol-node simply grants a Node API to match the official heroprotocol API.


For example, to generate a gameevents report with the official Python scripts:

py --gameevents "path/to/replay.StormReplay"

The above command is done from the command-line using Python 2.7 and prints to stdout. As we desired programmatic usage, the following API was chosen:

const heroprotocol = require('heroprotocol');

heroprotocol.gameevents('path/to/replay.StormReplay').then(output => {
  //output is a JSON object!

This allows us to generate a report, or many, then use that data in some other process. We have a few analytical itches to scratch in this department, so generating reports programmatically was a primary need.

See the full usage here.

Compatibility and maintenance

A couple of key points in heroprotocol-node:

  • All methods return promises
  • All requested data is in JSON

Rather than port the official heroprotocol project, we only call the underlying Python scripts and return their data via a promise., by default, does not return JSON. Including the --json option returns a number of JSON objects, separated by newlines. We prefer a single, JSON response and utilized a modified Python script from As the official heroprotocol project still handles the heavy lifting for parsing replay files, we can remain compatible for all future versions Blizzard supports.

Release schedule

Heroes of the Storm is constantly patched, with updates occurring multiple times per week. To closely mirror official releases, we have the following flow:

Architecture heroprotocol-node architecture diagram

ReleaseHawk monitors changes to the official heroprotocol repo. If a change is detected, a pull-request is created in the heroprotocol-node repo to update. Once our automated tests have run, if the board is green, we'll merge the PR and publish an updated version to NPM. The merge and publish steps are currently manual as we're verifying our processes. As more patches occur without issue, this process becomes more and more automated. For keeping our Node dependencies current, we utilize


If you're interested in parsing Heroes of the Storm replay files and use NodeJS, this project is for you. Let us know in the issues if you have any questions, concerns, or feature requests! We built this project to aid in other analytical applications we're developing and hope this can be of use to the community.

WC2 Art