From 44c79e90e1c50275bfcc5bc12470511b107ca255 Mon Sep 17 00:00:00 2001 From: Marek Wydmuch Date: Wed, 27 Sep 2023 17:49:57 +0200 Subject: [PATCH] Improve the documentation regarding scenarios/enviroments --- docs/environments/creatingCustom.md | 16 +-- docs/environments/default.md | 112 +++++++++++++---- docs/introduction/apisAndWrappers.md | 14 +-- scenarios/README.md | 178 +-------------------------- scenarios/deathmatch.cfg | 1 + scenarios/deathmatch.wad | Bin 103170 -> 102111 bytes scenarios/defend_the_center.cfg | 1 + scenarios/defend_the_line.cfg | 2 +- scenarios/my_way_home.cfg | 2 +- scenarios/predict_position.cfg | 7 +- scenarios/take_cover.cfg | 4 +- 11 files changed, 119 insertions(+), 218 deletions(-) diff --git a/docs/environments/creatingCustom.md b/docs/environments/creatingCustom.md index f7196614d..f0ae9c541 100644 --- a/docs/environments/creatingCustom.md +++ b/docs/environments/creatingCustom.md @@ -1,6 +1,6 @@ # Creating a custom environment -ViZDoom allows using of custom scenarios/environments that can be easily prepared using modern Doom map editors like [SLADE](http://slade.mancubus.net/index.php?page=downloads) (available for Linux, MacOS, and Windows) or [DoomBuilder](http://www.doombuilder.com/index.php?p=downloads) (a bit better editor, but only available for Windows), that we recommend using. These editors allow designing a map used by the environment as well as programming the custom logic and rewards using ACS scripting language. In addition to a map created in one of the editors that are saved to a .wad file, ViZDoom uses .cfg config files that store additional information about the environment. Such .wad and .cfg together define a custom environment that can be used with ViZDoom. The following will guide you through the process of creating a custom environment. +ViZDoom allows the use of custom scenarios/environments that can be easily prepared using modern Doom map editors like [SLADE](http://slade.mancubus.net/index.php?page=downloads) (available for Linux, MacOS, and Windows) or [DoomBuilder](http://www.doombuilder.com/index.php?p=downloads) (a bit better editor, but only available for Windows), that we recommend using. These editors allow you to create a map used by the environment and program custom logic and rewards using ACS scripting language. In addition to a map+script created in one of the editors that is saved to a .wad file, ViZDoom uses .cfg config files that store additional information about the environment. Such .wad and .cfg together define a custom environment that can be used with ViZDoom. The following will guide you through the process of creating a custom environment. ## Limitations and possibilities @@ -10,8 +10,8 @@ Before we start explaining the process of creating custom environments, one ques - **3D is limited:** ViZDoom engine does not support full 3D maps. As in the original Doom, the map is, in fact, a 2D map with additional information about floor and ceiling height. This means that some 3D structures, like bridges or multi-floor buildings, are impossible in ViZDoom. However, ViZDoom supports 3D movement like jumping, crouching, swimming, or flying, which were not possible in original Doom. - **Map editors are easy to use:** Because of 3D limitations, the Doom-level editors (like mentioned SLADE or DoomBuilder) are actually much simpler than editors for later full 3D engines since they are based on drawing a map from a top-down view. Because of that, they are much easier to use, and everyone is able to create new maps right away. - **Scripting is powerful:** ViZDoom environments are not limited to particular tasks, as ViZDoom supports ACS scripting language, which was created for later revisions of the Doom engine. -It has a simple C-like syntax and is very powerful. It allows to create of custom game rules and rewards. It has a large number of functions that allow to modify/extend the game logic in many ways. ZDoom ACS documentation (https://zdoom.org/wiki/ACS) is generally well-written and complete, making it easy to find the right function for the task. -Due to the engine's architecture, the only area that ACS is a bit lacking is the possibility of modifying map geometry. Simple modifications, like changing the height of some part of the level to create elevators or doors, are possible, but there are not many more options. Using those, it is possible, for example, to create a randomized maze, but something more complex might be tricky or impossible. +It has a simple C-like syntax and is very powerful. It allows you to create custom game rules and rewards. It has a large number of functions that allow the modification/extension of the game logic in many ways. ZDoom ACS documentation (https://zdoom.org/wiki/ACS) is generally well-written and complete, making it easy to find the right function for the task. +Due to the engine's architecture, the only area that ACS is a bit lacking is the possibility of modifying map geometry. Simple modifications are possible (like changing the height of some part of the level to create elevators or doors), but there are not many more options. Using those, it is possible, for example, to create a randomized maze, but something more complex might be tricky or impossible. - **Basic functionality provided by the library:** To simplify the creation of environments, some simple functionalities are also embedded into the library. This way, they don't need to be implemented in ACS every single time but can be configured in a config file. These include: - possibility to define actions space - possibility to define what is included in the observation (types of buffers, additional variables, etc.) @@ -25,9 +25,9 @@ Due to the engine's architecture, the only area that ACS is a bit lacking is the To create a custom scenario (.wad file), you need to use a dedicated editor. [SLADE](http://slade.mancubus.net/index.php?page=downloads) (available for Linux, MacOS, and Windows) or [DoomBuilder](http://www.doombuilder.com/index.php?p=downloads) (a bit better editor, but only available for Windows), are software that we recommend using for this task. -When creating a new map, select UDMF format for maps and ZDBPS, which is a node builder for ZDoom. You should not have any problems with creating a map using the editor, it is simple, and you can find a lot of tutorials on the internet. +When creating a new map, select UDMF format for maps. If asked for a node builder, you can select none, as ViZDoom has it built in. You should not have any problems with creating a map using the editor, it is simple, and you can find a lot of tutorials on the internet. -You can add some custom ACS scripts to your map. This ACS script allows to add implement a rewarding mechanism. +You can add some custom ACS scripts to your map. This ACS script allows the implementation of a rewarding mechanism. To do that, you need to employ the global variable 0 like this: ```{code-block} C @@ -43,13 +43,13 @@ script 1(void) The global variable 0 will be used by ViZDoom to get the reward value. -Please note that in ACS 1.0 and 1 are not the same. The first one is the fixed point number stored in int, and the second one is an ordinary int. Watch out for what is expected by the functions you use cause using the wrong format can result in rubbish. -ViZDoom treats the reward as a fixed point numeral, so you always need to use decimal points in ACS scripts. +Please note that in ACS, `1.0` and `1` are not the same. The first one is the fixed point number stored in int, and the second one is an ordinary int. Please be aware of that difference. ViZDoom treats the reward as a fixed point numeral, so you always need to use decimal points in ACS scripts. +Unfortunately, ACS does not support real floating point numbers. ## Step 2: Creating a custom config file -After creating a map, it is a good idea to create an accompanying config file, that allows to easily defined action space, available information in a state/observation, additional rewards, etc. The config file is a simple text file in ini-like format that can be created using any text editor. The config files are documented under [api/configurationFiles.md](api/configurationFiles.md). +After creating a map, it is a good idea to create an accompanying config file, that allows to easily define action space, available information in a state/observation, additional rewards, etc. The config file is a simple text file in an *.ini-like format that can be created using any text editor. The config files are documented under [api/configurationFiles.md](api/configurationFiles.md). The following is an example of a config file that can be used with the map created in the previous step: diff --git a/docs/environments/default.md b/docs/environments/default.md index 3a2351e7e..c38f9d1d4 100644 --- a/docs/environments/default.md +++ b/docs/environments/default.md @@ -1,11 +1,34 @@ # Default scenarios/environments -Below we describe all default scenarios (original ViZDoom nomenclature)/environments (Gymnasium/Open AI Gym nomenclature) included with ViZDoom. The PRs with new scenarios are welcome! +Below we describe a default singleplayer scenarios (original ViZDoom nomenclature)/environments (Gymnasium/Open AI Gym nomenclature) included with ViZDoom. The PRs with new scenarios are welcome! + + +## How to use default scenarios + +When using original ViZDoom API, each scenario can be loaded [`load_config`](../api/python/doomGame.md#vizdoom.DoomGame.load_config) (Python)/[`loadConfig`](../api/cpp/doomGame.md#loadconfig) (C++) method: + +Python example: +```{code-block} python +import os +import vizdoom as vzd +game = vzd.DoomGame() +game.load_config(os.path.join(vzd.scenarios_path, "basic.cfg")) # or any other scenario file +``` + +When using Gymnasium (or Gym) API the scenario can be loaded by passing the scenario id to `make` method like-this: + +```{code-block} python +import gymnasium +from vizdoom import gymnasium_wrapper # This import will register all the environments + +env = gymnasium.make("VizdoomBasic-v0") # or any other environment id +``` + ## Note on .wad, .cfg files, and rewards -The scenarios consist of two files - .wad and .cfg ([see scenarios directory](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios)). The .wad file contains the map and script, and the .cfg file contains additional settings. The maps contained in .wad files (Doom's engine format for storing maps and assets) usually do not implement action constraints, the death penalty, and living rewards (however it is possible). To make it easier, this can be specified in ViZDoom .cfg files as well as other options like access to additional information. These can also be overridden in the code when using the original ViZDoom API. Every mention of any settings that are not included in .wad files is specified with "(config)" in the descriptions below. ViZDoom does not support setting certain rewards (such as killing opponents) in .cfg files. These must be programmed in the .wad files instead. +A scenario usually consist of two files - .wad and .cfg ([see scenarios directory](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios)). The .wad file contains the map and script, and the .cfg file contains additional settings. The maps contained in .wad files (Doom's engine format for storing maps and assets) usually do not implement action constraints, the death penalty, and living rewards (however it is possible). To make it easier, this can be specified in ViZDoom .cfg files as well as other options like access to additional information. These can also be overridden in the code when using the original ViZDoom API. Every mention of any settings that are not included in .wad files is specified with "(config)" in the descriptions below. ViZDoom does not support setting certain rewards (such as killing opponents) in .cfg files. These must be programmed in the .wad files instead. ## BASIC @@ -20,7 +43,6 @@ and shoot. 1 hit is enough to kill the monster. The episode finishes when the monster is killed or on timeout. **REWARDS:** - * +106 for killing the monster * -5 for every shot * +1 for every tic the agent is alive @@ -28,10 +50,15 @@ finishes when the monster is killed or on timeout. The episode ends after killing the monster or on timeout. **CONFIGURATION:** -* 3 available buttons: move left, move right, shoot (attack) +* 3 available buttons: move left/right, shoot (attack) +* 1 available game variable: player's ammo * timeout = 300 tics -Configuration file: [basic.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/basic.cfg) + +**Gymnasium/Gym id: `"VizdoomBasic-v0"`** + +**Configuration file: [basic.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/basic.cfg)** + ## DEADLY CORRIDOR The purpose of this scenario is to teach the agent to navigate towards @@ -43,21 +70,45 @@ in total). A green vest is placed at the opposite end of the corridor. The reward is proportional (negative or positive) to the change in the distance between the player and the vest. If the player ignores monsters on the sides and runs straight for the vest, he will be killed somewhere -along the way. To ensure this behavior doom_skill = 5 (config) is +along the way. To ensure this behavior difficulty level (`doom_skill`) = 5 (config) is needed. **REWARDS:** - * +dX for getting closer to the vest. * -dX for getting further from the vest. * -100 for death **CONFIGURATION:** -* 5 available buttons: turn left, turn right, move left, move right, shoot (attack) +* 7 available buttons: move forward/backwward/left/right, turn left/right, shoot (attack) +* 1 available game variable: player's health +* timeout = 2100 +* difficulty level (`doom_skill`) = 5 + +**Gymnasium/Gym id: `"VizdoomCorridor-v0"`** + +**Configuration file: [deadly_corridor.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/deadly_corridor.cfg)** + + +## DEATHMATCH +In this scenario, the agent is spawned in the random place of the arena filled with resources. +A random monster is spawned every few seconds that will try to kill the player. +The reward for killing a monster depends on its difficulty. +The aim of the agent is to kill as many monsters as possible +before the time runs out or it's killed by monsters. + +**REWARDS:** +* Different rewards are given for killing different monsters + +**CONFIGURATION:** +* 16 available binary buttons: move forward/backwward/left/right, turn left/right, strafe, sprint (speed), shoot (attack), select weapon 1-6/next/previous +* 3 available delta buttons: look up/down, turn left/right, move left/right +* 5 available game variables: player's health, armor, selected weapon and ammo, killcount * timeout = 4200 -* doom_skill = 5 +* difficulty level (`doom_skill`) = 3 -Configuration file: [scenarios/basic.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/deadly_corridor.cfg) +**Gymnasium/Gym id: `"VizdoomDeathmatch-v0"`** + +**Configuration file: [scenarios/deathmatch.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/deathmatch.cfg)** ## DEFEND THE CENTER @@ -78,8 +129,13 @@ because of limited ammo). **CONFIGURATION:** * 3 available buttons: turn left, turn right, shoot (attack) +* 2 available game variables: player's health and ammo +* timeout = 2100 +* difficulty level (`doom_skill`) = 3 -Configuration file: [scenarios/defend_the_center.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/defend_the_center.cfg) +**Gymnasium/Gym id: `"VizdoomDefendCenter-v0"`** + +**Configuration file: [defend_the_center.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/defend_the_center.cfg)** ## DEFEND THE LINE @@ -101,8 +157,12 @@ because of limited ammo). **CONFIGURATION:** * 3 available buttons: turn left, turn right, shoot (attack) +* 2 available game variables: player's health and ammo +* difficulty level (`doom_skill`) = 3 + +**Gymnasium/Gym id: `"VizdoomDefendLine-v0"`** -Configuration file: [scenarios/defend_the_line.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/defend_the_line.cfg) +**Configuration file: [defend_the_line.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/defend_the_line.cfg)** ## HEALTH GATHERING (AND HEALTH GATHERING SUPREME) @@ -126,10 +186,12 @@ that makes map layout more complex. * -100 for death **CONFIGURATION:** -* 3 available buttons: turn left, turn right, move forward -* 1 available game variable: HEALTH +* 3 available buttons: turn left/right, move forward +* 1 available game variable: player's health -Configuration file: [scenarios/health_gathering.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/health_gathering.cfg)/[scenarios/health_gathering_supreme.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/health_gathering_supreme.cfg) +**Gymnasium/Gym id: `"VizdoomHealthGathering-v0"`/`"VizdoomHealthGatheringSupreme-v0"`** + +**Configuration file: [health_gathering.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/health_gathering.cfg)/[health_gathering_supreme.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/health_gathering_supreme.cfg)** ## MY WAY HOME @@ -148,10 +210,12 @@ direction. The episode ends when the vest is reached or on timeout/ * -0.0001 for every tic the agent is alive **CONFIGURATION:** -* 3 available buttons: turn left, turn right, move forward +* 3 available buttons: turn left/right, move forward * timeout = 2100 -Configuration file: [scenarios/my_way_home.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/my_way_home.cfg) +**Gymnasium/Gym id: `"VizdoomMyWayHome-v0"`** + +**Configuration file: [my_way_home.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/my_way_home.cfg)** ## PREDICT POSITION @@ -172,10 +236,12 @@ or on timeout. * -0.0001 for every tic the agent is alive **CONFIGURATION:** -* 3 available buttons: turn left, turn right, shoot (attack) +* 3 available buttons: turn left/right, shoot (attack) * timeout = 300 -Configuration file: [scenarios/predict_position.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/predict_position.cfg) +**Gymnasium/Gym id: `"VizdoomPredictPosition-v0"`** + +**Configuration file: [predict_position.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/predict_position.cfg)** ## TAKE COVER @@ -196,6 +262,10 @@ the player dies. * +1 for every tic the agent is alive **CONFIGURATION:** -* 2 available buttons: move left, move right +* 2 available buttons: move left/right +* 1 available game variable: player's health +* difficulty level (`doom_skill`) = 4 + +**Gymnasium/Gym id: `"VizdoomTakeCover-v0"`** -Configuration file: [scenarios/take_cover.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/take_cover.cfg) +**Configuration file: [take_cover.cfg](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios/take_cover.cfg)** diff --git a/docs/introduction/apisAndWrappers.md b/docs/introduction/apisAndWrappers.md index bec2456e8..164d4ee09 100644 --- a/docs/introduction/apisAndWrappers.md +++ b/docs/introduction/apisAndWrappers.md @@ -1,11 +1,11 @@ # APIs and wrappers -ViZDoom consists of a few APIs: C++ API, Python API that is a wrapper around C++ API, and Gymnasium/Gym wrappers that wrap around Python API to allow to use ViZDoom environments as Gymnasium/Gym environments. +ViZDoom consists of a few APIs: C++ API, Python API that is a wrapper around C++ API, and Gymnasium/Gym wrappers that wrap around Python API to allow the use of ViZDoom scenarios as Gymnasium/Gym environments. Because ViZDoom was created before the first release of OpenAI Gym, it uses a bit different nomenclature in its API than Gym/Gymnasium: - **environments = scenarios** - in the original ViZDoom API, environments are called scenarios, - **observations = states** - in the original ViZDoom API, observations are called states, -- **steps = tics** - in the original ViZDoom API, steps are called tics, that's in the original Doom engine. The tic is a single logic update of the game that is 1/35 of a second. +- **steps = tics** - in the original ViZDoom API, steps are called tics. The Doom engine uses the name to refer to a single logic step. The tic is a single logic update of the game state that corresponds to 1/35 of a second (original Doom's framerate). ## C++ API @@ -29,11 +29,11 @@ Installing ViZDoom with `pip install vizdoom` will include Gymnasium wrappers to interact with ViZDoom over [Gymnasium API](https://gymnasium.farama.org/). These wrappers are under `gymnasium_wrappers`, containing the basic environment and -few example environments based on the built-in scenarios. This environment +a few example single-player environments based on the built-in scenarios. This environment simply initializes ViZDoom with the settings from the scenario config files and implements the necessary API to function as a Gymnasium API. -See following examples for use: +See the following examples for use: - [examples/python/gymnasium_wrapper.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/gymnasium_wrapper.py) for basic usage - [examples/python/learning_stable_baselines.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/learning_stable_baselines.py) for example training with [stable-baselines3](https://github.com/DLR-RM/stable-baselines3/) (Update - Currently facing issues, to be fixed) @@ -46,11 +46,11 @@ Installing ViZDoom with `pip install vizdoom[gym]` will include Gym wrappers to interact with ViZDoom over Gym API. These wrappers are under `gym_wrappers`, containing the basic environment and -few example environments based on the built-in scenarios. This environment +a few example environments based on the built-in scenarios. This environment simply initializes ViZDoom with the settings from the scenario config files and implements the necessary API to function as a Gym API. -See following examples for use: +See the following examples for use: - [examples/python/gym_wrapper.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/gym_wrapper.py) for basic usage @@ -58,4 +58,4 @@ See following examples for use: > Julia, Lua, and Java bindings are no longer maintained. -Julia, Lua, and Java can be found in [julia](https://github.com/Farama-Foundation/ViZDoom/tree/julia) and [java&lua](https://github.com/Farama-Foundation/ViZDoom/tree/java%26lua) branches for manual bilding. +Julia, Lua, and Java can be found in [julia](https://github.com/Farama-Foundation/ViZDoom/tree/julia) and [java&lua](https://github.com/Farama-Foundation/ViZDoom/tree/java%26lua) branches for manual building. diff --git a/scenarios/README.md b/scenarios/README.md index c9348d200..d7f02651b 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -1,176 +1,6 @@ -# Scenarios/Environments Descriptions: +# Scenarios -Below we describe all default scenarios (original ViZDoom nomenclature)/environments (Gymnasium/Open AI Gym nomenclature) included with ViZDoom. The PRs with new scenarios are welcome! +This directory contains the files that define default ViZDoom scenarios/environments (Gymnasium/Open AI Gym nomenclature)nomenclature). +Usually, a scenario consists of two files - .wad and .cfg. The .wad file contains the map and script, and the .cfg file contains additional settings. The maps contained in .wad files (Doom's engine format for storing maps and assets) usually do not implement action constraints, the death penalty, and living rewards (however it is possible). To make it easier, this can be specified in ViZDoom .cfg files as well as other options like access to additional information. - -### Note on .wad, .cfg files, and rewards: - -The scenarios consist of two files - .wad and .cfg ([see scenarios directory](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios)). The .wad file contains the map and script, and the .cfg file contains additional settings. The maps contained in .wad files (Doom's engine format for storing maps and assets) usually do not implement action constraints, the death penalty, and living rewards (however it is possible). To make it easier, this can be specified in ViZDoom .cfg files as well as other options like access to additional information. These can also be overridden in the code when using the original ViZDoom API. Every mention of any settings that are not included in .wad files is specified with "(config)" in the descriptions below. ViZDoom does not support setting certain rewards (such as killing opponents) in .cfg files. These must be programmed in the .wad files instead. - - -## BASIC -The purpose of the scenario is just to check if using this -framework to train some AI in a 3D environment is feasible. - -The map is a rectangle with gray walls, ceiling, and floor. -The player is spawned along the longer wall in the center. -A red, circular monster is spawned randomly somewhere along -the opposite wall. A player can only (config) go left/right -and shoot. 1 hit is enough to kill the monster. The episode -finishes when the monster is killed or on timeout. - -__REWARDS:__ - -+101 for killing the monster --5 for missing -The episode ends after killing the monster or on timeout. - -Further configuration: -* living reward = -1, -* 3 available buttons: move left, move right, shoot (attack) -* timeout = 300 - -## DEADLY CORRIDOR -The purpose of this scenario is to teach the agent to navigate towards -his fundamental goal (the vest) and make sure he survives at the -same time. - -The map is a corridor with shooting monsters on both sides (6 monsters -in total). A green vest is placed at the opposite end of the corridor. -The reward is proportional (negative or positive) to the change in the -distance between the player and the vest. If the player ignores monsters -on the sides and runs straight for the vest, he will be killed somewhere -along the way. To ensure this behavior doom_skill = 5 (config) is -needed. - -__REWARDS:__ - -+dX for getting closer to the vest. --dX for getting further from the vest. - -Further configuration: -* 5 available buttons: turn left, turn right, move left, move right, shoot (attack) -* timeout = 4200 -* death penalty = 100 -* doom_skill = 5 - - -## DEFEND THE CENTER -The purpose of this scenario is to teach the agent that killing the -monsters is GOOD and when monsters kill you is BAD. In addition, -wasting ammunition is not very good either. Agent is rewarded only -for killing monsters so he has to figure out the rest for himself. - -The map is a large circle. A player is spawned in the exact center. -5 melee-only, monsters are spawned along the wall. Monsters are -killed after a single shot. After dying, each monster is respawned -after some time. The episode ends when the player dies (it's inevitable -because of limited ammo). - -__REWARDS:__ -+1 for killing a monster - -Further configuration: -* 3 available buttons: turn left, turn right, shoot (attack) -* death penalty = 1 - -## DEFEND THE LINE -The purpose of this scenario is to teach an agent that killing the -monsters is GOOD and when monsters kill you is BAD. In addition, -wasting ammunition is not very good either. The agent is rewarded only -for killing monsters, so it has to figure out the rest for itself. - -The map is a rectangle. A player is spawned along the longer wall in the -center. 3 melee-only and 3 shooting monsters are spawned along the -opposite wall. Monsters are killed after a single shot, at first. -After dying, each monster is respawned after some time and can endure -more damage. The episode ends when the player dies (it's inevitable -because of limited ammo). - -__REWARDS:__ -+1 for killing a monster - -Further configuration: -* 3 available buttons: turn left, turn right, shoot (attack) -* death penalty = 1 - -## HEALTH GATHERING -The purpose of this scenario is to teach the agent how to survive -without knowing what makes him survive. An agent knows only that life -is precious, and death is bad, so he must learn what prolongs his -existence and that his health is connected with it. - -The map is a rectangle with a green, acidic floor, which hurts the player -periodically. Initially, there are some medkits spread uniformly -over the map. A new medkit falls from the skies every now and then. -Medkits heal some portions of the player's health - to survive agent -needs to pick them up. The episode finishes after the player's death or -on timeout. - - -Further configuration: -* living_reward = 1 -* 3 available buttons: turn left, turn right, move forward -* 1 available game variable: HEALTH -* death penalty = 100 - -## MY WAY HOME -The purpose of this scenario is to teach the agent how to navigate -in a labyrinth-like surrounding and reach his ultimate goal -(and learn what it actually is). - -The map is a series of rooms with interconnection and 1 corridor -with a dead end. Each room has a different color. There is a -green vest in one of the rooms (the same room every time). -The player is spawned in a randomly chosen room facing a random -direction. The episode ends when the vest is reached or on timeout/ - -__REWARDS:__ -+1 for reaching the vest - -Further configuration: -* 3 available buttons: turn left, turn right, move forward -* living reward = -0.0001 -* timeout = 2100 - -## PREDICT POSITION -The purpose of the scenario is to teach an agent to synchronize -missile weapon shot (involving a significant delay between -shooting and hitting) with target movements. Agent should be -able to shoot so that the missile and the monster meet each other. - -The map is a rectangular room. A player is spawned along the longer -wall in the center. A monster is spawned randomly somewhere -along the opposite wall and walks between left and right corners -along the wall. The player is equipped with a rocket launcher and -a single rocket. The episode ends when the missile hits a wall/the monster -or on timeout. - -__REWARDS:__ -+1 for killing the monster - -Further configuration: -* living reward = -0.0001, -* 3 available buttons: turn left, turn right, shoot (attack) -* timeout = 300 - -## TAKE COVER -The purpose of this scenario is to teach an agent to link incoming -missiles with his estimated lifespan. An agent should learn that -being hit means health decrease, and this in turn will lead to -death which is undesirable. In effect, the agent should avoid -missiles. - -The map is a rectangle. A player is spawned along the longer wall, -in the center. A couple of shooting monsters are spawned -randomly somewhere along the opposite wall and try to kill -the player with fireballs. The player can only (config) move -left/right. More monsters appear with time. The episode ends when -the player dies. - -__REWARDS:__ -+1 for each tic of life - -Further configuration: -* living reward = 1.0, -* 2 available buttons: move left, move right +You can read more about the default scenarios in the [documentation](https://vizdoom.farama.org/environments/default/). Some of these files are also used in the [examples](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python). diff --git a/scenarios/deathmatch.cfg b/scenarios/deathmatch.cfg index bb396469c..00fd7a8c0 100644 --- a/scenarios/deathmatch.cfg +++ b/scenarios/deathmatch.cfg @@ -3,6 +3,7 @@ # It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout. doom_scenario_path = deathmatch.wad +doom_skill = 3 # Rendering options screen_resolution = RES_320X240 diff --git a/scenarios/deathmatch.wad b/scenarios/deathmatch.wad index da302bfc96b4834fee93b0661c644080bde43354..839388adeb15b37911411c659adc831111eddfa0 100644 GIT binary patch delta 206 zcmZo##&&-$8&^QMqYDQE14De@M6RTb*^Q4UPk6}1Y0Op4RbgvvWH8x~RgBBfnky|Q zF}>K delta 1529 zcmaJ>&ubGw6y69{T>2k)8FJc?HQjA$5z+{;iEXiILlUdBl(NlElL?!hu)ApzOIh(E zsEF2sUc45s;=w<{yH^jQe}hNgyqWDbf-dYb^L~8u-uJ%Q?;qx#p3muxhn4CzP1DZK z-sp#)22Xyx{rXG)od3Cd{^i+=%(pAC&ish@biCn`GO;bIgobeFjQzSZLEGX|!MaI` zi-j2{8-P<9bv=v%GT?p~(IDJg-UrV~c9#zh867x&*35=I9(70l+Gq-!x)U&;uJ#<} zhp{u>dF+A_w@C=eRw=-Nd7XOReV=uEQTDWi#{_ij1a5MQU9iledZA2Q+g8C+!NY(b zI)}_-5u-^8c$duN6EBJ-er&O_AyF`b1XQW#Ov|=vJLzw0BsyO%=|>~K6EW_SW6oUC zLdqluhJaAI1U_3KA$=#>2jJbvDS*;^{BMD z9MMkjE6x>T3>@F(149m$4NTc#J$5EJnI!_J{|=mqOHWJ_EE8s-uuf&a;~w)UR$(AJ z1{^yv$>;;eD-@ZNZBvg9c@W*>-Rz}&l0?y{-D7^YHKZNpc(OwY zT3Kx!)F!kuifF|fJJZl4MN=It&aIjxPUNI!vJa@Ipyy7&h7qyJcB8hXOD1I`Gz@wW zWVu2ehHc$ag`g2XVvdZIZ5f9w7;$%$we`x*#&+}f o%Z&E^s;0G8n;VUGOM88m(ZH=$H!7RkYY%E?uoq8lt18m9KOLa74FCWD diff --git a/scenarios/defend_the_center.cfg b/scenarios/defend_the_center.cfg index 3d4b1b731..3eaff70a4 100644 --- a/scenarios/defend_the_center.cfg +++ b/scenarios/defend_the_center.cfg @@ -3,6 +3,7 @@ # It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout. doom_scenario_path = defend_the_center.wad +doom_skill = 3 # Rewards death_penalty = 1 diff --git a/scenarios/defend_the_line.cfg b/scenarios/defend_the_line.cfg index 0a1d8a5e7..f323e4f54 100644 --- a/scenarios/defend_the_line.cfg +++ b/scenarios/defend_the_line.cfg @@ -3,6 +3,7 @@ # It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout. doom_scenario_path = defend_the_line.wad +doom_skill = 3 # Rewards death_penalty = 1 @@ -33,4 +34,3 @@ available_buttons = available_game_variables = { AMMO2 HEALTH } mode = PLAYER -doom_skill = 3 diff --git a/scenarios/my_way_home.cfg b/scenarios/my_way_home.cfg index bc961b12b..f13398092 100644 --- a/scenarios/my_way_home.cfg +++ b/scenarios/my_way_home.cfg @@ -3,6 +3,7 @@ # It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout. doom_scenario_path = my_way_home.wad +doom_skill = 5 # Rewards living_reward = -0.0001 @@ -37,4 +38,3 @@ available_buttons = available_game_variables = { AMMO0 } mode = PLAYER -doom_skill = 5 diff --git a/scenarios/predict_position.cfg b/scenarios/predict_position.cfg index fbc210533..aa66eef57 100644 --- a/scenarios/predict_position.cfg +++ b/scenarios/predict_position.cfg @@ -3,6 +3,7 @@ # It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout. doom_scenario_path = predict_position.wad +doom_skill = 1 # Rewards living_reward = -0.001 @@ -17,7 +18,7 @@ render_decals = false render_particles = false window_visible = true -# make episodes start after 16 tics (after producing the rocket launcher) +# make episodes start after 16 tics (after the rocket launcher is ready) episode_start_time = 16 # make episodes finish after 300 actions (tics) @@ -31,10 +32,10 @@ available_buttons = ATTACK } -# Empty list is allowed, in case you are lazy. +# Empty list is allowed, no additional variables will be available to the agent available_game_variables = { } +# Disable aim assist (autoaim) game_args += +sv_noautoaim 1 mode = PLAYER -doom_skill = 1 diff --git a/scenarios/take_cover.cfg b/scenarios/take_cover.cfg index c22ef4f54..a9650a639 100644 --- a/scenarios/take_cover.cfg +++ b/scenarios/take_cover.cfg @@ -4,6 +4,7 @@ doom_scenario_path = take_cover.wad doom_map = map01 +doom_skill = 4 # Rewards living_reward = 1 @@ -27,6 +28,3 @@ available_buttons = # Game variables that will be in the state available_game_variables = { HEALTH } - -# Change it if you wish. -doom_skill = 4