diff --git a/CMakeLists.txt b/CMakeLists.txt index b6902dcca..055904ec5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.4) # Project + versions #----------------------------------------------------------------------------------------------------------------------- -project(ViZDoom VERSION 1.2.0) +project(ViZDoom VERSION 1.2.1) set(ViZDoom_VERSION_STR ${ViZDoom_VERSION_MAJOR}.${ViZDoom_VERSION_MINOR}.${ViZDoom_VERSION_PATCH}) set(ViZDoom_VERSION_ID ${ViZDoom_VERSION_MAJOR}${ViZDoom_VERSION_MINOR}${ViZDoom_VERSION_PATCH}) diff --git a/docs/README.md b/docs/README.md index 41c50068c..ce07781c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,3 +3,9 @@ This directory contains the documentation for ViZDOOm. For more information about how to contribute to the documentation go to our [CONTRIBUTING.md](https://github.com/Farama-Foundation/Celshast/blob/main/CONTRIBUTING.md) + +If you edit the C++ documentation (inside `api_cpp`), you need to run to update other files: +``` +python scripts/create_python_docs_from_cpp_docs.py +python scripts/create_python_docstrings_from_cpp_docs.py +``` diff --git a/docs/api_cpp/configurationFiles.md b/docs/api/configurationFiles.md similarity index 98% rename from docs/api_cpp/configurationFiles.md rename to docs/api/configurationFiles.md index debf30139..27f3d3ea7 100644 --- a/docs/api_cpp/configurationFiles.md +++ b/docs/api/configurationFiles.md @@ -19,7 +19,7 @@ A violation of any of these rules will result in ignoring **only** the line with ### Appending values Each list assignment (**KEY = { VALUES }**)clears values specified for this key before (in other configuration files or in the code). That is why the **append operator(*KEY += { VALUES })** is available. This way you can more easily combine multiple configuration files and tinker in code. -### Supported configuration keys: +### Supported configuration keys: * `audioBufferEnabled/audio_buffer_enabled` * `audioBufferSize/audio_buffer_size` * `audioSamplingRate/audio_samping_rate` @@ -112,7 +112,6 @@ mode = PLAYER # Difficulty of gameplay ranging from 1 (baby) to 5 (nightmare) doom_skill = 5 - ``` Other examples of configuration files can be found in [https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios) diff --git a/docs/api/cpp.md b/docs/api/cpp.md new file mode 100644 index 000000000..00d464997 --- /dev/null +++ b/docs/api/cpp.md @@ -0,0 +1,18 @@ +# C++ API + +ViZDoom is implemented in C++ and can be used as a C++ library. The C++ API is one-to-one with the Python API. The only difference is the use of `camelCase` instead of `snake_case` for method names. + +ViZDoom can be built as a static or dynamic library. The header files are located in the `include` directory. +See [examples/cpp](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/cpp) for examples, including CMake files for building. + + +```{toctree} +:hidden: +:caption: C++ API + +cpp/doomGame +cpp/gameState +cpp/enums +cpp/exceptions +cpp/utils +``` diff --git a/docs/api_cpp/doomGame.md b/docs/api/cpp/doomGame.md similarity index 99% rename from docs/api_cpp/doomGame.md rename to docs/api/cpp/doomGame.md index 21393e633..96cc0192c 100644 --- a/docs/api_cpp/doomGame.md +++ b/docs/api/cpp/doomGame.md @@ -1,6 +1,6 @@ # 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. +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. diff --git a/docs/api_cpp/enums.md b/docs/api/cpp/enums.md similarity index 94% rename from docs/api_cpp/enums.md rename to docs/api/cpp/enums.md index 8f094a410..f4a606d33 100644 --- a/docs/api_cpp/enums.md +++ b/docs/api/cpp/enums.md @@ -1,5 +1,8 @@ # Enums +ViZDoom is using few types of enums as parameters for its functions. Below you can find the description of all of them. +The declarations of all the enums can be found in the `include/ViZDoomTypes.h` header file. + ## `Mode` Enum type that defines all supported modes. @@ -178,11 +181,11 @@ Other from 1 to 60 (global int 1-60) can be accessed as USER1 - USER60 GameVaria See also: - [ZDoom Wiki: ACS](http://zdoom.org/wiki/ACS), -- [`DoomGame: getAvailableGameVariables`](./doomGame.md#getAvailableGameVariables), -- [`DoomGame: setAvailableGameVariables`](./doomGame.md#setAvailableGameVariables), -- [`DoomGame: addAvailableGameVariable`](./doomGame.md#addAvailableGameVariable), -- [`DoomGame: getGameVariable`](./doomGame.md#getGameVariable), -- [`Utilities: doomFixedToDouble`](Utilities.md#doomFixedToDouble), +- [`DoomGame: getAvailableGameVariables`](./doomGame.md#getavailablegamevariables), +- [`DoomGame: setAvailableGameVariables`](./doomGame.md#setavailablegamevariables), +- [`DoomGame: addAvailableGameVariable`](./doomGame.md#addavailablegamevariable), +- [`DoomGame: getGameVariable`](./doomGame.md#getgamevariable), +- [`Utilities: doomFixedToDouble`](utils.md#doomfixedtodouble), - [examples/python/basic.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/basic.py), - [examples/python/shaping.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/shaping.py). @@ -271,3 +274,6 @@ Added in 1.1.9. - **SR_11025** - **SR_22050** - **SR_44100** + +See also: +- [`DoomGame: setAudioSamplingRate`](./doomGame.md#setaudiosamplingrate), diff --git a/docs/api_cpp/exceptions.md b/docs/api/cpp/exceptions.md similarity index 89% rename from docs/api_cpp/exceptions.md rename to docs/api/cpp/exceptions.md index 9d877416a..31d87cb5a 100644 --- a/docs/api_cpp/exceptions.md +++ b/docs/api/cpp/exceptions.md @@ -1,6 +1,9 @@ # Exceptions ViZDoom defines several exceptions that can be thrown by its API: +Most of the exceptions contain more information in "what()" message. +The declarations of all the enums can be found in the `include/ViZDoomExceptions.h` header file. + * `FileDoesNotExistException` - means that file specified as part of a configuration does not exist. @@ -13,5 +16,3 @@ ViZDoom defines several exceptions that can be thrown by its API: * `ViZDoomIsNotRunningException` - means that called method cannot be used when ViZDoom instance is not running. * `ViZDoomUnexpectedExitException` - means that ViZDoom's instance was closed/terminated/killed from the outside. - -Most of the exceptions contain more information in "what()" message. diff --git a/docs/api_cpp/gameState.md b/docs/api/cpp/gameState.md similarity index 94% rename from docs/api_cpp/gameState.md rename to docs/api/cpp/gameState.md index a584fa99c..20aa25c05 100644 --- a/docs/api_cpp/gameState.md +++ b/docs/api/cpp/gameState.md @@ -1,6 +1,7 @@ # GameState GameState is the main object returned by [`DoomGame: getState`](./doomGame.md#getstate) method. +The declarations of all the enums can be found in the `include/ViZDoomTypes.h` header file. ## `GameState` @@ -57,7 +58,10 @@ See also: - `double / float` **objectVelocityY / object_velocity_y** - `double / float` **objectVelocityZ / object_velocity_z** -**objectId / object_id** - unique object ID, if both Labels and Objects information is enabled, this will be the same as **id** in corresponding**Object**. + +Description of the object in the labels buffer. + +**objectId / object_id** - unique object ID, if both Labels and Objects information is enabled, this will be the same as **id** in corresponding **Object**. **objectName / object_name** - ingame object name, many different objects can have the same name (e.g. Medikit, Clip, Zombie). @@ -87,11 +91,12 @@ See also: - `double / float` **velocityY / velocity_y** - `double / float` **velocityZ / velocity_z** +Description of the object present in the game world. + **id** - unique object ID. **name** - ingame object name, many different objects can have the same name (e.g. Medikit, Clip, Zombie). -Right now `Object` is only available to C++ and Python. Added in 1.1.8. See also: @@ -109,13 +114,14 @@ See also: - `double / float` **y2** - `bool / bool` **isBlocking / is_blocking** +Description of the line that is part of a sector definition. + **x1**, **y1** - position of the line's first vertex. **x2**, **y2** - position of the line's second vertex. **isBlocking / is_blocking** - is true, if line is a wall that can't be passed. -Right now `Line` is only available to C++ and Python. Added in 1.1.8. See also: @@ -130,13 +136,14 @@ See also: - `double / float` **ceilingHeight / ceiling_height** - `std::vector