### Build Example Executable with zlib

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/CMakeLists.txt

Defines an executable target named 'example' from 'example.c', links it against the zlib library, and adds it as a test case. This is a basic setup for integrating zlib into an executable.

```cmake
#add_executable(example example.c)
#target_link_libraries(example ${ZLIBNAME})
#add_test(example example)
```

--------------------------------

### Build ViZDoom Examples

Source: https://github.com/farama-foundation/vizdoom/blob/main/examples/cpp/README.md

Commands to build the ViZDoom C++ examples after building the ViZDoom library.

```bash
cmake . && make
```

--------------------------------

### Install ViZDoom Dependencies on apt-based Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs all possible ViZDoom dependencies, including optional ones for alternative sound and music backends. Some dependencies may replace libraries included in the ViZDoom repository. Use this command for a comprehensive setup.

```sh
# All possible ViZDoom dependencies,
# most are optional and required only to support alternative sound and music backends in the engine
# other can replace libraries that are included in the ViZDoom repository
apt install build-essential cmake git libsdl2-dev libboost-all-dev libopenal-dev \
zlib1g-dev libjpeg-dev tar libbz2-dev libgtk2.0-dev libfluidsynth-dev libgme-dev \
timidity libwildmidi-dev unzip
```

--------------------------------

### Install ViZDoom from GitHub Repository

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Use this command to install the latest version of ViZDoom directly from its GitHub repository using pip. Ensure you have pip and Git installed.

```sh
pip install git+https://github.com/mwydmuch/ViZDoom.git
```

--------------------------------

### Install ViZDoom on Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/README.md

Install the ViZDoom package using pip. Ensure OpenAL is installed for audio features.

```sh
pip install vizdoom
```

```sh
apt install libopenal-dev
```

```sh
dnf install openal-soft-devel
```

--------------------------------

### Run Audio Buffer Example

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/faq/index.md

Execute the audio buffer example script to test audio functionality and diagnose issues.

```python
examples/python/audio_buffer.py
```

--------------------------------

### Install zlib Manual Page

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/CMakeLists.txt

Installs the zlib manual page (zlib.3) to the share/man/man3 directory.

```cmake
install(FILES zlib.3 DESTINATION share/man/man3)
```

--------------------------------

### Install DUMB Libraries with Standard Make

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/dumb/readme.txt

After compilation, use this command to install the DUMB libraries using the standard Makefile.

```bash
make install
```

--------------------------------

### init

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/cpp/doom_game.md

Initializes the ViZDoom game instance and starts a new episode. Returns true if the game started successfully, false otherwise. Configuration options set before this call are final.

```APIDOC
## init

### Description
Initializes ViZDoom game instance and starts a new episode. After calling this method, the first state from a new episode will be available. Some configuration options cannot be changed after calling this method. Init returns true when the game was started properly and false otherwise.

### Method
C++: `bool init()`
Python: `init() -> bool`
```

--------------------------------

### Install ViZDoom on macOS

Source: https://github.com/farama-foundation/vizdoom/blob/main/README.md

Install ViZDoom using pip. For older macOS versions or Intel chips, specific version installation might be required.

```sh
pip install vizdoom
```

```sh
pip install vizdoom==1.2.4
```

--------------------------------

### Install zlib Libraries

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/CMakeLists.txt

Installs the zlib target to the appropriate runtime, archive, and library directories based on build configuration.

```cmake
install(TARGETS ${ZLIBNAME}
    RUNTIME DESTINATION bin
    ARCHIVE DESTINATION lib
    LIBRARY DESTINATION lib )
```

--------------------------------

### Install ViZDoom in Editable Mode

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/dev_guide.md

Installs the project in editable mode, allowing C++ code changes to be reflected without reinstallation. Ensure dependencies are installed first.

```sh
pip install -U pip setuptools wheel
pip install -e . --no-build-isolation
```

--------------------------------

### Install DUMB Libraries with MinGW

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/dumb/readme.txt

After compilation, use this command to install the DUMB libraries when using MinGW.

```bash
mingw32-make install
```

--------------------------------

### Build 64-bit Example Executable with zlib

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/CMakeLists.txt

Conditionally defines a 64-bit example executable if HAVE_OFF64_T is defined. It links against zlib and sets compile flags for 64-bit file offsets. This is for handling large files.

