OpenAI Gym Env

Gym is deprecated in favor of Gymnasium and these wrappers will be removed in the future. Please consider migrating to Gymnasium. To install gym wrapper you need to run pip install vizdoom[gym] as it is not installed by default.

class VizdoomEnv(level, frame_skip=1, max_buttons_pressed=1, render_mode: str | None = None)

Base class for Gym interface for ViZDoom. Thanks to https://github.com/shakenes/vizdoomgym Child classes are defined in gym_env_defns.py,

Parameters:

  • level (str) – path to the config file to load. Most settings should be set by this config file.

  • frame_skip (int) – how many frames should be advanced per action. 1 = take action on every frame. Default: 1.

  • max_buttons_pressed (int) – defines the number of binary buttons that can be selected at once. Default: 1. Should be >= 0. If < 0 a RuntimeError is raised. If == 0, the binary action space becomes MultiDiscrete([2] * num_binary_buttons) and [0, num_binary_buttons] number of binary buttons can be selected. If > 0, the binary action space becomes Discrete(n) and [0, max_buttons_pressed] number of binary buttons can be selected.

  • render_mode (Optional[str]) – the render mode to use could be either ‘human’ or ‘rgb_array’

This environment forces window to be hidden. Use render() function to see the game.

Observations are dictionaries with different amount of entries, depending on if depth/label buffers were enabled in the config file (CHANNELS == 1 if GRAY8, else 3):

  • “screen” = the screen image buffer (always available) in shape (HEIGHT, WIDTH, CHANNELS)

  • “depth” = the depth image in shape (HEIGHT, WIDTH, 1), if enabled by the config file,

  • “labels” = the label image buffer in shape (HEIGHT, WIDTH, 1), if enabled by the config file.

    For info on labels, access env.state.labels variable.

  • “automap” = the automap image buffer in shape (HEIGHT, WIDTH, CHANNELS), if enabled by the config file

  • “gamevariables” = all game variables, in the order specified by the config file

Action space can be a single one of binary/continuous action space, or a Dict containing both.

  • “binary”:

    = MultiDiscrete([2] * num_binary_buttons): if max_buttons_pressed == 0 = Discrete(n): if max_buttons_pressed > 1

  • “continuous”:

    = Box(float32.min, float32.max, (num_delta_buttons,), float32).

close()

Override close in your subclass to perform any necessary cleanup.

Environments will automatically close() themselves when garbage collected or when the program exits.

render()

Compute the render frames as specified by render_mode attribute during initialization of the environment.

The set of supported modes varies per environment. (And some third-party environments may not support rendering at all.) By convention, if render_mode is:

  • None (default): no render is computed.

  • human: render return None. The environment is continuously rendered in the current display or terminal. Usually for human consumption.

  • rgb_array: return a single frame representing the current state of the environment. A frame is a numpy.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

  • rgb_array_list: return a list of frames representing the states of the environment since the last reset. Each frame is a numpy.ndarray with shape (x, y, 3), as with rgb_array.

  • ansi: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

Note

Make sure that your class’s metadata ‘render_modes’ key includes the list of supported modes. It’s recommended to call super() in implementations to use the functionality of this method.

reset(*, seed: int | None = None, options: dict | None = None)

Resets the environment to an initial state and returns the initial observation.

This method can reset the environment’s random number generator(s) if seed is an integer or if the environment has not yet initialized a random number generator. If the environment already has a random number generator and reset() is called with seed=None, the RNG should not be reset. Moreover, reset() should (in the typical use case) be called with an integer seed right after initialization and then never again.

Parameters:

  • seed (optional int) – The seed that is used to initialize the environment’s PRNG. If the environment does not already have a PRNG and seed=None (the default option) is passed, a seed will be chosen from some source of entropy (e.g. timestamp or /dev/urandom). However, if the environment already has a PRNG and seed=None is passed, the PRNG will not be reset. If you pass an integer, the PRNG will be reset even if it already exists. Usually, you want to pass an integer right after the environment has been initialized and then never again. Please refer to the minimal example above to see this paradigm in action.

  • options (optional dict) – Additional information to specify how the environment is reset (optional, depending on the specific environment)

Returns:

  • observation (object) – Observation of the initial state. This will be an element of observation_space (typically a numpy array) and is analogous to the observation returned by step().

  • info (dictionary) – This dictionary contains auxiliary information complementing observation. It should be analogous to the info returned by step().

step(action)

Run one timestep of the environment’s dynamics.

When end of episode is reached, you are responsible for calling reset() to reset this environment’s state. Accepts an action and returns either a tuple (observation, reward, terminated, truncated, info).

Parameters:

action (ActType) – an action provided by the agent

Returns:

  • observation (object) – this will be an element of the environment’s observation_space. This may, for instance, be a numpy array containing the positions and velocities of certain objects.

  • reward (float) – The amount of reward returned as a result of taking the action.

  • terminated (bool) – whether a terminal state (as defined under the MDP of the task) is reached. In this case further step() calls could return undefined results.

  • truncated (bool) – whether a truncation condition outside the scope of the MDP is satisfied. Typically a timelimit, but could also be used to indicate agent physically going out of bounds. Can be used to end the episode prematurely before a terminal state is reached.

  • info (dictionary) – info contains auxiliary diagnostic information (helpful for debugging, learning, and logging). This might, for instance, contain: metrics that describe the agent’s performance state, variables that are hidden from observations, or individual reward terms that are combined to produce the total reward. It also can contain information that distinguishes truncation and termination, however this is deprecated in favour of returning two booleans, and will be removed in a future version.

  • (deprecated)

  • done (bool) – A boolean value for if the episode has ended, in which case further step() calls will return undefined results. A done signal may be emitted for different reasons: Maybe the task underlying the environment was solved successfully, a certain timelimit was exceeded, or the physics simulation has entered an invalid state.