# google-deepmind/pysc2

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/google-deepmind-pysc2).**

_How this analysis was created: the description and tags below were written by an AI model that read this project's README and public documentation pages; stars, license and language come straight from the GitHub API. The model does not read the source code._

8,336 stars · 1,162 forks · Python · Apache-2.0

## Links

- GitHub: https://github.com/google-deepmind/pysc2
- awesome-repositories: https://awesome-repositories.com/repository/google-deepmind-pysc2.md

## Topics

`blizzard-api` `deepmind` `machine-learning` `reinforcement-learning` `starcraft-ii` `starcraft-ii-replays`

## Description

PySC2 is a Python library that exposes StarCraft II as a reinforcement learning environment. Agents receive observations and send actions through repeated observe-and-act cycles, with one or two players in the same game session. It is built as a research platform for developing and benchmarking machine learning agents on a real-time strategy game with partial information and long-horizon planning.

The way the game is presented to an agent is a central part of the project. Observations come as stacked feature layers for the screen and minimap, as rendered RGB images, or as raw unit data addressed by unit tags, alongside non-visual game information delivered as tensors. Actions are typed function calls with arguments, and each observation lists only the functions valid at that moment, which avoids one huge flat action space. Converters turn raw game protocol messages into dictionaries of numeric arrays with matching specs, so neural networks can consume observations and emit actions directly. They can be configured per episode or wrapped inside an environment.

The environment is configurable: you choose the map, the players and their difficulty, the observation resolution, the action space, and how many frames to skip per step. Custom maps and mini-game scenarios are defined by subclassing a map base class that sets episode length, player count, and scoring. Training content ranges from single-skill mini-games with score-based rewards to machine-learning melee maps and the multiplayer maps used on the online ladder. Baseline agents, including a random player and scripted mini-game players, serve as starting points.

The library also covers replays and debugging. Episodes can be saved as replays, played back with video export, and processed in parallel into the same array format used live, which allows offline training datasets to be built from recorded games. A visual interface lets a person play by hand or watch an agent while viewing the rendered feature layers.

## Tags

### Artificial Intelligence & ML

- [Reinforcement Learning Environments](https://awesome-repositories.com/f/artificial-intelligence-ml/reinforcement-learning-environments.md) — Wraps StarCraft II as a Python reinforcement learning environment where agents receive observations, send actions, and train on mini-games and full matches.
- [Agent Action Spaces](https://awesome-repositories.com/f/artificial-intelligence-ml/agent-action-spaces.md) — Defines how a game is presented to a learning agent, with typed function-call actions and per-frame lists of currently valid actions.
- [Agent-Environment Interaction Loops](https://awesome-repositories.com/f/artificial-intelligence-ml/agent-environment-interaction-loops.md) — Drives one or two players through repeated observe-and-act cycles in the same game session, stepping a configurable number of frames each time.
- [Feature Layer Observations](https://awesome-repositories.com/f/artificial-intelligence-ml/feature-layer-observations.md) — Exposes about twenty-five structured feature layers for the screen and minimap, giving agents meaningful grids instead of raw pixels. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/environment.md))
- [Game Environment Configuration](https://awesome-repositories.com/f/artificial-intelligence-ml/game-environment-configuration.md) — Lets users choose the map, players and difficulty, observation resolution, action space, and frames skipped per step when setting up a game environment. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/environment.md))
- [Game Observation and Action Converters](https://awesome-repositories.com/f/artificial-intelligence-ml/game-observation-and-action-converters.md) — Convert raw game protocol messages into neural-network-friendly dictionaries of numeric arrays with matching specs, so learning agents can read observations and send actions. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/converters.md))
- [Observation and Action Converters](https://awesome-repositories.com/f/artificial-intelligence-ml/observation-and-action-converters.md) — Converts raw game protocol messages into dictionaries of numeric arrays with matching specs so neural networks can consume observations and emit actions.
- [Spatial Feature Layers](https://awesome-repositories.com/f/artificial-intelligence-ml/spatial-feature-layers.md) — Breaks the screen and minimap into stacked grids of unit attributes so agents read meaningful values instead of raw pixels.
- [Agent Map Launchers](https://awesome-repositories.com/f/artificial-intelligence-ml/agent-map-launchers.md) — Launches a random, scripted, or custom agent on a selected map with a visual interface, or pits two agents against each other. ([source](https://github.com/google-deepmind/pysc2/blob/master/README.md))
- [Mini-Game Training Scenarios](https://awesome-repositories.com/f/artificial-intelligence-ml/mini-game-training-scenarios.md) — Offers single-player, fixed-length mini-game scenarios that each exercise one skill and expose a score or reward separating poor from strong play. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/maps.md))
- [Multi-Modal Game Observations](https://awesome-repositories.com/f/artificial-intelligence-ml/multi-modal-game-observations.md) — Offers structured feature layers, rendered RGB images, and a raw unit-data interface so agents can choose how to see the game.
- [Replay Processing Pipelines](https://awesome-repositories.com/f/artificial-intelligence-ml/observation-processing/visual-observation-pipelines/replay-processing-pipelines.md) — Plays back recorded games in parallel and converts them into observation and action arrays for building offline training datasets.
- [Pixel-Based Game Agent Training](https://awesome-repositories.com/f/artificial-intelligence-ml/reinforcement-learning/pixel-based-game-agent-training.md) — Trains agents on small focused scenarios that each exercise one skill, using score-based rewards to build toward full-length matches.
- [RGB Pixel Observations](https://awesome-repositories.com/f/artificial-intelligence-ml/rgb-pixel-observations.md) — Provides the main screen and minimap as color images at a chosen resolution, matching a human player's view without menus. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/environment.md))
- [Spatial Observation Planes](https://awesome-repositories.com/f/artificial-intelligence-ml/spatial-observation-planes.md) — Represents most observations as spatial planes of unit attributes for screen and minimap, and accepts point-and-click actions like a human player. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/converters.md))
- [Visual Observation Interfaces](https://awesome-repositories.com/f/artificial-intelligence-ml/visual-observation-interfaces.md) — Presents game state to agents as stacked feature layers and RGB images of the screen and minimap, plus non-visual tensors.

### Part of an Awesome List

- [Real-Time Strategy Game Agents](https://awesome-repositories.com/f/awesome-lists/ai/reinforcement-learning-agents/real-time-strategy-game-agents.md) — Supports training and evaluating agents that learn to play StarCraft II through observe-and-act loops against built-in opponents or other agents.

### Game Development

- [Game Simulation Environments](https://awesome-repositories.com/f/game-development/game-simulation-environments.md) — Sets up configurable simulated game worlds with chosen maps, opponents, difficulty, and scoring so researchers can run controlled machine learning experiments.
- [Custom Map Definitions](https://awesome-repositories.com/f/game-development/custom-map-definitions.md) — Defines custom maps by subclassing a base class that sets file location, episode length, player count, and scoring, then registers them on import. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/maps.md))

### Development Tools & Productivity

- [Game Replay Parsers](https://awesome-repositories.com/f/development-tools-productivity/deterministic-record-and-replay-frameworks/game-replay-parsers.md) — Runs recorded replays through a converter to produce the same array-based data format as live environments, enabling offline training on past games. ([source](https://github.com/google-deepmind/pysc2/blob/master/docs/converters.md))