You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/environments/creatingCustom.md
+8-8
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Creating a custom environment
2
2
3
-
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.
3
+
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.
4
4
5
5
6
6
## Limitations and possibilities
@@ -10,8 +10,8 @@ Before we start explaining the process of creating custom environments, one ques
10
10
-**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.
11
11
-**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.
12
12
-**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.
13
-
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.
14
-
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.
13
+
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.
14
+
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.
15
15
-**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:
16
16
- possibility to define actions space
17
17
- 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
25
25
26
26
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.
27
27
28
-
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.
28
+
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.
29
29
30
-
You can add some custom ACS scripts to your map. This ACS script allows to add implement a rewarding mechanism.
30
+
You can add some custom ACS scripts to your map. This ACS script allows the implementation of a rewarding mechanism.
31
31
To do that, you need to employ the global variable 0 like this:
32
32
33
33
```{code-block} C
@@ -43,13 +43,13 @@ script 1(void)
43
43
44
44
The global variable 0 will be used by ViZDoom to get the reward value.
45
45
46
-
Please note that in ACS1.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.
47
-
ViZDoom treats the reward as a fixed point numeral, so you always need to use decimal points in ACS scripts.
46
+
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.
47
+
Unfortunately, ACS does not support real floating point numbers.
48
48
49
49
50
50
## Step 2: Creating a custom config file
51
51
52
-
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).
52
+
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).
53
53
54
54
The following is an example of a config file that can be used with the map created in the previous step:
Copy file name to clipboardExpand all lines: docs/environments/default.md
+91-21
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,34 @@
1
1
# Default scenarios/environments
2
2
3
-
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!
3
+
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!
4
+
5
+
6
+
## How to use default scenarios
7
+
8
+
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:
9
+
10
+
Python example:
11
+
```{code-block} python
12
+
import os
13
+
import vizdoom as vzd
14
+
game = vzd.DoomGame()
15
+
game.load_config(os.path.join(vzd.scenarios_path, "basic.cfg")) # or any other scenario file
16
+
```
17
+
18
+
When using Gymnasium (or Gym) API the scenario can be loaded by passing the scenario id to `make` method like-this:
19
+
20
+
```{code-block} python
21
+
import gymnasium
22
+
from vizdoom import gymnasium_wrapper # This import will register all the environments
23
+
24
+
env = gymnasium.make("VizdoomBasic-v0") # or any other environment id
25
+
```
26
+
4
27
5
28
6
29
## Note on .wad, .cfg files, and rewards
7
30
8
-
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.
31
+
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.
9
32
10
33
11
34
## BASIC
@@ -20,18 +43,22 @@ and shoot. 1 hit is enough to kill the monster. The episode
20
43
finishes when the monster is killed or on timeout.
21
44
22
45
**REWARDS:**
23
-
24
46
* +106 for killing the monster
25
47
* -5 for every shot
26
48
* +1 for every tic the agent is alive
27
49
28
50
The episode ends after killing the monster or on timeout.
29
51
30
52
**CONFIGURATION:**
31
-
* 3 available buttons: move left, move right, shoot (attack)
53
+
* 3 available buttons: move left/right, shoot (attack)
0 commit comments