Arcade Learning Environment (ale-py)

Common errors

Warnings

Install

Imports

• ALEInterface
  wrong

  from ale_py._ale_py import ALEInterface

  correct

  from ale_py import ALEInterface

  The internal _ale_py module should not be directly imported.

• roms
  wrong

  import ale_py.roms

  correct

  from ale_py import roms

  While 'import ale_py.roms' works, 'from ale_py import roms' is more direct for accessing ROM paths.

• register_envs (Gymnasium)
  wrong

  import gymnasium as gym
  env = gym.make('ALE/Breakout-v5')

  correct

  import gymnasium as gym
  import ale_py
  gym.register_envs(ale_py)

  Gymnasium environments need explicit registration via `ale_py` before `gym.make` can find them.

Quickstart

This quickstart demonstrates both the direct Python interface of ALEInterface to interact with Atari games and its integration with the Gymnasium API. It shows how to load a ROM (now included in the package), reset the game, take an action, and retrieve observations. The Gymnasium example highlights environment registration and interaction.

import gymnasium as gym
import ale_py
from ale_py import ALEInterface, roms

# --- Direct ALEInterface usage ---
ale = ALEInterface()
# ROMs are now packaged within ale-py, access via roms.get_rom_path
ale.loadROM(roms.get_rom_path("breakout"))
ale.reset_game()
reward = ale.act(0) # Perform a 'noop' action
screen_obs = ale.getScreenRGB()
print(f"Direct ALE: Initial reward: {reward}, Screen shape: {screen_obs.shape}")
ale.close()

# --- Gymnasium integration ---
# Register ALE environments with Gymnasium
gym.register_envs(ale_py)

env = gym.make('ALE/Breakout-v5', render_mode='rgb_array')
obs, info = env.reset()
print(f"Gymnasium: Initial observation shape: {obs.shape}")

action = env.action_space.sample() # Take a random action
obs, reward, terminated, truncated, info = env.step(action)
print(f"Gymnasium: Step reward: {reward}, Terminated: {terminated}, Truncated: {truncated}")

env.close()