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

Update README.md

parent e4171cfd
# The NeuralMMO Challenge Starter Kit
![AIcrowd-Logo](https://raw.githubusercontent.com/AIcrowd/AIcrowd/master/app/assets/images/misc/aicrowd-horizontal.png)
This is the starter kit for the [The Neural MMO Challenge](https://www.aicrowd.com/challenges/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
```bash
git clone https://github.com/AIcrowd/neurips2020-procgen-starter-kit.git
```
- 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.7
```bash
conda create -n neuralmmo -y
conda activate neuralmmo
conda install python=3.7 -y
```
- Install dependencies
```bash
pip install -r envs/gym_neuralmmo
git clone --single-branch --depth=1 --branch v1.5 https://github.com/jsuarez5341/neural-mmo
git clone --single-branch --depth=1 --branch v1.5 https://github.com/jsuarez5341/neural-mmo-client neural-mmo/forge/embyr
cd neural-mmo && bash scripts/setup.sh
```
# 💪 Getting Started
### Rollout the agent
```
./run.sh
```
## 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
## 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
```
## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:
```json
{
"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 `run.sh`. Corresponding agents must be located in `agents\` directory. The file `rollout.py` will be replaced during evaluation.
## Submitting
### Initial setup
1) Setup an AIcrowd GitLab account if you don't have one by going to https://gitlab.aicrowd.com/
2) [Add your SSH key](https://discourse.aicrowd.com/t/how-to-add-ssh-key-to-gitlab/2603)
3) If you accept the challenge rules, click the `Participate` button on [the AIcrowd contest page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
### 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):
```bash
# 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.
`https://gitlab.aicrowd.com/<your-aicrowd-username>/the-neural-mmo-challenge/issues`
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