https://github.com/google-deepmind/alphastar
https://github.com/google-deepmind/alphastar
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/google-deepmind/alphastar
- Owner: google-deepmind
- License: apache-2.0
- Created: 2022-08-05T14:11:00.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-09-08T18:15:53.000Z (about 3 years ago)
- Last Synced: 2025-04-29T11:41:12.747Z (7 months ago)
- Language: Python
- Size: 281 KB
- Stars: 468
- Watchers: 11
- Forks: 65
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-sc2-ai - alphastar - A package from DeepMind that provides the tools to train an agent to master StarCraft II (Libraries / Python Libraries)
README
# AlphaStar.
[AlphaStar](https://github.com/deepmind/alphastar) is a package from
[DeepMind](http://deepmind.com) that provides the tools to train an agent to
master StarCraft II offered by [Blizzard Entertainment](http://blizzard.com).
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.
```shell
python3 -m venv alphastar
source alphastar/bin/activate
pip install --upgrade pip setuptools wheel
```
AlphaStar depends on [PySC2](https://github.com/deepmind/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](https://docs.bazel.build/versions/main/install-ubuntu.html).
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:
```shell
bazel build --cxxopt='-std=c++17' ...
```
To recursively run all of the tests within the `architectures/` subdirectory:
```shell
bazel test --cxxopt='-std=c++17' architectures/...
```
See the documentation for
[AlphaStar Unplugged](https://github.com/deepmind/alphastar/blob/master/alphastar/unplugged/README.md)
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](https://docs.bazel.build/versions/main/guide.html#bazelrc-the-bazel-configuration-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](https://github.com/deepmind/alphastar/blob/master/alphastar/unplugged/README.md). 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](https://openreview.net/pdf?id=Np8Pumfoty) paper.