Merge pull request #587 from Farama-Foundation/core-updates

Add isEpisodeTimeoutReached/is_episode_timeout_reached method to the core API
Farama-Foundation · Sep 7, 2024 · 03ed0a5 · 03ed0a5
2 parents 8419abf + 563a2a4
commit 03ed0a5
Show file tree

Hide file tree

Showing 34 changed files with 81 additions and 34 deletions.
diff --git a/docs/api/configurationFiles.md → docs/api/configuration_files.md b/docs/api/configurationFiles.md → docs/api/configuration_files.md
diff --git a/docs/api/cpp/doomGame.md → docs/api/cpp/doom_game.md b/docs/api/cpp/doomGame.md → docs/api/cpp/doom_game.md
@@ -179,6 +179,17 @@ Returns true if the current episode is in the terminal state (is finished).
 will take no effect after this point (unless [`newEpisode`](#newepisode) method is called).
 
 
+---
+### `isEpisodeTimeoutReached`
+
+| C++    | `bool isEpisodeTimeoutReached()`      |
+| :--    | :--                             |
+| Python | `is_episode_timeout_reached() -> bool` |
+
+Returns true if the current episode is in the terminal state due to exceeding the time limit (timeout)
+set with [`setEpisodeTimeout`](#setepisodetimeout) method or via `+timelimit` parameter.
+
+
 ---
 ### `isPlayerDead`
 

diff --git a/docs/api/cpp/gameState.md → docs/api/cpp/game_state.md b/docs/api/cpp/gameState.md → docs/api/cpp/game_state.md
diff --git a/docs/api/python/doomGame.md → docs/api/python/doom_game.md b/docs/api/python/doomGame.md → docs/api/python/doom_game.md
@@ -24,6 +24,7 @@ DoomGame is the main object of the ViZDoom library, representing a single instan
 .. autofunction:: vizdoom.DoomGame.make_action
 .. autofunction:: vizdoom.DoomGame.is_new_episode
 .. autofunction:: vizdoom.DoomGame.is_episode_finished
+.. autofunction:: vizdoom.DoomGame.is_episode_timeout_reached
 .. autofunction:: vizdoom.DoomGame.is_player_dead
 .. autofunction:: vizdoom.DoomGame.respawn_player
 .. autofunction:: vizdoom.DoomGame.send_game_command

diff --git a/docs/api/python/gameState.md → docs/api/python/game_state.md b/docs/api/python/gameState.md → docs/api/python/game_state.md
diff --git a/docs/environments/creatingCustom.md → docs/environments/creating_custom.md b/docs/environments/creatingCustom.md → docs/environments/creating_custom.md
diff --git a/docs/environments/thirdParty.md → docs/environments/third_party.md b/docs/environments/thirdParty.md → docs/environments/third_party.md
diff --git a/docs/index.md b/docs/index.md
@@ -59,9 +59,9 @@ game.close()
 :hidden:
 :caption: Introduction
 
-introduction/pythonQuickstart
+introduction/python_quickstart
 introduction/building
-introduction/apisAndWrappers
+introduction/apis_and_wrappers
 ```
 
 ```{toctree}
@@ -70,16 +70,16 @@ introduction/apisAndWrappers
 
 api/python
 api/cpp
-api/configurationFiles
+api/configuration_files
 ```
 
 ```{toctree}
 :hidden:
 :caption: Environments
 
 environments/default
-environments/thirdParty
-environments/creatingCustom
+environments/third_party
+environments/creating_custom
 ```
 
 ```{toctree}

diff --git a/docs/introduction/apisAndWrappers.md → docs/introduction/apis_and_wrappers.md b/docs/introduction/apisAndWrappers.md → docs/introduction/apis_and_wrappers.md
diff --git a/docs/introduction/pythonQuickstart.md → docs/introduction/python_quickstart.md b/docs/introduction/pythonQuickstart.md → docs/introduction/python_quickstart.md
diff --git a/include/ViZDoomGame.h b/include/ViZDoomGame.h
@@ -62,6 +62,7 @@ namespace vizdoom {
 
         bool isNewEpisode();
         bool isEpisodeFinished();
+        bool isEpisodeTimeoutReached();
         bool isPlayerDead();
         void respawnPlayer();
         void sendGameCommand(std::string cmd);

diff --git a/scenarios/basic.cfg b/scenarios/basic.cfg
@@ -18,10 +18,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes start after 20 tics (after unholstering the gun)
+# Make episodes start after 20 tics (after unholstering the gun)
 episode_start_time = 14
 
-# make episodes finish after 300 actions (tics)
+# Make episodes finish after 300 actions (tics)
 episode_timeout = 300
 
 # Available buttons

diff --git a/scenarios/cig.cfg b/scenarios/cig.cfg
@@ -4,7 +4,7 @@
 
 doom_scenario_path = cig.wad
 
-#12 minutes
+# Make episodes finish after 12 minutes
 episode_timeout = 25200
 
 # Rendering options

diff --git a/scenarios/deadly_corridor.cfg b/scenarios/deadly_corridor.cfg
@@ -21,6 +21,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
+# Make episodes start in the first tic
+episode_start_time = 1
+
+# Make episodes finish after 2100 actions (tics)
 episode_timeout = 2100
 
 # Available buttons

diff --git a/scenarios/deathmatch.cfg b/scenarios/deathmatch.cfg
@@ -15,7 +15,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes finish after 4200 actions (tics)
+# Make episodes start in the first tic
+episode_start_time = 1
+
+# Make episodes finish after 4200 actions (tics)
 episode_timeout = 4200
 
 # Available buttons

diff --git a/scenarios/defend_the_center.cfg b/scenarios/defend_the_center.cfg
@@ -18,10 +18,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes start after 10 tics (after unholstering the gun)
+# Make episodes start after 10 tics (after unholstering the gun)
 episode_start_time = 10
 
-# make episodes finish after 2100 actions (tics)
+# Make episodes finish after 2100 actions (tics)
 episode_timeout = 2100
 
 # Available buttons

diff --git a/scenarios/defend_the_line.cfg b/scenarios/defend_the_line.cfg
@@ -18,10 +18,9 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes start after 10 tics (after unholstering the gun)
+# Make episodes start after 10 tics (after unholstering the gun)
 episode_start_time = 10
 
-
 # Available buttons
 available_buttons =
 	{

diff --git a/scenarios/health_gathering.cfg b/scenarios/health_gathering.cfg
@@ -19,7 +19,7 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes finish after 2100 actions (tics)
+# Make episodes finish after 2100 actions (tics)
 episode_timeout = 2100
 
 # Available buttons

diff --git a/scenarios/health_gathering_supreme.cfg b/scenarios/health_gathering_supreme.cfg
@@ -19,7 +19,7 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes finish after 2100 actions (tics)
+# Make episodes finish after 2100 actions (tics)
 episode_timeout = 2100
 
 # Available buttons

diff --git a/scenarios/learning.cfg b/scenarios/learning.cfg
@@ -1,3 +1,7 @@
+# Lines starting with # are treated as comments (or with whitespaces+#).
+# It doesn't matter if you use capital letters or not.
+# It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout.
+
 doom_scenario_path = basic.wad
 
 # Rewards
@@ -13,10 +17,10 @@ render_decals = false
 render_particles = false
 window_visible = false
 
-# make episodes start after 20 tics (after unholstering the gun)
+# Make episodes start after 20 tics (after unholstering the gun)
 episode_start_time = 14
 
-# make episodes finish after 300 actions (tics)
+# Make episodes finish after 300 actions (tics)
 episode_timeout = 300
 
 # Available buttons

diff --git a/scenarios/multi.cfg b/scenarios/multi.cfg
@@ -18,7 +18,6 @@ render_particles = false
 
 window_visible = true
 
-
 # Available buttons
 available_buttons =
 	{

diff --git a/scenarios/multi_duel.cfg b/scenarios/multi_duel.cfg
@@ -1,3 +1,7 @@
+# Lines starting with # are treated as comments (or with whitespaces+#).
+# It doesn't matter if you use capital letters or not.
+# It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout.
+
 doom_scenario_path = multi_duel.wad
 
 screen_resolution = RES_320X240

diff --git a/scenarios/my_way_home.cfg b/scenarios/my_way_home.cfg
@@ -18,10 +18,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes start after 10 tics (after unholstering the gun)
+# Make episodes start after 10 tics (after unholstering the gun)
 episode_start_time = 10
 
-# make episodes finish after 2100 actions (tics)
+# Make episodes finish after 2100 actions (tics)
 episode_timeout = 2100
 
 # Available buttons

diff --git a/scenarios/predict_position.cfg b/scenarios/predict_position.cfg
@@ -18,10 +18,10 @@ render_decals = false
 render_particles = false
 window_visible = true
 
-# make episodes start after 16 tics (after the rocket launcher is ready)
+# Make episodes start after 16 tics (after the rocket launcher is ready)
 episode_start_time = 16
 
-# make episodes finish after 300 actions (tics)
+# Make episodes finish after 300 actions (tics)
 episode_timeout = 300
 
 # Available buttons

diff --git a/scenarios/rocket_basic.cfg b/scenarios/rocket_basic.cfg
@@ -12,10 +12,10 @@ render_weapon = true
 render_decals = false
 render_particles = false
 
-# make episodes start after 14 tics (after unholstering the gun)
+# Make episodes start after 14 tics (after unholstering the gun)
 episode_start_time = 14
 
-# make episodes finish after 300 actions (tics)
+# Make episodes finish after 300 actions (tics)
 episode_timeout = 300
 
 # Available buttons

diff --git a/scenarios/simpler_basic.cfg b/scenarios/simpler_basic.cfg
@@ -1,3 +1,7 @@
+# Lines starting with # are treated as comments (or with whitespaces+#).
+# It doesn't matter if you use capital letters or not.
+# It doesn't matter if you use underscore or camel notation for keys, e.g. episode_timeout is the same as episodeTimeout.
+
 doom_scenario_path = simpler_basic.wad
 
 # Rewards
@@ -13,10 +17,10 @@ render_weapon = true
 render_decals = false
 render_particles = false
 
-# make episodes start after 20 tics (after unholstering the gun)
+# Make episodes start after 20 tics (after unholstering the gun)
 episode_start_time = 14
 
-# make episodes finish after 300 actions (tics)
+# Make episodes finish after 300 actions (tics)
 episode_timeout = 300
 
 # Available buttons

diff --git a/scenarios/take_cover.cfg b/scenarios/take_cover.cfg
@@ -19,6 +19,9 @@ render_decals = false
 render_particles = false
 window_visible = true
 
+# Make episodes start in the first tic
+episode_start_time = 1
+
 # Available buttons
 available_buttons =
 	{

diff --git a/scripts/create_python_docs_from_cpp_docs.py b/scripts/create_python_docs_from_cpp_docs.py
@@ -5,8 +5,8 @@
 
 FILES_TO_PARSE = [
     {
-        "input_filepath": "docs/api/cpp/doomGame.md",
-        "output_filepath": "docs/api/python/doomGame.md",
+        "input_filepath": "docs/api/cpp/doom_game.md",
+        "output_filepath": "docs/api/python/doom_game.md",
         "submodule": "DoomGame.",
         "append_to_header": """
 ```{eval-rst}

diff --git a/scripts/create_python_docstrings_from_cpp_docs.py b/scripts/create_python_docstrings_from_cpp_docs.py
@@ -9,7 +9,7 @@ def camel_case_to_snake_case(text):
 
 
 FILES_TO_PARSE = [
-    {"filepath": "docs/api/cpp/doomGame.md", "namespace": "DoomGamePython"},
+    {"filepath": "docs/api/cpp/doom_game.md", "namespace": "DoomGamePython"},
     {"filepath": "docs/api/cpp/utils.md"},
 ]
 OUTPUT_FILE = "src/lib_python/ViZDoomMethodsDocstrings.h"

diff --git a/src/lib/ViZDoomController.cpp b/src/lib/ViZDoomController.cpp
@@ -281,10 +281,7 @@ namespace vizdoom {
     }
 
     bool DoomController::isTicPossible() {
-        return !((!this->gameState->GAME_MULTIPLAYER && this->gameState->PLAYER_DEAD)
-                 || (this->mapTimeout > 0 && this->mapTimeout + this->mapStartTime <= this->gameState->MAP_TIC)
-                 || (this->gameState->MAP_TICLIMIT > 0 && this->gameState->MAP_TICLIMIT <= this->gameState->MAP_TIC)
-                 || (this->gameState->MAP_END));
+        return !(this->isMapEnded() || this->isMapTimeoutReached());
     }
 
     void DoomController::tic(bool update) {
@@ -601,7 +598,14 @@ namespace vizdoom {
     }
 
     bool DoomController::isMapEnded() {
-        return this->doomRunning && this->gameState->MAP_END;
+        // Check if the map has ended or the player is dead (in single player mode)
+        return (!this->gameState->GAME_MULTIPLAYER && this->gameState->PLAYER_DEAD) || (this->gameState->MAP_END);
+    }
+
+    bool DoomController::isMapTimeoutReached() {
+        // Check if internal or user-defined map timeout has been reached
+        return (this->mapTimeout > 0 && this->mapTimeout + this->mapStartTime <= this->gameState->MAP_TIC) 
+                || (this->gameState->MAP_TICLIMIT > 0 && this->gameState->MAP_TICLIMIT <= this->gameState->MAP_TIC);
     }
 
     unsigned int DoomController::getMapLastTic() {

diff --git a/src/lib/ViZDoomController.h b/src/lib/ViZDoomController.h
@@ -160,6 +160,7 @@ namespace vizdoom {
         bool isMapLastTic();
         bool isMapFirstTic();
         bool isMapEnded();
+        bool isMapTimeoutReached();
         unsigned int getMapLastTic();
 
         void setNoConsole(bool console);

diff --git a/src/lib/ViZDoomGame.cpp b/src/lib/ViZDoomGame.cpp
@@ -342,6 +342,11 @@ namespace vizdoom {
         return !this->doomController->isTicPossible();
     }
 
+    bool DoomGame::isEpisodeTimeoutReached() {
+        if (!this->isRunning()) throw ViZDoomIsNotRunningException();
+        return this->doomController->isMapTimeoutReached();
+    }
+
     bool DoomGame::isPlayerDead() {
         if (!this->isRunning()) throw ViZDoomIsNotRunningException();
         return this->doomController->isPlayerDead();

diff --git a/src/lib_python/ViZDoomMethodsDocstrings.h b/src/lib_python/ViZDoomMethodsDocstrings.h
@@ -84,6 +84,9 @@ processes the specified number of tics, updates the state and calculates a new r
 :meth:`make_action` and :meth:`advance_action` methods
 will take no effect after this point (unless :meth:`new_episode` method is called).)DOCSTRING";
 
+    const char *isEpisodeTimeoutReached = R"DOCSTRING(Returns ``True`` if the current episode is in the terminal state due to exceeding the time limit (timeout) 
+set with :meth:`set_episode_timeout`` method or via ``+timelimit` parameter.)DOCSTRING";
+
     const char *isPlayerDead = R"DOCSTRING(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 :meth:`respawn_player` method can be called.)DOCSTRING";

diff --git a/src/lib_python/ViZDoomPythonModule.cpp b/src/lib_python/ViZDoomPythonModule.cpp
@@ -630,6 +630,7 @@ PYBIND11_MODULE(vizdoom, vz){
         CLASS_FUNC_2_PYT_WITH_ARGS("new_episode", DoomGamePython::newEpisode, pyb::arg("recording_file_path") = "")
         CLASS_FUNC_2_PYT_WITH_ARGS("replay_episode", DoomGamePython::replayEpisode, pyb::arg("file_path"), pyb::arg("player") = 0)
         CLASS_FUNC_2_PYT("is_episode_finished", DoomGamePython::isEpisodeFinished)
+        CLASS_FUNC_2_PYT("is_episode_timeout_reached", DoomGamePython::isEpisodeTimeoutReached)
         CLASS_FUNC_2_PYT("is_new_episode", DoomGamePython::isNewEpisode)
         CLASS_FUNC_2_PYT("is_player_dead", DoomGamePython::isPlayerDead)
         CLASS_FUNC_2_PYT("respawn_player", DoomGamePython::respawnPlayer)