README.md 9.73 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
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
71 72
ln -s neuralmmo/resource
python neuralmmo/Forge.py generate --config=CompetitionRound1
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
73 74
```

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

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

Jyotish P's avatar
Jyotish P committed
79
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.
80

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

Jyotish P's avatar
Jyotish P committed
83
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.
84

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

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

Jyotish P's avatar
Jyotish P committed
89
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.
90

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

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

Jyotish P's avatar
Jyotish P committed
97
**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
98

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

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

Jyotish P's avatar
Jyotish P committed
103 104 105 106 107 108 109 110 111
**File/Directory** | **Description**
--- | ---
[`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.**
112 113 114
[`neuralmmo/projekt`](projekt) | Per-round environment configs and RLlib demo.
[`neuralmmo/Forge.py`](Forge.py) | Main file for baselines and demos
[`neuralmmo/resource`](projekt) | Path where maps are generated.
115
[`baselines`](Forge.py) | Path where models are saved
116

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
117

Jyotish P's avatar
Jyotish P committed
118
## Runtime configuration
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
119

Jyotish P's avatar
Jyotish P committed
120
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
121

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

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

Jyotish P's avatar
Jyotish P committed
126
## 🚀 Submitting to AIcrowd
127

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
128 129 130 131 132
### **Add your SSH key** to AIcrowd GitLab

You can add your SSH Keys to your GitLab account by going to your profile settings [here](https://gitlab.aicrowd.com/profile/keys). If you do not have SSH Keys, you will first need to [generate one](https://docs.gitlab.com/ee/ssh/README.html#generating-a-new-ssh-key-pair).


Jyotish P's avatar
Jyotish P committed
133
### `aicrowd.json`
134

Jyotish P's avatar
Jyotish P committed
135
Your repository should have an `aicrowd.json` file with following fields:
136 137 138

```json
{
Jyotish P's avatar
Jyotish P committed
139 140 141
    "challenge_id" : "the-neural-mmo-challenge",
    "authors" : ["Your Name"],
    "description" : "Brief description for your submission"
142 143 144
}
```

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
145
This file is used to identify your submission as a part of the Neural MMO Challenge. You must use the `challenge_id` as specified above.
146

Jyotish P's avatar
Jyotish P committed
147
### Configuring the submission repository
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
148

Jyotish P's avatar
Jyotish P committed
149 150
```bash
git remote add aicrowd git@gitlab.aicrowd.com:<username>/neural-mmo-starter-kit.git
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
151 152
```

Jyotish P's avatar
Jyotish P committed
153
**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
154

Jyotish P's avatar
Jyotish P committed
155
### Pushing the code to AIcrowd
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
156

Jyotish P's avatar
Jyotish P committed
157 158 159
```bash
./utils/submit.sh "some description"
```
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
160

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


Jyotish P's avatar
Jyotish P committed
164
# 📝 Submission checklist
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
165

Jyotish P's avatar
Jyotish P committed
166
- [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.
167
- [x] **Add your agent code** that implements the `NeuralMMOBaseAgent` class from `evaluator/base_agent`. Make sure your `agent_type` is filled.
Jyotish P's avatar
Jyotish P committed
168
- [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).
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
169
- [x] **Evaluate your agents locally** to know that they work as expected. Ensure your agent is added to `config.py` and verified by running `python evaluator/rollout.py`.
Jyotish P's avatar
Jyotish P committed
170
- [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
171

Jyotish P's avatar
Jyotish P committed
172
# 📎 Important links
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
173

Jyotish P's avatar
Jyotish P committed
174 175
- 💪 Challenge information
   * [Challenge page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
ashivani's avatar
ashivani committed
176
   * [Leaderboard](https://www.aicrowd.com/challenges/the-neural-mmo-challenge/leaderboards)
Jyotish P's avatar
Jyotish P committed
177 178 179 180 181 182 183
 - 🗣 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
184

Jyotish P's avatar
Jyotish P committed
185
# ✨ Contributors
Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
186

187 188 189 190
- [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
191

Siddhartha Laghuvarapu's avatar
Siddhartha Laghuvarapu committed
192

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