README.md 9.16 KB
Newer Older
Jyotish P's avatar
Jyotish P committed
1 2
![](https://i.imgur.com/jbZ1HlW.png)
<h1 align="center"><a href="https://www.aicrowd.com/challenges/the-neural-mmo-challenge">The Neural MMO Challenge</a> - Starter Kit</h1>
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
3

Jyotish P's avatar
Jyotish P committed
4 5 6
<p align="center">
 <a href="https://discord.gg/N3cWFhsk8K"><img src="https://img.shields.io/discord/657211973435392011?style=for-the-badge" alt="chat on Discord"></a>
</p>
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
7

Jyotish P's avatar
Jyotish P committed
8
This is the starter kit for the [Neural MMO challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge) hosted on [AIcrowd](https://www.aicrowd.com). Clone the repository to compete now!
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
9

Jyotish P's avatar
Jyotish P committed
10
This repository contains:
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
11

Jyotish P's avatar
Jyotish P committed
12 13 14
- **Documentation** on how to submit your models to the leaderboard.
- Information on **evaluating your agents locally**, **baselines** and some best practises to have hassle free submissions.
- **Starter code** for you to get started!
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
15

16 17 18 19
[IMPORTANT - Accept the rules before you submit](https://www.aicrowd.com/challenges/the-neural-mmo-challenge/challenge_rules)



Jyotish P's avatar
Jyotish P committed
20
# Table of contents
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
21

Jyotish P's avatar
Jyotish P committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
- [📚 Competition procedure](#-competition-procedure)
- [💪 Getting started](#-getting-started)
- [🛠 Preparing your submission](#-preparing-your-submission)
  * [Write your agents](#write-your-agents)
  * [Evaluate your agents locally](#evaluate-your-agents-locally)
- [📨 Submission](#-submission)
  * [Repository Structure](#repository-structure)
  * [Runtime configuration](#runtime-configuration)
  * [🚀 Submitting to AIcrowd](#-submitting-to-aicrowd)
    + [`aicrowd.json`](#aicrowdjson)
    + [Configuring the submission repository](#configuring-the-submission-repository)
    + [Pushing the code to AIcrowd](#pushing-the-code-to-aicrowd)
- [📝 Submission checklist](#-submission-checklist)
- [📎 Important links](#-important-links)
- [✨ Contributors](#-contributors)
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
37

Jyotish P's avatar
Jyotish P committed
38
# 📚 Competition procedure
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
39

Jyotish P's avatar
Jyotish P committed
40
The Neural MMO Challenge is an opportunity for researchers and machine learning enthusiasts to test their skills by designing and building agents that can survive and thrive in a massively multiagent environment full of potential adversaries.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
41

Jyotish P's avatar
Jyotish P committed
42
In this challenge, you will train your models locally and then upload them to AIcrowd (via git) to be evaluated.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
43

Jyotish P's avatar
Jyotish P committed
44
**The following is a high level description of how this process works.**
45

Jyotish P's avatar
Jyotish P committed
46
![](https://i.imgur.com/xzQkwKV.jpg)
47

Jyotish P's avatar
Jyotish P committed
48 49 50 51
1. **Sign up** to join the competition [on the AIcrowd website](https://www.aicrowd.com/challenges/the-neural-mmo-challenge).
2. **Clone** this repo and start developing your solution.
3. **Design and build** your agents that can compete in Neural MMO environment and implement an agent class as described in [writing your agents](#write-your-agents) section.
4. [**Submit**](#-submission) your agents to [AIcrowd Gitlab](https://gitlab.aicrowd.com) for evaluation. [[Refer this for detailed instructions]](#-submission).
52

Jyotish P's avatar
Jyotish P committed
53
# 💪 Getting started
54

Jyotish P's avatar
Jyotish P committed
55
> We recommend using `python 3.8`. If you are using Miniconda/Anaconda, you can install it using `conda install python=3.8`.
56

Jyotish P's avatar
Jyotish P committed
57
Clone the starter kit repository and install the dependencies.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
58 59

```bash
Jyotish P's avatar
Jyotish P committed
60 61
git clone https://gitlab.aicrowd.com/neural-mmo/neural-mmo-starter-kit
cd neural-mmo-starter-kit
62 63 64
pip install neural-mmo

#Optional: Install ML dependencies
Jyotish P's avatar
Jyotish P committed
65
pip install -U -r requirements.txt
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
66
```
Jyotish P's avatar
Jyotish P committed
67 68 69
   
Generate the Neural MMO environment maps.
   
70
```bash
71
python Forge.py generate --config=CompetitionRound1
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
72 73
```

Jyotish P's avatar
Jyotish P committed
74
# 🛠 Preparing your submission
75

Jyotish P's avatar
Jyotish P committed
76
## Write your agents
77

Jyotish P's avatar
Jyotish P committed
78
Your agents need to implement the [`NeuralMMOAgent`](evaluator/base_agent.py#L4) class from [`evaluator/base_agent.py`](evaluator/base_agent.py). You can check the code in [`agents`](agents) directory for examples.
79

Jyotish P's avatar
Jyotish P committed
80
**Note:** If your agent doesn't inherit the `NeuralMMOAgent` class, the evaluation will fail.
81

Jyotish P's avatar
Jyotish P committed
82
Once your agent class is ready, you can specify the class to use as the player agent in your [`config.py`](config.py). The starter kit comes with a machine learning based baseline. The [`config.py`](config.py) in the starter kit points to this class. You should update it to use your class.
83

Jyotish P's avatar
Jyotish P committed
84
For information on tweaking and training the baseline agents, please refer [`training baselines`](docs/training-baselines.md).
85

Jyotish P's avatar
Jyotish P committed
86
## Evaluate your agents locally
87

Jyotish P's avatar
Jyotish P committed
88
We have provided [`evaluator/rollout.py`](evaluator/rollout.py) to test your agents locally. This file reads the configuration options specified in [`config.py`](config.py), runs the rollouts and reports the rewards obtained by the agents.
89

Jyotish P's avatar
Jyotish P committed
90
To run the evaluation locally, run the following command.
91

Jyotish P's avatar
Jyotish P committed
92 93 94
```bash
python evaluator/rollout.py
```
95

Jyotish P's avatar
Jyotish P committed
96
**Note:** Please note that the changes you make to any file inside [`evaluator`](evaluator) directory will be dropped during evaluation. We will use a slightly modified version of the [`evaluator/rollout.py`](evaluator/rollout.py) during the evaluation.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
97

Jyotish P's avatar
Jyotish P committed
98
# 📨 Submission
99

Jyotish P's avatar
Jyotish P committed
100
## Repository Structure
101

Jyotish P's avatar
Jyotish P committed
102 103
**File/Directory** | **Description**
--- | ---
104 105
[`projekt`](projekt) | Per-round environment configs and RLlib demo.
[`Forge.py`](Forge.py) | Main file for baselines and demos
Jyotish P's avatar
Jyotish P committed
106 107 108 109 110 111 112
[`agents`](agents) | Directory containing different scripted bots, baseline agent and bots performing random actions. We recommend that you add your agents to this directory.
[`config.py`](config.py) | File containing the configuration options for local evaluation. We will use the same player agent you specify here during the evaluation.
[`utils/submit.sh`](utils/submit.sh) | Helper script to submit your repository to [AIcrowd GitLab](https://gitlab.aicrowd.com).
[`Dockerfile`](Dockerfile) | Docker config for your submission. Refer [runtime configuration](#runtime-configuration) for more information.
[`requirements.txt`](requirements.txt) | File containing the list of python packages you want to install for the submission to run. Refer [runtime configuration](#runtime-configuration) for more information.
[`apt.txt`](apt.txt) | File containing the list of packages you want to install for submission to run. Refer [runtime configuration](#runtime-configuration) for more information.
[`evaluator`](evaluator) | Directory containing scripts for local evaluation. **Do not make changes to the files in this directory. Any changes made will be dropped during evaluation.**
113

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
114

Jyotish P's avatar
Jyotish P committed
115
## Runtime configuration
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
116

Jyotish P's avatar
Jyotish P committed
117
You can specify the list of python packages needed for your code to run in your [`requirements.txt`](requirements.txt) file. We will install the packages using `pip install` command.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
118

Jyotish P's avatar
Jyotish P committed
119
You can also specify the OS packages needed using [`apt.txt`](apt.txt) file. We install these packages using `apt-get install` command.
120

Jyotish P's avatar
Jyotish P committed
121
For more information on how you can configure the evaluation runtime, please refer [`RUNTIME.md`](docs/RUNTIME.md).
122

Jyotish P's avatar
Jyotish P committed
123
## 🚀 Submitting to AIcrowd
124

Jyotish P's avatar
Jyotish P committed
125
### `aicrowd.json`
126

Jyotish P's avatar
Jyotish P committed
127
Your repository should have an `aicrowd.json` file with following fields:
128 129 130

```json
{
Jyotish P's avatar
Jyotish P committed
131 132 133 134
    "challenge_id" : "the-neural-mmo-challenge",
    "grader_id" : "the-neural-mmo-challenge",
    "authors" : ["Your Name"],
    "description" : "Brief description for your submission"
135 136 137
}
```

Jyotish P's avatar
Jyotish P committed
138
This file is used to identify your submission as a part of the Neural MMO Challenge. You must use the `challenge_id`, and `grader_id` as specified above.
139

Jyotish P's avatar
Jyotish P committed
140
### Configuring the submission repository
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
141

Jyotish P's avatar
Jyotish P committed
142 143
```bash
git remote add aicrowd git@gitlab.aicrowd.com:<username>/neural-mmo-starter-kit.git
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
144 145
```

Jyotish P's avatar
Jyotish P committed
146
**Note:** This needs to be done only once. This configuration will be saved in your repository for future use.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
147

Jyotish P's avatar
Jyotish P committed
148
### Pushing the code to AIcrowd
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
149

Jyotish P's avatar
Jyotish P committed
150 151 152
```bash
./utils/submit.sh "some description"
```
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
153

Jyotish P's avatar
Jyotish P committed
154
If you want to submit without the helper script, please refer [`SUBMISSION.md`](docs/SUBMISSION.md).
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
155 156


Jyotish P's avatar
Jyotish P committed
157
# 📝 Submission checklist
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
158

Jyotish P's avatar
Jyotish P committed
159 160 161 162 163
- [x] **Accept the challenge rules**. You can do this by going to the [challenge overview page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge) and clicking the "Participate" button. You only need to do this once.
- [x] **Add your agent code** that implements the `NeuralMMOBaseAgent` class from `evaluator/base_agent`.
- [x] **Add your model checkpoints** (if any) to the repo. The `utils/submit.sh` will automatically detect large files and add them to git LFS. If you are using the script, please refer to [this post explaining how to add your models](https://discourse.aicrowd.com/t/how-to-upload-large-files-size-to-your-submission/2304).
- [x] **Evaluate your agents locally** to know that they work as expected.
- [x] **Update runtime configuration** using `requirements.txt`, `apt.txt` and/or `Dockerfile` as necessary. Please make sure that you specified the same package versions that you use locally on your machine.
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
164

Jyotish P's avatar
Jyotish P committed
165
# 📎 Important links
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
166

Jyotish P's avatar
Jyotish P committed
167 168 169 170 171 172 173 174 175 176
- 💪 Challenge information
   * [Challenge page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
   * [Leaderboard](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
 - 🗣 Community
    * [Neural MMO discord server](https://discord.gg/N3cWFhsk8K)
    * [Challenge discussion forum](https://discourse.aicrowd.com/c/the-neural-mmo-challenge/)
- 🎮 Neural MMO resources
    * [Neural MMO documentation](https://jsuarez5341.github.io)
    * [Neural MMO GitHub repository](https://github.com/jsuarez5341/neural-mmo)
    
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
177

Jyotish P's avatar
Jyotish P committed
178
# ✨ Contributors
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
179

180 181 182 183
- [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
184

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
185

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
186
**Best of Luck** 🎉