Metadata-Version: 2.1
Name: heroprotocol
Version: 2.55.3.88481
Summary: Python library to decode Heroes of the Storm replays
Home-page: https://github.com/Blizzard/heroprotocol
Author: Blizzard Entertainment
Author-email: HeroesReplays@blizzard.com
License: UNKNOWN
Description: # heroprotocol
        
        heroprotocol is a [Python](https://www.python.org/downloads/) 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](https://pypi.org/project/heroprotocol/) or as source code.
        
        Currently heroprotocol can decode these structures and events:
        
        * Replay header
        * Game details
        * Replay init data
        * Game events
        * Message events
        * Tracker 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.
        
        ## Supported Versions
        
        heroprotocol supports all Hereos of the Storm replay files that were played with retail and PTR versions of the game.
        
        ## Requirements
        
        * Python 2.7 or 3.x
          * Note: A future release may remove support for Python 2.7
        * Python Packages:
          * mpyq 0.2.5+
          * six 1.14.0+
        
        ## Installation
        
        Either install/update using pip:
        
        ```bash
        python -m pip install --upgrade heroprotocol
        ```
        
        Or clone the repository and run from source:
        
        ```bash
        git clone https://github.com/Blizzard/heroprotocol.git
        python -m pip install -r ./heroprotocol/heroprotocol/requirements.txt
        ```
        
        ## Command Line Arguments
        
        ```plain
        -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
        ```
        
        ## Example Usage
        
        If you want the output shown directly in the terminal, leave out the `> output.txt`.
        
        ```bash
        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 `--json`.
        
        **Note**, however, that the JSON file is formatted as a sequence/stream of JSON objects and
        will likely not parse as regular JSON.
        
        ## Tracker Events
        
        Some notes on tracker events:
        
        * Convert unit tag index, recycle pairs into unit tags (as seen in game events) with protocol.unit_tag (index, recycle)
        * Interpret the NNet.Replay.Tracker.SUnitPositionsEvent events like this:
        
        ```python
        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)
        ```
        
        * Only units that have inflicted or taken damage are mentioned in unit position events, and they occur periodically with a limit of 256 units mentioned per event.
        * NNet.Replay.Tracker.SUnitInitEvent events appear for units under construction. When complete you'll see a NNet.Replay.Tracker.SUnitDoneEvent with the same unit tag.
        * NNet.Replay.Tracker.SUnitBornEvent events appear for units that are created fully constructed.
        * You may receive a NNet.Replay.Tracker.SUnitDiedEvent after either a UnitInit or UnitBorn event for the corresponding unit tag.
        * In NNet.Replay.Tracker.SPlayerStatsEvent, m_scoreValueFoodUsed and m_scoreValueFoodMade are in fixed point (divide by 4096 for integer values). All other values are in integers.
        * There's a known issue where revived units are not tracked, and placeholder units track death but not birth.
        
        ## Reporting Bugs
        
        Please report bugs at the [Heroes of the Storm Bug Report Forum](https://us.forums.blizzard.com/en/heroes/c/bug-report).
        
        ## Acknowledgements
        
        The standalone tool uses [mpyq](https://github.com/eagleflo/mpyq) by
        [Aku Kotkavuo](https://github.com/eagleflo) to read mopaq files.
        
        Thank you to [healingbrew](https://github.com/healingbrew), [MGatner](https://github.com/mgatner),
        [koliva8245](https://github.com/koliva8245), [casualMLG](https://github.com/casualmlg), and others for submitting issues
        and feedback.
        
        Thank you to [Christian Clauss](https://github.com/cclauss), [Jingbei Li](https://github.com/petronny), and
        [Regner Blok-Andersen](https://github.com/regner) for contributions to the Python 3 update.
        
        Thank you to David Joerg and Graylin Kim of [GGTracker](http://www.ggtracker.com) for design feedback and beta-testing of
        the s2protocol library that heroprotocol is based upon.
        
        Thanks to Ben Barrett of [HOTSLogs](http://www.hotslogs.com) for early feedback on and beta-testing of the heroprotocol
        library.
        
        ## License
        
        Copyright 2021 Blizzard Entertainment
        
        Source code for this project is released to the public under the MIT license.
        See the included [LICENSE](LICENSE) file for more information.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment :: Real Time Strategy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Utilities
Requires-Python: >=2.7
Description-Content-Type: text/markdown
