sc2reader has a built in game engine that you can plug into to efficiently process replay events. You can add plugins to the engine by calling register_plugin():

import sc2reader
from sc2reader.engine.plugins import APMTracker, SelectionTracker

Plugins will be called in order of registration for each event. If plugin B depends on plugin A make sure to register plugin A first!

See the Creating a GameEngine Plugin article for instructions on making your own plugins.



This plugin is registered by default.

This plugin creates and maintains all the Unit and Ability data objects from the raw replay data. This creates all the event.player, event.unit, event.ability object references and maintains other game data structures like objects.



This plugin is registered by default.

This plugin fixes player lists, teams, game lengths, and frames for games that were played with the GameHeart mod.


The APMTracker adds three simple fields based on a straight tally of non-camera player action events such as selections, abilities, and hotkeys.

  • player.aps = a dictionary of second => total actions in that second
  • player.apm = a dictionary of minute => total actions in that minute
  • player.avg_apm = Average APM as a float



This plugin is intended to be used in conjunction with other user written plugins. If you attempt to use the player.selection attribute outside of a registered plugin the values will be the values as they were at the end of the game.

The SelectionTracker maintains a person.selection structure maps selection buffers for that player to the player’s current selection:

active_selection = event.player.selection[10]

Where buffer is a control group 0-9 or a 10 which represents the active selection.