# LevDoom
LevDoom is a benchmark with difficulty levels based on visual modifications, intended for research
in generalization of deep reinforcement learning agents. The benchmark is based upon
[ViZDoom](https://github.com/Farama-Foundation/ViZDoom), a platform addressed to pixel based learning in the
FPS game domain.
For more details please refer to our [CoG2022](https://ieee-cog.org/2022/assets/papers/paper_30.pdf) paper.
To reproduce the paper results, follow the instructions in the [RL](rl/README.md) module.
## Installation
To install LevDoom from PyPi, just run:
```bash
$ pip install LevDoom
```
Alternatively, to install LevDoom from source, clone this repo, cd to it, and then:
1. Clone the repository
```bash
$ git clone https://github.com/TTomilin/LevDoom
```
2. Navigate into the repository
```bash
$ cd LevDoom
```
3. Install the dependencies
```bash
$ pip install .
```
## Environments
The benchmark consists of 4 scenarios, each with 5 levels of increasing difficulty.
The full list of environments can be found in the [LevDoom](levdoom/README.md) module.
| Scenario | Success Metric | Enemies | Weapon | Items | Max Steps | Actions | Stochasticity |
|-------------------|----------------|---------|---------|---------|-----------|---------|---------------------------------|
| Defend the Center | Frames Alive | ✓ | ✓ | ✗ | 2100 | 6 | Enemy behaviour |
| Health Gathering | Frames Alive | ✗ | ✗ | ✓ | 2100 | 6 | Health kit spawn locations |
| Seek and Slay | Kill Count | ✓ | ✓ | ✗ | 1250 | 12 | Enemy and agent spawn locations |
| Dodge Projectiles | Frames Alive | ✓ | ✗ | ✗ | 2100 | 6 | Enemy behaviour |
### Environment Modifications
LevDoom imposes generalization difficulty by modifying the base environment of a scenario.
Each modification increases the difficulty level of the generalization task.
There are 8 types of modifications across all scenarios.
| Modification | Description |
|------------------|--------------------------------------------------------------------------|
| Textures | Varies the appearance of the walls, ceilings and floors |
| Obstacles | Adds impassable obstructions to the map that impede the agent's movement |
| Entity Size | Changes the size of enemies and obtainable items |
| Entity Type | Changes the type of enemies and obtainable items |
| Entity Rendering | Varies the rendering type of enemies and obtainable items |
| Entity Speed | Increases the speed of enemies |
| Agent Height | Vertically shifts the view point of the agent |
### Difficulty Levels
The number of combined modifications determines the difficulty level.
| Scenario | Level 0 | Level 1 | Level 2 | Level 3 | Level 4 |
|-------------------|----------------------------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| Defend the Center |  |  |  |  |  |
| Health Gathering |  |  |  |  |  |
| Seek and Slay |  |  |  |  |  |
| Dodge Projectiles |  |  |  |  |  |
# Quick Start
LevDoom follows the [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) interface. You can create an environment using the `make` function:
```python
import levdoom
env = levdoom.make('DefendTheCenterLevel0-v0')
```
You can also directly create all environments of a level using the `make_level` function:
```python
import levdoom
from levdoom.utils.enums import Scenario
level_envs = levdoom.make_level(Scenario.DODGE_PROJECTILES, level=3)
```
## Examples
Find examples of using LevDoom environments in the [examples](levdoom/examples) folder.
### Single Environment
```python
import levdoom
env = levdoom.make('HealthGatheringLevel3_1-v0')
env.reset()
done = False
steps = 0
total_reward = 0
while not done:
action = env.action_space.sample()
state, reward, done, truncated, info = env.step(action)
env.render()
steps += 1
total_reward += reward
print(f"Episode finished in {steps} steps. Reward: {total_reward:.2f}")
env.close()
```
### Single Level
```python
import levdoom
from levdoom.utils.enums import Scenario
max_steps = 100
level_envs = levdoom.make_level(Scenario.SEEK_AND_SLAY, level=1, max_steps=max_steps)
for env in level_envs:
env.reset()
total_reward = 0
for i in range(max_steps):
action = env.action_space.sample()
state, reward, done, truncated, info = env.step(action)
env.render()
total_reward += reward
if done or truncated:
break
print(f"{env.unwrapped.name} finished in {i + 1} steps. Reward: {total_reward:.2f}")
env.close()
```
## Citation
If you use our work in your research, please cite it as follows:
```bibtex
@inproceedings{tomilin2022levdoom,
title = {LevDoom: A Benchmark for Generalization on Level Difficulty in Reinforcement Learning},
author = {Tristan Tomilin and Tianhong Dai and Meng Fang and Mykola Pechenizkiy},
booktitle = {In Proceedings of the IEEE Conference on Games},
year = {2022}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/thu-ml/tianshou",
"name": "LevDoom",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "vizdoom,reinforcement learning,benchmarking,generalization",
"author": "Tristan Tomilin",
"author_email": "tristan.tomilin@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/77/68/bd832784f2f5e0301d6f1541596ebe55419281dba1b500ead05d7454a836/LevDoom-1.0.1.tar.gz",
"platform": null,
"description": "# LevDoom\nLevDoom is a benchmark with difficulty levels based on visual modifications, intended for research \nin generalization of deep reinforcement learning agents. The benchmark is based upon \n[ViZDoom](https://github.com/Farama-Foundation/ViZDoom), a platform addressed to pixel based learning in the \nFPS game domain.\n\nFor more details please refer to our [CoG2022](https://ieee-cog.org/2022/assets/papers/paper_30.pdf) paper.\nTo reproduce the paper results, follow the instructions in the [RL](rl/README.md) module.\n\n\n\n## Installation\nTo install LevDoom from PyPi, just run:\n```bash\n$ pip install LevDoom\n```\nAlternatively, to install LevDoom from source, clone this repo, cd to it, and then:\n1. Clone the repository\n```bash\n$ git clone https://github.com/TTomilin/LevDoom\n```\n2. Navigate into the repository\n```bash\n$ cd LevDoom\n```\n3. Install the dependencies \n```bash \n$ pip install .\n```\n## Environments\nThe benchmark consists of 4 scenarios, each with 5 levels of increasing difficulty.\nThe full list of environments can be found in the [LevDoom](levdoom/README.md) module.\n\n| Scenario | Success Metric | Enemies | Weapon | Items | Max Steps | Actions | Stochasticity | \n|-------------------|----------------|---------|---------|---------|-----------|---------|---------------------------------|\n| Defend the Center | Frames Alive | ✓ | ✓ | ✗ | 2100 | 6 | Enemy behaviour | \n| Health Gathering | Frames Alive | ✗ | ✗ | ✓ | 2100 | 6 | Health kit spawn locations |\n| Seek and Slay | Kill Count | ✓ | ✓ | ✗ | 1250 | 12 | Enemy and agent spawn locations |\n| Dodge Projectiles | Frames Alive | ✓ | ✗ | ✗ | 2100 | 6 | Enemy behaviour |\n\n\n### Environment Modifications\nLevDoom imposes generalization difficulty by modifying the base environment of a scenario.\nEach modification increases the difficulty level of the generalization task. \nThere are 8 types of modifications across all scenarios.\n\n| Modification | Description |\n|------------------|--------------------------------------------------------------------------|\n| Textures | Varies the appearance of the walls, ceilings and floors |\n| Obstacles | Adds impassable obstructions to the map that impede the agent's movement |\n| Entity Size | Changes the size of enemies and obtainable items |\n| Entity Type | Changes the type of enemies and obtainable items |\n| Entity Rendering | Varies the rendering type of enemies and obtainable items |\n| Entity Speed | Increases the speed of enemies |\n| Agent Height | Vertically shifts the view point of the agent |\n\n\n### Difficulty Levels\nThe number of combined modifications determines the difficulty level.\n\n| Scenario | Level 0 | Level 1 | Level 2 | Level 3 | Level 4 |\n|-------------------|----------------------------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|\n| Defend the Center |  |  |  |  |  |\n| Health Gathering |  |  |  |  |  |\n| Seek and Slay |  |  |  |  |  |\n| Dodge Projectiles |  |  |  |  |  |\n\n\n\n\n# Quick Start\nLevDoom follows the [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) interface. You can create an environment using the `make` function:\n```python\nimport levdoom\n\nenv = levdoom.make('DefendTheCenterLevel0-v0')\n```\nYou can also directly create all environments of a level using the `make_level` function:\n```python\nimport levdoom\nfrom levdoom.utils.enums import Scenario\n\nlevel_envs = levdoom.make_level(Scenario.DODGE_PROJECTILES, level=3)\n```\n\n\n## Examples\nFind examples of using LevDoom environments in the [examples](levdoom/examples) folder.\n\n### Single Environment\n\n```python\nimport levdoom\n\nenv = levdoom.make('HealthGatheringLevel3_1-v0')\nenv.reset()\ndone = False\nsteps = 0\ntotal_reward = 0\nwhile not done:\n action = env.action_space.sample()\n state, reward, done, truncated, info = env.step(action)\n env.render()\n steps += 1\n total_reward += reward\nprint(f\"Episode finished in {steps} steps. Reward: {total_reward:.2f}\")\nenv.close()\n```\n\n### Single Level\n```python\nimport levdoom\nfrom levdoom.utils.enums import Scenario\n\nmax_steps = 100\nlevel_envs = levdoom.make_level(Scenario.SEEK_AND_SLAY, level=1, max_steps=max_steps)\nfor env in level_envs:\n env.reset()\n total_reward = 0\n for i in range(max_steps):\n action = env.action_space.sample()\n state, reward, done, truncated, info = env.step(action)\n env.render()\n total_reward += reward\n if done or truncated:\n break\n print(f\"{env.unwrapped.name} finished in {i + 1} steps. Reward: {total_reward:.2f}\")\n env.close()\n```\n\n## Citation\nIf you use our work in your research, please cite it as follows:\n```bibtex\n@inproceedings{tomilin2022levdoom,\n title = {LevDoom: A Benchmark for Generalization on Level Difficulty in Reinforcement Learning},\n author = {Tristan Tomilin and Tianhong Dai and Meng Fang and Mykola Pechenizkiy},\n booktitle = {In Proceedings of the IEEE Conference on Games},\n year = {2022}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "LevDoom: A Generalization Benchmark for Deep Reinforcement Learning",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/thu-ml/tianshou"
},
"split_keywords": [
"vizdoom",
"reinforcement learning",
"benchmarking",
"generalization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "628e79cd15f4cb790432fab0be67ee4a25018e4453440c80dc04adbd157c269a",
"md5": "c916cdf9b546eeb49e6302af5941b567",
"sha256": "7ecdd310f166cf8a36f78d52c9e5b4f7bbf33615d3428929252c6873b5dfbb7d"
},
"downloads": -1,
"filename": "LevDoom-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c916cdf9b546eeb49e6302af5941b567",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6122,
"upload_time": "2024-02-02T14:52:12",
"upload_time_iso_8601": "2024-02-02T14:52:12.295512Z",
"url": "https://files.pythonhosted.org/packages/62/8e/79cd15f4cb790432fab0be67ee4a25018e4453440c80dc04adbd157c269a/LevDoom-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7768bd832784f2f5e0301d6f1541596ebe55419281dba1b500ead05d7454a836",
"md5": "d4b80275e067643184f1a9d6e9d18e71",
"sha256": "e75047327d250b12e249afa3aeafa883a9a3d3a53b75e05c0ad1089ae40a036d"
},
"downloads": -1,
"filename": "LevDoom-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d4b80275e067643184f1a9d6e9d18e71",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6095,
"upload_time": "2024-02-02T14:52:14",
"upload_time_iso_8601": "2024-02-02T14:52:14.341730Z",
"url": "https://files.pythonhosted.org/packages/77/68/bd832784f2f5e0301d6f1541596ebe55419281dba1b500ead05d7454a836/LevDoom-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 14:52:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thu-ml",
"github_project": "tianshou",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "levdoom"
}
JSON
