diff --git a/doc/DoomGame.md b/doc/DoomGame.md index 6714051df..2bd480603 100644 --- a/doc/DoomGame.md +++ b/doc/DoomGame.md @@ -1,9 +1,102 @@ # DoomGame -## Flow control methods - ---- -### `init` +[Flow control methods](#flow) +* [init](#init) +* [close](#close) +* [newEpisode](#newEpisode) +* [replayEpisode](#replayEpisode) +* [isRunning](#isRunning) +* [setAction](#setAction) +* [advanceAction](#advanceAction) +* [makeAction](#makeAction) +* [isNewEpisode](#isNewEpisode) +* [isEpisodeFinished](#isEpisodeFinished) +* [isPlayerDead](#isPlayerDead) +* [respawnPlayer](#respawnPlayer) +* [sendGameCommand](#sendGameCommand) +* [getState](#getState) +* [getLastAction](#getLastAction) +* [getEpisodeTime](#getEpisodeTime) + +[Buttons settings methods](#buttons) +* [addAvailableButton](#addAvailableButton) +* [clearAvailableButtons](#clearAvailableButtons) +* [getAvailableButtonsSize](#getAvailableButtonsSize) +* [setButtonMaxValue](#setButtonMaxValue) +* [getButtonMaxValue](#getButtonMaxValue) + +[GameVariables methods](#vars) +* [addAvailableGameVariable](#addAvailableGameVariable) +* [clearAvailableGameVariables](#clearAvailableGameVariables) +* [getAvailableGameVariablesSize](#getAvailableGameVariablesSize) +* [getGameVariable](#getGameVariable) + +[Game Arguments methods](#args) +* [addGameArgs](#addGameArgs) +* [clearGameArgs](#clearGameArgs) + +[Rewards methods](#rewards) +* [getLivingReward](#getLivingReward) +* [setLivingReward](#setLivingReward) +* [getDeathPenalty](#getDeathPenalty) +* [setDeathPenalty](#setDeathPenalty) +* [getLastReward](#getLastReward) +* [getTotalReward](#getTotalReward) + +[General game setting methods](#settings) +* [loadConfig](#loadConfig) +* [getMode](#getMode) +* [setMode](#setMode) +* [getTicrate](#getTicrate) +* [setTicrate](#setTicrate) +* [setViZDoomPath](#setViZDoomPath) +* [setDoomGamePath](#setDoomGamePath) +* [setDoomScenarioPath](#setDoomScenarioPath) +* [setDoomMap](#setDoomMap) +* [setDoomSkill](#setDoomSkill) +* [setDoomConfigPath](#setDoomConfigPath) +* [getSeed](#getSeed) +* [setSeed](#setSeed) +* [getEpisodeStartTime](#getEpisodeStartTime) +* [setEpisodeStartTime](#setEpisodeStartTime) +* [getEpisodeTimeout](#getEpisodeTimeout) +* [setEpisodeTimeout](#setEpisodeTimeout) + +[Output/rendering setting methods](#rendering) +* [setScreenResolution](#setScreenResolution) +* [getScreenFormat](#getScreenFormat) +* [setScreenFormat](#setScreenFormat) +* [isDepthBufferEnabled](#isDepthBufferEnabled) +* [setDepthBufferEnabled](#setDepthBufferEnabled) +* [isLabelsBufferEnabled](#isLabelsBufferEnabled) +* [setLabelsBufferEnabled](#setLabelsBufferEnabled) +* [isAutomapBufferEnabled](#isAutomapBufferEnabled) +* [setAutomapBufferEnabled](#setAutomapBufferEnabled) +* [setAutomapMode](#setAutomapMode) +* [setAutomapRotate](#setAutomapRotate) +* [setAutomapRenderTextures](#setAutomapRenderTextures) +* [setRenderHud](#setRenderHud) +* [setRenderMinimalHud](#setRenderMinimalHud) +* [setRenderWeapon](#setRenderWeapon) +* [setRenderCrosshair](#setRenderCrosshair) +* [setRenderDecals](#setRenderDecals) +* [setRenderParticles](#setRenderParticles) +* [setRenderEffectsSprites](#setRenderEffectsSprites) +* [setRenderMessages](#setRenderMessages) +* [setWindowVisible](#setWindowVisible) +* [setConsoleEnabled](#setConsoleEnabled) +* [setSoundEnabled](#setSoundEnabled) +* [getScreenWidth](#getScreenWidth) +* [getScreenHeight](#getScreenHeight) +* [getScreenChannels](#getScreenChannels) +* [getScreenPitch](#getScreenPitch) +* [getScreenSize](#getScreenSize) + + +## Flow control methods: + +--- +### `init` | C++ | `bool init()` | | :-- | :-- | @@ -12,13 +105,13 @@ | Python | `bool init()` | Initializes ViZDoom game instance and starts newEpisode. -After calling this method, first state from new episode will be available. -Some configuration options cannot be changed after calling method. +After calling this method, 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` +### `close` | C++ | `void close()` | | :-- | :-- | @@ -32,26 +125,26 @@ Game can be initialized again after being closed. --- -### `newEpisode` +### `newEpisode` -| C++ | `void newEpisode(std::string filePath = "")` | +| C++ | `void newEpisode(std::string recordFilePath = "")` | | :-- | :-- | -| Lua | `void newEpisode(string filePath = "")` | -| Java | `void newEpisode(String filePath = "")` | -| Python | `void new_episode(str filePath = "")` | +| Lua | `void newEpisode(string recordFilePath = "")` | +| Java | `void newEpisode(String recordFilePath = "")` | +| Python | `void new_episode(str recordFilePath = "")` | Changed in 1.1 Initializes a new episode. All rewards, variables and state are restarted. After calling this method, first state from new episode will be available. -If the filePath is not empty, given episode will be recorded to this file. +If the recordFilePath is not empty, given episode will be recorded to this file (as a Doom lump). In multiplayer game, 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` +### `replayEpisode` | C++ | `void replayEpisode(std::string filePath, unsigned int player = 0)` | | :-- | :-- | @@ -67,13 +160,13 @@ of default player in record file. After calling this method, first state from replay will be available. All rewards, variables and state are available during replaying episode. -See also: +See also: - examples/python/record_episodes.py, - examples/python/record_multiplayer.py. --- -### `isRunning` +### `isRunning` | C++ | `bool isRunning()` | | :-- | :-- | @@ -85,7 +178,7 @@ Checks if the ViZDoom game instance is running. --- -### `setAction` +### `setAction` | C++ | `void setAction(std::vector const &actions)` | | :-- | :-- | @@ -99,7 +192,7 @@ or in configuration file (in order of appearance). --- -### `advanceAction` +### `advanceAction` | C++ | `void advanceAction(unsigned int tics = 1, bool updateState = true, bool renderOnly = false)` | | :-- | :-- | @@ -114,7 +207,7 @@ will be rendered after last processed tic. --- -### `makeAction` +### `makeAction` | C++ | `double makeAction(std::vector const &actions, unsigned int tics = 1)` | | :-- | :-- | @@ -128,7 +221,7 @@ updates the state and calculates a new reward, which is returned. --- -### `isNewEpisode` +### `isNewEpisode` | C++ | `bool isNewEpisode()` | | :-- | :-- | @@ -136,11 +229,11 @@ updates the state and calculates a new reward, which is returned. | Java | `boolean isNewEpisode()` | | Python | `bool is_new_episode()` | -Returns true if the current episode is in the initial state - first state, no actions were performed yet. +Returns true if the current episode is in the initial state - the first state, no actions were performed yet. --- -### `isEpisodeFinished` +### `isEpisodeFinished` | C++ | `bool isEpisodeFinished()` | | :-- | :-- | @@ -153,7 +246,7 @@ Returns true if the current episode is in the terminal state (is finished). --- -### `isPlayerDead` +### `isPlayerDead` | C++ | `bool isPlayerDead()` | | :-- | :-- | @@ -161,13 +254,13 @@ Returns true if the current episode is in the terminal state (is finished). | Java | `boolean isPlayerDead()` | | Python | `bool is_player_dead()` | -Returns true if the player is dead state. +Returns true if the player is dead. In singleplayer player death is equivalent to the end of the episode. In multiplayer when player is dead `respawnPlayer` can be called. --- -### `respawnPlayer` +### `respawnPlayer` | C++ | `void respawnPlayer()` | | :-- | :-- | @@ -180,7 +273,7 @@ After calling this method, first state after respawn will be available. --- -### `sendGameCommand` +### `sendGameCommand` | C++ | `void sendGameCommand(std::string cmd)` | | :-- | :-- | @@ -189,14 +282,13 @@ After calling this method, first state after respawn will be available. | Python | `void send_game_command(cmd)` | Sends the command to Doom console. Can be used for cheats, multiplayer etc. -Some commands will be block in some modes. +Some commands will be blocked in some modes. -See also: -- ZDoom Wiki: http://zdoom.org/wiki/Console +See also: [ZDoom Wiki](http://zdoom.org/wiki/Console) --- -### `getState` +### `getState` | C++ | `GameStatePtr (std::shared_ptr) GameState getState()` | | :-- | :-- | @@ -210,11 +302,12 @@ Returns `GameState` object with the current game state. If game is not running or episode is finished `nullptr/null/None` will be returned. See also: + - Types: `GameState` --- -### `getLastAction` +### `getLastAction` | C++ | `std::vector getLastAction()` | | :-- | :-- | @@ -228,7 +321,7 @@ Most useful in `SPECTATOR` mode. --- -### `getEpisodeTime` +### `getEpisodeTime` | C++ | `unsigned int getEpisodeTime()` | | :-- | :-- | @@ -239,10 +332,10 @@ Most useful in `SPECTATOR` mode. Returns number of current episode tic. -## Buttons settings methods +## Buttons settings methods --- -### `addAvailableButton` +### `addAvailableButton` | C++ | `void addAvailableButton(Button button, unsigned int maxValue = 0)` | | :-- | :-- | @@ -263,7 +356,7 @@ See also: --- -### `clearAvailableButtons` +### `clearAvailableButtons` | C++ | `void clearAvailableButtons()` | | :-- | :-- | @@ -275,7 +368,7 @@ Clears all available `Buttons` added so far. --- -### `getAvailableButtonsSize` +### `getAvailableButtonsSize` | C++ | `int getAvailableButtonsSize()` | | :-- | :-- | @@ -287,7 +380,7 @@ Returns the number of available `Buttons`. --- -### `setButtonMaxValue` +### `setButtonMaxValue` | C++ | `void setButtonMaxValue(Button button, unsigned int maxValue = 0)` | | :-- | :-- | @@ -302,7 +395,7 @@ Constraints limit applies in all Modes. --- -### `getButtonMaxValue` +### `getButtonMaxValue` | C++ | `unsigned int getButtonMaxValue(Button button)` | | :-- | :-- | @@ -313,11 +406,11 @@ Constraints limit applies in all Modes. Returns the maximum allowed, absolute value for the specified button. -## GameVariables methods +## GameVariables methods --- -### `addAvailableGameVariable` +### `addAvailableGameVariable` | C++ | `void addAvailableGameVariable(GameVariable variable)` | | :-- | :-- | @@ -335,7 +428,7 @@ See also: - ConfigFile: List --- -### `clearAvailableGameVariables` +### `clearAvailableGameVariables` | C++ | `void clearAvailableGameVariables()` | | :-- | :-- | @@ -347,7 +440,7 @@ Clears the list of available `GameVariables` that are included in the GameState --- -### `getAvailableGameVariablesSize` +### `getAvailableGameVariablesSize` | C++ | `unsigned int getAvailableGameVariablesSize()` | | :-- | :-- | @@ -359,7 +452,7 @@ Returns the number of available `GameVariables`. --- -### `getGameVariable` +### `getGameVariable` | C++ | `int getGameVariable(GameVariable variable)` | | :-- | :-- | @@ -375,10 +468,10 @@ See also: - Types: `GameVariable` -## Game Arguments methods +## Game Arguments methods --- -### `addGameArgs` +### `addGameArgs` | C++ | `void addGameArgs(std::string args)` | | :-- | :-- | @@ -396,7 +489,7 @@ See also: --- -### `clearGameArgs` +### `clearGameArgs` | C++ | `void clearGameArgs()` | | :-- | :-- | @@ -407,10 +500,10 @@ See also: Clears all arguments previously added with addGameArgs method. -## Reward methods +## Reward methods --- -### `getLivingReward` +### `getLivingReward` | C++ | `double getLivingReward()` | | :-- | :-- | @@ -422,7 +515,7 @@ Returns the reward granted to the player after every tic. --- -### `setLivingReward` +### `setLivingReward` | C++ | `void setLivingReward(double livingReward)` | | :-- | :-- | @@ -438,7 +531,7 @@ Config key: `livingReward/living_reward` --- -### `getDeathPenalty` +### `getDeathPenalty` | C++ | `double getDeathPenalty()` | | :-- | :-- | @@ -450,7 +543,7 @@ Returns the penalty for player's death. --- -### `setDeathPenalty` +### `setDeathPenalty` | C++ | `void setDeathPenalty(double deathPenalty)` | | :-- | :-- | @@ -466,7 +559,7 @@ Config key: `deathPenalty/death_penalty` --- -### `getLastReward` +### `getLastReward` | C++ | `double getLastReward()` | | :-- | :-- | @@ -478,7 +571,7 @@ Returns a reward granted after last update of state. --- -### `getTotalReward` +### `getTotalReward` | C++ | `double getTotalReward()` | | :-- | :-- | @@ -489,10 +582,10 @@ Returns a reward granted after last update of state. Returns the sum of all rewards gathered in the current episode. -## General game setting methods +## General game setting methods --- -### `loadConfig` +### `loadConfig` | C++ | `bool loadConfig(std::string filePath)` | | :-- | :-- | @@ -508,7 +601,7 @@ false if file was contained errors. --- -### `getMode` +### `getMode` | C++ | `Mode getMode()` | | :-- | :-- | @@ -520,7 +613,7 @@ Returns current mode. --- -### `setMode` +### `setMode` | C++ | `void setMode(Mode mode)` | | :-- | :-- | @@ -539,7 +632,7 @@ See also: --- -### `getTicrate` +### `getTicrate` | C++ | `unsigned int getTicrate()` | | :-- | :-- | @@ -553,7 +646,7 @@ Returns current ticrate. --- -### `setTicrate` +### `setTicrate` | C++ | `void setTicrate(unsigned int ticrate)` | | :-- | :-- | @@ -574,7 +667,7 @@ See also: --- -### `setViZDoomPath` +### `setViZDoomPath` | C++ | `void setViZDoomPath(std::string filePath)` | | :-- | :-- | @@ -590,7 +683,7 @@ Config key: `ViZDoomPath/vizdoom_path` --- -### `setDoomGamePath` +### `setDoomGamePath` | C++ | `void setDoomGamePath(std::string filePath)` | | :-- | :-- | @@ -606,7 +699,7 @@ Config key: `DoomGamePath/doom_game_path` --- -### `setDoomScenarioPath` +### `setDoomScenarioPath` | C++ | `void setDoomScenarioPath(std::string filePath)` | | :-- | :-- | @@ -622,7 +715,7 @@ Config key: `DoomScenarioPath/set_doom_scenario_path` --- -### `setDoomMap` +### `setDoomMap` | C++ | `void setDoomMap(std::string map)` | | :-- | :-- | @@ -638,7 +731,7 @@ Config key: `DoomMap/doom_map` --- -### `setDoomSkill` +### `setDoomSkill` | C++ | `void setDoomSkill(int skill)` | | :-- | :-- | @@ -663,7 +756,7 @@ Config key: `skill` --- -### `setDoomConfigPath` +### `setDoomConfigPath` | C++ | `void setDoomConfigPath(std::string filePath)` | | :-- | :-- | @@ -682,7 +775,7 @@ Config key: `DoomConfigPath/doom_config_path` --- -### `getSeed` +### `getSeed` | C++ | `unsigned int getSeed()` | | :-- | :-- | @@ -694,7 +787,7 @@ Return ViZDoom's seed. --- -### `setSeed` +### `setSeed` | C++ | `void setSeed(unsigned int seed)` | | :-- | :-- | @@ -713,7 +806,7 @@ See also: --- -### `getEpisodeStartTime` +### `getEpisodeStartTime` | C++ | `unsigned int getEpisodeStartTime()` | | :-- | :-- | @@ -725,7 +818,7 @@ Returns start delay of every episode in tics. --- -### `setEpisodeStartTime` +### `setEpisodeStartTime` | C++ | `void setEpisodeStartTime(unsigned int tics)` | | :-- | :-- | @@ -742,7 +835,7 @@ Config key: `episodeStartTime/episode_start_time` --- -### `getEpisodeTimeout` +### `getEpisodeTimeout` | C++ | `unsigned int getEpisodeTimeout()` | | :-- | :-- | @@ -754,7 +847,7 @@ Returns the number of tics after which the episode will be finished. --- -### `setEpisodeTimeout` +### `setEpisodeTimeout` | C++ | `void setEpisodeTimeout(unsigned int tics)` | | :-- | :-- | @@ -767,11 +860,11 @@ Sets the number of tics after which the episode will be finished. 0 will result Config key: `episodeTimeout/episode_timeout` -## Output/rendering setting methods +## Output/rendering setting methods ------------------------------------------------------------------------------------------------------------ --- -### `setScreenResolution` +### `setScreenResolution` | C++ | `void setScreenResolution(ScreenResolution resolution)` | | :-- | :-- | @@ -792,7 +885,7 @@ See also: --- -### `getScreenFormat` +### `getScreenFormat` | C++ | `ScreenFormat getScreenFormat()` | | :-- | :-- | @@ -804,7 +897,7 @@ Returns the format of the screen buffer and the automap buffer. --- -### `setScreenFormat` +### `setScreenFormat` | C++ | `void setScreenFormat(ScreenFormat format)` | | :-- | :-- | @@ -825,7 +918,7 @@ See also: --- -### `isDepthBufferEnabled` +### `isDepthBufferEnabled` | C++ | `bool isDepthBufferEnabled()` | | :-- | :-- | @@ -839,7 +932,7 @@ Returns true if the depth buffer is enabled. --- -### `setDepthBufferEnabled` +### `setDepthBufferEnabled` | C++ | `void setDepthBufferEnabled(bool depthBuffer)` | | :-- | :-- | @@ -861,7 +954,7 @@ See also: --- -### `isLabelsBufferEnabled` +### `isLabelsBufferEnabled` | C++ | `bool isLabelsBufferEnabled()` | | :-- | :-- | @@ -875,7 +968,7 @@ Returns true if the labels buffer is enabled. --- -### `setLabelsBufferEnabled` +### `setLabelsBufferEnabled` | C++ | `void setLabelsBufferEnabled(bool labelsBuffer)` | | :-- | :-- | @@ -899,7 +992,7 @@ See also: --- -### `isAutomapBufferEnabled` +### `isAutomapBufferEnabled` | C++ | `bool isAutomapBufferEnabled()` | | :-- | :-- | @@ -913,7 +1006,7 @@ Returns true if the automap buffer is enabled. --- -### `setAutomapBufferEnabled` +### `setAutomapBufferEnabled` | C++ | `void setAutomapBufferEnabled(bool automapBuffer)` | | :-- | :-- | @@ -935,7 +1028,7 @@ See also: --- -### `setAutomapMode` +### `setAutomapMode` | C++ | `void setAutomapMode(AutomapMode mode)` | | :-- | :-- | @@ -956,7 +1049,7 @@ See also: --- -### `setAutomapRotate` +### `setAutomapRotate` | C++ | `void setAutomapRotate(bool rotate)` | | :-- | :-- | @@ -974,7 +1067,7 @@ Config key: `automapRotate/render_hud` --- -### `setAutomapRenderTextures` +### `setAutomapRenderTextures` | C++ | `setAutomapRenderTextures(bool textures)` | | :-- | :-- | @@ -992,7 +1085,7 @@ Config key: `automapRenderTextures/automap_render_textures` --- -### `setRenderHud` +### `setRenderHud` | C++ | `void setRenderHud(bool hud)` | | :-- | :-- | @@ -1008,7 +1101,7 @@ Config key: `renderHud/render_hud` --- -### `setRenderMinimalHud` +### `setRenderMinimalHud` | C++ | `void setRenderMinimalHud(bool minHud)` | | :-- | :-- | @@ -1026,7 +1119,7 @@ Config key: `renderMinimalHud/render_minimal_hud` --- -### `setRenderWeapon` +### `setRenderWeapon` | C++ | `void setRenderWeapon(bool weapon)` | | :-- | :-- | @@ -1042,7 +1135,7 @@ Config key: `renderWeapon/render_weapon` --- -### `setRenderCrosshair` +### `setRenderCrosshair` | C++ | `void setRenderCrosshair(bool crosshair)` | | :-- | :-- | @@ -1058,7 +1151,7 @@ Config key: `renderCrosshair/render_crosshair` --- -### `setRenderDecals` +### `setRenderDecals` | C++ | `void setRenderDecals(bool decals)` | | :-- | :-- | @@ -1074,7 +1167,7 @@ Config key: `renderDecals/render_decals` --- -### `setRenderParticles` +### `setRenderParticles` | C++ | `void setRenderParticles(bool particles)` | | :-- | :-- | @@ -1090,7 +1183,7 @@ Config key: `renderParticles/render_particles` --- -### `setRenderEffectsSprites` +### `setRenderEffectsSprites` | C++ | `void setRenderEffectsSprites(bool sprites)` | | :-- | :-- | @@ -1108,7 +1201,7 @@ Config key: `renderEffectsSprites/render_effects_sprites` --- -### `setRenderMessages` +### `setRenderMessages` | C++ | `void setRenderMessages(bool messages)` | | :-- | :-- | @@ -1126,7 +1219,7 @@ Config key: `renderMessages/render_messages` --- -### `setWindowVisible` +### `setWindowVisible` | C++ | `void setWindowVisible(bool visibility)` | | :-- | :-- | @@ -1143,7 +1236,7 @@ Config key: `windowVisible/window_visible` --- -### `setConsoleEnabled` +### `setConsoleEnabled` | C++ | `void setConsoleEnabled(bool console)` | | :-- | :-- | @@ -1159,7 +1252,7 @@ Config key: `consoleEnabled/console_enabled` --- -### `setSoundEnabled` +### `setSoundEnabled` | C++ | `void setSoundEnabled(bool sound)` | | :-- | :-- | @@ -1175,7 +1268,7 @@ Config key: `soundEnabled/sound_enabled` --- -### `getScreenWidth` +### `getScreenWidth` | C++ | `int getScreenWidth()` | | :-- | :-- | @@ -1187,7 +1280,7 @@ Returns game's screen width - width of all buffers. --- -### `getScreenHeight` +### `getScreenHeight` | C++ | `int getScreenHeight()` | | :-- | :-- | @@ -1199,7 +1292,7 @@ Returns game's screen height - height of all buffers. --- -### `getScreenChannels` +### `getScreenChannels` | C++ | `int getScreenChannels()` | | :-- | :-- | @@ -1211,7 +1304,7 @@ Returns number of channels in screen buffer and map buffer (depth and labels buf --- -### `getScreenPitch` +### `getScreenPitch` | C++ | `size_t getScreenPitch()` | | :-- | :-- | @@ -1223,7 +1316,7 @@ Returns size in bytes of one row in screen buffer and map buffer. --- -### `getScreenSize` +### `getScreenSize` | C++ | `size_t getScreenSize()` | | :-- | :-- |