Commit 6cde04f5 authored by Jyotish P's avatar Jyotish P
Browse files

Update readme

parent cc8cc7be
# The NeuralMMO Challenge Starter Kit
<h1 align="center"><a href="">The Neural MMO Challenge</a> - Starter Kit</h1>
<p align="center">
<a href=""><img src="" alt="chat on Discord"></a>
# **[The Neural MMO Challenge](** - Starter Kit
This is the starter kit for the [Neural MMO challenge]( hosted on [AIcrowd]( Clone the repository to compete now!
This repository contains:
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.
- **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!
Quick Links:
# Table of contents
* [The Neural MMO Challenge - Competition Page](
* [Neural MMO - Github](
* [Neural MMO - Documentation](
* [Neural MMO - Discord Server](
* [The NetHack Challenge - Starter Kit](
* [IMPORTANT - Accept the rules before you submit](
- [📚 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)
# 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)
# 📚 Competition procedure
# About The NeuralMMO Challenge
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.
**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.
In this challenge, you will train your models locally and then upload them to AIcrowd (via git) to be evaluated.
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.**
**The following is a high level description of how this process works.**
You can read more in the Neural-MMO documentation.
1. **Sign up** to join the competition [on the AIcrowd website](
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]( for evaluation. [[Refer this for detailed instructions]](#-submission).
# 💪 Getting started
**A high level description of the Challenge Procedure:**
> We recommend using `python 3.8`. If you are using Miniconda/Anaconda, you can install it using `conda install python=3.8`.
- Sign up to join the competition on the AIcrowd website.
- Clone this repo and start developing your solution.
- Train your models, or build a scripted agent on NeuralMMO, and ensure runs rollouts.
- Submit your 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.
git clone
- Download and install [Miniconda]( (if you don't have it already)
- (Optional) Create a new environment with python 3.8
Clone the starter kit repository and install the dependencies.
conda create -n neuralmmo -y
conda activate neuralmmo
conda install python=3.8 -y
git clone
cd neural-mmo-starter-kit
pip install -U -r requirements.txt
- 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.
Generate the Neural MMO environment maps.
git clone --single-branch --depth=1 --branch master
git clone --single-branch --depth=1 --branch v1.5.1 neural-mmo/forge/embyr
cd neural-mmo && bash scripts/
neural-mmo-forge generate
## Generate maps
You'll need these to run training and local evaluations
# 🛠 Preparing your submission
python generate --config=SmallMaps
# 💪 Getting Started
## Write your agents
## Train an agent
Your agents need to implement the [`NeuralMMOAgent`](evaluator/ class from [`evaluator/`](evaluator/ You can check the code in [`agents`](agents) directory for examples.
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.
**Note:** If your agent doesn't inherit the `NeuralMMOAgent` class, the evaluation will fail.
python train --config=SmallMultimodalSkills --LOAD=False
Once your agent class is ready, you can specify the class to use as the player agent in your [``]( The starter kit comes with a machine learning based baseline. The [``]( in the starter kit points to this class. You should update it to use your class.
- If you want to change the config for the agent, check out `neural-mmo/projekt/`
For information on tweaking and training the baseline agents, please refer [`training baselines`](docs/
- We recommend you to subclass the `CompetitionRound1` class and add your config changes.
## Evaluate your agents locally
- Lot more details about training and the environment are available in the [neural-mmo documentation](
We have provided [`evaluator/`](evaluator/ to test your agents locally. This file reads the configuration options specified in [``](, runs the rollouts and reports the rewards obtained by the agents.
## Add your agent for submission
To run the evaluation locally, run the following command.
Add your custom config name to the `agents/` which is currently using `projekt.config.CompetitionRound1`
python evaluator/
## Evaluate an agent
**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/`](evaluator/ during the evaluation.
- Add the neural-mmo folder to the starter python path, this is needed for importing the neural-mmo environment and config loaders.
# 📨 Submission
export PYTHONPATH=$PYTHONPATH:`pwd`/neural-mmo
## Repository Structure
- Run the rollout script, this is the same file that will be used during evaluation on aicrowd.
**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.
[``]( | File containing the configuration options for local evaluation. We will use the same player agent you specify here during the evaluation.
[`utils/`](utils/ | Helper script to submit your repository to [AIcrowd GitLab](
[`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.**
<!-- ## 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/`).
Agents to be used for rollout should be updated in `players.yaml`. -->
## Runtime configuration
# 🚀 Submission
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.
**Before submitting you need to fill in a few other files**
You can also specify the OS packages needed using [`apt.txt`](apt.txt) file. We install these packages using `apt-get install` command.
## `requirements.txt`
For more information on how you can configure the evaluation runtime, please refer [``](docs/
We will build the environment for your run based on the python3 packages you specify in `requirements.txt`
## 🚀 Submitting to AIcrowd
If you want to specify stuff apart from python packages, check the section on [Submission environment configuration](#submission-environment-configuration)
### `aicrowd.json`
## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:
Your repository should have an `aicrowd.json` file with following fields:
"challenge_id": "the-neural-mmo-challenge",
"authors": ["aicrowd-bot"],
"description": "(optional) description about your awesome agent"
"challenge_id" : "the-neural-mmo-challenge",
"grader_id" : "the-neural-mmo-challenge",
"authors" : ["Your Name"],
"description" : "Brief description for your submission"
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 [](/docs/ for making submissions.
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.
# 📋 Helpful information
## Repository Structure
├── agents # Directory to implement your custom agent
│ ├── # 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 class for implementing custom agents. Custom agents should inherit this
│ ├── # Functions for getting action_spaces and observation_spaces
│ ├── # 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 script (DO NOT EDIT)
├── # Entrypoint to your submission
### Configuring the submission repository
git remote add aicrowd<username>/neural-mmo-starter-kit.git
## Submission environment configuration
**Note:** This needs to be done only once. This configuration will be saved in your repository for future use.
You can specify your software environment by using `Dockerfile``requirements.txt`. Available options are
### Pushing the code to AIcrowd
- `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.
./utils/ "some description"
A sample [`Dockerfile`](Dockerfile) and a corresponding [`requirements.txt`](requirements.txt) are provided in this repository for you reference.
If you want to submit without the helper script, please refer [``](docs/
For more details check [](/docs/
## Code entrypoint
The evaluator will read the value of `agents` from `players.yaml` in the repository, and will run ``. Corresponding agents must be located in `agents/` directory. The file `` **will be replaced during evaluation** with the file in the original starter kit, DON't modify it.
# 📝 Submission checklist
## Evaluating against other agents locally
- [x] **Accept the challenge rules**. You can do this by going to the [challenge overview page]( 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/` 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](
- [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.
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.
# 📎 Important links
- 💪 Challenge information
* [Challenge page](
* [Leaderboard](
- 🗣 Community
* [Neural MMO discord server](
* [Challenge discussion forum](
- 🎮 Neural MMO resources
* [Neural MMO documentation](
* [Neural MMO GitHub repository](
## Contributors
# Contributors
- [Siddhartha Laghuvarapu](
- [Jyotish Poonganam](
......@@ -203,10 +174,4 @@ You can specify `opponent_agents` in `players.yaml` and make as many duplicates
- [Dipam Chakraborty](
# 📡 Important links
- 💪 Challenge Page:
- 🗣️ Discussion Forum:
- 🏆 Leaderboard:
**Best of Luck** 🎉
## 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.
python train --config=SmallMultimodalSkills --LOAD=False
- If you want to change the config for the agent, check out `neural-mmo/projekt/`
- 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](
# Define agents that will be used for evaluation.
# Agents need to implement abstract class NeuralMMOAgent.
# Agents will be located in agents/
# Number of opponent agents is exactly 127
file: scripted_baseline_agent
agent_class: BaselineCombatAgent
agent_type: scripted
file: scripted_baseline_agent
agent_class: BaselineForageAgent
agent_type: scripted
num_agents: 50
file: scripted_baseline_agent
agent_class: BaselineCombatAgent
agent_type: scripted
num_agents: 45
file: random_agent
agent_class: RandomNeuralMMOAgent
agent_type: neural
num_agents: 6
file: scripted_baseline_agent
agent_class: BaselineRandomAgent
agent_type: scripted
num_agents: 26
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment