Merge branch 'dipam/updates' into 'master'

documentation and other minor changes

See merge request neural-mmo/neuralmmo-starter-kit!1

README.md

 # 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
+# **[The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)** - Starter Kit
 
 
-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.
+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.
 
-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.
+Quick Links:
 
-You can read more in the Neural-MMO documentation
+* [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)
 
-# 🔧 Installation
+# About The NeuralMMO Challenge
 
-## Quick start
+**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
+- 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
@@ -39,34 +74,92 @@ conda install python=3.8 -y
 - Install dependencies
 
 ```bash
-pip install -e env/gym_neuralmmo
-
+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
 ```
 
-
-# 💪 Getting Started
-
 ## 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.sh
+
+- 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 ?
+<!-- ## 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`.
+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
 
 ```
@@ -89,21 +182,6 @@ Agents to be used for rollout should be updated in `players.yaml`.
 
 ```
 
-## `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",
-  "gpu": false
-}
-
-```
-
-This file is used to identify your submission as a part of the The Neural MMO Challenge. You must use the `challenge_id` as specified above.
-
 ## Submission environment configuration
 
 You can specify your software environment by using `Dockerfile``requirements.txt`. Available options are
@@ -113,40 +191,28 @@ You can specify your software environment by using `Dockerfile``requirements.txt
 
 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 `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. 
+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. 
 
-## Submitting
+## Evaluating against other agents locally
 
-### Initial setup
+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.
 
-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):
+## Contributors
 
-```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.
-```
-
-or, run 
-
-```bash
-./utils/submit.sh "submissio -v0.21"
-```
+- [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)
 
-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`
 
+# 📡 Important links
 
-Happy Submitting!! :rocket:
+- 💪 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** 🎉 
\ No newline at end of file

aicrowd.json

@@ -4,7 +4,6 @@
   "authors": [
     "aicrowd-bot"
   ],
-  "description": "(optional) description about your awesome agent",
-  "gpu": false
+  "description": "(optional) description about your awesome agent"
 }
 

apt.txt

+gcc
+g++
+git
\ No newline at end of file

docs/RUNTIME.md

+# Adding your runtime
+
+## **Installation setup steps**
+
+### **How to specify your installation setup for the submission**
+The entrypoint to the installation is the Dockerfile
+The Dockerfile provided will have commands to install apt packages from apt.txt and pip packages from requirements.txt
+You are strongly advised to specify the version of the library that you use to use for your submission
+
+Examples
+
+For requirements.txt
+
+```torch==1.8.1```
+
+You can add git repositories to requirements.txt as well
+
+```git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm```
+
+For apt.txt
+
+```firefox=45.0.2+build1-0ubuntu1```
+
+## (Optional) Check your installation setup on your own machine
+
+### Setup the environment 
+Install docker on your machine and run
+
+```bash
+docker build -t your-custom-tag . 
+```
+
+If you get installation errors during the above step, your submission is likely to fail, please review the errors and fix the installation
+
+### Run the submission locally
+
+Run the docker container This will create an environment that emulates how your submission environment will be.
+
+```bash
+docker run -it your-custom-tag /bin/bash
+```
+
+```bash
+python rollout.py 
+```
+
+If you get runtime errors during the above step, your submission is likely to fail. Please review the errors.
+A common error is not specifying one or multiple required libraries
+
+## Installation FAQ
+- How to install with an `environment.yml`?
+
+  - Add `environment.yml` to the base of your repo. You also need to add commands to add `environment.yml` to the `Dockerfile`. Afterwards, You’re encouraged to follow the above steps Check your installation setup on your own machine to check everything is properly installed.
+
+- How do I install with a setup.py
+  - You need to add the command to run it in the ```Dockerfile``` - ```RUN pip install .```
+
+- What’s the package versions I have installed on my machine?
+
+  - You can find the versions of the python package installations you currently have using pip freeze
+
+- What’s aicrowd_gym
+  - AIcrowd gym is a library AIcrowd uses to limit the functionality on the submission environment to prevent tampering with the RL Library. For all intents and purposes, aicrowd_gym should work the same as gym for you.
+- How do I use a custom script to install?
+  - You’ll need to call the custom script in the ```Dockerfile```, example you can add this line ```RUN ./custom_script.sh```

docs/SUBMISSION.md

+# Making submission
+
+This file will help you in making your first submission.
+
+
+## Submission Entrypoint (where you write your code!)
+
+The evaluator will execute `rollout.py` for generating actions in the neural-mmo environment, this file will be replaced during aicrowd evaluations, so don't modify it!
+
+## IMPORTANT: Saving Models before submission!
+
+Before you submit make sure that you have saved your models, which are needed by your inference code.
+In case your files are larger in size you can use `git-lfs` to upload them. More details [here](https://discourse.aicrowd.com/t/how-to-upload-large-files-size-to-your-submission/2304).
+
+## How to submit a trained model!
+
+To make a submission, you will have to create a **private** repository on [https://gitlab.aicrowd.com/](https://gitlab.aicrowd.com/).
+
+You will have to 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).
+
+Then you can create a submission by making a _tag push_ to your repository on [https://gitlab.aicrowd.com/](https://gitlab.aicrowd.com/).
+**Any tag push (where the tag name begins with "submission-") to your private repository is considered as a submission**  
+Then you can add the correct git remote, and finally submit by doing :
+
+```
+cd neuralmmo-starter-kit
+# Add AIcrowd git remote endpoint
+git remote add aicrowd git@gitlab.aicrowd.com:<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit.git
+git push aicrowd master
+```
+
+```
+# 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.
+```
+
+You now should be able to see the details of your submission at :
+[gitlab.aicrowd.com/<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit/issues](https://gitlab.aicrowd.com//<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit/issues)
+
+**NOTE**: Remember to update your username instead of `<YOUR_AICROWD_USER_NAME>` above :wink:
+
+### Other helpful files
+
+👉 [RUNTIME.md](/docs/RUNTIME.md)