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 recording_file_path argument 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.

Note: Changed in 1.1.0

replay_episode(self: vizdoom.DoomGame, file_path: str, player: int = 0) → None#

Replays the recorded episode from the given file using the perspective of the specified player. Players are numbered from 1, If player argument is equal to 0, the episode will be replayed 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 when replaying the episode.

See also:

Note: added in 1.1.0.

is_running(self: vizdoom.DoomGame) → bool#: Returns True if the controlled game instance is running.

is_multiplayer_game(self: vizdoom.DoomGame) → bool#

Returns True if the game is in multiplayer mode.

See also:

Note: added in 1.1.2.

is_recording_episode(self: vizdoom.DoomGame) → bool#

Returns True if the game is in recording mode.

Note: added in 1.1.5.

is_replaying_episode(self: vizdoom.DoomGame) → bool#

Returns True if the game is in replay mode.

Note: added in 1.1.5.

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

advance_action(self: vizdoom.DoomGame, tics: int = 1, update_state: bool = True) → None#: Processes the specified number of tics. If update_state argument 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 get_state() and to get the new reward use get_last_reward().

make_action(self: vizdoom.DoomGame, action: object, tics: int = 1) → float#: This method combines functionality of set_action(), advance_action() and get_last_reward(). Sets the player’s action for the next tics, processes the 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). make_action() and advance_action() methods will take no effect after this point (unless new_episode() method is called).

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 respawn_player() 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.

See also:

is_multiplayer_game()

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.

See also:

get_state(self: vizdoom.DoomGame) → vizdoom.GameState#

Returns GameState object with the current game state. If the current episode is finished, None will be returned.

Note: Changed in 1.1.0

get_server_state(self: vizdoom.DoomGame) → vizdoom.ServerState#

Returns ServerState object with the current server state.

Note: added in 1.1.6.

get_last_action(self: vizdoom.DoomGame) → list#: Returns the last action performed. Each value corresponds to a button added with set_available_buttons() or/and add_available_button() (in order of appearance). 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 save game functionality.

Note: added in 1.1.9.

load(self: vizdoom.DoomGame, file_path: str) → None#

Loads a game’s internal state from the file using ZDoom 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.

Note: added in 1.1.9.

Buttons settings methods#

get_available_buttons(self: vizdoom.DoomGame) → list#: Returns the list of available Button s, that were added with set_available_buttons() or/and add_available_button() methods.

set_available_buttons(self: vizdoom.DoomGame, buttons: list) → None#

Sets given list of Button s (e.g. TURN_LEFT, MOVE_FORWARD) as available buttons.

Has no effect when the game is running.

Config key: availableButtons/available_buttons (list of values)

add_available_button(self: vizdoom.DoomGame, button: vizdoom.Button, max_value: float = -1) → None#

Adds Button type (e.g. TURN_LEFT, MOVE_FORWARD) 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 will be overridden.

Has no effect when the game is running.

Config key: availableButtons/available_buttons (list of values)

clear_available_buttons(self: vizdoom.DoomGame) → None#

Clears all available :class:`.Button`s added so far.

Has no effect when the game is running.

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

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.

Has no effect when the game is running.

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 GameVariable s, that were added with set_available_game_variables() or/and add_available_game_variable() methods.

set_available_game_variables(self: vizdoom.DoomGame, variables: list) → None#

Sets list of GameVariable s as available game variables in the GameState returned by get_state() method.

Has no effect when the game is running.

Config key: availableGameVariables/available_game_variables (list of values)

add_available_game_variable(self: vizdoom.DoomGame, variable: vizdoom.GameVariable) → None#

Adds the specified GameVariable to the list of available game variables (e.g. HEALTH, AMMO1, ATTACK_READY) in the GameState returned by get_state() method.

Has no effect when the game is running.

Config key: availableGameVariables/available_game_variables (list of values)

