MAGE: Multi-Agent Grid Environment

Introduction

MAGE is a grid-based environment with obstacles (walls) and agents. The agents can move in one of the four cardinal directions. If they try to move over an obstacle or out of the grid bounds, they stay in place. Each agent has a unique color and a goal state of the same color. The environment is episodic, i.e. the episode ends when all agents reach their goals.

To initialise the grid, the user must decide where to put the walls on the grid. This can bee done by either selecting an existing map or by passing a custom map. To load an existing map, the name of the map must be passed to the obstacle_map argument. Available pre-existing map names are "4x4" and "8x8". Conversely, to load custom map, the user must provide a map correctly formatted to the obstacle_map argument. The obstacle map must be passed as a list of strings, where each string denotes a row of the grid and it is composed by a sequence of 0s and 1s, where 0 denotes a free cell and 1 denotes a wall cell. An example of a 4x4 map is the following:

["0000", 
 "0101", 
 "0001", 
 "1000"]

The user must also decide the number of agents and their starting and goal positions on the grid. This can be done by passing two lists of tuples, namely starts_xy and goals_xy, where each tuple is a pair of coordinates (x, y) representing the agent starting/goal position.

Currently, the user must also define the color of each agent. This can be done by passing a list of strings, where each string is a color name. The available color names are: red, green, blue, purple, yellow, grey and black. This requirement will be removed in the future and the color will be assigned automatically.

The user can also decide whether the agents disappear when they reach their goal. This can be done by passing a boolean value to disappear_on_goal. If disappear_on_goal is True, the agent disappears when it reaches its goal, otherwise the agent remains on the grid after it reaches its goal. This feature is currently not implemented and will be added in future versions.

Note that, currently no reward mechanism is implemented in the environment but it will be introduced soon.

Installation

Currently, only editable installation is supported:

git clone https://github.com/damat-le/mage.git
cd mage
pip install -e .

Getting Started

An example illustrating how to use MAGE is available in the example.py script.

Citation

Please use this bibtex if you want to cite this repository in your publications:

@misc{mage,
  author = {Leo D'Amato},
  title = {Multi-Agent Grid Environment},
  year = {2022},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/damat-le/mage}},
}

Disclaimer

The project is under development. In the future releases, the following features will be added:

• add reward mechanism for RL tasks
• add gym/PettingZoo integration
• add the random generation of maps
• add the disappear-on-goal feature
• prepare the project to be uploaded on PyPI