StarCraft: BroodWars OpenAI Gym environment
MIT License
This repository provides an OpenAI Gym interface to StarCraft: BroodWars online multiplayer game. This package was used in experiments for ICLR 2019 paper for IC3Net: Learning when to communicate at scale in multiagent cooperative and competitive tasks
M vs N
environment which can be further extended for specific cases of general M vs N
scenarios.M vs N
environment, any unit type with any quantity can be initialized anywhere on map or within a specific bounding box. This environment can also be used in case of StarCraft community-building tasks as buildings themselves are units.python setup.py develop
for installing this repo.gym-starcraft/envs/config.yml
as per your requirements. Explanation is present in comments.attack_closest
match between 10 marines and 3 zealots in bounding box of (100, 100) to (150, 150) with GUI, run the following command: python examples/attack_closest.py --server_ip 127.0.0.1 --torchcraft_dir=TORCHCRAFT_DIR --set_gui --nagents 10 --max_steps 200 --frame_skip 8 --nenemies 3 --our_unit_type 0 --enemy_unit_type 65 --init_range_start 100 --init_range_end 150 --full_vision --unlimited_attack_range --initialize_enemy_together --step_size 16
Most of the other flags are self explanatory.
Use python examples/attack_closest.py -h
for other options that are available.
StarCraftBaseEnv
like below:import gym_starcraft.envs.starcraft_base_env as sc
class YourCustomSCEnv(sc.StarCraftBaseEnv):
def __init__(self, args):
# Either use argparse namespace and pass as dict
# or pass each of the arguments using specific keywords
super(YourCustomSCEnv, self).__init__(**vars(args))
Now you will need to update or implement some of the required functions. In case you are using either of MvN or explore mode, then you may skip some of these so they default to original implementation. Otherwise, you need to implement most of the required functions which we list below one by one. For each of the function, see sample implementation in MvN environment:
_set_units
function in which you set self.my_unit_pairs
and self.enemy_unit_pairs
which are used to instantiate our and enemy units._action_space
and _observation_space
if required._make_commands
function which takes actions
as parameter and returns a list of commands in TorchCraft format. See sample implementation for an example._make_observation
function which return an numpy array of shape defined in _observation_space
function._has_step_completed
function is checked to make sure current step is completed in _step
function by default. This can be implemented in case you need to make custom checks._compute_reward
function must return reward for current step in case you are planning to use it. See attack_closest
agent to see how reward is retrieved for each agent from environment.reward_terminal
function is used to calculate reward at the end of the episode and can be called by the trainer.step
function implemented as per gym specification must call internal _step
at some point to calculate observation from StarCraft.reset
function implemented as per gym specification must call internal _reset
at some point to reset the actual StarCraft environment through BWAPI and return initial observation._get_info
which returns info for current step and _get_enemy_commands
which can be overriden to implement custom AI for StarCraft.Initial implementation of this package was based out of Alibaba's gym-starcraft which didn't work properly with latest TorchCraft version. To handle customized needs for our ICLR 2019 paper (not public yet), we developed this version. Without contributions of @ebetica (Zeming Lin), @tesatory (Sainbayar Sukhbaatar) and @tshrjn (Tushar Jain) and others at Facebook AI Research (FAIR) this package won't be possible.
If you use this project in your research, kindly cite it using:
@article{singh2018learning,
title={Learning when to Communicate at Scale in Multiagent Cooperative and Competitive Tasks},
author={Singh, Amanpreet and Jain, Tushar and Sukhbaatar, Sainbayar},
journal={arXiv preprint arXiv:1812.09755},
year={2018}
}
ic3net-envs
is available at apsdehal/ic3net-envs
Code for this project is available under MIT license.