heroprotocol is a Python library and command-line tool to decode Heroes of the Storm replay files into Python data structures.
The tool is available as a PyPI Package or as source code.
Currently heroprotocol can decode these structures and events:
heroprotocol can be used as a base-build-specific library to decode binary blobs, or it can be run as a standalone tool to pretty print information from supported replay files.
Note that heroprotocol does not expose game balance information or provide any kind of high level analysis of replays; it's meant to be just the first tool in the chain for your data mining application.
heroprotocol supports all Hereos of the Storm replay files that were played with retail and PTR versions of the game.
Either install/update using pip:
python -m pip install --upgrade heroprotocol
Or clone the repository and run from source:
git clone https://github.com/Blizzard/heroprotocol.git python -m pip install -r ./heroprotocol/heroprotocol/requirements.txt
-h, --help Show the options that are available. Tracker Events: --gameevents Print all game events including coordinates --messageevents Print message events such as ping events --trackerevents Print tracker events such as units killed, game stat events, score result event --attributeevents Print attribute events, a table of attrid, namespace, and attribute values --header Print protocol header including build id and elapsedGameLoops --details Print protocol details, e.g. teamId, player names and chosen heroes, player region, game result, observer status --initdata Print protocol initdata, e.g. interface settings for every player Output Options: --stats Output stats about the active tracker event to the STDERR stream --json Use JSON syntax for output
If you want the output shown directly in the terminal, leave out the
python -m heroprotocol --details "Blackheart's Bay.StormReplay" > output.txt
By default, data is output as a Python dictionary object. To output a JSON file, add
Note, however, that the JSON file is formatted as a sequence/stream of JSON objects and will likely not parse as regular JSON.
Some notes on tracker events:
unitIndex = event['m_firstUnitIndex'] for i in range(0, len(event['m_items']), 3): unitIndex += event['m_items'][i + 0] x = event['m_items'][i + 1] * 4 y = event['m_items'][i + 2] * 4 # unit identified by unitIndex at the current event['_gameloop'] time # is at approximate position (x, y)
Please report bugs at the Heroes of the Storm Bug Report Forum.
Thank you to David Joerg and Graylin Kim of GGTracker for design feedback and beta-testing of the s2protocol library that heroprotocol is based upon.
Thanks to Ben Barrett of HOTSLogs for early feedback on and beta-testing of the heroprotocol library.
Copyright 2021 Blizzard Entertainment
Source code for this project is released to the public under the MIT license. See the included LICENSE file for more information.