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** 🎉