README.md 6.71 KB
Newer Older
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
# The NeuralMMO Challenge Starter Kit
![AIcrowd-Logo](https://raw.githubusercontent.com/AIcrowd/AIcrowd/master/app/assets/images/misc/aicrowd-horizontal.png)

This is the starter kit for the [The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)

# 🕵️ About The NeuralMMO Challenge


Neural-MMO is a platform for agent-based intelligence research featuring hundreds of concurrent agents, multi-thousand-step time horizons, and procedurally-generated, million-tile maps. This release ships with pretrained models, scripted baselines, evaluation tools, a customizable dashboard, and an interactive 3D client packed with visualization tools.

Progress in multiagent intelligence research is fundamentally limited by the complexity of environments available for study. Neural MMO is a massively multiagent AI research environment inspired by Massively Multiplayer Online (MMO) role playing games – self-contained worlds featuring thousands of agents per persistent macrocosm, diverse skilling systems, local and global economies, complex emergent social structures, and ad-hoc high-stakes single and team based conflict. Our goal is not to simulate the near-infinite physical processes of life on Earth but instead to construct an efficient facsimile that incentivizes the emergence of high-level social and general artificial intelligence. To this end, we consider MMOs the best proxy for the real world among human games.

You can read more in the Neural-MMO documentation


# 🔧 Installation

## Quick start


## Setup the environment

- Clone this repository

```bash
git clone https://github.com/AIcrowd/neurips2020-procgen-starter-kit.git
```

- Download and install [Miniconda](https://docs.conda.io/en/latest/miniconda.html) (if you don't have it already)

- Create a new environment with python 3.7

```bash
conda create -n neuralmmo -y
conda activate neuralmmo
conda install python=3.7 -y
```

- Install dependencies

```bash
pip install -r envs/gym_neuralmmo

git clone --single-branch --depth=1 --branch v1.5 https://github.com/jsuarez5341/neural-mmo
git clone --single-branch --depth=1 --branch v1.5 https://github.com/jsuarez5341/neural-mmo-client neural-mmo/forge/embyr
cd neural-mmo && bash scripts/setup.sh
```


# 💪 Getting Started


### Rollout the agent

```
./run.sh
```

## How do I add a custom agent for rollout ?
To add a custom model, create an agent inside `agents/` directory. The created agents should inherit a base class (`utils/base_agent.py`). 
Agents to be used for rollout should be updated in `players.yaml`.

# 🚀 Submission

## Repository Structure

```
.
├── agents                             # Directory to implement your custom agent
│   ├── random_agent.py                # Simple agent that takes random actions 
├── envs                                
│   ├── gym-neuralmmo                   # Environment for NeuralMMO
├── examples                            # Directory for adding your own training examples
├── utils                               # Helper scripts for the competition (DO NOT EDIT THESE FILES)
│   ├── base_agent.py                   # Base class for implementing custom agents. Custom agents should inherit this
│   ├── env_spaces.py                   # Functions for getting action_spaces and observation_spaces
│   ├── helpers.py                      # Helper functions for rollout
├── Dockerfile                          # Docker config for your submission environment
├── aicrowd.json                        # Submission config file (required)
├── requirements.txt                    # These python packages will be installed using `pip`
├── players.yaml                        # Edit this file to include custom agents for your evaluation
├── rollout.py                          # Rollout script (DO NOT EDIT)
├── run.sh                              # Entrypoint to your submission

```

## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:

```json
{
    "challenge_id" : "evaluations-api-neurips-2020-procgen",
    "grader_id": "evaluations-api-neurips-2020-procgen",
    "authors" : ["aicrowd-bot"],
    "description" : "NeurIPS 2020: Procgen Competition Agent",
    "docker_build" : false
}
```

This file is used to identify your submission as a part of the The Neural MMO Challenge. You must use the `challenge_id`, and `grader_id` as specified above.

## Submission environment configuration
By default we will run your code in an Ubuntu 18.04 environment with `tensorflow==1.14.0`, `ray[rllib]==0.8.5` installed.

If you want to run your submissions in a customized environment, first head to `aicrowd.json` and set `docker_build` to `true`. This flag tells that you need a custom environment.

You can specify your software environment by using `Dockerfile``requirements.txt`. Available options are

- `requirements.txt`: We will use `pip install -r requiremens.txt` to install your packages.
- `Dockerfile`: We will build the docker image using the specified Dockerfile. **If you have a Dockerfile in your repository, any other automatic installation will not be triggered.** This means that you will have to include installation steps for packages in `requirements.txt` yourself.

A sample [`Dockerfile`](Dockerfile) and a corresponding [`requirements.txt`](requirements.txt) are provided in this repository for you reference.


## Code entrypoint
The evaluator will read the value of `agents` from `agents.yaml` in the repository, and will run the script `run.sh`.  Corresponding agents must be located in `agents\` directory. The file `rollout.py` will be replaced during evaluation. 

## Submitting

### Initial setup

1) Setup an AIcrowd GitLab account if you don't have one by going to https://gitlab.aicrowd.com/
2) [Add your SSH key](https://discourse.aicrowd.com/t/how-to-add-ssh-key-to-gitlab/2603)
3) If you accept the challenge rules, click the `Participate` button on [the AIcrowd contest page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)

### Manually submitting the code
Create a submission by pushing a tag to your repository with a prefix `submission-`. An example is shown below (you can keep repository name as you desire or have multiple repositories):

```bash
# Create a tag for your submission and push
git tag -am "submission-v0.1" submission-v0.1
git push aicrowd master
git push aicrowd submission-v0.1

# Note : If the contents of your repository (latest commit hash) does not change, 
# then pushing a new tag will not trigger a new evaluation.
```

5) You should now be able to see the details of your submission in the repository's issues page.
`https://gitlab.aicrowd.com/<your-aicrowd-username>/the-neural-mmo-challenge/issues`


Happy Submitting!! :rocket: