ViZDoom Documentation

ViZDoom is a C++ library with a Python API designed for research in machine visual learning and deep reinforcement learning. Key capabilities include:

• Multi-platform support: Linux, macOS, and Windows.
• High performance: Capable of rendering up to 7000 fps on a single CPU thread.
• Visual & Audio access: Access to the depth buffer (3D vision), audio buffer, and automatic labeling of visible game objects.
• Game state information: Access to the list of actors/objects and map geometry.
• Advanced rendering: Supports off-screen rendering and episode recording.
• Customization: Supports single-player and multi-player modes, in-game time scaling, and custom scenario creation via visual editors and scripting.

Certain parameters like available_buttons and available_game_variables require a list of values instead of a single value.

List Syntax

Lists must be enclosed in braces { and } and values should be separated by whitespace. Lists can span multiple lines.

Appending vs. Overwriting

• Overwriting: Using KEY = { VALUES } clears any existing values for that key (from previous files or code) and replaces them with the new list.
• Appending: Using the append operator KEY += { VALUES } adds the new values to the existing list without clearing the previous ones. This is useful for combining multiple configuration files.

ViZDoom uses vizdoom.Mode to define how the agent interacts with the game and how the game progresses.

Agent Control

• PLAYER and ASYNC_PLAYER: The agent controls the in-game character.
• SPECTATOR and ASYNC_SPECTATOR: A human controls the character, and the agent receives information about the human's actions.

Game Progression

• PLAYER and SPECTATOR: The game waits for the agent to provide an action or permission to continue.
• ASYNC modes: The game progresses at a constant speed (default 35 tics per second, configurable via set_ticrate) without waiting for agent actions.

A Sector represents a part of the map with a constant floor and ceiling height. It is composed of a list of Line segments.

• Sector: Use DoomGame::setSectorsInfoEnabled to populate this. The id field is referenced by Object.sector_id.
• Line: Describes the boundaries of a sector. The is_blocking field indicates if the line acts as a wall.

Original Doom levels in Gymnasium follow the pattern: "Vizdoom<Game><Map>-S<X>-v0".

<Game> can be Freedoom, Freedoom2, Doom, or Doom2. S<X> represents the skill level (difficulty):

• S1: VERY EASY
• S2: EASY
• S3: NORMAL
• S4: HARD
• S5: VERY HARD

Example: "VizdoomDoomE1M1-S1-v0" is Doom 1, E1M1, Very Easy.

A ViZDoom scenario typically consists of two files:

1. .wad file: Contains the map and scripts (Doom's engine format). It usually does not implement action constraints, death penalties, or living rewards unless programmed into the script.
2. .cfg file: Contains additional settings such as action constraints, death penalties, living rewards, and access to additional information.

Important Notes:

• Settings specified in .cfg files are often marked as (config) in documentation.
• Certain rewards (like killing specific opponents) cannot be set in .cfg files; they must be programmed directly into the .wad files.
• Settings in .cfg files can be overridden in code when using the original ViZDoom API.

ViZDoom uses the ACS scripting language to allow custom game logic. To implement a rewarding mechanism, you must use the global variable 0.

Important Note on Numbers: ACS does not support real floating-point numbers; it uses fixed-point numbers. Because ViZDoom treats rewards as fixed-point numerals, you must use decimal points (e.g., 1.0 instead of 1) in your ACS scripts to ensure the reward is processed correctly.

global int 0:reward;
...
script 1(void)
{
    ...
    reward += 100.0;
}
...

ViZDoom provides several API layers. The core is a C++ API, which is wrapped by a Python API. To use ViZDoom with reinforcement learning frameworks, Gymnasium wrappers wrap the Python API to provide a standard Gymnasium interface.

Because ViZDoom predates OpenAI Gym, it uses different terminology for core concepts:

• scenarios (instead of environments)
• states (instead of observations)
• tics (instead of steps). A tic represents a single logic update of the game state, corresponding to 1/35th of a second.

Relationship Summary:

• C++ API $\rightarrow$ Python API $\rightarrow$ Gymnasium Wrappers

For every Gymnasium environment provided, there is a corresponding MultiBinary variant.

• Discrete Action Space (Default): The agent selects a single action from a predefined list.
• MultiBinary Action Space: The agent can press multiple buttons simultaneously. This is often more natural for ViZDoom gameplay and allows for more complex behaviors.

Naming Convention: To use the MultiBinary variant, append -MultiBinary before the version number in the environment ID.

Example: VizdoomBasic-v1 (Discrete) $\rightarrow$ VizdoomBasic-MultiBinary-v1 (MultiBinary).

MultiBinary variants share the same observation space, rewards, and configurations as their Discrete counterparts.