ALE v0.11.2

• Fix audio and rendering for Windows and Linux by @unexploredtest (#628)

Optimise AtariVectorEnv

• Optimising frame stack with contiguous memory by @pseudo-rnd-thoughts (#618)
• Optimise StateBufferQueue to use Semaphore not mutexes by @pseudo-rnd-thoughts (#619)

Full Changelog: v0.11.1...v0.11.2

ALE v0.11.1

In v0.11.0, AtariVectorEnv was added, providing a C++ based vectorizer as an experimental feature.
This release fills out the implementation with many, many bug fixes and adds a couple of features.

See the documentation for using the vector environment and parameters - https://ale.farama.org/vector-environment/

Bug fixes for AtariVectorEnv

• Vector environment wouldn't seed correctly if equal to 0 (#603)
• Fix the vector continuous action implementations (#607)
• Terminate an episode if episodic_life is enabled (#611)
• Correctly end frame skips (#613)
• For async mode ensure that only the batch size number of results are returned (#612)

Features added to AtariVectorEnv

• Add RGB obs support (#606)
• Parametrize testing for each ROMs (#615)
• Add same-step autoreset mode (#614)
• Add XLA support - experimental feature (#604)

Other changes

• Remove environment IDs for Deterministic and RAM (#561)
• Change get_keys_to_action from dict[ale_py.Action, tuple[int, ...] to dict[str, tuple[int, ...]] (#608)
• Add Linux ARM64 wheels (#609)

Full Changelog: v0.11.0...v0.11.1

ALE v0.11.0

This release adds (an experiment) built-in vectorisation environment, available through gymnasium.make_vec("ALE/{game_name}-v5", num_envs) or ale_py.AtariVectorEnv("{rom_name}", num_envs).

import gymnasium as gym
import ale_py

gym.register_envs(ale_py)

envs = gym.make_vec("ALE/Pong-v5")
observations, infos = envs.reset()

for i in range(100):
  actions = envs.action_space.sample()
  observations, rewards, terminations, truncations, infos = envs.step(actions)

envs.close()

Vectorisation is a crucial feature of RL to help increase the sample rate of environments through sampling multiple sub-environments at the same time.
Gymnasium provides a generalised vectorisation capability, however, is relatively slow due its python implementation.
For faster implementations, EnvPool provide C++ vectorisation that significantly increase the sample speed but it no longer maintained.
Inspired by the EnvPool implementation, we've implemented an asynchronous vectorisation environment in C++, in particular, the standard Atari preprocessing including frame skipping, frame stacking, observation resizing, etc.

For full documentation of the vector environment, see this page.

We will continue building out this vectorisation to include XLA support, improved preprocessing and auto resetting.

As this is an experimental feature, we wish to hear about any bugs, problems or features to add. Raise an issue on GitHub or ask a question on the Farama Discord server.

ALE v0.10.2

Fixed performance regression for CPP users

A single-argument act function was missing, causing the paddle_strength introduced in v0.10.0 to default to zero rather than one. As Gymnasium passed this variable to act, this was only an issue for users directly interacting with ale_interface. For more details, see #595.

ALE v0.10.1

Revert change to requirements that numpy < 2.0, now numpy > 1.20 and add support for building from source distribution, tar.gz (though not recommended).

ALE v0.10.0

In v0.10, ALE now has its own dedicated website, https://ale.farama.org/ with Atari's documentation being moved from Gymnasium.

We have moved the project main code from src into src/ale to help incorporate ALE into C++ projects and in the Python API, we have updated get_keys_to_action to work with gymnasium.utils.play by changing the key for no-op from None to the e key.

Furthermore, we have updated the API to support continuous actions by @jjshoots and @psc-g, see https://arxiv.org/pdf/2410.23810 for the impact.

Previously, users could interact with the ALE interface with only discrete actions linked to joystick controls, ie:

• All left actions (LEFTDOWN, LEFTUP, LEFT...) -> paddle left max
• All right actions (RIGHTDOWN, RIGHTUP, RIGHT...) -> paddle right max
• Up... etc.
• Down... etc.

However, for games using paddles, this loses the ability to specify non-max values for moving left or right. Therefore, this release adds to both the Python and C++ interfaces the ability to use continuous actions (FYI, this only impacts environments with paddles, otherwise they can't make use of this change).

C++ interface changes

Old Discrete ALE interface

reward_t ALEInterface::act(Action action)

New Mixed Discrete-Continuous ALE interface

reward_t ALEInterface::act(Action action, float paddle_strength = 1.0)

Games where the paddle is not used simply have the paddle_strength parameter ignored.
This mirrors the real-world scenario where you have a paddle connected, but the game doesn't react to it when the paddle is turned.
This maintains backwards compatibility.

Python interface changes

Old Discrete ALE Python Interface

ale.act(action: int)

New Mixed Discrete-Continuous ALE Python Interface

ale.act(action: int, strength: float = 1.0)

The continuous action space is implemented at the Python level within the Gymnasium environment.

if continuous:
    # action is expected to be a [2,] array of floats
    x, y = action[0] * np.cos(action[1]), action[0] * np.sin(action[1])
    action_idx = self.map_action_idx(
        left_center_right=(
            -int(x < self.continuous_action_threshold)
            + int(x > self.continuous_action_threshold)
        ),
        down_center_up=(
            -int(y < self.continuous_action_threshold)
            + int(y > self.continuous_action_threshold)
        ),
        fire=(action[-1] > self.continuous_action_threshold),
    )
    ale.act(action_idx, action[1])

Full Changelog: v0.9.1...v0.10.0

ALE v0.9.1

This release adds support for NumPy 2.0 by updating the PyBind 11 version to 2.13.1 used to compile the wheels, see #535 for the changes.

We have added support for users to use their own PyBind version if already installed when compiling

Full Changelog: v0.9.0...v0.9.1

ALE v0.9.0

Previously, ALE implemented only a Gym based environment, however, as Gym is no longer maintained (the last commit was 18 months ago). We have updated ale-py to use Gymnasium >= 1.0.0a1 (a maintained fork of Gym) as the sole backend environment implementation. For more information on Gymnasium’s API, see their introduction page.

import gymnasium as gym
import ale_py

gym.register_envs(ale_py)  # unnecessary but prevents IDEs from complaining

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

obs, info = env.reset()
episode_over = False
while not episode_over:
	action = policy(obs)  # replace with actual policy
	obs, reward, terminated, truncated, info = env.step(action)
	episode_over = terminated or truncated
env.close()

An important change in this update is that the Atari ROMs are packaged within the PyPI installation such that users no longer require pip install "gym[accept-rom-license]" (AutoROM) or ale-import-roms for downloading or loading ROMs. This should significantly simplify installing Atari for users. For users who wish to load ROMs from an alternative folder, use the ALE_ROM_DIR system environment variable to specify a folder directory.

Importantly, Gymnasium 1.0.0 removes a registration plugin system that ale-py utilises where atari environments would be registered behind the scenes. As a result, projects will need to import ale_py, to register all the atari environments, before an atari environment can be created with gymnasium.make. We understand this will cause annoyance to some users, however, the previous method brought significant complexity behind the scenes that the development team believed caused more issues than help.

Other changes

• Added Python 3.12 support.
• Replace interactive exit by sys.exit (#498)
• Fix C++ documentation example links(#501)
• Add support for gcc 13 (#503)
• Unpin cmake dependency and remove wheel from build system (#493)
• Add missing imports for cstdint (#486)
• Allow installing without git (#492)
• Update to require importlib-resources for < 3.9 (#491)

Full Changelog: v0.8.1...v0.9.0

Arcade Learning Environment 0.8.1

Added

• Added type stubs for the native ALE Python module generated via pybind11. You'll now get type hints in your IDE.

Fixed

• Fixed render_mode attribute on legacy Gym environment (@younik)
• Fixed a bug which could parse invalid ROM names containing numbers, e.g., TicTacToe3D or Pitfall2
• Changed the ROM identifier of VideoChess & VideoCube to match VideoCheckers & VideoPinball.
  Specifically, the environment ID changed from Videochess -> VideoChess and Videocube -> VideoCube.
  Most ROMs had the ID correctly as video_chess.bin and video_cube.bin but for those who didn't you can
  simply run ale-import-roms which will automatically correct this for you.
• Reverted back to manylinux2014 (glibc 2.17) to better support older operating systems.

Arcade Learning Environment 0.8.0

Added

• Added compliance with the Gym v26 API. This includes multiple breaking changes to the Gym API. See the Gym release for additional information.
• Reworked the ROM plugin API resulting in reduced startup time when importing ale_py.roms.
• Added a truncation API to the ALE interface to query whether an episode was truncated or terminated (ale.game_over(with_truncation=true/false) and ale.game_truncated())
• Added proper Gym truncation on max episode frames. This no longer relies on the TimeLimit wrapper with the new truncation API in Gym v26.
• Added a setting for truncating on loss-of-life.
• Added a setting for clamping rewards.
• Added const keywords to attributes in ale::ALEInterface (#457) (@AlessioZanga).
• Added explicit exports via __all__ in ale-py so linting tools can better detect exports.
• Added builds for Python 3.11.

Fixed

• Moved the Gym environment entrypoint from gym.envs.atari:AtariEnv to ale_py.env.gym:AtariEnv. This resolves many issues with the namespace package but does break backwards compatability for some Gym code that relied on the entry point being prefixed with gym.envs.atari.