DoomGame#

DoomGame is the main object of the ViZDoom library, representing a single instance of the Doom game and providing the interface for a single agent/player to interact with the game. The object allows sending actions to the game, getting the game state, etc.

class DoomGame(self: vizdoom.DoomGame)#

Flow control methods#

init(self: vizdoom.DoomGame) → None#: Initializes ViZDoom game instance and starts a new episode. After calling this method, the first state from a new episode will be available. Some configuration options cannot be changed after calling this method. Init returns True when the game was started properly and False otherwise.

close(self: vizdoom.DoomGame) → None#: Closes ViZDoom game instance. It is automatically invoked by the destructor. The game can be initialized again after being closed.

new_episode(self: vizdoom.DoomGame, recording_file_path: str = '') → None#

Initializes a new episode. The state of an environment is completely restarted (all variables and rewards are reset to their initial values). After calling this method, the first state from the new episode will be available. If the recordingFilePath is not empty, the new episode will be recorded to this file (as a Doom lump).

In a multiplayer game, the host can call this method to finish the game. Then the rest of the players must also call this method to start a new episode.

replay_episode(self: vizdoom.DoomGame, file_path: str, player: int = 0) → None#: Replays a recorded episode from the given file using the perspective of the specified player. Players are numbered from 1, player equal to 0 results in replaying the demo using the perspective of the default player in the recording file. After calling this method, the first state from the replay will be available. All rewards, variables, and states are available during the replaying episode.

is_running(self: vizdoom.DoomGame) → bool#: Checks if the ViZDoom game instance is running.

is_multiplayer_game(self: vizdoom.DoomGame) → bool#: Checks if the game is in multiplayer mode.

is_recording_episode(self: vizdoom.DoomGame) → bool#: Checks if the game is in recording mode.

is_replaying_episode(self: vizdoom.DoomGame) → bool#: Checks if the game is in replaying mode.

set_action(self: vizdoom.DoomGame, action: object) → None#: Sets the player’s action for the next tics. Each value corresponds to a button specified with addAvailableButton method or in the configuration file (in order of appearance).

advance_action(self: vizdoom.DoomGame, tics: int = 1, update_state: bool = True) → None#: Processes a specified number of tics. If updateState is set, the state will be updated after the last processed tic and a new reward will be calculated. To get the new state, use getState and to get the new reward use getLastReward. If updateState is not set, the state will not be updated.

make_action(self: vizdoom.DoomGame, action: object, tics: int = 1) → float#: Method combining usability of setAction. Sets the player’s action for the next tics, processes a specified number of tics, updates the state and calculates a new reward, which is returned.

is_new_episode(self: vizdoom.DoomGame) → bool#: Returns True if the current episode is in the initial state - the first state, no actions were performed yet.

is_episode_finished(self: vizdoom.DoomGame) → bool#: Returns True if the current episode is in the terminal state (is finished). makeAction.

is_player_dead(self: vizdoom.DoomGame) → bool#: Returns True if the player is dead. In singleplayer, the player’s death is equivalent to the end of the episode. In multiplayer, when the player is dead respawnPlayer method can be called.

respawn_player(self: vizdoom.DoomGame) → None#: This method respawns the player after death in multiplayer mode. After calling this method, the first state after the respawn will be available.

send_game_command(self: vizdoom.DoomGame, cmd: str) → None#: Sends the command to Doom console. It can be used for controlling the game, changing settings, cheats, etc. Some commands will be blocked in some modes.

get_state(self: vizdoom.DoomGame) → vizdoom.GameState#: Returns GameState object with the current game state. If the current episode is finished, nullptr/null/None will be returned.

get_server_state(self: vizdoom.DoomGame) → vizdoom.ServerState#: Returns ServerState object with the current server state.

get_last_action(self: vizdoom.DoomGame) → list#: Returns the last action performed. Each value corresponds to a button added with addAvailableButton. Most useful in `SPECTATOR mode.

get_episode_time(self: vizdoom.DoomGame) → int#: Returns number of current episode tic.

save(self: vizdoom.DoomGame, file_path: str) → None#: Saves a game’s internal state to the file using ZDoom’s save game functionality.

load(self: vizdoom.DoomGame, file_path: str) → None#: Loads a game’s internal state from the file using ZDoom’s load game functionality. A new state is available after loading. Loading the game state does not reset the current episode state, tic counter/time and total reward state keep their values.

Buttons settings methods#

get_available_buttons(self: vizdoom.DoomGame) → list#: Returns the list of available Buttons.

set_available_buttons(self: vizdoom.DoomGame, buttons: list) → None#: Set given list of Button`s (e.g. `TURN_LEFT, MOVE_FORWARD) as available Buttons.