clear_available_game_variables(self: vizdoom.DoomGame) → None#

Clears the list of available GameVariable s that are included in the GameState returned by get_state() method.

Has no effect when the game is running.

get_available_game_variables_size(self: vizdoom.DoomGame) → int#: Returns the number of available GameVariable. It corresponds to taking the size of the list returned by get_available_game_variables().

get_game_variable(self: vizdoom.DoomGame, variable: vizdoom.GameVariable) → float#: Returns the current value of the specified GameVariable (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#

set_game_args(self: vizdoom.DoomGame, args: str) → None#

Sets custom arguments that will be passed to ViZDoom process during initialization. It is useful for changing additional game settings. Use with caution, as in rare cases it may prevent the library from working properly. Using this method is equivalent to first calling clear_game_args() and then add_game_args().

Config key: gameArgs/game_args

See also:

Note: added in 1.2.3.

add_game_args(self: vizdoom.DoomGame, args: str) → None#

Adds custom arguments that will be passed to ViZDoom process during initialization. It is useful for changing additional game settings. Use with caution, as in rare cases it may prevent the library from working properly.

Config key: gameArgs/game_args

See also:

clear_game_args(self: vizdoom.DoomGame) → None#: Clears all arguments previously added with set_game_args() or/and add_game_args() methods.

get_game_args(self: vizdoom.DoomGame) → str#

Returns the additional arguments for ViZDoom process set with set_game_args() or/and add_game_args() methods.

Note: added in 1.2.3.

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

Config key: livingReward/living_reward

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

Config key: deathPenalty/death_penalty

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 library location>/scenarios/.

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

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

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

Default value: PLAYER.

Has no effect when the game is running.

Config key: mode

get_ticrate(self: vizdoom.DoomGame) → int#

Returns current ticrate.

Note: added in 1.1.0.

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

Sets the 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).

Has no effect when the game is running.

Config key: ticrate

See also:

examples/python/ticrate.py

Note: added in 1.1.0.

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

Sets the path to the ViZDoom engine executable vizdoom.

Default value: <ViZDoom library location>/<vizdoom or vizdoom.exe on Windows>.

Config key: ViZDoomPath/vizdoom_path

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 library/pyd is).

Default value: <ViZDoom library location>/<doom2.wad, doom.wad, freedoom2.wad, or freedoom.wad - in this order>

Config key: DoomGamePath/doom_game_path

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: ""

Config key: DoomScenarioPath/set_doom_scenario_path

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.

Config key: DoomMap/doom_map

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

Config key: DoomSkill/doom_skill

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.

Config key: DoomConfigPath/doom_config_path

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

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

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

Default value: randomized in constructor

Config key: seed

See also:

examples/python/seed.py

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

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

