ViZDoom: Doom-Based Reinforcement Learning

What is ViZDoom?

ViZDoom is a reinforcement learning research platform built on the ZDoom engine that lets you train AI bots to play Doom using nothing but the screen buffer as input. It exposes a Python API (with Gymnasium/Gym wrappers) and a C++ API for building and running scenarios, and per the README it's also usable for learning from demonstration and apprenticeship learning, not just plain RL.

Key Capabilities for AI Development

• ✓A Python API with Gymnasium/Gym wrappers installed alongside the package, plus a separate C++ API for the same simulator - Python methods use snake_case, C++ ones use camelCase.
• ✓Sync mode reportedly reaches up to 7000 frames per second on a single CPU thread, per the README, so the simulator itself isn't the bottleneck in a training loop.
• ✓Beyond the RGB screen buffer, ViZDoom exposes a depth buffer for 3D vision, an audio buffer, and automatic labeling of visible game objects.
• ✓Access to the list of in-game actors and objects, map geometry, and in-game text or notifications - not just rendered frames.
• ✓Both async and sync simulation modes, in single-player and multiplayer configurations, with customizable resolution and rendering parameters.
• ✓Off-screen rendering, episode recording, and in-game time scaling for async mode are all built in.
• ✓Custom scenarios can be built with visual map editors and a scripting language inherited from the ZDoom engine, with example scenarios shipped in the repo.

Who Benefits from ViZDoom?

ViZDoom fits researchers and engineers who want a fast, pixel-based 3D environment for deep reinforcement learning experiments and don't need a modern game engine's fidelity to get useful results - the built-in Gymnasium wrappers mean you can plug it into an existing training pipeline without writing a custom env class. It also suits anyone studying visual or multimodal perception in RL, since the depth buffer, audio buffer, and object labels provide signal beyond raw pixels. It's a poor fit if you need an actively developed modern 3D game beyond Doom-era mechanics, or if Windows is your only target platform and you need first-class, well-tested support there.

Getting Started with ViZDoom Installation

On Linux, `pip install vizdoom` pulls prebuilt wheels for Python 3.10+ on both x86-64 and ARM64; enabling audio separately requires OpenAL from your package manager - `apt install libopenal-dev` on Debian/Ubuntu, or `dnf install openal-soft-devel` on Fedora/RHEL-family distros. The same `pip install vizdoom` command works on macOS, though starting with version 1.3.0 the prebuilt wheel targets only Apple Silicon on macOS 14.0 or newer; Intel Mac users on macOS 13.0+ instead pin the older release with `pip install vizdoom==1.2.4`. On Windows, `pip install vizdoom` covers x86-64 with Python 3.10+ wheels, but the README flags Windows as less tested than the other two platforms and points to Docker or WSL for anything beyond light experimentation. Outside those wheel combinations, pip falls back to building from source, which needs a C++11-capable compiler alongside CMake 3.12 or newer, Boost 1.54 or newer, and SDL2, with OpenAL optional. Gymnasium/Gym wrapper environments install automatically with the package on every supported platform.

Building and Training AI Agents

Training code lives in the repo's examples folder rather than a single quick-start script: the Python examples are the most integrated, with some wired up to PyTorch, TensorFlow, and Theano, while the C++ examples cover the same scenarios with a smaller set. The Python and C++ surfaces mirror each other, differing mainly in casing convention (snake_case in Python, camelCase in C++), so a Gymnasium-style Python prototype maps fairly directly onto the C++ side if you need to port it later. The Gymnasium/Gym wrapper is what most RL codebases will actually import - the repo has a dedicated Gymnasium doc and an example script for wiring it into a standard training loop. One quirk to know before you start: ViZDoom can't ship the original Doom assets, so scenarios render with Freedoom graphics by default; if you own Doom or Doom II, you can drop your own doom2.wad into the working directory, or point at any Doom-engine WAD with the set_doom_game_path/setDoomGamePath method instead.

Related Tools and Alternatives

Frequently Asked Questions about ViZDoom

The problem it solves

Reinforcement learning researchers testing visual, pixel-based control need an environment cheap enough to run millions of simulation steps but complex enough to actually stress perception - most repurposed game engines are too heavy for that or don't expose the buffers researchers actually want. ViZDoom addresses this by wrapping the ZDoom engine (the engine behind the 1993 Doom) into a lightweight, few-MB simulator that hands back not just the screen buffer but depth, object labels, and audio too, so a bot can be trained on visual information alone, the way the README frames it.

Best use cases

• •Benchmarking pixel-based deep reinforcement learning algorithms where you want a fast, inexpensive 3D environment instead of a full modern game engine.
• •Research that needs more than RGB frames - depth buffers, object labels, or audio - for visual or multimodal perception work in an RL agent.
• •Building custom training scenarios with ViZDoom's visual editors and scripting language rather than relying only on the stock example configs.
• •Prototyping in Gymnasium-standard Python before porting a trained approach to a C++ pipeline, since the two APIs are nearly identical.
• •Academic work citing ViZDoom's own platform papers - the 2016 IEEE CIG paper (Best Paper award) and the 2019 IEEE Transactions on Games paper (2022 Outstanding Paper award).

Related repositories