Utils#

Visualization#

gymnasium.utils.play.play(env: Env, transpose: Optional[bool] = True, fps: Optional[int] = None, zoom: Optional[float] = None, callback: Optional[Callable] = None, keys_to_action: Optional[Dict[Union[Tuple[Union[str, int]], str], ActType]] = None, seed: Optional[int] = None, noop: ActType = 0)#

Allows one to play the game using keyboard.

Example:

>>> import gymnasium as gym
>>> from gymnasium.utils.play import play
>>> play(gym.make("CarRacing-v1", render_mode="rgb_array"), keys_to_action={
...                                                "w": np.array([0, 0.7, 0]),
...                                                "a": np.array([-1, 0, 0]),
...                                                "s": np.array([0, 0, 1]),
...                                                "d": np.array([1, 0, 0]),
...                                                "wa": np.array([-1, 0.7, 0]),
...                                                "dw": np.array([1, 0.7, 0]),
...                                                "ds": np.array([1, 0, 1]),
...                                                "as": np.array([-1, 0, 1]),
...                                               }, noop=np.array([0,0,0]))

Above code works also if the environment is wrapped, so it’s particularly useful in verifying that the frame-level preprocessing does not render the game unplayable.

If you wish to plot real time statistics as you play, you can use gym.utils.play.PlayPlot. Here’s a sample code for plotting the reward for last 150 steps.

>>> import gymnasium as gym
>>> def callback(obs_t, obs_tp1, action, rew, terminated, truncated, info):
...        return [rew,]
>>> plotter = PlayPlot(callback, 150, ["reward"])
>>> play(gym.make("CartPole-v1"), callback=plotter.callback)
Parameters:

  • env – Environment to use for playing.

  • transpose – If this is True, the output of observation is transposed. Defaults to True.

  • fps – Maximum number of steps of the environment executed every second. If None (the default), env.metadata["render_fps""] (or 30, if the environment does not specify “render_fps”) is used.

  • zoom – Zoom the observation in, zoom amount, should be positive float

  • callback – If a callback is provided, it will be executed after every step. It takes the following input: obs_t: observation before performing action obs_tp1: observation after performing action action: action that was executed rew: reward that was received terminated: whether the environment is terminated or not truncated: whether the environment is truncated or not info: debug info

  • keys_to_action –

    Mapping from keys pressed to action performed. Different formats are supported: Key combinations can either be expressed as a tuple of unicode code points of the keys, as a tuple of characters, or as a string where each character of the string represents one key. For example if pressing ‘w’ and space at the same time is supposed to trigger action number 2 then key_to_action dict could look like this:

    >>> {
...    # ...
...    (ord('w'), ord(' ')): 2
...    # ...
... }

    or like this:

    >>> {
...    # ...
...    ("w", " "): 2
...    # ...
... }

    or like this:

    >>> {
...    # ...
...    "w ": 2
...    # ...
... }

    If None, default key_to_action mapping for that environment is used, if provided.

  • seed – Random seed used when resetting the environment. If None, no seed is used.

  • noop – The action used when no key input has been entered, or the entered key combination is unknown.

class gymnasium.utils.play.PlayPlot(callback: callable, horizon_timesteps: int, plot_names: List[str])#

Provides a callback to create live plots of arbitrary metrics when using play().

This class is instantiated with a function that accepts information about a single environment transition:

  • obs_t: observation before performing action

  • obs_tp1: observation after performing action

  • action: action that was executed

  • rew: reward that was received

  • terminated: whether the environment is terminated or not

  • truncated: whether the environment is truncated or not

  • info: debug info

It should return a list of metrics that are computed from this data. For instance, the function may look like this:

>>> def compute_metrics(obs_t, obs_tp, action, reward, terminated, truncated, info):
...     return [reward, info["cumulative_reward"], np.linalg.norm(action)]

PlayPlot provides the method callback() which will pass its arguments along to that function and uses the returned values to update live plots of the metrics.

Typically, this callback() will be used in conjunction with play() to see how the metrics evolve as you play:

>>> plotter = PlayPlot(compute_metrics, horizon_timesteps=200,
...                    plot_names=["Immediate Rew.", "Cumulative Rew.", "Action Magnitude"])
>>> play(your_env, callback=plotter.callback)

Constructor of PlayPlot.

The function callback that is passed to this constructor should return a list of metrics that is of length len(plot_names).

Parameters:

  • callback – Function that computes metrics from environment transitions

  • horizon_timesteps – The time horizon used for the live plots

  • plot_names – List of plot titles

Raises:

DependencyNotInstalled – If matplotlib is not installed

callback(obs_t: ObsType, obs_tp1: ObsType, action: ActType, rew: float, terminated: bool, truncated: bool, info: dict)#

The callback that calls the provided data callback and adds the data to the plots.

Parameters:

  • obs_t – The observation at time step t

  • obs_tp1 – The observation at time step t+1

  • action – The action

  • rew – The reward

  • terminated – If the environment is terminated

  • truncated – If the environment is truncated

  • info – The information from the environment

class gymnasium.utils.play.PlayableGame(env: Env, keys_to_action: Optional[Dict[Tuple[int, ...], int]] = None, zoom: Optional[float] = None)#

Wraps an environment allowing keyboard inputs to interact with the environment.

Wraps an environment with a dictionary of keyboard buttons to action and if to zoom in on the environment.

Parameters:

  • env – The environment to play

  • keys_to_action – The dictionary of keyboard tuples and action value

  • zoom – If to zoom in on the environment render

process_event(event: Event)#

Processes a PyGame event.

In particular, this function is used to keep track of which buttons are currently pressed and to exit the play() function when the PyGame window is closed.

Parameters:

event – The event to process

Save Rendering Videos#

gymnasium.utils.save_video.save_video(frames: list, video_folder: str, episode_trigger: Optional[Callable[[int], bool]] = None, step_trigger: Optional[Callable[[int], bool]] = None, video_length: Optional[int] = None, name_prefix: str = 'rl-video', episode_index: int = 0, step_starting_index: int = 0, **kwargs)#

Save videos from rendering frames.

This function extract video from a list of render frame episodes.

Parameters:

  • frames (List[RenderFrame]) – A list of frames to compose the video.

  • video_folder (str) – The folder where the recordings will be stored

  • episode_trigger – Function that accepts an integer and returns True iff a recording should be started at this episode

  • step_trigger – Function that accepts an integer and returns True iff a recording should be started at this step

  • video_length (int) – The length of recorded episodes. If it isn’t specified, the entire episode is recorded. Otherwise, snippets of the specified length are captured.

  • name_prefix (str) – Will be prepended to the filename of the recordings.

  • episode_index (int) – The index of the current episode.

  • step_starting_index (int) – The step index of the first frame.

  • **kwargs – The kwargs that will be passed to moviepy’s ImageSequenceClip. You need to specify either fps or duration.

Example

>>> import gymnasium as gym
>>> from gymnasium.utils.save_video import save_video
>>> env = gym.make("FrozenLake-v1", render_mode="rgb_array_list")
>>> env.reset()
>>> step_starting_index = 0
>>> episode_index = 0
>>> for step_index in range(199):
...    action = env.action_space.sample()
...    _, _, terminated, truncated, _ = env.step(action)
...
...    if terminated or truncated:
...       save_video(
...          env.render(),
...          "videos",
...          fps=env.metadata["render_fps"],
...          step_starting_index=step_starting_index,
...          episode_index=episode_index
...       )
...       step_starting_index = step_index + 1
...       episode_index += 1
...       env.reset()
>>> env.close()
gymnasium.utils.save_video.capped_cubic_video_schedule(episode_id: int) → bool#

The default episode trigger.

This function will trigger recordings at the episode indices 0, 1, 4, 8, 27, …, \(k^3\), …, 729, 1000, 2000, 3000, …

Parameters:

episode_id – The episode number

Returns:

If to apply a video schedule number

Old to New Step API Compatibility#

gymnasium.utils.step_api_compatibility.step_api_compatibility(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]], output_truncation_bool: bool = True, is_vector_env: bool = False) → Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]]#

