AlphaStar.

AlphaStar is a package from DeepMind that provides the tools to train an agent to master StarCraft II offered by Blizzard Entertainment.

As part of our open-sourcing efforts to drive more research interest around StarCraft II, we provide the following key offerings with this package:

1. General purpose architectures to train StarCraftII agents in architectures/ that can be used with different learning algorithms in online and offline settings.

2. Data readers, offline training and evaluation scripts for fully offline reinforcement learning with Behavior Cloning as a representative example under unplugged/ directory.

Setup

We have tested AlphaStar only in Python3.9 and Linux. Currently, we do not support other operating systems and recommend users to stick to Linux.

Preliminaries

We recommend using a Python virtual environment to manage dependencies. This should help to avoid version conflicts and just generally make the installation process easier.

python3 -m venv alphastar
source alphastar/bin/activate
pip install --upgrade pip setuptools wheel

AlphaStar depends on PySC2 converters for data generation and evaluation. Since the code for converters is written in C++, any changes to the converter code will require recompiling the PySC2 native extensions. Because of this we offer two different ways to use AlphaStar:

1. Installing AlphaStar with pip: this option requires the least setup. However if you make changes to PySC2, or if you want to use a version for which no pre-built wheel is available, you will need to manually build and install a new wheel for PySC2.
2. Building AlphaStar using Bazel: in this case AlphaStar and PySC2 are built together from source. By default the PySC2 sources are fetched from GitHub. If you wish to use a local repository instead (e.g. because you have made local modifications to PySC2) you should modify alphastar/WORKSPACE as described in the comments.

Installing with pip

If you're interested in running the bleeding edge versions, you can do so by cloning our GitHub repository and then executing the following command from the main directory (where setup.py is located):

pip install -e .  # For an editable version
pip install .     # For a non-editable version

Note that this will also install all the dependencies of AlphaStar.

Building with Bazel

First, install Bazel by following the instructions here.

PySC2 requires C++ 17, so Bazel builds of AlphaStar + PySC2 must use --cxxopt='-std=c++17'. For example, to build all AlphaStar targets, run the following command from the workspace root:

bazel build --cxxopt='-std=c++17' ...

To recursively run all of the tests within the architectures/ subdirectory:

bazel test --cxxopt='-std=c++17' architectures/...

See the documentation for AlphaStar Unplugged for example run commands.

Note: Bazel caches Python package dependencies downloaded from pip. To clear this cache (for example if you have edited requirements.txt), run bazel clean --expunge.

You may wish to use a .bazelrc file to avoid the need to repeatedly specify command-line options, for instance --cxxopt='-std=c++17'.

Quickstart

For quickstart instructions on how to run training and evaluation scripts in fully offline settings, please refer to this README. In this repository, we have not provided any online RL training code. But, the architectures are fit to be used in both online and offline training.

About

Disclaimer: This is not an official Google product.

If you use the agents, architectures and offline RL benchmarks published in this repository, please cite our AlphaStar Unplugged paper.