Concepts in sc2reader

Some of the important concepts in sc2reader in no particular order.


All resources are loaded through a factory. There are four kinds:

  • SC2Factory - Basic factory. Loads resources.
  • DictCachedSC2Factory - Caches remote resources in memory. When loading remote resources, the dict cache is checked first.
  • FileCachedSC2Factory - Caches remote resources on the file system. When loading remote resources, the file system is checked first.
  • DoubleCachedSC2Factory - Caches remote resource in memory and on the file system.

A default factory is automatically configured and attached to the sc2reader module when the library is imported. Calling any factory method on the sc2reader module will use this default factory:

replay = sc2reader.load_replay('my_replay.SC2Replay')

The default factory can be configured with the following environment variables:

  • SC2READER_CACHE_DIR - Enables caching to file at the specified directory.
  • SC2READER_CACHE_MAX_SIZE - Enables memory caching of resources with a maximum number of entries; not based on memory imprint!


A Starcraft II resource is any Starcraft II game file. This primarily refers to Replay and Map resources but also includes less common resources such as GameSummary, Localization, and SC2Mods.

Player vs User

All entities in a replay fall into one of two overlapping buckets:

  • User: A human entity, only users have game and message events.
  • Player: A entity that actively plays in the game, only players have tracker events.

As such the following statements are true:

  • A Participant is a Player and a User
  • An Observer is a User and not a Player
  • An Computer is a Player and not a User

Game vs Real

Many attributes in sc2reader are prefixed with game_ and real_. Game refers to the value encoded in the replay. Real refers to the real life value, as best as we can tell. For instance, game_type might be 2v2 but by looking at the teams we know that real_type is 1v1.


The game engine is used to process replay events and augument the replay with new statistics and game state. It implements a plugin system that allows developers to inject their own logic into the game loop. It also allows plugins to yield new events to the event stream. This allows for basic message passing between plugins.

A default engine is automatically configured and attached to the sc2reader.engine module when the library is imported. Calling any game engine method on the engine module will use this default factory:



A datapack is a collection of Unit and Ability classes that represent the game meta data for a given replay. Because this information is not stored in a replay, sc2reader ships with a datapack for standard ladder games from each Starcraft patch.

For non-standard maps, this datapack will be both wrong and incomplete and the Unit/Ability data should not be trusted. If you want to add a datapack for your map, see the article on Adding new Datapacks.