ALE v0.12.0

This release modernises ALE's build and binding infrastructure, broadens platform support (including running ALE in the browser via WebAssembly), extends the XLA vectoriser to GPUs, and continues to optimise the C++ AtariVectorEnv.

Bug Fixes and deprecations

For users using continuous actions, these have been fixed to accurately map both axes correctly, as previously moving down-left would incorrectly take the wrong action (see #638 by @markub3327 for more details). Additionally, python 3.9 and macos x86_64 have been deprecated in favor of python 3.14 and macos arm64.

Build system, bindings and AtariVectorEnv

• Migrate to scikit-build-core by @pseudo-rnd-thoughts (#644). This replaces the large, hard-to-maintain setup.py with the modern scikit-build-core backend, simplifying configuration and making cross-compilation (and Windows builds) considerably easier.
• Switch from pybind11 to nanobind by @pseudo-rnd-thoughts (#646). nanobind is a more modern C++↔Python binding library that produces smaller wheels with lower memory footprint and overhead.
• Add WebAssembly support by @pseudo-rnd-thoughts (#655). ALE can now be compiled to WASM and distributed as an NPM package / standalone bundle, allowing demos to run directly in the browser without a Python install. An example website is included in docs/wasm/example.
• Add XLA GPU support by @pseudo-rnd-thoughts (#648). The XLA VectorEnv integration, previously CPU-only, now also runs on GPU for accelerated batched environment execution. Note: GPU XLA requires NumPy 2.X.
• Minimise data copies in the vectoriser by @pseudo-rnd-thoughts (#652). Reduces observation copies from three down to one (the theoretical minimum) by writing preprocessed observations directly into the output array and, on autoreset, only updating the sub-environments whose episode ended. Memory transfer was the largest bottleneck in the vectoriser. Note: we are still exploring how to optimise the vectoriser's throughput as significant further gains are believed possible.

Full Changelog: v0.11.2...v0.12.0

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.