vizdoom 1.3.0.dev2__tar.gz → 1.3.0.dev3__tar.gz

vizdoom-1.3.0.dev3/CMakeLists.txt

@@ -0,0 +1,199 @@
+cmake_minimum_required(VERSION 3.12)
+
+# Project + versions
+#-----------------------------------------------------------------------------------------------------------------------
+
+project(ViZDoom VERSION 1.3.0)
+set(ViZDoom_VERSION_SUFFIX ".dev3")
+set(ViZDoom_VERSION_STR ${ViZDoom_VERSION_MAJOR}.${ViZDoom_VERSION_MINOR}.${ViZDoom_VERSION_PATCH}${ViZDoom_VERSION_SUFFIX})
+set(ViZDoom_VERSION_ID ${ViZDoom_VERSION_MAJOR}${ViZDoom_VERSION_MINOR}${ViZDoom_VERSION_PATCH})
+
+
+# Building options
+#-----------------------------------------------------------------------------------------------------------------------
+
+option(BUILD_PYTHON "Build ViZDoom Python (3) binding/module" ON)
+option(BUILD_ENGINE "Build ViZDoom Engine (required to build Python package)" ON)
+option(CREATE_PYTHON_STUBS "Build ViZDoom Python (3) .pyi type stubs" OFF)
+
+
+# CMake options
+#-----------------------------------------------------------------------------------------------------------------------
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_LINK)
+
+if(POLICY CMP0003)
+    cmake_policy(SET CMP0003 NEW)
+endif()
+
+if(POLICY CMP0167)
+  find_package(Boost 1.70 QUIET CONFIG)
+  if(Boost_FOUND)
+    cmake_policy(SET CMP0167 NEW)
+  else()
+    cmake_policy(SET CMP0167 OLD)
+  endif()
+  unset(Boost_FOUND CACHE)
+  unset(Boost_DIR CACHE)
+endif()
+
+# Add cmake_modules to module
+set(CMAKE_MODULE_PATH
+    ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}" "${PROJECT_SOURCE_DIR}"
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake_modules")
+
+# Set the release mode if not specified
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
+
+# System dependent settings
+#-----------------------------------------------------------------------------------------------------------------------
+
+set(Boost_USE_MULTITHREADED ON)
+set(Boost_USE_STATIC_RUNTIME OFF)
+
+if(UNIX)
+    message(STATUS "Unix-like system detected, setting up Unix specific options")
+    set(Boost_USE_STATIC_LIBS OFF)
+endif()
+
+if(WIN32)
+    message(STATUS "Windows detected, setting up Windows specific options")
+    set(Boost_USE_STATIC_LIBS ON)
+
+    macro(get_WIN32_WINNT version)
+        if(WIN32 AND CMAKE_SYSTEM_VERSION)
+            set(ver ${CMAKE_SYSTEM_VERSION})
+            string(REPLACE "10" "A" ver ${ver})
+            string(REPLACE "." "" ver ${ver})
+            string(REGEX REPLACE "([A-F0-9])" "0\\1" ver ${ver})
+            string(SUBSTRING ${ver} 0 4 ver)
+
+            set(${version} "0x${ver}")
+        endif()
+    endmacro()
+
+    get_WIN32_WINNT(ver)
+    add_definitions(-D_WIN32_WINNT=${ver})
+endif()
+
+if(APPLE)
+    message(STATUS "macOS detected, setting up macOS specific options")
+    set(CMAKE_MACOSX_RPATH ON)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=hidden -fvisibility-inlines-hidden")
+
+    if(CMAKE_APPLE_SILICON_PROCESSOR MATCHES "")
+        message(STATUS "CMAKE_APPLE_SILICON_PROCESSOR not set")
+        if(CMAKE_HOST_SYSTEM_PROCESSOR MATCHES "arm64")
+            set(CMAKE_OSX_ARCHITECTURES "arm64" CACHE INTERNAL "" FORCE)
+            message(STATUS "Apple Silicon detected, building for arm64")
+        else()
+            set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE INTERNAL "" FORCE)
+            message(STATUS "Intel CPU detected, building for x86_64")
+        endif()
+    endif()
+endif(APPLE)
+
+
+# Compiler dependent settings
+#-----------------------------------------------------------------------------------------------------------------------
+
+if(CMAKE_COMPILER_IS_GNUCXX)
+    add_definitions("-fPIC")
+    # Explicitly silence some warnings
+    add_definitions("-Wno-implicit-fallthrough -Wno-shift-negative-value -Wno-stringop-truncation")
+    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-class-memaccess -Wno-deprecated-copy") # C++ only
+endif()
+
+# Main library
+#-----------------------------------------------------------------------------------------------------------------------
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+set(VIZDOOM_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+set(VIZDOOM_OUTPUT_DIR ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
+set(VIZDOOM_SCRIPTS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/scripts)
+set(VIZDOOM_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src)
+set(VIZDOOM_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include)
+set(VIZDOOM_LIB_SRC_DIR ${VIZDOOM_SRC_DIR}/lib)
+set(VIZDOOM_LIB_INCLUDE_DIR ${VIZDOOM_INCLUDE_DIR} ${VIZDOOM_LIB_SRC_DIR})
+set(VIZDOOM_OUTPUT_NAME vizdoom)
+
+if(Boost_VERSION VERSION_GREATER_EQUAL 1.89)
+    find_package(Boost 1.89 COMPONENTS filesystem thread date_time chrono regex iostreams REQUIRED)
+else()
+    find_package(Boost 1.56 COMPONENTS filesystem thread system date_time chrono regex iostreams REQUIRED)
+endif()
+find_package(Threads REQUIRED)
+
+include_directories(${VIZDOOM_LIB_INCLUDE_DIR} ${Boost_INCLUDE_DIR})
+
+set(VIZDOOM_LIBS
+    ${Boost_LIBRARIES}
+    ${CMAKE_THREAD_LIBS_INIT})
+
+if(UNIX AND NOT APPLE)
+    set(VIZDOOM_LIBS ${VIZDOOM_LIBS} rt)
+endif()
+
+configure_file(
+    "${VIZDOOM_LIB_SRC_DIR}/ViZDoomVersion.h.in"
+    "${VIZDOOM_LIB_SRC_DIR}/ViZDoomVersion.h"
+)
+
+configure_file(
+    "${VIZDOOM_SRC_DIR}/vizdoom/src/viz_version.h.in"
+    "${VIZDOOM_SRC_DIR}/vizdoom/src/viz_version.h"
+)
+
+file(GLOB VIZDOOM_LIB_SOURCES
+    ${VIZDOOM_INCLUDE_DIR}/*.h
+    ${VIZDOOM_LIB_SRC_DIR}/*.h
+    ${VIZDOOM_LIB_SRC_DIR}/*.cpp)
+
+add_library(libvizdoom_static STATIC ${VIZDOOM_LIB_SOURCES})
+target_link_libraries(libvizdoom_static PRIVATE ${VIZDOOM_LIBS})
+
+add_library(libvizdoom_shared SHARED ${VIZDOOM_LIB_SOURCES})
+target_link_libraries(libvizdoom_shared PRIVATE ${VIZDOOM_LIBS})
+
+set_target_properties(libvizdoom_static libvizdoom_shared
+    PROPERTIES
+    LINKER_LANGUAGE CXX
+    LIBRARY_OUTPUT_DIRECTORY ${VIZDOOM_OUTPUT_DIR}
+    LIBRARY_OUTPUT_DIRECTORY_RELEASE ${VIZDOOM_OUTPUT_DIR}
+    LIBRARY_OUTPUT_DIRECTORY_DEBUG ${VIZDOOM_OUTPUT_DIR}
+    LIBRARY_OUTPUT_DIRECTORY_MINSIZEREL ${VIZDOOM_OUTPUT_DIR}
+    LIBRARY_OUTPUT_DIRECTORY_RELWITHDEBINFO ${VIZDOOM_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY ${VIZDOOM_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY_RELEASE ${VIZDOOM_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY_DEBUG ${VIZDOOM_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY_MINSIZEREL ${VIZDOOM_OUTPUT_DIR}
+    ARCHIVE_OUTPUT_DIRECTORY_RELWITHDEBINFO ${VIZDOOM_OUTPUT_DIR}
+    OUTPUT_NAME ${VIZDOOM_OUTPUT_NAME})
+
+set_target_properties(libvizdoom_static
+    PROPERTIES
+    PROJECT_LABEL "Core static library")
+
+set_target_properties(libvizdoom_shared
+    PROPERTIES
+    PROJECT_LABEL "Core shared library")
+
+
+# ViZDoom Engine
+#-----------------------------------------------------------------------------------------------------------------------
+
+if(BUILD_ENGINE)
+    add_subdirectory(${VIZDOOM_SRC_DIR}/vizdoom)
+endif()
+
+
+# Python bindings
+#-----------------------------------------------------------------------------------------------------------------------
+
+if(BUILD_PYTHON)
+    add_subdirectory(${VIZDOOM_SRC_DIR}/lib_python)
+endif()

vizdoom-1.3.0.dev3/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: vizdoom
+Version: 1.3.0.dev3
+Summary: ViZDoom is Doom-based AI Research Platform for Reinforcement Learning from Raw Visual Information.
+Home-page: https://vizdoom.farama.org
+Author: Marek Wydmuch, Michał Kempka, Wojciech Jaśkowski, Farama Foundation, and the respective contributors
+Author-email: mwydmuch@cs.put.poznan.pl
+Keywords: vizdoom,doom,ai,deep learning,reinforcement learning,research
+Platform: Linux
+Platform: Mac OS X
+Platform: Windows
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9.0,<3.14
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: gymnasium>=0.28.0
+Requires-Dist: pygame>=2.1.3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: psutil; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+[![PyPI version](https://badge.fury.io/py/vizdoom.svg)](https://badge.fury.io/py/vizdoom) [![Build and test](https://github.com/Farama-Foundation/ViZDoom/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/Farama-Foundation/ViZDoom/actions/workflows/build-and-test.yml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Farama-Foundation/ViZDoom/master/docs/_static/img/vizdoom-text.png" width="500px"/>
+</p>
+
+ViZDoom allows developing AI **bots that play Doom using only visual information** (the screen buffer). It is primarily intended for research in machine visual learning, and deep reinforcement learning, in particular.
+
+ViZDoom is based on [ZDoom](https://zdoom.org) engine to provide the game mechanics.
+
+![ViZDoom Demo](https://raw.githubusercontent.com/Farama-Foundation/ViZDoom/master/docs/_static/img/vizdoom-demo.gif)
+
+
+## Features
+- API for Python (including [Gymnasium](https://gymnasium.farama.org/)/Gym wrappers) and C++,
+- Multi-platform (Linux, macOS, Windows),
+- Fast (up to 7000 frames/steps per second in sync mode, single-threaded on a modern CPU),
+- Lightweight (few MBs),
+- Easy-to-create custom scenarios (visual editors, scripting language, and examples available),
+- Async and sync single-player and multiplayer modes,
+- Customizable resolution and rendering parameters,
+- Access to the depth buffer (3D vision),
+- Automatic labeling and categorization of game objects visible in the frame,
+- Access to the audio buffer,
+- Access to the list of actors/objects and map geometry,
+- Off-screen rendering,
+- Episodes recording,
+- In-game time scaling in async mode.
+
+ViZDoom API is **reinforcement learning** friendly (suitable also for learning from demonstration, apprenticeship learning or apprenticeship via inverse reinforcement learning, etc.).
+
+
+## Cite as
+> M Wydmuch, M Kempka & W Jaśkowski, ViZDoom Competitions: Playing Doom from Pixels, IEEE Transactions on Games, vol. 11, no. 3, pp. 248-259, 2019
+([arXiv:1809.03470](https://arxiv.org/abs/1809.03470))
+```
+@article{Wydmuch2019ViZdoom,
+  author  = {Marek Wydmuch and Micha{\l} Kempka and Wojciech Ja\'skowski},
+  title   = {{ViZDoom} {C}ompetitions: {P}laying {D}oom from {P}ixels},
+  journal = {IEEE Transactions on Games},
+  year    = {2019},
+  volume  = {11},
+  number  = {3},
+  pages   = {248--259},
+  doi     = {10.1109/TG.2018.2877047},
+  note    = {The 2022 IEEE Transactions on Games Outstanding Paper Award}
+}
+```
+or/and
+
+> M. Kempka, M. Wydmuch, G. Runc, J. Toczek & W. Jaśkowski, ViZDoom: A Doom-based AI Research Platform for Visual Reinforcement Learning, IEEE Conference on Computational Intelligence and Games, pp. 341-348, Santorini, Greece, 2016	([arXiv:1605.02097](http://arxiv.org/abs/1605.02097))
+```
+@inproceedings{Kempka2016ViZDoom,
+  author    = {Micha{\l} Kempka and Marek Wydmuch and Grzegorz Runc and Jakub Toczek and Wojciech Ja\'skowski},
+  title     = {{ViZDoom}: A {D}oom-based {AI} Research Platform for Visual Reinforcement Learning},
+  booktitle = {IEEE Conference on Computational Intelligence and Games},
+  year      = {2016},
+  address   = {Santorini, Greece},
+  month     = {Sep},
+  pages     = {341--348},
+  publisher = {IEEE},
+  doi       = {10.1109/CIG.2016.7860433},
+  note      = {The Best Paper Award}
+}
+```
+
+
+## Python quick start
+
+### Note about versions
+
+#### ViZDoom 1.3.0.dev (development)
+
+We are currently working on version 1.3.0, and decideded to make development releases from time to time on PyPI.
+These releases are mostly incremental updates to the 1.2.4 version.
+We aim to keep the API stable, so 1.3.0 development releases should be compatible with the 1.2.4 version.
+However some minor behaviors may change, and bugs may be introduced.
+The main changes include/will include:
+- The update of Gymnasium environments to the latest Gymnasium API, and some minor improvements and bug fixes,
+- New version of the old environments and completely new environments,
+- New features including methods for easy setting of shaping reward, and natual language log of the game events,
+- Python 3.13 support,
+- Python type hinting support.
+
+To install the latest development version of ViZDoom, just run:
+```sh
+pip install vizdoom --pre
+```
+
+#### ViZDoom 1.2.4 (stable)
+
+ViZDoom 1.2.4 is the latest stable release, which is compatible with Python 3.8-3.12 and both NumPy 1.x and 2.x versions.
+⚠️ Versions 1.2.3 and below do not work correctly with NumPy 2.0+. To use NumPy 2.0+ please upgrade ViZDoom to version 1.2.4+.
+⚠️ For Python 3.13 install ViZDoom 1.3.0.dev release.
+
+
+### Linux
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+Both x86-64 and AArch64 (ARM64) architectures are supported.
+Wheels are available for Python 3.8+ on Linux.
+
+⚠️ To use audio features, you need OpenAL install in your system.
+On apt-based distros (Ubuntu, Debian, Linux Mint, etc.)
+```sh
+apt install libopenal-dev
+```
+
+On dnf/yum-based distros (Fedora, RHEL, CentOS, Alma/Rocky Linux, etc.)
+```sh
+dnf install openal-soft-devel
+```
+
+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/python_quickstart/) for more details.
+
+
+### macOS
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+Both Intel and Apple Silicon CPUs are supported.
+Pre-build wheels are available for Intel macOS 13.0+ and Apple Silicon (M-series chips) 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.
+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/building/) for more details how to install dependencies.
+
+
+### Windows
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+At the moment, only x86-64 architecture is supported on Windows.
+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) with Linux version.
+
+
+### Gymnasium/Gym wrappers
+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.
+
+
+## Examples
+- [Python](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/python) (contain learning examples implemented in PyTorch, TensorFlow, and Theano)
+- [C++](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/c%2B%2B)
+
+Python examples are currently the richest, so we recommend looking at them, even if you plan to use C++.
+The API is almost identical between the languages, with the only difference being that Python uses snake_case and C++ camelCase for methods and functions.
+
+
+## Original Doom graphics
+Unfortunately, we cannot distribute ViZDoom with original Doom graphics.
+If you own original Doom or Doom 2 games, you can replace [Freedoom](https://freedoom.github.io/) graphics by placing `doom.wad` or `doom2.wad` into your working directory or `vizdoom` package directory.
+
+Alternatively, any base game WAD (including other Doom engine-based games and custom/community games) can be used by pointing to it with the [`set_doom_game_path/setDoomGamePath`](https://vizdoom.farama.org/main/api/python/doom_game/index.html#vizdoom.DoomGame.set_doom_game_path) method.
+
+
+## Documentation
+Detailed descriptions of all ViZDoom types and methods can be found in the [documentation](https://vizdoom.farama.org/).
+
+Full documentation of the ZDoom engine and ACS scripting language can be found on
+[ZDoom Wiki](https://zdoom.org/wiki/).
+
+Useful articles (for advanced users who want to create custom environments/scenarios):
+- [ZDoom Wiki: ACS (scripting language)](https://zdoom.org/wiki/ACS)
+- [ZDoom Wiki: CVARs (console variables)](https://zdoom.org/wiki/CVARs)
+- [ZDoom Wiki: CCMD (console commands)](https://zdoom.org/wiki/CCMDs)
+
+
+## Awesome Doom tools/projects
+- [SLADE3](http://slade.mancubus.net/) - Great Doom map (scenario) editor for Linux, MacOS and Windows.
+- [Doom Builder 2](http://www.doombuilder.com/) - Another great Doom map editor for Windows.
+- [OBLIGE](http://oblige.sourceforge.net/) - Doom random map generator and [PyOblige](https://github.com/mwydmuch/PyOblige) is a simple Python wrapper for it.
+- [Omgifol](https://github.com/devinacker/omgifol) - Nice Python library for manipulating Doom maps.
+- [NavDoom](https://github.com/agiantwhale/navdoom) - Maze navigation generator for ViZDoom (similar to DeepMind Lab).
+- [MazeExplorer](https://github.com/microsoft/MazeExplorer) - A more sophisticated maze navigation generator for ViZDoom.
+- [Sample Factory](https://github.com/alex-petrenko/sample-factory) - A high-performance reinforcement learning framework for ViZDoom.
+- [EnvPool](https://github.com/sail-sg/envpool/) - A high-performance vectorized environment for ViZDoom.
+- [Obsidian](https://github.com/dashodanger/Obsidian) - Doom random map generator, a continuation of OBLIGE.
+- [LevDoom](https://github.com/TTomilin/LevDoom) - Generalization benchmark in ViZDoom featuring difficulty levels in visual complexity.
+- [COOM](https://github.com/TTomilin/COOM) - Continual learning benchmark in ViZDoom offering task sequences with diverse objectives.
+- [HASARD](https://github.com/TTomilin/HASARD) - A safe reinforcement learning benchmark in ViZDoom
+
+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.
+
+We have a roadmap for future development work for ViZDoom available [here](https://github.com/Farama-Foundation/ViZDoom/issues/546).
+
+
+## License
+The code original to ViZDoom is under MIT license. ZDoom uses code from several sources with [varying licensing schemes](http://zdoom.org/wiki/license).

vizdoom-1.3.0.dev3/README.md

@@ -0,0 +1,202 @@
+[![PyPI version](https://badge.fury.io/py/vizdoom.svg)](https://badge.fury.io/py/vizdoom) [![Build and test](https://github.com/Farama-Foundation/ViZDoom/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/Farama-Foundation/ViZDoom/actions/workflows/build-and-test.yml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Farama-Foundation/ViZDoom/master/docs/_static/img/vizdoom-text.png" width="500px"/>
+</p>
+
+ViZDoom allows developing AI **bots that play Doom using only visual information** (the screen buffer). It is primarily intended for research in machine visual learning, and deep reinforcement learning, in particular.
+
+ViZDoom is based on [ZDoom](https://zdoom.org) engine to provide the game mechanics.
+
+![ViZDoom Demo](https://raw.githubusercontent.com/Farama-Foundation/ViZDoom/master/docs/_static/img/vizdoom-demo.gif)
+
+
+## Features
+- API for Python (including [Gymnasium](https://gymnasium.farama.org/)/Gym wrappers) and C++,
+- Multi-platform (Linux, macOS, Windows),
+- Fast (up to 7000 frames/steps per second in sync mode, single-threaded on a modern CPU),
+- Lightweight (few MBs),
+- Easy-to-create custom scenarios (visual editors, scripting language, and examples available),
+- Async and sync single-player and multiplayer modes,
+- Customizable resolution and rendering parameters,
+- Access to the depth buffer (3D vision),
+- Automatic labeling and categorization of game objects visible in the frame,
+- Access to the audio buffer,
+- Access to the list of actors/objects and map geometry,
+- Off-screen rendering,
+- Episodes recording,
+- In-game time scaling in async mode.
+
+ViZDoom API is **reinforcement learning** friendly (suitable also for learning from demonstration, apprenticeship learning or apprenticeship via inverse reinforcement learning, etc.).
+
+
+## Cite as
+> M Wydmuch, M Kempka & W Jaśkowski, ViZDoom Competitions: Playing Doom from Pixels, IEEE Transactions on Games, vol. 11, no. 3, pp. 248-259, 2019
+([arXiv:1809.03470](https://arxiv.org/abs/1809.03470))
+```
+@article{Wydmuch2019ViZdoom,
+  author  = {Marek Wydmuch and Micha{\l} Kempka and Wojciech Ja\'skowski},
+  title   = {{ViZDoom} {C}ompetitions: {P}laying {D}oom from {P}ixels},
+  journal = {IEEE Transactions on Games},
+  year    = {2019},
+  volume  = {11},
+  number  = {3},
+  pages   = {248--259},
+  doi     = {10.1109/TG.2018.2877047},
+  note    = {The 2022 IEEE Transactions on Games Outstanding Paper Award}
+}
+```
+or/and
+
+> M. Kempka, M. Wydmuch, G. Runc, J. Toczek & W. Jaśkowski, ViZDoom: A Doom-based AI Research Platform for Visual Reinforcement Learning, IEEE Conference on Computational Intelligence and Games, pp. 341-348, Santorini, Greece, 2016	([arXiv:1605.02097](http://arxiv.org/abs/1605.02097))
+```
+@inproceedings{Kempka2016ViZDoom,
+  author    = {Micha{\l} Kempka and Marek Wydmuch and Grzegorz Runc and Jakub Toczek and Wojciech Ja\'skowski},
+  title     = {{ViZDoom}: A {D}oom-based {AI} Research Platform for Visual Reinforcement Learning},
+  booktitle = {IEEE Conference on Computational Intelligence and Games},
+  year      = {2016},
+  address   = {Santorini, Greece},
+  month     = {Sep},
+  pages     = {341--348},
+  publisher = {IEEE},
+  doi       = {10.1109/CIG.2016.7860433},
+  note      = {The Best Paper Award}
+}
+```
+
+
+## Python quick start
+
+### Note about versions
+
+#### ViZDoom 1.3.0.dev (development)
+
+We are currently working on version 1.3.0, and decideded to make development releases from time to time on PyPI.
+These releases are mostly incremental updates to the 1.2.4 version.
+We aim to keep the API stable, so 1.3.0 development releases should be compatible with the 1.2.4 version.
+However some minor behaviors may change, and bugs may be introduced.
+The main changes include/will include:
+- The update of Gymnasium environments to the latest Gymnasium API, and some minor improvements and bug fixes,
+- New version of the old environments and completely new environments,
+- New features including methods for easy setting of shaping reward, and natual language log of the game events,
+- Python 3.13 support,
+- Python type hinting support.
+
+To install the latest development version of ViZDoom, just run:
+```sh
+pip install vizdoom --pre
+```
+
+#### ViZDoom 1.2.4 (stable)
+
+ViZDoom 1.2.4 is the latest stable release, which is compatible with Python 3.8-3.12 and both NumPy 1.x and 2.x versions.
+⚠️ Versions 1.2.3 and below do not work correctly with NumPy 2.0+. To use NumPy 2.0+ please upgrade ViZDoom to version 1.2.4+.
+⚠️ For Python 3.13 install ViZDoom 1.3.0.dev release.
+
+
+### Linux
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+Both x86-64 and AArch64 (ARM64) architectures are supported.
+Wheels are available for Python 3.8+ on Linux.
+
+⚠️ To use audio features, you need OpenAL install in your system.
+On apt-based distros (Ubuntu, Debian, Linux Mint, etc.)
+```sh
+apt install libopenal-dev
+```
+
+On dnf/yum-based distros (Fedora, RHEL, CentOS, Alma/Rocky Linux, etc.)
+```sh
+dnf install openal-soft-devel
+```
+
+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/python_quickstart/) for more details.
+
+
+### macOS
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+Both Intel and Apple Silicon CPUs are supported.
+Pre-build wheels are available for Intel macOS 13.0+ and Apple Silicon (M-series chips) 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.
+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/building/) for more details how to install dependencies.
+
+
+### Windows
+To install the latest release of ViZDoom, just run:
+```sh
+pip install vizdoom
+```
+At the moment, only x86-64 architecture is supported on Windows.
+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) with Linux version.
+
+
+### Gymnasium/Gym wrappers
+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.
+
+
+## Examples
+- [Python](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/python) (contain learning examples implemented in PyTorch, TensorFlow, and Theano)
+- [C++](https://github.com/Farama-Foundation/ViZDoom/blob/master/examples/c%2B%2B)
+
+Python examples are currently the richest, so we recommend looking at them, even if you plan to use C++.
+The API is almost identical between the languages, with the only difference being that Python uses snake_case and C++ camelCase for methods and functions.
+
+
+## Original Doom graphics
+Unfortunately, we cannot distribute ViZDoom with original Doom graphics.
+If you own original Doom or Doom 2 games, you can replace [Freedoom](https://freedoom.github.io/) graphics by placing `doom.wad` or `doom2.wad` into your working directory or `vizdoom` package directory.
+
+Alternatively, any base game WAD (including other Doom engine-based games and custom/community games) can be used by pointing to it with the [`set_doom_game_path/setDoomGamePath`](https://vizdoom.farama.org/main/api/python/doom_game/index.html#vizdoom.DoomGame.set_doom_game_path) method.
+
+
+## Documentation
+Detailed descriptions of all ViZDoom types and methods can be found in the [documentation](https://vizdoom.farama.org/).
+
+Full documentation of the ZDoom engine and ACS scripting language can be found on
+[ZDoom Wiki](https://zdoom.org/wiki/).
+
+Useful articles (for advanced users who want to create custom environments/scenarios):
+- [ZDoom Wiki: ACS (scripting language)](https://zdoom.org/wiki/ACS)
+- [ZDoom Wiki: CVARs (console variables)](https://zdoom.org/wiki/CVARs)
+- [ZDoom Wiki: CCMD (console commands)](https://zdoom.org/wiki/CCMDs)
+
+
+## Awesome Doom tools/projects
+- [SLADE3](http://slade.mancubus.net/) - Great Doom map (scenario) editor for Linux, MacOS and Windows.
+- [Doom Builder 2](http://www.doombuilder.com/) - Another great Doom map editor for Windows.
+- [OBLIGE](http://oblige.sourceforge.net/) - Doom random map generator and [PyOblige](https://github.com/mwydmuch/PyOblige) is a simple Python wrapper for it.
+- [Omgifol](https://github.com/devinacker/omgifol) - Nice Python library for manipulating Doom maps.
+- [NavDoom](https://github.com/agiantwhale/navdoom) - Maze navigation generator for ViZDoom (similar to DeepMind Lab).
+- [MazeExplorer](https://github.com/microsoft/MazeExplorer) - A more sophisticated maze navigation generator for ViZDoom.
+- [Sample Factory](https://github.com/alex-petrenko/sample-factory) - A high-performance reinforcement learning framework for ViZDoom.
+- [EnvPool](https://github.com/sail-sg/envpool/) - A high-performance vectorized environment for ViZDoom.
+- [Obsidian](https://github.com/dashodanger/Obsidian) - Doom random map generator, a continuation of OBLIGE.
+- [LevDoom](https://github.com/TTomilin/LevDoom) - Generalization benchmark in ViZDoom featuring difficulty levels in visual complexity.
+- [COOM](https://github.com/TTomilin/COOM) - Continual learning benchmark in ViZDoom offering task sequences with diverse objectives.
+- [HASARD](https://github.com/TTomilin/HASARD) - A safe reinforcement learning benchmark in ViZDoom
+
+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.
+
+We have a roadmap for future development work for ViZDoom available [here](https://github.com/Farama-Foundation/ViZDoom/issues/546).
+
+
+## License
+The code original to ViZDoom is under MIT license. ZDoom uses code from several sources with [varying licensing schemes](http://zdoom.org/wiki/license).