```cmake
#if(HAVE_OFF64_T)
#    add_executable(example64 example.c)
#    target_link_libraries(example64 ${ZLIBNAME})
#    set_target_properties(example64 PROPERTIES COMPILE_FLAGS "-D_FILE_OFFSET_BITS=64")
#    add_test(example64 example64)
```

--------------------------------

### Install ViZDoom on Windows

Source: https://github.com/farama-foundation/vizdoom/blob/main/README.md

Install the ViZDoom package using pip. Note that Windows support is primarily for x86-64 architecture and may be less stable than Linux/macOS.

```sh
pip install vizdoom
```

--------------------------------

### Install OpenAL on Debian/Ubuntu

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs the OpenAL library required for audio buffer functionality on apt-based Linux distributions.

```sh
apt install libopenal1
```

--------------------------------

### Install zlib Public Headers

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/CMakeLists.txt

Installs the public header files of the zlib library to the include directory.

```cmake
install(FILES ${ZLIB_PUBLIC_HDRS} DESTINATION include)
```

--------------------------------

### Install ViZDoom from Main Branch

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs the latest development version of ViZDoom directly from its GitHub main branch using pip. Requires pre-installed dependencies.

```sh
pip install git+https://github.com/Farama-Foundation/ViZDoom
```

--------------------------------

### Install Essential ViZDoom Dependencies on apt-based Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs only the essential ViZDoom dependencies required for core functionality. Use this command if you do not need support for alternative sound and music backends.

```sh
# Only essential ViZDoom dependencies
apt install build-essential cmake git libboost-all-dev libsdl2-dev libopenal-dev
```

--------------------------------

### Install Doom Assets (Python Only)

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs original Doom game assets (IWADs) into the ViZDoom package directory using a Python script. Requires the path to the .wad file.

```python
python -c 'import os,shutil,sys,vizdoom; src=sys.argv[1]; dst=os.path.join(vizdoom.install_path, os.path.basename(src).lower()); shutil.copy2(src,dst);' /path/to/file.wad
```

--------------------------------

### Install OpenAL on Fedora/RHEL/CentOS

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs the OpenAL library required for audio buffer functionality on dnf/yum-based Linux distributions.

```sh
dnf install openal-soft
```

--------------------------------

### Install ViZDoom Dependencies (Fedora/RHEL/CentOS)

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs necessary dependencies including cmake, git, Boost, SDL2, and OpenAL for building ViZDoom from source on dnf/yum-based systems.

```sh
dnf install cmake git boost-devel SDL2-devel openal-soft-devel
pip install vizdoom
```

--------------------------------

### Install ViZDoom Dependencies (Debian/Ubuntu)

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs necessary dependencies including cmake, git, Boost, SDL2, and OpenAL for building ViZDoom from source on apt-based systems.

```sh
apt install cmake git libboost-all-dev libsdl2-dev libopenal-dev
pip install vizdoom
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/farama-foundation/vizdoom/blob/main/AGENTS.md

Installs the pre-commit framework to enforce code formatting and linting for Python code. This ensures consistency across the project.

```sh
pre-commit install
```

--------------------------------

### Install Python Type Stub Dependencies

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Install the required Python packages for generating and testing ViZDoom's type stubs. This includes pybind11-stubgen and optionally black and isort.

```sh
pip install pybind11-stubgen black isort
```

--------------------------------

### Install Doom Assets (Python + Shell)

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/introduction/python_quickstart.md

Installs original Doom game assets (IWADs) into the ViZDoom package directory using a combination of shell variables and Python execution. Requires the path to the .wad file.

```sh
src=/path/to/file.wad; dst_dir="$(python -c 'import vizdoom; print(vizdoom.install_path)')"; cp "$src" "$dst_dir/$(basename "${src,,}")"
```

--------------------------------

### Install ViZDoom in Editable Mode

Source: https://github.com/farama-foundation/vizdoom/blob/main/AGENTS.md

Installs the project in editable mode, allowing C++ code changes to be reflected without reinstallation. Ensure pip, setuptools, and wheel are up-to-date beforehand. Use --no-build-isolation to maintain CMake stability.

```sh
python -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools wheel
pip install -e . --no-build-isolation
```

--------------------------------

### LZMA Include Directory Setup

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/CMakeLists.txt

Sets the include directory for the LZMA library.

```cmake
set( LZMA_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/lzma/C" )
```

--------------------------------

### Second Level Lookup Table Y Example

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/algorithm.txt

This is a second-level lookup table (Table Y), used when the first three bits are '111'. It is three bits long and decodes symbols that start with '111'.

```text
000: F,2
001: F,2
010: G,2
011: G,2
100: H,2
101: H,2
110: I,3
111: J,3
```

--------------------------------

### Sample ViZDoom Configuration

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/configuration_files.md

This sample demonstrates how to configure various aspects of ViZDoom, including game paths, rewards, rendering options, episode settings, available buttons, game variables, and game mode. It also shows how to set the difficulty.

```ini
doom_game_path = freedoom2.wad
doom_scenario_path = ../../scenarios/basic.wad
doom_map = map01

# Rewards
living_reward = -1

# Rendering options
screen_resolution = RES_320X240
screen_format = CRCGCB
render_hud = true
render_crosshair = false
render_weapon = true
render_decals = false
render_particles = false
window_visible = true

# make episodes start after 14 tics (after unholstering the gun)
episode_start_time = 14

# make episodes finish after 300 actions (tics)
episode_timeout = 300

# Available buttons
available_buttons =
    {
        MOVE_LEFT
        MOVE_RIGHT
        ATTACK
    }

# Game variables that will be in the state
available_game_variables = { AMMO2 }

# Default mode - the game is controlled from the code
mode = PLAYER

# Difficulty of gameplay ranging from 1 (baby) to 5 (nightmare)
doom_skill = 5
```

--------------------------------

### Second Level Lookup Table X Example

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/algorithm.txt

This is a second-level lookup table (Table X), used when the first three bits are '110'. It is two bits long and decodes symbols that start with '110'.

```text
00: C,1
01: C,1
10: D,2
11: E,2
```

--------------------------------

### Start X-Server for WSL GUI

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/faq/index.md

Launch VcXsrv on Windows to enable graphical applications, including ViZDoom, to display their windows within WSL.

```bash
"C:\Program Files\VcXsrv\vcxsrv.exe" :0 -ac -terminate -lesspointer -multiwindow -clipboard -wgl -dpi auto
```

--------------------------------

### Basic ViZDoom Environment Usage

Source: https://github.com/farama-foundation/vizdoom/blob/main/examples/cpp/README.md

Demonstrates fundamental ViZDoom features, including engine configuration, random action execution, and state/reward printing.

```cpp
#include <iostream>
#include <vizdoom.h>

int main() {
    ViZDoom doom;
    doom.loadConfig("scenarios/basic.cfg");
    doom.init();

    // Available actions are stored in:
    // doom.getAvailableButtons()
    // doom.getAvailableButtonCombos()

    // Random actions
    for (int i = 0; i < 100; ++i) {
        doom.performAction(doom.getRandomAction());
        doom.advanceFrame();

        std::cout << "State: " << doom.getState() << std::endl;
        std::cout << "Reward: " << doom.getReward() << std::endl;
    }

    doom.clear পেতে();
    return 0;
}
```

--------------------------------

### ViZDoom CMakeLists.txt Configuration

Source: https://github.com/farama-foundation/vizdoom/blob/main/examples/cpp/CMakeLists.txt

This is the main CMakeLists.txt file for the ViZDoom C++ examples. It sets the minimum CMake version, project name, C++ standard, and configures how to link against the ViZDoom library (static or shared). It also finds required packages like Boost and Threads, sets include directories, and defines output directories for executables.

```cmake
cmake_minimum_required(VERSION 3.12)
project(ViZDoomC++Examples)

if(COMMAND cmake_policy)
	cmake_policy(SET CMP0003 NEW)
endif(COMMAND cmake_policy)

set(CMAKE_CXX_STANDARD 11)

# Set the release mode if not specified
if (NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release)
endif ()

# Select if we want to link against static or shared libvizdoom
set( LIBVIZDOOM_TYPE STATIC CACHE STRING "Type of libvizdoom library to link against STATIC or SHARED" )

if( LIBVIZDOOM_TYPE STREQUAL "SHARED" )
	add_library( libvizdoom SHARED IMPORTED )
	if (WIN32)
		set_property(TARGET libvizdoom PROPERTY IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/vizdoom.dll)
	elseif (UNIX AND NOT APPLE)
		set_property(TARGET libvizdoom PROPERTY IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/libvizdoom.so)
	elseif (APPLE)
		set_property(TARGET libvizdoom PROPERTY IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/libvizdoom.dylib)
	endif()
else()
	add_library( libvizdoom STATIC IMPORTED )
	if (WIN32)
		set_property(TARGET libvizdoom PROPERTY IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/vizdoom.dll)
	elseif (UNIX)
		set_property(TARGET libvizdoom PROPERTY IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/libvizdoom.a)
	endif()
endif()

find_package(Boost COMPONENTS filesystem thread system date_time chrono regex iostreams REQUIRED)
find_package(Threads REQUIRED)

set( VIZDOOM_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../include )
include_directories( ${VIZDOOM_INCLUDE_DIR} )

set( VIZDOOM_EXAMPLES_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../bin/examples )

set( VIZDOOM_LIBS libvizdoom
	${Boost_LIBRARIES}
	${CMAKE_THREAD_LIBS_INIT} )

if( UNIX AND NOT APPLE)
	set( VIZDOOM_LIBS ${VIZDOOM_LIBS} rt)
endif()

add_executable( basic Basic.cpp )
target_link_libraries (basic ${VIZDOOM_LIBS})

add_executable( cig CIG.cpp )
target_link_libraries (cig ${VIZDOOM_LIBS})

add_executable( cigbots CIGBots.cpp )
target_link_libraries (cigbots ${VIZDOOM_LIBS})

add_executable( cighost CIGHost.cpp )
target_link_libraries (cighost ${VIZDOOM_LIBS})

add_executable( deltabuttons DeltaButtons.cpp )
target_link_libraries (deltabuttons ${VIZDOOM_LIBS})

add_executable( fpstest FPSTest.cpp )
target_link_libraries (fpstest ${VIZDOOM_LIBS})

add_executable( seed Seed.cpp )
target_link_libraries (seed ${VIZDOOM_LIBS})

add_executable( shaping Shaping.cpp )
target_link_libraries (shaping ${VIZDOOM_LIBS})

add_executable( spectator Spectator.cpp )
target_link_libraries (spectator ${VIZDOOM_LIBS})

set_target_properties( basic cig cigbots cighost deltabuttons fpstest seed shaping spectator
	PROPERTIES
	RUNTIME_OUTPUT_DIRECTORY ${VIZDOOM_EXAMPLES_OUTPUT_DIR}
	RUNTIME_OUTPUT_DIRECTORY_DEBUG ${VIZDOOM_EXAMPLES_OUTPUT_DIR}
	RUNTIME_OUTPUT_DIRECTORY_RELEASE ${VIZDOOM_EXAMPLES_OUTPUT_DIR}
	RUNTIME_OUTPUT_DIRECTORY_MINSIZEREL ${VIZDOOM_EXAMPLES_OUTPUT_DIR}
	RUNTIME_OUTPUT_DIRECTORY_RELWITHDEBINFO ${VIZDOOM_EXAMPLES_OUTPUT_DIR} )

```

--------------------------------

### Linking Libraries and Include Directories

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/lib_python/CMakeLists.txt

Sets up the libraries and include directories required for building the Python bindings, including ViZDoom's core libraries and Boost.

```cmake
set(VIZDOOM_PYTHON_LIBS
    ${VIZDOOM_LIBS}
    ${Boost_LIBRARIES})

include_directories(${VIZDOOM_PYTHON_INCLUDE_DIR}
    ${Boost_INCLUDE_DIR})
```

--------------------------------

### Build and Install ViZDoom Manually with Conda

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Manually builds and installs ViZDoom within a Conda environment after cloning the repository. This method is used when installing ViZDoom in a Conda environment.

```default
git clone https://github.com/Farama-Foundation/ViZDoom.git
cd ViZDoom
python setup.py build && python setup.py install
```

--------------------------------

### Initialize and Interact with ViZDoom using Original API

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/index.md

This snippet demonstrates how to use the native ViZDoom API for game interaction. It requires loading a configuration file and initializing the DoomGame instance.

```python
import vizdoom as vzd
game = vzd.DoomGame()
game.load_config(os.path.join(vzd.scenarios_path, "deadly_corridor.cfg"))
game.init()
for _ in range(1000):
   state = game.get_state()
   action = policy(state)  # this is where you would insert your policy
   reward = game.make_action(action)

   if game.is_episode_finished():
      game.new_episode()

game.close()
```

--------------------------------

### Install Dependencies using Conda

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs necessary dependencies (Boost, CMake, GTK2, SDL2, OpenAL) into a Conda environment, useful when root access is unavailable. These packages are installed from the conda-forge channel.

```sh
conda install -c conda-forge boost cmake gtk2 sdl2 openal-soft
```

--------------------------------

### Install Python 3 Dependencies on apt-based Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs Python 3 development headers and pip, necessary for building Python bindings. Alternatively, ensure Anaconda 3 is installed and added to your PATH.

```sh
# Python 3 dependencies (alternatively Anaconda 3 installed)
apt install python3-dev python3-pip
# or install Anaconda 3 and add it to PATH
```

--------------------------------

### Initialize VizdoomEnv

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/python/gymnasium_wrapper.md

Instantiate the VizdoomEnv with various configuration options. Use a config file or provide settings via kwargs. Frame skipping, max buttons pressed, and render mode can be specified.

```python
env = VizdoomEnv(config_file=None, frame_skip=1, max_buttons_pressed=0, render_mode="human", treat_episode_timeout_as_truncation=True, use_multi_binary_action_space=True)
```

--------------------------------

### Full File Parsing Example

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/tools/lemon/lemon.html

A complete C function demonstrating how to use the Lemon parser to parse a file. It includes tokenization, parsing, and cleanup.

```c
01 ParseTree *ParseFile(const char *zFilename){
02    Tokenizer *pTokenizer;
03    void *pParser;
04    Token sToken;
05    int hTokenId;
06    ParserState sState;
07
08    pTokenizer = TokenizerCreate(zFilename);
09    pParser = ParseAlloc( malloc );
10    InitParserState(&sState);
11    while( GetNextToken(pTokenizer, &hTokenId, &sToken) ){
12       Parse(pParser, hTokenId, sToken, &sState);
13    }
14    Parse(pParser, 0, sToken, &sState);
15    ParseFree(pParser, free );
16    TokenizerFree(pTokenizer);
17    return sState.treeRoot;
18 }
```

--------------------------------

### setEpisodeStartTime

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/cpp/doom_game.md

Sets the start time (delay) of every episode in tics. Episodes will start after the specified number of tics.

```APIDOC
## setEpisodeStartTime

### Description
Sets the start time (delay) of every episode in tics. Every episode will effectively start (from the user’s perspective) after the provided number of tics.

### Method Signature
- C++: `void setEpisodeStartTime(unsigned int tics)`
- Python: `set_episode_start_time(tics: int) -> None`

### Parameters
- `tics` (unsigned int/int): The number of tics to delay the start of the episode.
```

--------------------------------

### Create Gymnasium Environment for ViZDoom

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/environments/default.md

Instantiate a ViZDoom environment using `gymnasium.make` by providing the scenario ID. The `vizdoom.gymnasium_wrapper` import registers all available environments. Additional keyword arguments like `frame_skip` can be passed.

```python
import gymnasium
from vizdoom import gymnasium_wrapper # This import will register all the environments

env = gymnasium.make("VizdoomBasic-v1", frame_skip=1) # or any other environment id
```

--------------------------------

### Build ViZDoom from Local Source

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Clone the ViZDoom repository and then build and install it using pip from the local source directory. This method is useful for development or when modifying the source code.

```sh
git clone https://github.com/mwydmuch/ViZDoom.git
cd ViZDoom
pip install .
```

--------------------------------

### set_episode_start_time

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/python/doom_game.md

Sets the start time (delay) of every episode in tics. Every episode will effectively start after the provided number of tics.

```APIDOC
## set_episode_start_time

### Description
Sets the start time (delay) of every episode in tics. Every episode will effectively start (from the user’s perspective) after the provided number of tics.

### Parameters
#### Path Parameters
- **start_time** (SupportsInt) - Required - The delay in tics before an episode starts.

### Default Value
1
```

--------------------------------

### Example ViZDoom Configuration File

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/environments/creating_custom.md

This INI-style configuration file defines various parameters for a ViZDoom scenario, including the WAD file, map, rewards, episode settings, available buttons, game variables, and depth buffer.

```ini
doom_scenario_path = mywad.wad
doom_map = map01        # map in the wad file that will be used (wad can contain more than one map)

living_reward = -1      # add -1 reward for each tic (action)
episode_start_time = 14 # make episodes start after 14 tics (after unholstering the gun)
episode_timeout = 300   # make episodes finish after 300 actions (tics)

available_buttons = {   # limit action space to only three buttons
    MOVE_LEFT
    MOVE_RIGHT
    ATTACK
}

available_game_variables = { # make information about ammo available in the state
    AMMO2
    AMMO3
}

depth_buffer_enabled = true     # add depth buffer to the state

```

--------------------------------

### Load Game Configuration from File

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/cpp/doom_game.md

Loads game configuration from a specified file path. Overwrites existing configurations, applying only overlapping parameters. Returns true on success, false if errors occur.

```C++
bool loadConfig(std::string filePath)
```

```Python
load_config(file_path: str) -> bool
```

--------------------------------

### Install ViZDoom Dependencies on macOS

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs required dependencies for building ViZDoom on macOS using Homebrew. This includes CMake, Boost, SDL2, and OpenAL.

```sh
brew install cmake boost sdl2 openal-soft
```

--------------------------------

### ViZDoom Deterministic Episodes with Seed

Source: https://github.com/farama-foundation/vizdoom/blob/main/examples/cpp/README.md

Demonstrates how to run deterministic episodes by setting the seed, ensuring identical episodes if the agent behaves deterministically.

```cpp
// Seed.cpp example (content not provided in source)
```

--------------------------------

### Manual Build Configuration (Linux/macOS)

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Configure and build ViZDoom manually on Linux or macOS. Ensure you are in the ViZDoom root directory. CMake options like -DBUILD_ENGINE and -DBUILD_PYTHON are optional.

```bash
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_ENGINE=ON -DBUILD_PYTHON=ON -DCREATE_PYTHON_STUBS=OFF
make
```

--------------------------------

### Set the grammar start symbol

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/tools/lemon/lemon.html

The %start_symbol directive allows specifying a non-terminal symbol other than the default first one as the grammar's start symbol.

```lemon
%start_symbol  prog
```

--------------------------------

### Initialize and Interact with ViZDoom using Gymnasium

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/index.md

Use this snippet to integrate ViZDoom environments into your reinforcement learning workflows via the Gymnasium API. Ensure the vizdoom gymnasium wrapper is imported.

```python
import gymnasium
from vizdoom import gymnasium_wrapper
env = gymnasium.make("VizdoomDeadlyCorridor-v1")
observation, info = env.reset()
for _ in range(1000):
   action = policy(observation)  # this is where you would insert your policy
   observation, reward, terminated, truncated, info = env.step(action)

   if terminated or truncated:
      observation, info = env.reset()

env.close()
```

--------------------------------

### Configuring Include Directories

Source: https://github.com/farama-foundation/vizdoom/blob/main/CMakeLists.txt

Adds ViZDoom's library include directories and Boost's include directory to the build. This makes headers accessible during compilation.

```cmake
include_directories(${VIZDOOM_LIB_INCLUDE_DIR} ${Boost_INCLUDE_DIR})
```

--------------------------------

### Using Registered Gymnasium Environment

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/environments/creating_custom.md

Instantiate and use the custom ViZDoom environment as any other standard Gymnasium environment after registration.

```python
env = gymnasium.make("<name of your environment>")

```

--------------------------------

### Load Music File from Path

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/game-music-emu/gme.txt

Opens a music file from a given file path. The library automatically detects the file type.

```c
error = gme_open_file( pathname, &emu );
```

--------------------------------

### UDMF Example: Minimally Defined Entity

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/specs/udmf.txt

An example of a minimally defined entity in UDMF, specifically a 'linedef' with only its 'id' field specified. Compliant parsers ignore unknown keywords.

```UDMF
linedef { id = 1; }
```

--------------------------------

### DoomGame Initialization and Control

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/api/python/doom_game.md

Methods for initializing, closing, and managing game episodes and replays.

```APIDOC
## init()

### Description
Initializes ViZDoom game instance and starts a new episode. After calling this method, the first state from a new episode will be available. Some configuration options cannot be changed after calling this method. Init returns `True` when the game was started properly and `False` otherwise.

### Method
`init()`

### Parameters
None

### Response
- `bool`: `True` if the game was started properly, `False` otherwise.
```

```APIDOC
## close()

### Description
Closes ViZDoom game instance. It is automatically invoked by the destructor. The game can be initialized again after being closed.

### Method
`close()`

### Parameters
None

### Response
None
```

```APIDOC
## new_episode(recording_file_path: str = '')

### Description
Initializes a new episode. The state of an environment is completely restarted (all variables and rewards are reset to their initial values). After calling this method, the first state from the new episode will be available. If the `recording_file_path` argument is not empty, the new episode will be recorded to this file (as a Doom lump).
In a multiplayer game, the host can call this method to finish the game. Then the rest of the players must also call this method to start a new episode.

### Method
`new_episode(recording_file_path: str = '')`

### Parameters
- **recording_file_path** (str) - Optional - Path to save the recording of the new episode.

### Response
None
```

```APIDOC
## replay_episode(file_path: str, player: SupportsInt = 0)

### Description
Replays the recorded episode from the given file using the perspective of the specified player. Players are numbered from 1. If `player` argument is equal to 0, the episode will be replayed using the perspective of the default player in the recording file. After calling this method, the first state from the replay will be available. All rewards, variables, and states are available when replaying the episode.

### Method
`replay_episode(file_path: str, player: SupportsInt = 0)`

### Parameters
- **file_path** (str) - Required - The path to the recording file.
- **player** (SupportsInt) - Optional - The player perspective to use for replaying (default is 0, meaning the default player in the recording).

### Response
None
```

--------------------------------

### Install Python 3 Dependencies on dnf/yum-based Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs Python 3 development headers and pip for dnf/yum-based systems. This is required for building Python bindings. Anaconda 3 can be used as an alternative.

```sh
# Python 3 dependencies (alternatively Anaconda 3 installed)
dnf install python3-devel python3-pip
```

--------------------------------

### Set up Homebrew Environment Variables on Apple Silicon

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Configures environment variables for Homebrew on Apple Silicon (M-series chip) if both arm64 and x86 versions were installed. This ensures the correct Homebrew installation is used.

```sh
eval "$(/opt/homebrew/bin/brew shellenv)"
```

--------------------------------

### Basic GME Playback Workflow

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/game-music-emu/gme.txt

This outlines the fundamental steps for playing a game music file using the GME library. Ensure generated samples are played through the system's audio output.

```c
gme_err_t err = gme_open_file( path, &emu );
if ( err == gme_wrong_file_type )
    ...

gme_start_track();
while ( !gme_track_ended() ) {
    gme_play( samples, sample_count );
    // Play samples through speaker
}
gme_delete( emu );
```

--------------------------------

### Install ViZDoom Dependencies on dnf/yum-based Linux

Source: https://github.com/farama-foundation/vizdoom/blob/main/docs/dev/building_from_source.md

Installs essential ZDoom dependencies on dnf/yum-based Linux distributions like Fedora, RHEL, CentOS, Alma/Rocky Linux. This includes CMake, Git, Boost, SDL2, and OpenAL.

```sh
# Essential ZDoom dependencies
dnf install cmake git boost-devel SDL2-devel openal-soft-devel
```

--------------------------------

### Example Huffman Symbols and Lengths

Source: https://github.com/farama-foundation/vizdoom/blob/main/src/vizdoom/zlib/algorithm.txt

This lists example symbols with their corresponding bit lengths, used to illustrate the construction of inflate's lookup tables. The lengths vary, demonstrating the need for an adaptive lookup strategy.

```text
A: 0
B: 10
C: 1100
D: 11010
E: 11011
F: 11100
G: 11101
H: 11110
I: 111110
J: 111111
```