DOCSEARCHbyAlgolia
Submit Docs

sc2reader

repository·upstream·Indexed 41 days ago

https://github.com/ggtracker/sc2reader

A Python 3 library for parsing StarCraft II replay files, maps, and game summaries. It provides a GameEngine with a plugin system for processing events, a factory system for resource loading and caching, and built-in datapacks for unit and ability metadata.

Tokens
17.1K
Snippets
51
Records
102
Agent score
47%

What's inside sc2reader

  1. Overview of sc2reader features and capabilities

    upstream

    sc2reader is an open-source Python library designed to extract gameplay information from StarCraft II replay and map files. It is suitable for building statistics, analytics, and replay organization tools.

    Core Features

    • Full Parsing: Extracts all available data from replay files (including Arcade) across all official game releases.
    • Map Handling: Automatically retrieves maps, extracts basic map data/images, and links unit/ability IDs to game data.
    • Object Model: Processes raw replay data into an interlinked set of Team, Player, and Unit objects for easy manipulation.

    Available Plugins

    • Selection Tracking: Tracks every player's current selection and hotkeys at every frame.
    • APM Tracking: Provides APM (Actions Per Minute) information by minute and as game averages.
    • GameHeartNormalizer: Normalizes data (teams, races, times) for GameHeart games.

    Included Scripts

    • sc2printer: Prints basic replay information to the terminal.
    • sc2json: Renders replay information to JSON for use in other programming languages.
    • sc2replayer: Plays back a replay one event at a time with detailed printouts.

  3. What is a Datapack in sc2reader?

    upstream

    A Datapack is a collection of sc2reader.data.Unit and sc2reader.data.Ability classes that represent the game metadata for a specific replay. Since this metadata is not stored within the replay file itself, sc2reader includes built-in datapacks for standard ladder games from various StarCraft patches.

    Warning: For non-standard maps, the built-in datapack may be incorrect or incomplete. In such cases, Unit and Ability data should not be trusted. To support custom maps, you must provide your own datapack.

  4. Handle events in a GameEngine Plugin

    upstream

    Plugins can opt in to handle specific events by implementing methods following the naming convention: handleEventName(self, event, replay).

    Event Handler Hierarchy

    The engine matches handlers from most general to most specific. You can handle specific event types or use built-in parent classes to catch groups of events:

    • handleEvent: Called for every single event of all types.
    • handleMessageEvent: Called for events in replay.message.events.
    • handleGameEvent: Called for events in replay.game.events.
    • handleTrackerEvent: Called for events in replay.tracker.events.
    • handlePlayerActionEvent: Called for all game events indicating player actions.
    • handleAbilityEvent: Called for all types of ability events.
    • handleHotkeyEvent: Called for all player hotkey events.

    Handler Execution Order

    When an event occurs, the engine loops through registered plugins. If multiple handlers match, they are called in order of registration, moving from general handlers to specific ones.

    Example Order: For a TargetAbilityEvent, the engine might call:

    1. Plugin1.handleAbilityEvent (General)
    2. Plugin2.handleEvent (Most General)
    3. Plugin2.handleTargetAbilityEvent (Specific)

  5. Understand the core structures in sc2reader.resources

    upstream

    The sc2reader.resources module provides the primary data structures used to represent StarCraft II replay data. When you load a replay, the resulting object contains several key components:

    • Replay: The top-level container representing the entire replay file, including players, chat, and event streams.
    • Map: Information about the map used in the game (name, dimensions, etc.).
    • GameSummary: High-level metadata about the match, such as game length, speed, and basic match details.

  6. Understand and use Tracker Events

    upstream
    Tracker events are engine-generated events introduced in Starcraft patch 2.0.8. They represent important non-player occurrences or periodic snapshots of the game state. You can access these events via the sc2reader.events.tracker module. These events are useful for monitoring game state changes that are not directly tied to player actions, such as periodic snapshots of resources or unit counts.

  7. Understand the structure of a SC2Replay file

    upstream

    A SC2Replay file is an archive (similar to a .zip or .tar file) containing several files that define the game state and events. The data is categorized into three main types:

    1. Initial State: Files that describe the game before any events occur (e.g., replay.initData, replay.details, and replay.attributes.events).
    2. Input Events: A feed of player actions, including chat messages/pings (replay.message.events) and every action taken by players (replay.game.events). Note that AI actions are not recorded because the game is deterministic.
    3. Output Events: A record of important game events and state updates (replay.tracker.events). This was introduced in patch 2.0.4 and is primarily used by community developers for replay analysis rather than game reproduction.

    Understanding this structure is essential when determining what kind of data can be extracted directly from a replay file versus what must be simulated or inferred.

  8. Access Replay attributes and nested data

    upstream

    The Replay object is a data structure where information is accessed via attributes rather than methods. Many attributes are nested objects that can be traversed using dot notation or indexing.

    Common Replay Attributes:

    • replay.filename: Path to the file.
    • replay.release_string: SC2 version.
    • replay.category: Game type (e.g., 'Ladder').
    • replay.start_time: Start timestamp.
    • replay.type: Match type (e.g., '2v2').
    • replay.map_name: Name of the map.
    • replay.game_length: Match duration.
    • replay.teams: A list of Team objects.

    Nested Access Examples:

    • Accessing a player's color hex: replay.teams[0].players[0].color.hex
    • Accessing a player's profile URL: replay.player.name('PlayerName').url

  9. Understand the types of events in sc2reader

    upstream

    All gameplay and state information within a StarCraft II replay is represented as events. There are three primary categories of events you can extract:

    1. game events: Capture human actions (e.g., unit commands) and specific triggered game events.
    2. message events: Capture chat messages and pings sent between players.
    3. tracker events: Capture raw game state information (e.g., unit health, position, and resource counts) provided by the game engine.

  11. Default plugins: ContextLoader and GameHeartNormalizer

    upstream

    The following plugins are registered by default and do not require manual registration:

    • ContextLoader: Creates and maintains sc2reader.data.Unit and sc2reader.data.Ability objects. It populates event.player, event.unit, and event.ability object references and maintains Replay.objects.
    • GameHeartNormalizer: Fixes player lists, teams, game lengths, and frames for replays played with the GameHeart mod.

  12. Understand the difference between Player and User

    upstream

    In sc2reader, entities in a replay are categorized into two overlapping groups based on the types of events they generate:

    • User: A human entity. Only Users generate game and message events.
    • Player: An entity that actively plays in the game. Only Players generate tracker events.

    This leads to the following classifications:

    • Participant: Both a Player and a User.
    • Observer: A User, but NOT a Player.
    • Computer: A Player, but NOT a User.