Merge pull request #564 from Farama-Foundation/docs-update

Improve the documentation regarding scenarios/enviroments

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:
 

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,18 +43,22 @@ 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
 
 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)**