SC2Reader User Manual

There is a pressing need in the SC2 community for better statistics, better analytics, better tools for organizing and searching replays. Better websites for sharing replays and hosting tournaments. These tools can’t be created with out first being able to open up replay files and analyze the content within. That’s why sc2reader was built, to provide a solid foundation on which the next generation of tools and websites can be built and benefit the community.

So lets get you started right away! Through the linked tutorials and reference pages below we’ll get you started building your own tools and systems in no time. Any questions, suggestions, or concerns should be posted to the sc2reader mailing list. You can also pop on to our #sc2reader, our IRC channel on Freenode if you want to chat or need some live support.


Checkout our Frequently Asked Questions. If your question isn’t covered there, let us know and we’ll add it to the list.

About sc2reader

sc2reader is an open source, MIT licensed, python library for extracting game play information from Starcraft II replay and map files. It is production ready, actively maintained, and hosted publicly on Github [source].


  • Fully parses and extracts all available data from all replay files (arcade included) from every official release (plus the HotS Beta).
  • Automatically retrieves maps; extracts basic map data and images. Maps unit type and ability link ids to unit/ability game data.
  • Processes replay data into an interlinked set of Team, Player, and Unit objects for easy data manipulation


  • Selection Tracking: See every player’s current selection and hotkeys at every frame of the game.
  • APM Tracking: Provides basic APM information for each player by minute and as game averages.
  • GameHeartNormalizer: Fixes teams, races, times, and other oddities typical of GameHeart games.


  • sc2printer: Print basic replay information to the terminal.
  • sc2json: Render basic replay information to json for use in other languages.
  • sc2replayer: Play back a replay one event at a time with detailed printouts.

I am actively looking for community members to assist in documenting the replay data and in creating plugins that enhance functionality. Contact me!

Getting Started

I recommend the following steps when getting started:

Now that you’ve been oriented, you can see sc2reader in action by working through a couple of the tutorials below.


The best way to pick sc2reader up and get started is probably by example. With that in mind, we’ve written up a series of tutorials on getting various simple tasks done with sc2reader; hopefully they can serve as a quick on ramp for you.


A collection of short handwritten articles about aspects of working with replays and sc2reader.