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 to provide the game mechanics.
ViZDoom API is reinforcement learning friendly (suitable also for learning from demonstration, apprenticeship learning or apprenticeship via inverse reinforcement learning, etc.).
Julia (thanks to Jun Tian), Lua, and Java bindings are available in other branches but are no longer maintained.
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)
@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
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)
@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}
}
Both x86-64 and ARM64 architectures are supported. ViZDoom requires C++11 compiler, CMake 3.4+, Boost 1.65+ SDL2, OpenAL (optional) and Python 3.8+. Below you will find instructrion how to install these dependencies.
To install ViZDoom run (may take few minutes):
apt install cmake git libboost-all-dev libsdl2-dev libopenal-dev
pip install vizdoom
We recommend using at least Ubuntu 18.04+ or Debian 10+ with Python 3.8+.
To install ViZDoom run (may take few minutes):
dnf install cmake git boost-devel SDL2-devel openal-soft-devel
pip install vizdoom
We recommend using at least Fedora 35+ or RHEL/CentOS/Alma/Rocky Linux 9+ with Python 3.8+. To install openal-soft-devel on RHEL/CentOS/Alma/Rocky Linux 9, one needs to use dnf --enablerepo=crb install
.
To install ViZDoom on a conda environment (no system-wide installations required):
conda install -c conda-forge boost cmake sdl2
git clone https://github.com/mwydmuch/ViZDoom.git --recurse-submodules
cd ViZDoom
python setup.py build && python setup.py install
Note that pip install vizdoom
won't work with conda install and you have to follow these steps.
Both Intel and Apple Silicon CPUs are supported.
To install ViZDoom on run (may take few minutes):
brew install cmake git boost openal-soft sdl2
pip install vizdoom
We recommend using at least macOS High Sierra 10.13+ with Python 3.8+. On Apple Silicon (M1 and M2), make sure you are using Python for Apple Silicon.
To install pre-build release for Windows 10 or 11 64-bit and Python 3.8+ just run (should take few seconds):
pip install vizdoom
Please note that the Windows version is not as well-tested as Linux and macOS versions. It can be used for development and testing if you want to conduct experiments on Windows, please consider using Docker or WSL.
Gymnasium environments are installed along with ViZDoom. See documentation and examples on the use of Gymnasium API.
OpenAI-Gym wrappers are also available, to install them run:
pip install vizdoom[gym]
See documentation and examples on the use of Gym API. OpenAI-Gym wrappers are deprecated and will be removed in future versions in favour of Gymnasium.
Python examples are currently the richest, so we recommend to look at them, even if you plan to use other language. The API is almost identical for all languages.
See also the tutorial.
Unfortunately, we cannot distribute ViZDoom with original Doom graphics. If you own original Doom or Doom 2 games, you can replace Freedoom 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
method.
Detailed description of all types and methods:
Additional documents:
Full documentation of the Doom engine and ACS scripting language can be found on ZDoom Wiki.
Useful articles:
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.
Author: Farama-Foundation
Source Code: https://github.com/Farama-Foundation/ViZDoom
License: MIT license