Commit 164b455d authored by Siddhartha Laghuvarapu's avatar Siddhartha Laghuvarapu
Browse files


parent e4171cfd
# The NeuralMMO Challenge Starter Kit
This is the starter kit for the [The Neural MMO Challenge](
# 🕵️ 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. This release ships with 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
# 🔧 Installation
## Quick start
## Setup the environment
- Clone this repository
git clone
- Download and install [Miniconda]( (if you don't have it already)
- Create a new environment with python 3.7
conda create -n neuralmmo -y
conda activate neuralmmo
conda install python=3.7 -y
- Install dependencies
pip install -r envs/gym_neuralmmo
git clone --single-branch --depth=1 --branch v1.5
git clone --single-branch --depth=1 --branch v1.5 neural-mmo/forge/embyr
cd neural-mmo && bash scripts/
# 💪 Getting Started
### Rollout the agent
## 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`.
# 🚀 Submission
## 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
## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:
"challenge_id" : "evaluations-api-neurips-2020-procgen",
"grader_id": "evaluations-api-neurips-2020-procgen",
"authors" : ["aicrowd-bot"],
"description" : "NeurIPS 2020: Procgen Competition Agent",
"docker_build" : false
This file is used to identify your submission as a part of the The Neural MMO Challenge. You must use the `challenge_id`, and `grader_id` as specified above.
## Submission environment configuration
By default we will run your code in an Ubuntu 18.04 environment with `tensorflow==1.14.0`, `ray[rllib]==0.8.5` installed.
If you want to run your submissions in a customized environment, first head to `aicrowd.json` and set `docker_build` to `true`. This flag tells that you need a custom environment.
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.
## Code entrypoint
The evaluator will read the value of `agents` from `agents.yaml` in the repository, and will run the script ``. Corresponding agents must be located in `agents\` directory. The file `` will be replaced during evaluation.
## Submitting
### Initial setup
1) Setup an AIcrowd GitLab account if you don't have one by going to
2) [Add your SSH key](
3) If you accept the challenge rules, click the `Participate` button on [the AIcrowd contest page](
### Manually submitting the code
Create a submission by pushing a tag to your repository with a prefix `submission-`. An example is shown below (you can keep repository name as you desire or have multiple repositories):
# Create a tag for your submission and push
git tag -am "submission-v0.1" submission-v0.1
git push aicrowd master
git push aicrowd submission-v0.1
# Note : If the contents of your repository (latest commit hash) does not change,
# then pushing a new tag will not trigger a new evaluation.
5) You should now be able to see the details of your submission in the repository's issues page.
Happy Submitting!! :rocket:
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