add_available_button(self: vizdoom.DoomGame, button: vizdoom.Button, max_value: float = -1) → None#: Add Button to available Buttons and sets the maximum allowed, absolute value for the specified button. If the given button has already been added, it will not be added again, but the maximum value is overridden.

clear_available_buttons(self: vizdoom.DoomGame) → None#: Clears all available Buttons added so far.

get_available_buttons_size(self: vizdoom.DoomGame) → int#: Returns the number of available Buttons.

set_button_max_value(self: vizdoom.DoomGame, button: vizdoom.Button, max_value: float) → None#: Sets the maximum allowed absolute value for the specified button. Setting the maximum value to 0 results in no constraint at all (infinity). This method makes sense only for delta buttons. The constraints limit applies in all Modes.

get_button_max_value(self: vizdoom.DoomGame, button: vizdoom.Button) → float#: Returns the maximum allowed absolute value for the specified button.

get_button(self: vizdoom.DoomGame, button: vizdoom.Button) → float#: Returns the current state of the specified button (ATTACK, USE etc.).

GameVariables methods#

get_available_game_variables(self: vizdoom.DoomGame) → list#: Returns the list of available GameVariables.

set_available_game_variables(self: vizdoom.DoomGame, variables: list) → None#: Set list of GameVariable returned by getState method.

add_available_game_variable(self: vizdoom.DoomGame, variable: vizdoom.GameVariable) → None#: Adds the specified GameVariable returned by getState method.

clear_available_game_variables(self: vizdoom.DoomGame) → None#: Clears the list of available GameVariables that are included in the GameState method.

get_available_game_variables_size(self: vizdoom.DoomGame) → int#: Returns the number of available GameVariables.

get_game_variable(self: vizdoom.DoomGame, variable: vizdoom.GameVariable) → float#: Returns the current value of the specified game variable (HEALTH, AMMO1 etc.). The specified game variable does not need to be among available game variables (included in the state). It could be used for e.g. shaping. Returns 0 in case of not finding given GameVariable.

Game Arguments methods#

add_game_args(self: vizdoom.DoomGame, args: str) → None#: Adds a custom argument that will be passed to ViZDoom process during initialization. Useful for changing additional game settings.

clear_game_args(self: vizdoom.DoomGame) → None#: Clears all arguments previously added with addGameArgs method.

Reward methods#

get_living_reward(self: vizdoom.DoomGame) → float#: Returns the reward granted to the player after every tic.

set_living_reward(self: vizdoom.DoomGame, living_reward: float) → None#

Sets the reward granted to the player after every tic. A negative value is also allowed.

Default value: 0

get_death_penalty(self: vizdoom.DoomGame) → float#: Returns the penalty for the player’s death.

set_death_penalty(self: vizdoom.DoomGame, death_penalty: float) → None#

Sets a penalty for the player’s death. Note that in case of a negative value, the player will be rewarded upon dying.

Default value: 0

get_last_reward(self: vizdoom.DoomGame) → float#: Returns a reward granted after the last update of state.

get_total_reward(self: vizdoom.DoomGame) → float#: Returns the sum of all rewards gathered in the current episode.

General game setting methods#

load_config(self: vizdoom.DoomGame, config: str) → bool#

Loads configuration (resolution, available buttons, game variables etc.) from a configuration file. In case of multiple invocations, older configurations will be overwritten by the recent ones. Overwriting does not involve resetting to default values. Thus only overlapping parameters will be changed. The method returns True if the whole configuration file was correctly read and applied, False if the file contained errors.

If the file relative path is given, it will be searched for in the following order: current directory, current directory + /scenarios/, ViZDoom’s installation directory + /scenarios/.

get_mode(self: vizdoom.DoomGame) → vizdoom.Mode#: Returns current mode (PLAYER, SPECTATOR, ASYNC_PLAYER, ASYNC_SPECTATOR).

set_mode(self: vizdoom.DoomGame, mode: vizdoom.Mode) → None#

Sets mode (PLAYER, SPECTATOR, ASYNC_PLAYER, ASYNC_SPECTATOR) in which the game will be running.

Default value: PLAYER.

get_ticrate(self: vizdoom.DoomGame) → int#: Returns current ticrate.

set_ticrate(self: vizdoom.DoomGame, button: int) → None#

Sets ticrate for ASNYC Modes - number of logic tics executed per second. The default Doom ticrate is 35. This value will play a game at normal speed.

Default value: 35 (default Doom ticrate).

set_vizdoom_path(self: vizdoom.DoomGame, button: str) → None#

Sets path to the ViZDoom engine executable vizdoom.

Default value: “{vizdoom.so location}/{vizdoom or vizdoom.exe (on Windows)}”.

set_doom_game_path(self: vizdoom.DoomGame, button: str) → None#

