DOCSEARCHbyAlgolia
Submit Docs

heroprotocol Documentation

repository·master·Indexed 19 days ago

https://github.com/blizzard/heroprotocol

A Python library and CLI tool for decoding Heroes of the Storm replay files into structured Python dictionaries or JSON. It provides functionality for data mining, including tools for interpreting SUnitPositionsEvent tracker events, managing unit lifecycles, and processing player stats.

Tokens
1.4K
Snippets
4
Records
5
Agent score
14%

What's inside heroprotocol

  1. How to handle unit lifecycle and stats in tracker events

    master

    When processing tracker events, keep the following logic in mind:

    Unit Lifecycle

    • Construction: NNet.Replay.Tracker.SUnitInitEvent indicates a unit is under construction. A NNet.Replay.Tracker.SUnitDoneEvent with the same tag follows when complete.
    • Creation: NNet.Replay.Tracker.SUnitBornEvent indicates a unit was created fully constructed.
    • Death: A NNet.Replay.Tracker.SUnitDiedEvent may follow either a UnitInit or UnitBorn event.
    • Unit Tags: To convert unit tag index/recycle pairs into unit tags, use protocol.unit_tag(index, recycle).

    Player Stats

    • In NNet.Replay.Tracker.SPlayerStatsEvent, the fields m_scoreValueFoodUsed and m_scoreValueFoodMade are in fixed point. Divide them by 4096 to get the integer values. All other values are integers.

    Known Limitations

    • Revived units are not currently tracked.
    • Placeholder units track death but not birth.

  2. How to interpret SUnitPositionsEvent tracker events

    master

    To determine the approximate (x, y) position of a unit from an NNet.Replay.Tracker.SUnitPositionsEvent, you must iterate through the m_items list in steps of 3. The unitIndex is updated cumulatively using m_firstUnitIndex and the values in the items list. Coordinates must be multiplied by 4 to get the correct position.

    Important Notes:

    • Only units that have inflicted or taken damage are included in these events.
    • There is a limit of 256 units mentioned per event.
    • The unitIndex refers to the unit at the current event['_gameloop'] time.
    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)

  3. Install heroprotocol via pip or source

    master

    You can install heroprotocol directly from PyPI using pip, or by cloning the repository and installing from source.

    Requirements:

    • Python 2.7 or 3.x
    • mpyq 0.2.5+
    • six 1.14.0+
    # Install via pip
python -m pip install --upgrade heroprotocol

# Install from source
git clone https://github.com/Blizzard/heroprotocol.git
python -m pip install -r ./heroprotocol/heroprotocol/requirements.txt

  4. Reference: heroprotocol CLI arguments

    master

    The following flags are available for the heroprotocol command-line tool to control which data structures are printed from the replay file.

    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

  5. Use the heroprotocol CLI to decode replays

    master

    The heroprotocol command-line tool can decode Heroes of the Storm replay files into Python dictionaries or JSON. By default, the output is a Python dictionary object. To output a JSON file, use the --json flag.

    Note: The JSON output is formatted as a sequence/stream of JSON objects and may not parse as a single standard JSON document.

    # Decode a replay and save to a file (default Python dict output)
python -m heroprotocol --details "Blackheart's Bay.StormReplay" > output.txt

# Decode a replay to JSON format
python -m heroprotocol --details --json "Blackheart's Bay.StormReplay" > output.json