README.md 6.44 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
# 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
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
26
git clone https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
27 28 29 30
```

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

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
31
- Create a new environment with python 3.8
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
32 33 34 35

```bash
conda create -n neuralmmo -y
conda activate neuralmmo
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
36
conda install python=3.8 -y
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
37 38 39 40 41
```

- Install dependencies

```bash
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
42
pip install -e env/gym_neuralmmo
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
43

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
44 45
git clone --single-branch --depth=1 --branch master https://github.com/jsuarez5341/neural-mmo
git clone --single-branch --depth=1 --branch v1.5.1 https://github.com/jsuarez5341/neural-mmo-client neural-mmo/forge/embyr
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
46 47 48 49 50 51
cd neural-mmo && bash scripts/setup.sh
```


# 💪 Getting Started

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
52 53 54 55 56
## Generate maps

```
python Forge.py generate --config=SmallMaps
```
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
57

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
58
## Evaluate an agent
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
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

```
./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
{
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
97 98 99 100
  "challenge_id": "the-neural-mmo-challenge",
  "authors": ["aicrowd-bot"],
  "description": "(optional) description about your awesome agent",
  "gpu": false
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
101
}
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
102

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
103 104
```

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
105
This file is used to identify your submission as a part of the The Neural MMO Challenge. You must use the `challenge_id` as specified above.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
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

## Submission environment configuration

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.
```

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
141 142 143 144 145 146
or, run 

```bash
./utils/submit.sh "submissio -v0.21"
```

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
147 148 149 150 151 152
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: