Skip to content
Python library to decode StarCraft II replay protocols
Python
Failed to load latest commit information.
mpyq initial commit: base versions 23260 and 24944 Apr 17, 2013
.gitattributes Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
.gitignore initial commit: base versions 23260 and 24944 Apr 17, 2013
LICENSE initial commit: base versions 23260 and 24944 Apr 17, 2013
README.md Fix python block syntax May 7, 2013
__init__.py adding init so that this can be used as a module May 8, 2013
decoders.py fix for missing fields during decoding Aug 1, 2013
protocol15405.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol16561.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol16605.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol16755.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol16939.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol17266.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol17326.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol18092.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol18468.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol18574.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol19132.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol19458.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol19595.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol19679.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol21029.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol21995.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol22612.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol23260.py initial commit: base versions 23260 and 24944 Apr 17, 2013
protocol24764.py added support for old ptr and beta versions Aug 5, 2013
protocol24944.py added old protocols May 6, 2013
protocol26490.py added support for patch 2.0.10 replays Jul 31, 2013
protocol27950.py added protocol27950 (2.1 PTR) Dec 9, 2013
protocol28272.py added protocol28272 (2.1 PTR patch #1) Jan 15, 2014
protocol28667.py added protocol28667 (2.1 patch) Jan 22, 2014
protocol32283.py added protocol32283 (2.1.4 patch) Sep 23, 2014
protocol34784.py added protocol34784 (Void Beta) Apr 1, 2015
protocol34835.py added protocol34835 (Void Beta) Apr 2, 2015
protocol36442.py added protocol36442 (Void Beta) Jul 17, 2015
protocol38215.py added protocol38215 (3.0 patch) Oct 6, 2015
protocol38535.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol38624.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol38749.py added protocol38749 (3.0.3 patch) Oct 26, 2015
protocol38996.py added protocol38996 (3.0.4 patch) Nov 11, 2015
protocol39117.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol39576.py added protocol39576 (3.1.0 patch) Dec 15, 2015
protocol39948.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol40384.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol40977.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol41128.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol41219.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol41743.py added protocol41743 (3.2 patch) Mar 29, 2016
protocol41973.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol42253.py Automated upload of generated SC2 Replay Protocol. (3.2.3.42253) Apr 26, 2016
protocol42932.py Automated upload of generated SC2 Replay Protocol. (3.3.0.42932) May 18, 2016
s2protocol.py added old protocols May 6, 2013

README.md

S2 Protocol

s2protocol is a reference Python library and standalone tool to decode StarCraft II replay files into Python data structures.

Currently s2protocol can decode these structures and events:

  • replay header
  • game details
  • replay init data
  • game events
  • message events
  • tracker events

s2protocol 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 s2protocol 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

s2protocol supports all StarCraft II replay files that were written with retail versions of the game. The current plan is to support all future publicly released versions, including public betas.

Tracker Events

Some notes on tracker events:

  • Tracker events are new in version 2.0.8, they do not exist in replays recorded with older versions of the game.
  • 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:
    unitIndex = event['m_firstUnitIndex']
    for i in xrange(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.

License

Copyright (c) 2013 Blizzard Entertainment

Open sourced under the MIT license. See the included LICENSE file for more information.

Acknowledgements

The standalone tool uses mpyq to read mopaq files.

Thanks to David Joerg and Graylin Kim of GGTracker for design feedback and beta-testing.

Something went wrong with that request. Please try again.