# google-deepmind/pysc2 architecture

> Architecture diagram of the GitHub repository google-deepmind/pysc2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/pysc2
- Repository: https://github.com/google-deepmind/pysc2

## Overview

##### Main Components
- Environment Interface: This is the core of PySC2. It is located under the “pysc2/env” directory and handles communication with the StarCraft II game. It includes modules that set up the environment (sc2_env.py, run_loop.py), wrappers, and specialized converters.
- Observation and Action Converters: Under “pysc2/env/converter” you have additional layers (both Python and C++ implementations) dedicated to converting raw game data into actionable observations. This part, which includes “converter.py” along with C++ files in the “cc” subdirectory, is critical for data transformation.
- Agent Implementations: The “pysc2/agents” directory defines multiple baseline agents (no_op_agent, random_agent, scripted_agent). This represents the intelligence layer that receives observations and issues commands.
- Command-line Interfaces and Utilities (Binaries): The “pysc2/bin” directory houses executable scripts (e.g., agent.py, play.py, run_tests.py) that tie together user inputs, running specific agents, or playing games. They serve as the entry points for different use cases like testing, playing as a human, or running automated agents.
- Build and Dependencies Management: The “bazel” directory with multiple BUILD files, patches, and external repository setup scripts indicates the use of Bazel for building parts of the system (especially the C++ components) and managing dependencies.
- Libraries and Helpers: The “pysc2/lib” directory includes modules to support actions, rendering (e.g., renderer_human, renderer_ascii), replay processing, and other utilities. These support the other major components by providing common functionality.
- Maps and Configurations: The “pysc2/maps” and “pysc2/run_configs” directories provide game-specific configurations, map definitions, and settings needed for executing particular scenarios or mini-games.
- Testing: The “pysc2/tests” directory comprises unit and integration tests ensuring each module (from converters to agents) works as expected.

##### Relationships and Interactions
- The Agents send commands via the Environment Interface.
- The Environment Interface communicates with the external StarCraft II game (installed separately, as per the README instructions) by calling specific APIs and handling game state.
- The Converters (both Python and C++ implemented) process raw observations from the game, transforming them into a format useful for agents.
- Command-line binaries (located in pysc2/bin) orchestrate the entire flow (from launching an agent to playing the game and recording replays).
- The Bazel build files connect with the native C++ components in the converter modules to ensure correct compilation and linking.
- Utility libraries support common operations (action processing, replays, metrics) used throughout the system.
- Testing modules verify each interaction: for instance, running tests on observation processing, agent behaviors, and environment functionality.

##### Architectural Patterns and Design Principles
- Modularity: The project is split into well-defined modules (agents, environment, converters, libs) which encourage reusability and separation of concerns.
- Extensibility: The directory structure (with clear separation, e.g., for agents and maps) indicates that new components (like custom agents or game maps) can be added with minimal changes to core functionality.
- Build Integration: Use of Bazel along with Python’s modular organization ensures the integration of compiled components (the C++ converters) with the main Python code.

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "CLI/Entry"
    CLI_Binaries["CLI/Binaries"]:::cli
  end

  subgraph "Agent Layer"
    Agents["Agent Implementations"]:::core
  end

  subgraph "Environment Layer"
    EnvInterface["Environment Interface"]:::core
    Converter["Converter Modules"]:::core
  end

  subgraph "Utilities & Libraries"
    Libs["Libraries & Helpers"]:::util
  end

  subgraph "Configurations"
    Maps["Maps"]:::config
    RunConfigs["Run Configs"]:::config
  end

  subgraph "Build & Testing"
    Build["Build & Dependencies"]:::build
    Testing["Testing"]:::test
  end

  External["StarCraft II API"]:::external

  CLI_Binaries -->|"launches"| Agents
  Agents -->|"sends_commands"| EnvInterface
  EnvInterface -->|"processes_observations"| Converter
  Converter -->|"returns_data"| Agents
  EnvInterface -->|"calls_API"| External
  EnvInterface -->|"loads_maps"| Maps
  EnvInterface -->|"loads_configs"| RunConfigs
  Build -->|"compiles"| Converter
  Libs -->|"supports"| Agents
  Libs -->|"supports"| EnvInterface
  Testing -->|"tests"| Agents
  Testing -->|"tests"| EnvInterface
  Testing -->|"tests"| Converter

  click CLI_Binaries "https://github.com/google-deepmind/pysc2/tree/master/pysc2/bin"
  click Agents "https://github.com/google-deepmind/pysc2/tree/master/pysc2/agents"
  click EnvInterface "https://github.com/google-deepmind/pysc2/tree/master/pysc2/env"
  click Converter "https://github.com/google-deepmind/pysc2/tree/master/pysc2/env/converter"
  click Build "https://github.com/google-deepmind/pysc2/tree/master/bazel"
  click Libs "https://github.com/google-deepmind/pysc2/tree/master/pysc2/lib"
  click Maps "https://github.com/google-deepmind/pysc2/tree/master/pysc2/maps"
  click RunConfigs "https://github.com/google-deepmind/pysc2/tree/master/pysc2/run_configs"
  click Testing "https://github.com/google-deepmind/pysc2/tree/master/pysc2/tests"

  classDef cli fill:#fdebd0,stroke:#d35400,stroke-width:2px;
  classDef core fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
  classDef util fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
  classDef config fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
  classDef build fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
  classDef test fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
  classDef external fill:#f8d7da,stroke:#c0392b,stroke-width:2px;
```