Sets the path to the Doom engine based game file (wad format). If not used DoomGame will look for doom2.wad and freedoom2.wad (in that order) in the directory of ViZDoom’s installation (where vizdoom.so/pyd is).

Default value: “{vizdoom.so location}/{doom2.wad, doom.wad, freedoom2.wad or freedoom.wad}”

set_doom_scenario_path(self: vizdoom.DoomGame, button: str) → None#

Sets the path to an additional scenario file (wad format). If not provided, the default Doom single-player maps will be loaded.

Default value: “”

set_doom_map(self: vizdoom.DoomGame, button: str) → None#

Sets the map name to be used.

Default value: “map01”, if set to empty “map01” will be used.

set_doom_skill(self: vizdoom.DoomGame, button: int) → None#

Sets Doom game difficulty level, which is called skill in Doom. The higher the skill, the harder the game becomes. Skill level affects monsters’ aggressiveness, monsters’ speed, weapon damage, ammunition quantities, etc. Takes effect from the next episode.

1 - VERY EASY, “I’m Too Young to Die” in Doom.
2 - EASY, “Hey, Not Too Rough” in Doom.
3 - NORMAL, “Hurt Me Plenty” in Doom.
4 - HARD, “Ultra-Violence” in Doom.
5 - VERY HARD, “Nightmare!” in Doom.

Default value: 3

set_doom_config_path(self: vizdoom.DoomGame, button: str) → None#

Sets the path for ZDoom’s configuration file. The file is responsible for the configuration of the ZDoom engine itself. If it does not exist, it will be created after the vizdoom executable is run. This method is not needed for most of the tasks and is added for the convenience of users with hacking tendencies.

Default value: “”, if left empty “_vizdoom.ini” will be used.

get_seed(self: vizdoom.DoomGame) → int#: Return ViZDoom’s seed.

set_seed(self: vizdoom.DoomGame, seed: int) → None#

Sets the seed of the ViZDoom’s RNG that generates seeds (initial state) for episodes.

Default value: randomized in constructor

get_episode_start_time(self: vizdoom.DoomGame) → int#: Returns start delay of every episode in tics.

set_episode_start_time(self: vizdoom.DoomGame, start_time: int) → None#

Sets start delay of every episode in tics. Every episode will effectively start (from the user’s perspective) after the provided number of tics.

Default value: 1

get_episode_timeout(self: vizdoom.DoomGame) → int#: Returns the number of tics after which the episode will be finished.

set_episode_timeout(self: vizdoom.DoomGame, timeout: int) → None#: Sets the number of tics after which the episode will be finished. 0 will result in no timeout.

Output/rendering setting methods#

set_screen_resolution(self: vizdoom.DoomGame, resolution: vizdoom.ScreenResolution) → None#

Sets the screen resolution. ZDoom engine supports only specific resolutions. Supported resolutions are part of ScreenResolution enumeration (e.g., RES_320X240, RES_640X480, RES_1920X1080). The buffers, as well as the content of ViZDoom’s display window, will be affected.

Default value: RES_320X240

get_screen_format(self: vizdoom.DoomGame) → vizdoom.ScreenFormat#: Returns the format of the screen buffer and the automap buffer.

set_screen_format(self: vizdoom.DoomGame, format: vizdoom.ScreenFormat) → None#

Sets the format of the screen buffer and the automap buffer. Supported formats are defined in ScreenFormat enumeration type (e.g. CRCGCB, RGB24, GRAY8). The format change affects only the buffers, so it will not have any effect on the content of ViZDoom’s display window.

Default value: CRCGCB

is_depth_buffer_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the depth buffer is enabled.

set_depth_buffer_enabled(self: vizdoom.DoomGame, depth_buffer: bool) → None#

Enables rendering of the depth buffer, it will be available in the state. Depth buffer will contain noise if viz_nocheat is enabled.

Default value: False

is_labels_buffer_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the labels buffer is enabled.

set_labels_buffer_enabled(self: vizdoom.DoomGame, labels_buffer: bool) → None#

Enables rendering of the labels buffer, it will be available in the state with the vector of Label`s. LabelsBuffer will contain noise if `viz_nocheat is enabled.

Default value: False

is_automap_buffer_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the automap buffer is enabled.

set_automap_buffer_enabled(self: vizdoom.DoomGame, automap_buffer: bool) → None#

Enables rendering of the automap buffer, it will be available in the state.

Default value: False

set_automap_mode(self: vizdoom.DoomGame, mode: vizdoom.AutomapMode) → None#

Sets the automap mode (NORMAL, WHOLE, OBJECTS, OBJECTS_WITH_SIZE), which determines what will be visible on it.

Default value: NORMAL

