# The NeuralMMO Challenge Starter Kit
![AIcrowd-Logo](https://raw.githubusercontent.com/AIcrowd/AIcrowd/master/app/assets/images/misc/aicrowd-horizontal.png)


# **[The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)** - Starter Kit


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.

Quick Links:

* [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)

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

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

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

## Setup the environment

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

- You'll need this repository to make submissions.

```bash
git clone https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit
```

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

- Create a new environment with python 3.8

```bash
conda create -n neuralmmo -y
conda activate neuralmmo
conda install python=3.8 -y
```

- Install dependencies

```bash
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
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
cd neural-mmo && bash scripts/setup.sh
```

## Generate maps

You'll need these to run training and local evaluations

```
python Forge.py generate --config=SmallMaps
```

# 💪 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`

## Evaluate an agent

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

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

```bash
python rollout.py
```

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

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

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

For more details check [RUNTIME.md](/docs/RUNTIME.md) 

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

## Evaluating against other agents locally

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.


## Contributors

- [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)


# 📡 Important links

- 💪 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

**Best of Luck** 🎉