README.md 9.73 KB
Newer Older
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
1
2
3
4
# The NeuralMMO Challenge Starter Kit
![AIcrowd-Logo](https://raw.githubusercontent.com/AIcrowd/AIcrowd/master/app/assets/images/misc/aicrowd-horizontal.png)


5
# **[The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)** - Starter Kit
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
6
7


8
9
10
11
This repository is the Nethack Challenge **Starter kit**! It contains:
* **Instructions** for setting up your codebase to make submissions easy.
* **Baselines** for quickly getting started training your agent.
* **Documentation** for how to submit your model to the leaderboard.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
12

13
Quick Links:
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
14

15
16
17
18
19
20
* [The Neural MMO Challenge - Competition Page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
* [Neural MMO - Github](https://github.com/jsuarez5341/neural-mmo)
* [Neural MMO - Documentation](https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html)
* [Neural MMO - Discord Server](https://discord.gg/JrRNh8rZ7j)
* [The NetHack Challenge - Starter Kit](https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit)
* [IMPORTANT - Accept the rules before you submit](https://www.aicrowd.com/challenges/the-neural-mmo-challenge/challenge_rules)
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
21

22
23
24
25
26
# Table of Contents
1. [About The NeuralMMO Challenge](#about-the-neuralmmo-challenge)
2. [Setup and Installation](#🛠-setup-and-installation)
3. [Getting Started](#💪-getting-started)
4. [Helpful Information](#📋-helpful-information)
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
27

28
# About The NeuralMMO Challenge
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
29

30
**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. It provides pretrained models, scripted baselines, evaluation tools, a customizable dashboard, and an interactive 3D client packed with visualization tools.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
31

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
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.

https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html


**A high level description of the Challenge Procedure:**


- Sign up to join the competition on the AIcrowd website.

- Clone this repo and start developing your solution.

- Train your models on NeuralMMO, and ensure rollout.py runs rollouts.

 - Submit your trained models to AIcrowd Gitlab
for evaluation (full instructions below). The automated evaluation setup
will evaluate the submissions against the scripted bots and submissions from othe participants, and your scores will evolve on the leaderboard accordingly.

# 🛠 Setup and Installation
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
53
54
55

## Setup the environment

56
57
58
- Clone this repository to a private repository on your own aicrowd gitlab account.

- You'll need this repository to make submissions.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
59
60

```bash
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
61
git clone https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
62
63
64
65
```

- 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
66
- Create a new environment with python 3.8
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
67
68
69
70

```bash
conda create -n neuralmmo -y
conda activate neuralmmo
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
71
conda install python=3.8 -y
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
72
73
74
75
76
```

- Install dependencies

```bash
77
78
79
80
81
cd neuralmmo-starter-kit/
pip install -e ./env/gym_neuralmmo
```
- Get the neuralmmo environment - you can clone it anywhere you like, but our instructions assume you get the neural-mmo folder inside the starter kit.
```bash
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
82
83
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
84
85
86
cd neural-mmo && bash scripts/setup.sh
```

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
87
88
## Generate maps

89
90
You'll need these to run training and local evaluations

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
91
92
93
```
python Forge.py generate --config=SmallMaps
```
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
94

95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
# 💪 Getting Started

## Train an agent

Training your first agent is super easy with this one line command. It might take a long time though, but you can try it out for a few epochs.

```bash
python Forge.py train --config=SmallMultimodalSkills --LOAD=False
```

- If you want to change the config for the agent, check out `neural-mmo/projekt/config.py`

- We recommend you to subclass the `CompetitionRound1` class and add your config changes.

- Lot more details about training and the environment are available in the [neural-mmo documentation](https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html)

## Add your trained agent for submission

Add your custom config name to the `agents/neural_baseline_agent.py` which is currently using `projekt.config.CompetitionRound1`

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
115
## Evaluate an agent
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
116

117
118
119
120
- Add the neural-mmo folder to the starter python path, this is needed for importing the neural-mmo environment and config loaders.

```bash
export PYTHONPATH=$PYTHONPATH:`pwd`/neural-mmo
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
121
```
122
123
124
125
126

- Run the rollout script, this is the same file that will be used during evaluation on aicrowd.

```bash
python rollout.py
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
127
128
```

129
<!-- ## How do I add a custom agent for rollout ?
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
130
To add a custom model, create an agent inside `agents/` directory. The created agents should inherit a base class (`utils/base_agent.py`). 
131
Agents to be used for rollout should be updated in `players.yaml`. -->
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
132
133
134

# 🚀 Submission

135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
**Before submitting you need to fill in a few other files**

## `requirements.txt`

We will build the environment for your run based on the python3 packages you specify in `requirements.txt` 

If you want to specify stuff apart from python packages, check the section on [Submission environment configuration](#submission-environment-configuration)

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

```json
{
  "challenge_id": "the-neural-mmo-challenge",
  "authors": ["aicrowd-bot"],
  "description": "(optional) description about your awesome agent"
}

```

This file is used to identify your submission as a part of the The Neural MMO Challenge. Don't change the `challenge_id`, you can add in the rest.

## Making the submission

Please follow the instructions in [SUBMISSION.md](/docs/SUBMISSION.md) for making submissions.

# 📋 Helpful information

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
## 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

```

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

194
For more details check [RUNTIME.md](/docs/RUNTIME.md) 
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
195
196

## Code entrypoint
197
The evaluator will read the value of `agents` from `players.yaml` in the repository, and will run `rollout.py`.  Corresponding agents must be located in `agents/` directory. The file `rollout.py` **will be replaced during evaluation** with the file in the original starter kit, DON't modify it. 
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
198

199
## Evaluating against other agents locally
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
200

201
You can specify `opponent_agents` in `players.yaml` and make as many duplicates of them as you like. The total number of players should add up to 128.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
202
203


204
## Contributors
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
205

206
207
208
209
- [Siddhartha Laghuvarapu](https://www.aicrowd.com/participants/siddhartha)
- [Jyotish Poonganam](https://www.aicrowd.com/participants/jyotish)
- [Joseph Suarez](https://www.aicrowd.com/participants/joseph_suarez)
- [Dipam Chakraborty](https://www.aicrowd.com/participants/dipam)
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
210

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
211

212
# 📡 Important links
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
213

214
215
216
- 💪 Challenge Page: https://www.aicrowd.com/challenges/the-neural-mmo-challenge
- 🗣️ Discussion Forum: https://www.aicrowd.com/challenges/the-neural-mmo-challenge/discussion
- 🏆 Leaderboard: https://www.aicrowd.com/challenges/the-neural-mmo-challenge/leaderboards
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
217

218
**Best of Luck** 🎉