From f57c3b400b5cf3cad3b9cb151949839da0a88280 Mon Sep 17 00:00:00 2001 From: Marek Wydmuch Date: Sat, 7 Sep 2024 13:11:33 +0200 Subject: [PATCH] Update mentions of Gym in the docs --- README.md | 17 ++++++----------- docs/environments/default.md | 2 +- docs/introduction/apis_and_wrappers.md | 18 +++++------------- docs/introduction/building.md | 6 +----- docs/introduction/python_quickstart.md | 24 +++++++++++++----------- examples/python/audio_buffer.py | 4 ++-- examples/python/gym_wrapper.py | 21 --------------------- examples/python/gymnasium_wrapper.py | 2 +- 8 files changed, 29 insertions(+), 65 deletions(-) delete mode 100755 examples/python/gym_wrapper.py diff --git a/README.md b/README.md index 4606351f0..a227c6766 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ViZDoom is based on [ZDoom](https://zdoom.org) engine to provide the game mechan ## Features - Multi-platform (Linux, macOS, Windows), - API for Python and C++, -- [Gymnasium](https://gymnasium.farama.org/)/[OpenAI Gym](https://www.gymlibrary.dev/) environment wrappers (thanks to [Arjun KG](https://github.com/arjun-kg) [Benjamin Noah Beal](https://github.com/bebeal), [Lawrence Francis](https://github.com/ldfrancis), and [Mark Towers](https://github.com/pseudo-rnd-thoughts)), +- [Gymnasium](https://gymnasium.farama.org/)/Gym environment wrappers (thanks to [Arjun KG](https://github.com/arjun-kg) [Benjamin Noah Beal](https://github.com/bebeal), [Lawrence Francis](https://github.com/ldfrancis), and [Mark Towers](https://github.com/pseudo-rnd-thoughts)), - Easy-to-create custom scenarios (visual editors, scripting language, and examples available), - Async and sync single-player and multiplayer modes, - Fast (up to 7000 fps in sync mode, single-threaded), @@ -81,7 +81,7 @@ Both x86-64 and AArch64 (ARM64) architectures are supported. Wheels are available for Python 3.8+ on Linux. If Python wheel is not available for your platform (Python version <3.8, distros below manylinux_2_28 standard), pip will try to install (build) ViZDoom from the source. -ViZDoom requires a C++11 compiler, CMake 3.12+, Boost 1.54+ SDL2, OpenAL (optional), and Python 3.8+ to install from source. See [documentation](https://vizdoom.farama.org/introduction/pythonQuickstart/) for more details. +ViZDoom requires a C++11 compiler, CMake 3.12+, Boost 1.54+ SDL2, OpenAL (optional), and Python 3.8+ to install from source. See [documentation](https://vizdoom.farama.org/introduction/python_quickstart/) for more details. ### macOS @@ -111,20 +111,13 @@ Wheels are available for Python 3.9+ on Windows. Please note that the Windows version is not as well-tested as Linux and macOS versions. It can be used for development and testing but if you want to conduct serious (time and resource-extensive) experiments on Windows, -please consider using [Docker](https://docs.docker.com/docker-for-windows/install/) or [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) with Linux version. +please consider using [Docker](https://docs.docker.com/docker-for-windows/install/) or [WSL](https://docs.microsoft.com/en-us/windows/wsl) with Linux version. ### Gymnasium/Gym wrappers -Gymnasium environments are installed along with ViZDoom. +Gymnasium environments are installed along with ViZDoom and are available on all platforms. See [documentation](https://github.com/Farama-Foundation/ViZDoom/blob/master/doc/Gymnasium.md) and [examples](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/python/gymnasium_wrapper.py) on the use of Gymnasium API. -OpenAI-Gym wrappers are also available, to install them run: -``` -pip install vizdoom[gym] -``` -See [documentation](https://github.com/Farama-Foundation/ViZDoom/blob/master/doc/Gym.md) and [examples](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/python/gym_wrapper.py) on the use of Gym API. -**OpenAI-Gym wrappers are deprecated and will be removed in future versions in favor of Gymnasium.** - ## Examples - [Python](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/python) (contain learning examples implemented in PyTorch, TensorFlow, and Theano) @@ -166,6 +159,8 @@ Useful articles (for advanced users who want to create custom environments/scena - [LevDoom](https://github.com/TTomilin/LevDoom) - Generalization benchmark in ViZDoom featuring difficulty levels in visual complexity. - [COOM](https://github.com/hyintell/COOM) - Continual learning benchmark in ViZDoom offering task sequences with diverse objectives. +If you have a cool project that uses ViZDoom or could be interesting to ViZDoom community, feel free to open PR to add it to this list! + ## Contributions This project is maintained and developed in our free time. All bug fixes, new examples, scenarios, and other contributions are welcome! We are also open to feature ideas and design suggestions. diff --git a/docs/environments/default.md b/docs/environments/default.md index c38f9d1d4..323560423 100644 --- a/docs/environments/default.md +++ b/docs/environments/default.md @@ -15,7 +15,7 @@ game = vzd.DoomGame() game.load_config(os.path.join(vzd.scenarios_path, "basic.cfg")) # or any other scenario file ``` -When using Gymnasium (or Gym) API the scenario can be loaded by passing the scenario id to `make` method like-this: +When using Gymnasium API the scenario can be loaded by passing the scenario id to `make` method like-this: ```{code-block} python import gymnasium diff --git a/docs/introduction/apis_and_wrappers.md b/docs/introduction/apis_and_wrappers.md index 164d4ee09..42391d646 100644 --- a/docs/introduction/apis_and_wrappers.md +++ b/docs/introduction/apis_and_wrappers.md @@ -35,27 +35,19 @@ and implements the necessary API to function as a Gymnasium API. See the following examples for use: - [examples/python/gymnasium_wrapper.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/gymnasium_wrapper.py) for basic usage -- [examples/python/learning_stable_baselines.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/learning_stable_baselines.py) for example training with [stable-baselines3](https://github.com/DLR-RM/stable-baselines3/) (Update - Currently facing issues, to be fixed) +- [examples/python/learning_stable_baselines.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/learning_stable_baselines.py) for example training with [stable-baselines3](https://github.com/DLR-RM/stable-baselines3/). ## OpenAI Gym wrappers -> Gym is deprecated in favor of Gymnasium and these wrappers will be removed in the future. +> Original OpenAI Gym wrappers are no longer maintained and were removed from master branch. We recommend using Gymnasium wrappers instead. -Installing ViZDoom with `pip install vizdoom[gym]` will include -Gym wrappers to interact with ViZDoom over Gym API. - -These wrappers are under `gym_wrappers`, containing the basic environment and -a few example environments based on the built-in scenarios. This environment -simply initializes ViZDoom with the settings from the scenario config files -and implements the necessary API to function as a Gym API. - -See the following examples for use: -- [examples/python/gym_wrapper.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/gym_wrapper.py) for basic usage +Installing ViZDoom version < 1.3.0 with `pip install vizdoom[gym]` will include +Gym 0.26 wrappers to interact with ViZDoom over Gym API. ## Julia, Lua, and Java APIs -> Julia, Lua, and Java bindings are no longer maintained. +> Julia, Lua, and Java bindings are no longer maintained and were removed from master branch Julia, Lua, and Java can be found in [julia](https://github.com/Farama-Foundation/ViZDoom/tree/julia) and [java&lua](https://github.com/Farama-Foundation/ViZDoom/tree/java%26lua) branches for manual building. diff --git a/docs/introduction/building.md b/docs/introduction/building.md index c238f0c91..31f5e636a 100644 --- a/docs/introduction/building.md +++ b/docs/introduction/building.md @@ -1,7 +1,7 @@ # Building from source Here we describe how to build ViZDoom from source. -If you want to install pre-build ViZDoom wheels for Python, see [Python quick start](./pythonQuickstart.md). +If you want to install pre-build ViZDoom wheels for Python, see [Python quick start](./python_quickstart.md). ## Dependencies @@ -67,7 +67,6 @@ python setup.py build && python setup.py install ### MacOS - To build ViZDoom on MacOS, the following dependencies are required: * CMake 3.12+ * Clang 5.0+ @@ -135,7 +134,6 @@ Instructions below can be used to build ViZDoom manually. We recommend doing it only if you want to use C++ API, work on the ViZDoom, or if you have problems with pip installation. ### Linux / MacOS - In ViZDoom's root directory: ```bash mkdir build @@ -148,7 +146,6 @@ where `-DBUILD_ENGINE=ON` and `-DBUILD_PYTHON=ON` CMake options are optional (de ### Windows - 1. Run CMake GUI or cmake command in cmd/powershell in ViZDoom root directory with the following paths provided: * BOOST_ROOT * BOOST_INCLUDEDIR @@ -176,5 +173,4 @@ Compilation output will be placed in `build/bin` and it should contain the follo ### Manual installation - To manually install Python package copy `vizdoom_root_dir/build/bin/pythonX.X/vizdoom` contents to `python_root_dir/lib/pythonX.X/site-packages/site-packages/vizdoom`. diff --git a/docs/introduction/python_quickstart.md b/docs/introduction/python_quickstart.md index 3ecc56d67..a27f90058 100644 --- a/docs/introduction/python_quickstart.md +++ b/docs/introduction/python_quickstart.md @@ -1,5 +1,6 @@ # Python quick start + ## Linux To install the latest release of ViZDoom, just run: ```sh @@ -9,7 +10,6 @@ Both x86-64 and AArch64 (ARM64) architectures are supported. Wheels are available for Python 3.8+ on Linux. ### Audio buffer requirement - If you want to use audio buffer, you need to have OpenAL library installed. It is installed by default in many desktop distros. Otherwise it can be installed from the package manager. On apt-based distros (Ubuntu, Debian, Linux Mint, etc.), you can install it by running: @@ -23,13 +23,11 @@ dnf install openal-soft On RHEL/CentOS/Alma/Rocky Linux 9, you may need first enable crb repository by running `dnf --enablerepo=crb install`. ### Installing from source distribution on Linux - If Python wheel is not available for your platform (distros incompatible with manylinux_2_28 standard), pip will try to install (build) ViZDoom from the source. ViZDoom requires a C++11 compiler, CMake 3.12+, Boost 1.54+ SDL2, OpenAL (optional), and Python 3.8+ to install from source. Below, you will find instructions on how to install these dependencies. #### apt-based distros (Ubuntu, Debian, Linux Mint, etc.) - To build ViZDoom run (it may take a few minutes): ```sh apt install cmake git libboost-all-dev libsdl2-dev libopenal-dev @@ -38,7 +36,6 @@ pip install vizdoom We recommend using at least Ubuntu 18.04+ or Debian 10+ with Python 3.7+. #### dnf/yum-based distros (Fedora, RHEL, CentOS, Alma/Rocky Linux, etc.) - To install ViZDoom, run (it may take a few minutes): ```sh dnf install cmake git boost-devel SDL2-devel openal-soft-devel @@ -48,7 +45,6 @@ We recommend using at least Fedora 35+ or RHEL/CentOS/Alma/Rocky Linux 9+ with P To install openal-soft-devel on RHEL/CentOS/Alma/Rocky Linux 9, one needs to enable crb repository first by running `dnf --enablerepo=crb install`. ### Installing master branch version - To install the master branch version of ViZDoom run: ```sh pip install git+https://github.com/Farama-Foundation/ViZDoom @@ -59,14 +55,20 @@ It requires the to have the above dependencies installed. ## macOS To install the latest release of ViZDoom, just run (it may take a few minutes as it will build ViZDoom from source on M1/M2 chips): ```sh -brew install cmake boost sdl2 openal-soft pip install vizdoom ``` -Both Intel and Apple Silicon (M1/2/3) CPUs are supported. +Both Intel and Apple Silicon CPUs are supported. +Pre-build wheels are available for Intel macOS 12.0+ and Apple Silicon macOS 14.0+. + +If Python wheel is not available for your platform (Python version <3.8, older macOS version), pip will try to install (build) ViZDoom from the source. +In this case, install the required dependencies using Homebrew: +```sh +brew install cmake boost sdl2 openal-soft +``` We recommend using at least macOS High Sierra 10.13+ with Python 3.8+. -On Apple Silicon, make sure you are using Python/Pip for Apple Silicon. +On Apple Silicon (M1, M2, and M3), make sure you are using Python/Pip for Apple Silicon. -To install the master branch version of ViZDoom, run: +To install the master branch version of ViZDoom, run, in this case you also need to have the above dependencies installed: ```sh pip install git+https://github.com/Farama-Foundation/ViZDoom ``` @@ -78,9 +80,9 @@ To install the latest release of ViZDoom, just run: pip install vizdoom ``` At the moment, only x86-64 architecture is supported on Windows. -Wheels are available for Python 3.8+ x86-64 on Windows. +Wheels are available for Python 3.9+ x86-64 on Windows. Please note that the Windows version is not as well-tested as Linux and macOS versions. It can be used for development and testing but if you want to conduct serious (time and resource-extensive) experiments on Windows, -please consider using [Docker](https://docs.docker.com/docker-for-windows/install/) or [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) with Linux version. +please consider using [Docker](https://docs.docker.com/docker-for-windows/install/) or [WSL](https://docs.microsoft.com/en-us/windows/wsl) with Linux version. Windows version is bundled with OpenAL library, so you don't need to install it separately. diff --git a/examples/python/audio_buffer.py b/examples/python/audio_buffer.py index 73ef9cbe5..750c59bcf 100755 --- a/examples/python/audio_buffer.py +++ b/examples/python/audio_buffer.py @@ -27,7 +27,7 @@ # Setting game.set_sound_enabled(True) is not required for audio buffer to work. # Note: This requires OpenAL library to be installed on your system. # It is installed by default on many Linux desktop distros. - # And it can be installed from package manager, see: https://vizdoom.farama.org/introduction/pythonQuickstart/#audio-buffer-requirements + # And it can be installed from package manager, see: https://vizdoom.farama.org/introduction/python_quickstart/#audio-buffer-requirements AUDIO_BUFFER_ENABLED = True game.set_audio_buffer_enabled(AUDIO_BUFFER_ENABLED) @@ -95,7 +95,7 @@ "[WARNING] Audio buffers were full of silence. This is a common bug on e.g. Ubuntu 20.04\n" " See https://github.com/Farama-Foundation/ViZDoom/pull/486\n" " There are some possible fixes:\n" - " 1) Check that you have OpenAL installed, if not install, see: https://vizdoom.farama.org/introduction/pythonQuickstart/#audio-buffer-requirements\n" + " 1) Check that you have OpenAL installed, if not install, see: https://vizdoom.farama.org/introduction/python_quickstart/#audio-buffer-requirements\n" " 2) Try setting game.add_game_args('+snd_efx 0'). This my disable some audio effects\n" " 3) Try installing a newer version of OpenAL Soft library, see https://github.com/Farama-Foundation/ViZDoom/pull/486#issuecomment-889389185" ) diff --git a/examples/python/gym_wrapper.py b/examples/python/gym_wrapper.py deleted file mode 100755 index 6b2114151..000000000 --- a/examples/python/gym_wrapper.py +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env python3 - -##################################################################### -# Example for running a vizdoom scenario as a gym env -##################################################################### - -import gym - -from vizdoom import gym_wrapper # noqa - - -if __name__ == "__main__": - env = gym.make("VizdoomHealthGatheringSupreme-v0", render_mode="human") - - # Rendering random rollouts for ten episodes - for _ in range(10): - done = False - obs = env.reset() - while not done: - obs, rew, terminated, truncated, info = env.step(env.action_space.sample()) - done = terminated or truncated diff --git a/examples/python/gymnasium_wrapper.py b/examples/python/gymnasium_wrapper.py index be8c0ec26..65d7e5f9e 100755 --- a/examples/python/gymnasium_wrapper.py +++ b/examples/python/gymnasium_wrapper.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 ##################################################################### -# Example for running a vizdoom scenario as a gym env +# Example for running a vizdoom scenario as a Gymnasium env ##################################################################### import gymnasium