Concepts in sc2reader¶
Some of the important concepts in sc2reader in no particular order.
Factories¶
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:
sc2reader.configure(debug=True)
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!
Resources¶
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.
GameEngine¶
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:
sc2reader.engine.register_plugin(MyPlugin())
sc2reader.engine.run(replay)
Datapack¶
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.