Sets the start time (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

Config key: episodeStartTime/episode_start_time

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.

Default value: 0

Config key: episodeTimeout/episode_timeout

Output/rendering setting methods#

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

Sets the screen resolution and additional buffers (depth, labels, and automap). 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

Has no effect when the game is running.

Config key: screenResolution/screen_resolution

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

Has no effect when the game is running.

Config key: screenFormat/screen_format

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. The buffer always has the same resolution as the screen buffer. Depth buffer will contain noise if viz_nocheat flag is enabled.

Default value: False

Has no effect when the game is running.

Config key: depthBufferEnabled/depth_buffer_enabled

See also:

Note: added in 1.1.0.

is_labels_buffer_enabled(self: vizdoom.DoomGame) → bool#

Returns True if the labels buffer is enabled.

Note: added in 1.1.0.

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. The buffer always has the same resolution as the screen buffer. LabelsBuffer will contain noise if viz_nocheat is enabled.

Default value: False

Has no effect when the game is running.

Config key: labelsBufferEnabled/labels_buffer_enabled

See also:

Note: added in 1.1.0.

is_automap_buffer_enabled(self: vizdoom.DoomGame) → bool#

Returns True if the automap buffer is enabled.

Note: added in 1.1.0.

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

Enables rendering of the automap buffer, it will be available in the state. The buffer always has the same resolution as the screen buffer.

Default value: False

Has no effect when the game is running.

Config key: automapBufferEnabled/automap_buffer_enabled

See also:

Note: added in 1.1.0.

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

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

Default value: NORMAL

Config key: automapMode/set_automap_mode

Note: added in 1.1.0.

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

Config key: automapRotate/automap_rotate

Note: added in 1.1.0.

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

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

Default value: True

Config key: automapRenderTextures/automap_render_textures

Note: added in 1.1.0.

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

Determine if the hud will be rendered in the game.

Default value: False

Config key: renderHud/render_hud

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

Config key: renderMinimalHud/render_minimal_hud

Note: added in 1.1.0.

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

Config key: renderWeapon/render_weapon

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

Determine if the crosshair will be rendered in the game.

Default value: False

Config key: renderCrosshair/render_crosshair

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

Config key: renderDecals/render_decals

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

Determine if the particles will be rendered in the game.

Default value: True

Config key: renderParticles/render_particles

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

Config key: renderEffectsSprites/render_effects_sprites

Note: added in 1.1.0.

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

Config key: renderMessages/render_messages

Note: added in 1.1.0.

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

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

Default value: True

Config key: renderCorpses/render_corpses

Note: added in 1.1.0.

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

Config key: renderScreenFlashes/render_screen_flashes

Note: added in 1.1.0.

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

Config key: renderAllFrames/render_all_frames

See also:

set_window_visible()

Note: added in 1.1.3.

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

Has no effect when the game is running.

Config key: windowVisible/window_visible

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

Determines if ViZDoom’s console output will be enabled.

Default value: False

Config key: consoleEnabled/console_enabled

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

Determines if ViZDoom’s sound will be played.

Default value: False

Config key: soundEnabled/sound_enabled

get_screen_width(self: vizdoom.DoomGame) → int#: Returns game’s screen width - width of screen, depth, labels, and automap buffers.

get_screen_height(self: vizdoom.DoomGame) → int#: Returns game’s screen height - height of screen, depth, labels, and automap 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.

Note: added in 1.1.8.

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

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

Default value: False

Has no effect when the game is running.

Config key: objectsInfoEnabled/objects_info_enabled

See also:

Note: added in 1.1.8.

is_sectors_info_enabled(self: vizdoom.DoomGame) → bool#

Returns True if the information about sectors is enabled.

Note: added in 1.1.8.

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

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

Default value: False

Has no effect when the game is running.

Config key: sectorsInfoEnabled/sectors_info_enabled

See also:

Note: added in 1.1.8.

is_audio_buffer_enabled(self: vizdoom.DoomGame) → bool#

Returns True if the audio buffer is enabled.

Note: added in 1.1.9.

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

Enables rendering of the audio buffer, it will be available in the state. The audio buffer will contain audio from the number of the last tics specified by set_audio_buffer_size() method. Sampling rate can be set with set_audio_sampling_rate() method.

Default value: False

Has no effect when the game is running.

Config key: audioBufferEnabled/audio_buffer_enabled

See also:

Note: added in 1.1.9.

get_audio_sampling_rate(self: vizdoom.DoomGame) → int#

Returns the SamplingRate of the audio buffer.

See also:

Note: added in 1.1.9.

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

Sets the SamplingRate of the audio buffer.

Default value: False

Has no effect when the game is running.

Config key: audioSamplingRate/audio_samping_rate

See also:

Note: added in 1.1.9.

get_audio_buffer_size(self: vizdoom.DoomGame) → int#

Returns the size of the audio buffer.

Note: added in 1.1.9.

See also:

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

Has no effect when the game is running.

Config key: audioBufferSize/audio_buffer_size

See also:

Note: added in 1.1.9.