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. The declarations of this class and its methods can be found in the include/ViZDoomGame.h
header file.
Here we document all the methods of the DoomGame class and their corresponding Python bindings implemented as pybind11 module.
Flow control methods#
init
#
C++ |
|
---|---|
Python |
|
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
#
C++ |
|
---|---|
Python |
|
Closes ViZDoom game instance. It is automatically invoked by the destructor. The game can be initialized again after being closed.
newEpisode
#
C++ |
|
---|---|
Python |
|
Changed in 1.1.0
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.
replayEpisode
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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.
See also:
isRunning
#
C++ |
|
---|---|
Python |
|
Checks if the ViZDoom game instance is running.
isMultiplayerGame
#
C++ |
|
---|---|
Python |
|
Added in 1.1.2
Checks if the game is in multiplayer mode.
isRecordingEpisode
#
C++ |
|
---|---|
Python |
|
Added in 1.1.5
Checks if the game is in recording mode.
isReplayingEpisode
#
C++ |
|
---|---|
Python |
|
Added in 1.1.5
Checks if the game is in replaying mode.
setAction
#
C++ |
|
---|---|
Python |
`set_action(actions: list |
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).
advanceAction
#
C++ |
|
---|---|
Python |
|
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.
makeAction
#
C++ |
|
---|---|
Python |
`make_action(actions: list |
Method combining usability of setAction
, advanceAction
and getLastReward
.
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.
isNewEpisode
#
C++ |
|
---|---|
Python |
|
Returns true if the current episode is in the initial state - the first state, no actions were performed yet.
isEpisodeFinished
#
C++ |
|
---|---|
Python |
|
Returns true if the current episode is in the terminal state (is finished).
makeAction
and advanceAction
methods will take no effect after this point (unless newEpisode
method is called).
isPlayerDead
#
C++ |
|
---|---|
Python |
|
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.
respawnPlayer
#
C++ |
|
---|---|
Python |
|
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:
sendGameCommand
#
C++ |
|
---|---|
Python |
|
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:
getState
#
C++ |
|
---|---|
Python |
|
Changed in 1.1.0
Returns GameState
object with the current game state.
If the current episode is finished, nullptr/null/None
will be returned.
See also:
getServerState
#
C++ |
|
---|---|
Python |
|
Added in 1.1.6
Returns ServerState
object with the current server state.
See also:
getLastAction
#
C++ |
|
---|---|
Python |
|
Returns the last action performed.
Each value corresponds to a button added with [addAvailableButton](#addAvailableButton)
(in order of appearance).
Most useful in SPECTATOR
mode.
getEpisodeTime
#
C++ |
|
---|---|
Python |
|
Returns number of current episode tic.
save
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Saves a game’s internal state to the file using ZDoom’s save game functionality.
load
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
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.
GameVariables methods#
getAvailableGameVariables
#
C++ |
|
---|---|
Python |
|
Returns the list of available GameVariables
.
See also:
setAvailableGameVariables
#
C++ |
|
---|---|
Python |
`set_available_game_variables(variables: list |
Set list of GameVariable
as available GameVariables
in the GameState
returned by getState
method.
Config key: availableGameVariables/available_game_variables
(list)
See also:
addAvailableGameVariable
#
C++ |
|
---|---|
Python |
|
Adds the specified GameVariable
to the list of available game variables (e.g. HEALTH
, AMMO1
, ATTACK_READY
) in the GameState
returned by getState
method.
Config key: availableGameVariables/available_game_variables
(list)
See also:
clearAvailableGameVariables
#
C++ |
|
---|---|
Python |
|
Clears the list of available GameVariables
that are included in the GameState
returned by getState
method.
See also:
getAvailableGameVariablesSize
#
C++ |
|
---|---|
Python |
|
Returns the number of available GameVariables
.
See also:
getGameVariable
#
C++ |
|
---|---|
Python |
|
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
.
See also:
Game Arguments methods#
addGameArgs
#
C++ |
|
---|---|
Python |
|
Adds a custom argument that will be passed to ViZDoom process during initialization. Useful for changing additional game settings.
Config key: gameArgs/game_args
See also:
clearGameArgs
#
C++ |
|
---|---|
Python |
|
Clears all arguments previously added with addGameArgs
method.
Reward methods#
getLivingReward
#
C++ |
|
---|---|
Python |
|
Returns the reward granted to the player after every tic.
setLivingReward
#
C++ |
|
---|---|
Python |
|
Sets the reward granted to the player after every tic. A negative value is also allowed.
Default value: 0
Config key: livingReward/living_reward
getDeathPenalty
#
C++ |
|
---|---|
Python |
|
Returns the penalty for the player’s death.
setDeathPenalty
#
C++ |
|
---|---|
Python |
|
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
getLastReward
#
C++ |
|
---|---|
Python |
|
Returns a reward granted after the last update of state.
getTotalReward
#
C++ |
|
---|---|
Python |
|
Returns the sum of all rewards gathered in the current episode.
General game setting methods#
loadConfig
#
C++ |
|
---|---|
Python |
|
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/
.
See also:
getMode
#
C++ |
|
---|---|
Python |
|
Returns current mode (PLAYER
, SPECTATOR
, ASYNC_PLAYER
, ASYNC_SPECTATOR
).
See also:
setMode
#
C++ |
|
---|---|
Python |
|
Sets mode (PLAYER
, SPECTATOR
, ASYNC_PLAYER
, ASYNC_SPECTATOR
) in which the game will be running.
Default value: PLAYER
.
Config key: mode
See also:
getTicrate
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Returns current ticrate.
setTicrate
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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).
Config key: ticrate
See also:
setViZDoomPath
#
C++ |
|
---|---|
Python |
|
Sets path to the ViZDoom engine executable vizdoom.
Default value: “{vizdoom.so location}/{vizdoom or vizdoom.exe (on Windows)}”.
Config key: `ViZDoomPath/vizdoom_path
setDoomGamePath
#
C++ |
|
---|---|
Python |
|
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}”
Config key: DoomGamePath/doom_game_path
setDoomScenarioPath
#
C++ |
|
---|---|
Python |
|
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
setDoomMap
#
C++ |
|
---|---|
Python |
|
Sets the map name to be used.
Default value: “map01”, if set to empty “map01” will be used.
Config key: DoomMap/doom_map
setDoomSkill
#
C++ |
|
---|---|
Python |
|
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
setDoomConfigPath
#
C++ |
|
---|---|
Python |
|
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
getSeed
#
C++ |
|
---|---|
Python |
|
Return ViZDoom’s seed.
setSeed
#
C++ |
|
---|---|
Python |
|
Sets the seed of the ViZDoom’s RNG that generates seeds (initial state) for episodes.
Default value: randomized in constructor
Config key: seed
See also:
getEpisodeStartTime
#
C++ |
|
---|---|
Python |
|
Returns start delay of every episode in tics.
setEpisodeStartTime
#
C++ |
|
---|---|
Python |
|
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
Config key: episodeStartTime/episode_start_time
getEpisodeTimeout
#
C++ |
|
---|---|
Python |
|
Returns the number of tics after which the episode will be finished.
setEpisodeTimeout
#
C++ |
|
---|---|
Python |
|
Sets the number of tics after which the episode will be finished. 0 will result in no timeout.
Config key: episodeTimeout/episode_timeout
Output/rendering setting methods#
setScreenResolution
#
C++ |
|
---|---|
Python |
|
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
Config key: screenResolution/screen_resolution
See also:
getScreenFormat
#
C++ |
|
---|---|
Python |
|
Returns the format of the screen buffer and the automap buffer.
setScreenFormat
#
C++ |
|
---|---|
Python |
|
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
Config key: screenFormat/screen_format
See also:
isDepthBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Returns true if the depth buffer is enabled.
setDepthBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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
Config key: depthBufferEnabled/depth_buffer_enabled
See also:
isLabelsBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Returns true if the labels buffer is enabled.
setLabelsBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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
Config key: labelsBufferEnabled/labels_buffer_enabled
See also:
isAutomapBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Returns true if the automap buffer is enabled.
setAutomapBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Enables rendering of the automap buffer, it will be available in the state.
Default value: false
Config key: automapBufferEnabled/automap_buffer_enabled
See also:
setAutomapMode
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Sets the automap mode (NORMAL
, WHOLE
, OBJECTS
, OBJECTS_WITH_SIZE
),
which determines what will be visible on it.
Default value: NORMAL
Config key: automapMode/set_automap_mode
See also:
setAutomapRotate
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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
setAutomapRenderTextures
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Determine if the automap will be textured, showing the floor textures.
Default value: true
Config key: automapRenderTextures/automap_render_textures
setRenderHud
#
C++ |
|
---|---|
Python |
|
Determine if the hud will be rendered in the game.
Default value: false
Config key: renderHud/render_hud
setRenderMinimalHud
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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
setRenderWeapon
#
C++ |
|
---|---|
Python |
|
Determine if the weapon held by the player will be rendered in the game.
Default value: true
Config key: renderWeapon/render_weapon
setRenderCrosshair
#
C++ |
|
---|---|
Python |
|
Determine if the crosshair will be rendered in the game.
Default value: false
Config key: renderCrosshair/render_crosshair
setRenderDecals
#
C++ |
|
---|---|
Python |
|
Determine if the decals (marks on the walls) will be rendered in the game.
Default value: true
Config key: renderDecals/render_decals
setRenderParticles
#
C++ |
|
---|---|
Python |
|
Determine if the particles will be rendered in the game.
Default value: true
Config key: renderParticles/render_particles
setRenderEffectsSprites
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
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
setRenderMessages
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Determine if in-game messages (information about pickups, kills, etc.) will be rendered in the game.
Default value: false
Config key: renderMessages/render_messages
setRenderCorpses
#
C++ |
|
---|---|
Python |
|
Added in 1.1.0
Determine if actors’ corpses will be rendered in the game.
Default value: true
Config key: renderCorpses/render_corpses
setRenderScreenFlashes
#
C++ |
|
---|---|
Python |
|
Added in 1.1.3
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
setRenderAllFrames
#
C++ |
|
---|---|
Python |
|
Added in 1.1.3
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:
setWindowVisible
#
C++ |
|
---|---|
Python |
|
Determines if ViZDoom’s window will be visible. ViZDoom with window disabled can be used on Linux systems without X Server.
Default value: false
Config key: windowVisible/window_visible
setConsoleEnabled
#
C++ |
|
---|---|
Python |
|
Determines if ViZDoom’s console output will be enabled.
Default value: false
Config key: consoleEnabled/console_enabled
setSoundEnabled
#
C++ |
|
---|---|
Python |
|
Determines if ViZDoom’s sound will be played.
Default value: false
Config key: soundEnabled/sound_enabled
getScreenWidth
#
C++ |
|
---|---|
Python |
|
Returns game’s screen width - width of all buffers.
getScreenHeight
#
C++ |
|
---|---|
Python |
|
Returns game’s screen height - height of all buffers.
getScreenChannels
#
C++ |
|
---|---|
Python |
|
Returns number of channels in screen buffer and map buffer (depth and labels buffer always have one channel).
getScreenPitch
#
C++ |
|
---|---|
Python |
|
Returns size in bytes of one row in screen buffer and map buffer.
getScreenSize
#
C++ |
|
---|---|
Python |
|
Returns size in bytes of screen buffer and map buffer.
isObjectsInfoEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.8
Returns true if the objects information is enabled.
setObjectsInfoEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.8
Enables information about all objects present in the current episode/level. It will be available in the state.
Default value: false
Config key: objectsInfoEnabled/objects_info_enabled
See also:
isSectorsInfoEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.8
Returns true if the information about sectors is enabled.
setSectorsInfoEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.8
Enables information about all sectors (map layout) present in the current episode/level. It will be available in the state.
Default value: false
Config key: sectorsInfoEnabled/sectors_info_enabled
See also:
isAudioBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Returns true if the audio buffer is enabled.
setAudioBufferEnabled
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Returns true if the audio buffer is enabled.
Default value: false
Config key: audioBufferEnabled/audio_buffer_enabled
See also:
getAudioSamplingRate
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Returns the sampling rate of the audio buffer.
See also:
setAudioSamplingRate
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Sets the sampling rate of the audio buffer.
Default value: false
Config key: audioSamplingRate/audio_samping_rate
See also:
getAudioBufferSize
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
Returns the size of the audio buffer.
See also:
setAudioBufferSize
#
C++ |
|
---|---|
Python |
|
Added in 1.1.9
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
Config key: audioBufferSize/audio_buffer_size
See also: