GitHub - oxwhirl/smac: SMAC: The StarCraft Multi-Agent Challenge
source link: https://github.com/oxwhirl/smac
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
- This is a BETA release.
SMAC - StarCraft Multi-Agent Challenge
SMAC is WhiRL's environment for research in the field of collaborative multi-agent reinforcement learning (MARL) based on Blizzard's StarCraft II RTS game. SMAC makes use of Blizzard's StarCraft II Machine Learning API and DeepMind's PySC2 to provide a convenient interface for autonomous agents to interact with StarCraft II, getting observations and performing actions. Unlike the PySC2, SMAC concentrates on decentralised micromanamgent scenarios, where each unit of the game is controlled by an individual RL agent.
Please refer to the accompanying paper and blogpost for the outline of our motivation for using SMAC as a testbed for MARL research and the initial experimental results.
About
Together with SMAC we also release PyMARL - our framework for MARL research, which includes implementations of several state-of-the-art algorithms, such as QMIX and COMA.
Should you have any question, please reach to [email protected] or [email protected].
Quick Start
Installing SMAC
You can install SMAC by using the following command:
$ pip install git+https://github.com/oxwhirl/smac.git
Alternatively, you can clone the SMAC repository and then install smac
with its dependencies:
$ git clone https://github.com/oxwhirl/smac.git $ pip install smac/
SMAC uses features of PySC2 that are not included in the latest release yet. If you have PySC2-2.0.1 already installed, please uninstall it first. SMAC will install a newer version from the master branch. You may also need to upgrade pip: pip install --upgrade pip
for the install to work.
Installing StarCraft II
SMAC is based on the full game of StarCraft II (versions >= 3.16.1). To install the game, follow the commands bellow.
Linux
Please use the Blizzard's repository to download the Linux version of StarCraft II. By default, the game is expected to be in ~/StarCraftII/
directory. This can be changed by setting the environment variable SC2PATH
.
MacOS/Windows
Please install StarCraft II from Battle.net. The free Starter Edition also works. PySC2 will find the latest binary should you use the default install location. Otherwise, similar to the Linux version, you would need to set the SC2PATH
environment variable with the correct location of the game.
SMAC maps
SMAC is composed of many combat scenarios with pre-configured maps. Before SMAC can be used, these maps need to be downloaded into the Maps
directory of StarCraft II.
Download the SMAC Maps and extract them to your $SC2PATH/Maps
directory. If you installed SMAC via git, simply copy the SMAC_Maps
directory from smac/env/starcraft2/maps/
into $SC2PATH/Maps
directory.
List the maps
To see the list of SMAC maps, together with the number of ally and enemy units and episode limit, run:
$ python -m smac.bin.map_list
Testing SMAC
Please run the following command to make sure that smac
and its maps are properly installed.
$ python -m smac.examples.random_agents
Watch a replay
You can watch saved replays by running:
$ python -m pysc2.bin.play --norender --rgb_minimap_size 0 --replay <path-to-replay>
This works for any replay as long as the map can be found by the game.
For more information, please refer to PySC2 documentation.
Documentation
For the detailed description of the environment, read the SMAC documentation.
The initial results of our experiments using SMAC can be found in the accompanying paper.
Citing SMAC
If you use SMAC in your research, please cite the SMAC paper.
M. Samvelyan, T. Rashid, C. Schroeder de Witt, G. Farquhar, N. Nardelli, T.G.J. Rudner, C.-M. Hung, P.H.S. Torr, J. Foerster, S. Whiteson. The StarCraft Multi-Agent Challenge, CoRR abs/1902.04043, 2019.
In BibTeX format:
@article{samvelyan19smac, title = {{The} {StarCraft} {Multi}-{Agent} {Challenge}}, author = {Mikayel Samvelyan and Tabish Rashid and Christian Schroeder de Witt and Gregory Farquhar and Nantas Nardelli and Tim G. J. Rudner and Chia-Man Hung and Philiph H. S. Torr and Jakob Foerster and Shimon Whiteson}, journal = {CoRR}, volume = {abs/1902.04043}, year = "2019" }
Code Example
Below is a small code example which illustrates how SMAC can be used. Here, individual agents execute random policies after receiving the observations and global state from the environment.
If you want to try the state-of-the-art algorithms (such as QMIX and COMA) on SMAC, make use of PyMARL - our framework for MARL research.
from smac.env import StarCraft2Env import numpy as np def main(): env = StarCraft2Env(map_name="8m") env_info = env.get_env_info() n_actions = env_info["n_actions"] n_agents = env_info["n_agents"] n_episodes = 10 for e in range(n_episodes): env.reset() terminated = False episode_reward = 0 while not terminated: obs = env.get_obs() state = env.get_state() actions = [] for agent_id in range(n_agents): avail_actions = env.get_avail_agent_actions(agent_id) avail_actions_ind = np.nonzero(avail_actions)[0] action = np.random.choice(avail_actions_ind) actions.append(action) reward, terminated, _ = env.step(actions) episode_reward += reward print("Total reward in episode {} = {}".format(e, episode_reward)) env.close()
RLlib Examples
You can also run SMAC environments in RLlib, which includes scalable algorithms such as PPO and IMPALA. Check out the example code.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK