Release: heroprotocol-node

Alexis Abril
May 16, 2018 · 3 min read
Image for post
Image for post

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.


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:

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

  • 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

Image for post
Image for post
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


Image for post
Image for post

If you want to check out what I’m working on or have web development needs, visit

Originally published at

Articles about JavaScript, NodeJS and APIs from,

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store