set_automap_rotate(self: vizdoom.DoomGame, rotate: bool) → None#

Determine if the automap will be rotating with the player. If False, north always will be at the top of the buffer.

Default value: False

set_automap_render_textures(self: vizdoom.DoomGame, textures: bool) → None#

Determine if the automap will be textured, showing the floor textures.

Default value: True

set_render_hud(self: vizdoom.DoomGame, hud: bool) → None#

Determine if the hud will be rendered in the game.

Default value: False

set_render_minimal_hud(self: vizdoom.DoomGame, min_hud: bool) → None#

Determine if the minimalistic version of the hud will be rendered instead of the full hud.

Default value: False

set_render_weapon(self: vizdoom.DoomGame, weapon: bool) → None#

Determine if the weapon held by the player will be rendered in the game.

Default value: True

set_render_crosshair(self: vizdoom.DoomGame, crosshair: bool) → None#

Determine if the crosshair will be rendered in the game.

Default value: False

set_render_decals(self: vizdoom.DoomGame, decals: bool) → None#

Determine if the decals (marks on the walls) will be rendered in the game.

Default value: True

set_render_particles(self: vizdoom.DoomGame, particles: bool) → None#

Determine if the particles will be rendered in the game.

Default value: True

set_render_effects_sprites(self: vizdoom.DoomGame, sprites: bool) → None#

Determine if some effects sprites (gun puffs, blood splats etc.) will be rendered in the game.

Default value: True

set_render_messages(self: vizdoom.DoomGame, messages: bool) → None#

Determine if in-game messages (information about pickups, kills, etc.) will be rendered in the game.

Default value: False

set_render_corpses(self: vizdoom.DoomGame, bodies: bool) → None#

Determine if actors’ corpses will be rendered in the game.

Default value: True

set_render_screen_flashes(self: vizdoom.DoomGame, flashes: bool) → None#

Determine if the screen flash effect upon taking damage or picking up items will be rendered in the game.

Default value: True

set_render_all_frames(self: vizdoom.DoomGame, all_frames: bool) → None#

Determine if all frames between states will be rendered (when skip greater than 1 is used). Allows smooth preview but can reduce performance. It only makes sense to use it if the window is visible.

Default value: False

set_window_visible(self: vizdoom.DoomGame, visiblity: bool) → None#

Determines if ViZDoom’s window will be visible. ViZDoom with window disabled can be used on Linux systems without X Server.

Default value: False

set_console_enabled(self: vizdoom.DoomGame, console: bool) → None#

Determines if ViZDoom’s console output will be enabled.

Default value: False

set_sound_enabled(self: vizdoom.DoomGame, sound: bool) → None#

Determines if ViZDoom’s sound will be played.

Default value: False

get_screen_width(self: vizdoom.DoomGame) → int#: Returns game’s screen width - width of all buffers.

get_screen_height(self: vizdoom.DoomGame) → int#: Returns game’s screen height - height of all buffers.

get_screen_channels(self: vizdoom.DoomGame) → int#: Returns number of channels in screen buffer and map buffer (depth and labels buffer always have one channel).

get_screen_pitch(self: vizdoom.DoomGame) → int#: Returns size in bytes of one row in screen buffer and map buffer.

get_screen_size(self: vizdoom.DoomGame) → int#: Returns size in bytes of screen buffer and map buffer.

is_objects_info_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the objects information is enabled.

set_objects_info_enabled(self: vizdoom.DoomGame, objects_info: bool) → None#

Enables information about all objects present in the current episode/level. It will be available in the state.

Default value: False

is_sectors_info_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the information about sectors is enabled.

set_sectors_info_enabled(self: vizdoom.DoomGame, sectors_info: bool) → None#

Enables information about all sectors (map layout) present in the current episode/level. It will be available in the state.

Default value: False

is_audio_buffer_enabled(self: vizdoom.DoomGame) → bool#: Returns True if the audio buffer is enabled.

set_audio_buffer_enabled(self: vizdoom.DoomGame, audio_buffer: bool) → None#

Returns True if the audio buffer is enabled.

Default value: False

get_audio_sampling_rate(self: vizdoom.DoomGame) → int#: Returns the sampling rate of the audio buffer.

set_audio_sampling_rate(self: vizdoom.DoomGame, sampling_rate: vizdoom.SamplingRate) → None#

Sets the sampling rate of the audio buffer.

Default value: False

get_audio_buffer_size(self: vizdoom.DoomGame) → int#: Returns the size of the audio buffer.

set_audio_buffer_size(self: vizdoom.DoomGame, buffer_size: int) → None#

Sets the size of the audio buffer. The size is defined by a number of logic tics. After each action audio buffer will contain audio from the specified number of the last processed tics. Doom uses 35 ticks per second.

Default value: 4