PySC2 OpenAI Gym Environments

OpenAI Gym Environments for the StarCraft II PySC2 environment.

Installation:

After cloning the repository, you can use the environments in
one of two ways:

Add the directory where you cloned the repo to your PYTHON_PATH
Install the package in development mode using pip: pip install -e .

If you use the first option, you need to manually make sure the
dependencies are installed.

The second option will install the package into your pip environment
as a link to the directory, so it will reflect the changes when
you git pull or make any changes to the code.

Usage:

You need the following minimum code to run any environment:

Import gym and this package:

import gym
import sc2gym.envs

Import and initialize absl.flags: (this is due to pysc2 dependency)

import sys
from absl import flags
FLAGS = flags.FLAGS
FLAGS(sys.argv)

Create and initialize the specific environment as indicated in the
next section.

Available environemnts:

SC2Game:

The full StarCraft II game environment. Initialize as follows:

env = gym.make('SC2Game-v0')
env.settings['map_name'] = '<desired map name>'

Versions:

SC2Game-v0: The full game with complete access to action and
observation space.

Notes:

The action space for this environment doesn’t require the call to
functionCall like pysc2 does. You just need to call it with an
array of action and arguments. For example:
```
  _SELECT_ARMY = actions.FUNCTIONS.select_army.id
  _SELECT_ALL = [0]
  env.step([_SELECT_ARMY, _SELECT_ALL])
```
It will check the first element in the array (the action) and make
sure it’s available before trying to pass it along to the
pysc2 environment.
This environment doesn’t specify the observation_space and
action_space members like traditional gym environments. Instead,
it provides access to the observation_spec and action_spec objects
from the pysc2 environment.

MoveToBeacon:

The MoveToBeacon mini game. Initialize as follows:

env = gym.make('SC2MoveToBeacon-v0')

Versions:

‘SC2MoveToBeacon-v0’: The observation is a [1, 64, 64] numpy
array that represents the obs.observation['screen'][_PLAYER_RELATIVE]
plane from the pysc2 observation. The action is a number
between 0 and 4095 (64x64-1), which is a 1-d representation of the
screen coordinates to move the marine towards. The environment
pre-selects the marine at the start of each episode.
‘SC2MoveToBeacon-v1’: The observation is a [1, 64, 64] numpy
array that represents the obs.observation['screen'][_PLAYER_RELATIVE]
plane from the pysc2 observation. The action is an array of
two numbers, each between 0 and 63, representing the screen coordinates
to move the marine towards. The environment pre-selects the marine at
the start of each episode.

CollectMineralShards:

The CollectMineralShards mini game. Initialize as follows:

env = gym.make('SC2CollectMineralShards-v0')

Versions:

‘SC2CollectMineralShards-v0’: The observation is a [1, 64, 64] numpy
array that represents the obs.observation['screen'][_PLAYER_RELATIVE]
plane from the pysc2 observation. The action is a number
between 0 and 4095 (64x64-1), which is a 1-d representation of the
screen coordinates to move the marines towards. The environment
pre-selects both marines at the start of each episode.
‘SC2CollectMineralShards-v1’: The observation is a [1, 64, 64] numpy
array that represents the obs.observation['screen'][_PLAYER_RELATIVE]
plane from the pysc2 observation. The action is an array of
two numbers, each between 0 and 63, representing the screen coordinates
to move the marines towards. The environment pre-selects the marine at
the start of each episode.
‘SC2CollectMineralShards-v2’: The observation is a [2, 64, 64] numpy
array that represents the obs.observation['screen'][_PLAYER_RELATIVE]
and the obs.observation['screen'][_SELECTED] planes from the pysc2
observation. The action is an array of three numbers. The first number
is between 0 and 2, representing which control group to move.
The remaining two numbers are integers between 0 and 63, representing the screen coordinates
to move the marines in this control group towards.
The environment automatically creates the following control groups at
the start of each episode.
Each episode starts with control group 3 pre-selected.
- Group 1 [index 0]: Both marines
- Group 2 [index 1]: Marine 1
- Group 3 [index 2]: Marine 2

General Notes:

Per the Gym environment specifications, the reset function returns an
observation, and the step function returns a tuple
(observation, reward, done, info), where info is an empty dictionary and
the observation is the observation object from the pysc2 environment.
The reward is the same as observation.reward, and done is equal true if
observation.step_type is LAST.
In addition to step() and reset(), the environments define a
save_replay() method, that takes a single parameter, replay_dir,
which is the name of the replay directory to save to inside the
StarCraft II/Replays/ folder.
All the environments have action_spec and observation_spec properties,
in addition to the action_space and observation_space properties defined
for the mini game environments.
All the environments have the following additional properties:
- episode: The current episode number
- num_step: The total number of steps taken
- episode_reward: The total reward received this episode
- total_reward: The total reward received for all episodes
The examples folder contains examples of using the various environments.

Copyright 2017 Islam Elnabarawy
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.