How do I parse StarCraft 2 replay files (.sc2replay)? Is there an API?

I know of Sc2gears, but it doesn't quite fulfil my needs.


closed as off-topic by Vaillancourt, MAnd, Kromster says support Monica, Jesse Dorsey Feb 12 '16 at 14:42

  • This question does not appear to be about game development within the scope defined in the help center.
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 3
    \$\begingroup\$ I'm voting to close this question as off-topic because it's not about developing a game. \$\endgroup\$ – Vaillancourt Feb 8 '16 at 20:00

The Starcraft 2 replays are stored as MPQ a compressed file-format developed and used by Blizzard. On the bottom of the Wiki page you'll also find links to MPQ parsers.

Maybe you'll also want to have a look at the following open-source projects: WARP (a Starcraft 2 replay parser written in Java) or phpsc2replay (a replay parser written in PHP).

Update: As of now, there's also a Python library out there that can read a lot of the replay data: sc2reader. This is most likely the best option that is currently available (as of March 2013).

Update 2018: sc2reader is now maintained by ggtracker. Anyway sc2reader is hosted now on PyPi so maybe the best way is to pip install sc2reader and find it on sc2readers pypi page


Disclosure: I'm the author of Scelight and Sc2gears.

Blizzard released an official, open-source SC2Replay file parser library called s2protocol written in python:


That is the most complete, up-to-date, official replay parser. It is considered the reference implementation. It is quite low-level though.

There is another project called Scelight (which is the successor to Sc2gears). In Scelight there is a setting (a combobox): Skill level. If you set this to Developer (this requires a tiny programming task to be solved first to prove your developer skills to unlock it), a whole bunch of new information is displayed for opened replays in the Inspector tab of the Replay Analyzer which are intended for developers only including the internal structure of replays including every last bit of it, hex viewer and much more.

Scelight also has an extension interface called External Module API which has a well documented API. The External Module API provides access to SC2Replay parser and both low and high-level replay internal datastructures and tools.The javadoc of the External Module API is also available online here:



Both Scelight and Sc2gears have been open-sourced, you can see exactly how they do it (both projects count more than 100,000 lines of code):




I played with parsing the SC2 replay files a while back. You can view what I've done and what I've been able to reverse engineer (as well as bunch of links to helpful sites at the bottom):


  • \$\begingroup\$ A bunch of links in one place is really nice. \$\endgroup\$ – kirilloid Apr 30 '13 at 10:21

Not the answer you're looking for? Browse other questions tagged or ask your own question.