Function to transform step returns to the API specified by output_truncation_bool bool.

Done (old) step API refers to step() method returning (observation, reward, done, info) Terminated Truncated (new) step API refers to step() method returning (observation, reward, terminated, truncated, info) (Refer to docs for details on the API change)

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • output_truncation_bool (bool) – Whether the output should return two booleans (new API) or one (old) (True by default)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

Returns:

step_returns (tuple) – Depending on output_truncation_bool bool, it can return (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

Examples

This function can be used to ensure compatibility in step interfaces with conflicting API. Eg. if env is written in old API,

wrapper is written in new API, and the final step output is desired to be in old API.

>>> import gymnasium as gym
>>> env = gym.make("OldEnv")
>>> obs, rew, done, info = step_api_compatibility(env.step(action), output_truncation_bool=False)
>>> obs, rew, terminated, truncated, info = step_api_compatibility(env.step(action), output_truncation_bool=True)

>>> vec_env = gym.vector.make("OldEnv")
>>> observations, rewards, dones, infos = step_api_compatibility(vec_env.step(action), is_vector_env=True)
gymnasium.utils.step_api_compatibility.convert_to_terminated_truncated_step_api(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]]], is_vector_env=False) → Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]]#

Function to transform step returns to new step API irrespective of input API.

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

gymnasium.utils.step_api_compatibility.convert_to_done_step_api(step_returns: Union[Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[bool, ndarray], Union[dict, list]], Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]], is_vector_env: bool = False) → Tuple[Union[ObsType, ndarray], Union[float, ndarray], Union[bool, ndarray], Union[dict, list]]#

Function to transform step returns to old step API irrespective of input API.

Parameters:

  • step_returns (tuple) – Items returned by step(). Can be (obs, rew, done, info) or (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – Whether the step_returns are from a vector environment

Seeding#

gymnasium.utils.seeding.np_random(seed: Optional[int] = None) → Tuple[Generator, Any]#

Generates a random number generator from the seed and returns the Generator and seed.

Parameters:

seed – The seed used to create the generator

Returns:

The generator and resulting seed

Raises:

Error – Seed must be a non-negative integer or omitted

Environment Checking#

gymnasium.utils.env_checker.check_env(env: Env, warn: Optional[bool] = None, skip_render_check: bool = False)#

Check that an environment follows Gym API.

This is an invasive function that calls the environment’s reset and step.

This is particularly useful when using a custom environment. Please take a look at https://gymnasium.farama.org/content/environment_creation/ for more information about the API.

Parameters:

  • env – The Gym environment that will be checked

  • warn – Ignored

  • skip_render_check – Whether to skip the checks for the render method. True by default (useful for the CI)