Atari Environments#

Arcade Learning Environment (ALE)#

ALE is a collection of 50+ Atari 2600 games powered by the Stella emulator.

Shimmy provides compatibility wrappers to convert all ALE environments to Gymnasium.

For reference information and a complete list of environments, see Gymnasium Atari.

Note: PettingZoo also provides 20+ multi-agent Atari environments: PettingZoo Atari

Installation#

To install shimmy and required dependencies:

pip install shimmy[atari]

We also provide a Dockerfile for reproducibility and cross-platform compatibility:

curl https://raw.githubusercontent.com/Farama-Foundation/Shimmy/main/bin/atari.Dockerfile | docker build -t atari -f - . && docker run -it atari

Usage#

Load an ALE environment:

import gymnasium as gym

env = gym.make("ALE/Pong-v5", render_mode="human")

Run the environment:

observation, info = env.reset(seed=42)
for _ in range(1000):
   action = env.action_space.sample()  # 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()

To get a list of all available atari environments (208 total):

from gymnasium.envs.registration import registry
ATARI_ENV_IDS = [
    env_id
    for env_id in registry
    if env_id.startswith("ALE") and env_id != "atari/compatibility-env-v0"
]
print(ATARI_ENV_IDS)

Class Description#

class shimmy.atari_env.AtariEnv(game: str = 'pong', mode: int | None = None, difficulty: int | None = None, obs_type: str = 'rgb', frameskip: tuple[int, int] | int = 4, repeat_action_probability: float = 0.25, full_action_space: bool = False, max_num_frames_per_episode: int | None = None, render_mode: str | None = None)[source]#

(A)rcade (L)earning (Gymnasium) (Env)ironment.

A Gymnasium wrapper around the Arcade Learning Environment (ALE).

Initialize the ALE interface for Gymnasium.

Default parameters are taken from Machado et al., 2018.

Parameters:

game – str => Game to initialize env with.
mode – Optional[int] => Game mode, see Machado et al., 2018
difficulty – Optional[int] => Game difficulty,see Machado et al., 2018
obs_type – str => Observation type in { ‘rgb’, ‘grayscale’, ‘ram’ }
frameskip – Union[Tuple[int, int], int] => Stochastic frameskip as tuple or fixed.
repeat_action_probability – int => Probability to repeat actions, see Machado et al., 2018
full_action_space – bool => Use full action space?
max_num_frames_per_episode – int => Max number of frame per episode. Once max_num_frames_per_episode is reached the episode is truncated.
render_mode – str => One of { ‘human’, ‘rgb_array’ }. If human we’ll interactively display the screen and enable game sounds. This will lock emulation to the ROMs specified FPS If rgb_array we’ll return the rgb key in step metadata with the current environment RGB frame.

Note

The game must be installed, see ale-import-roms, or ale-py-roms.
Frameskip values of (low, high) will enable stochastic frame skip which will sample a random frameskip uniformly each action.
It is recommended to enable full action space. See Machado et al., 2018 for more details.

References

Revisiting the Arcade Learning Environment: Evaluation Protocols and Open Problems for General Agents, Machado et al., 2018, JAIR URL: https://jair.org/index.php/jair/article/view/11182

metadata: dict[str, Any] = {'obs_types': {'grayscale', 'ram', 'rgb'}, 'render_modes': ['human', 'rgb_array']}#

action_space: spaces.Space[ActType]#

observation_space: spaces.Space[ObsType]#

seed(seed: int | None = None) → tuple[int, int][source]#

Seeds both the internal numpy rng for stochastic frame skip and the ALE RNG.

This function must also initialize the ROM and set the corresponding mode and difficulty. seed may be called to initialize the environment during deserialization by Gymnasium so these side-effects must reside here.

Parameters:: seed – int => Manually set the seed for RNG.
Returns:: tuple[int, int] => (np seed, ALE seed)

reset(*, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[np.ndarray, AtariEnvStepMetadata][source]#

Resets environment and returns initial observation.

Parameters:

seed – The reset seed
options – The reset options

Returns:

The reset observation and info

step(action_ind: int) → tuple[ndarray, float, bool, bool, AtariEnvStepMetadata][source]#

Perform one agent step, i.e., repeats action frameskip # of steps.

Parameters:: action_ind – int => Action index to execute
Returns:: Tuple[np.ndarray, float, bool, Dict[str, Any]] => observation, reward, terminal, metadata

Note: metadata contains the keys “lives” and “rgb” if render_mode == ‘rgb_array’.

render() → Any[source]#

Renders the ALE environment.

Returns:: If render_mode is “rgb_array”, returns the screen RGB view.

get_keys_to_action() → dict[tuple[int], Action][source]#

Return keymapping -> actions for human play.

Returns:: A dictionary of keys to actions.

get_action_meanings() → list[str][source]#

Return the meaning of each integer action.

Returns:: A list of action meaning

clone_state(include_rng: bool = False) → ALEState[source]#

Clone emulator state w/o system state.

Restoring this state will not give an identical environment. For complete cloning and restoring of the full state, see {clone,restore}_full_state().

Parameters:: include_rng – If to include the rng in the cloned state
Returns:: The cloned state

restore_state(state: ALEState)[source]#

Restore emulator state w/o system state.

Parameters:: state – The state to restore

clone_full_state() → ALEState[source]#: Deprecated method which would clone the emulator and system state.

restore_full_state(state: ALEState)[source]#: Restore emulator state w/ system state including pseudo-randomness.