From 67d0c603c839ae50c85e80fc14b1a704f00c2887 Mon Sep 17 00:00:00 2001 From: Mark Towers Date: Thu, 9 May 2024 17:04:47 +1200 Subject: [PATCH] Update readme and changelog for v0.9.0 changes (#526) --- CHANGELOG.md | 35 ++++++++++++++++++++++++- README.md | 71 ++++++++++++++++++-------------------------------- pyproject.toml | 15 +++++++---- 3 files changed, 70 insertions(+), 51 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c2f8ceff7..4c1bd7fae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,40 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.9.0] - 2024-05-10 + +Previously, ALE implemented only a [Gym](https://github.com/openai/gym) based environment, however, as Gym is no longer maintained (last commit was 18 months ago). We have updated `ale-py` to use [Gymnasium](http://github.com/farama-Foundation/gymnasium) (a maintained fork of Gym) as the sole backend environment implementation. For more information on Gymnasium’s API, see their [introduction page](https://gymnasium.farama.org/main/introduction/basic_usage/). + +```python +import gymnasium as gym +import ale_py + +gym.register_envs(ale_py) # this is unnecessary but prevents IDE 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 AutoROM or `ale-import-roms` for downloading or loading ROMs. This should significantly simplify installing Atari for users. For users that 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 scene. 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`. For example, see below + +### Other changes +- Added Python 3.12 support. +- Replace interactive exit by sys.exit (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/498) +- Fix C++ documentation example links(https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/501) +- Add support for gcc 13 (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/503) +- Unpin cmake dependency and remove wheel from build system (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/493) +- Add missing imports for cstdint (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/486) +- Allow installing without git (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/492) +- Update to require `importlib-resources` for < 3.9 (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/491) ## [0.8.1] - 2023-02-17 diff --git a/README.md b/README.md index 5642baf60..da6afdfea 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,12 @@ The Arcade Learning Environment - Arcade Learning Environment + Arcade Learning Environment =============================== -[![Continuous Integration](https://github.com/mgbellemare/Arcade-Learning-Environment/actions/workflows/ci.yml/badge.svg)](https://github.com/mgbellemare/Arcade-Learning-Environment/actions/workflows/ci.yml) +[![Python](https://img.shields.io/pypi/pyversions/ale-py.svg)](https://badge.fury.io/py/ale-py) [![PyPI Version](https://img.shields.io/pypi/v/ale-py)](https://pypi.org/project/ale-py) - **The Arcade Learning Environment (ALE) is a simple framework that allows researchers and hobbyists to develop AI agents for Atari 2600 games.** It is built on top of the Atari 2600 emulator [Stella](https://stella-emu.github.io) and separates the details of emulation from agent design. This [video](https://www.youtube.com/watch?v=nzUiEkasXZI) depicts over 50 games currently supported in the ALE. @@ -19,20 +18,18 @@ Features -------- - Object-oriented framework with support to add agents and games. -- Emulation core uncoupled from rendering and sound generation modules for fast - emulation with minimal library dependencies. -- Automatic extraction of game score and end-of-game signal for more than 100 - Atari 2600 games. +- Emulation core uncoupled from rendering and sound generation modules for fast emulation with minimal library dependencies. +- Automatic extraction of game score and end-of-game signal for more than 100 Atari 2600 games. - Multi-platform code (compiled and tested under macOS, Windows, and several Linux distributions). - Python bindings through [pybind11](https://github.com/pybind/pybind11). -- Native support for OpenAI Gym. +- Native support for [Gymnasium](http://github.com/farama-Foundation/gymnasium), a maintained fork of OpenAI Gym. - Visualization tools. +- Atari roms are packaged within the pip package Quick Start =========== -The ALE currently supports three different interfaces: C++, Python, and OpenAI Gym. - +The ALE currently supports three different interfaces: C++, Python, and Gymnasium. Python ------ @@ -42,55 +39,39 @@ You simply need to install the `ale-py` package distributed via PyPI: ```shell pip install ale-py ``` -Note: Make sure you're using an up to date version of `pip` or the install may fail. - +Note: Make sure you're using an up-to-date version of `pip` or the installation may fail. -You can now import the ALE in your Python projects with +You can now import the ALE in your Python projects with providing a direct interface to Stella for interacting with games ```python from ale_py import ALEInterface ale = ALEInterface() -``` - -### ROM Management - -The ALE doesn't distribute ROMs but we do provide a couple tools for managing your ROMs. First is the command line tool `ale-import-roms`. You can simply specify a directory as the first argument to this tool and we'll import all supported ROMs by the ALE. - -```shell -ale-import-roms roms/ - -[SUPPORTED] breakout roms/breakout.bin -[SUPPORTED] freeway roms/freeway.bin +ale.loadROM("Breakout") +ale.reset_game() -[NOT SUPPORTED] roms/custom.bin - -Imported 2/3 ROMs -``` -Furthermore, Python packages can expose ROMs for discovery using the special `ale-py.roms` entry point. For more details check out the example [python-rom-package](./examples/python-rom-package). - -Once you've imported a supported ROM you can simply import the path from the `ale-py.roms` package and load the ROM in the ALE: -```py -from ale_py.roms import Breakout - -ale.loadROM(Breakout) +reward = ale.act(0) # noop +screen_obs = ale.getScreenRGB() ``` -## OpenAI Gym - -Gym support is included in `ale-py`. Simply install the Python package using the instructions above. You can also install `gym[atari]` which also installs `ale-py` with Gym. +## Gymnasium -As of Gym v0.20 and onwards all Atari environments are provided via `ale-py`. We do recommend using the new `v5` environments in the `ALE` namespace: +For simplicity for installing ale-py with Gymnasium, `pip install "gymnasium[atari]"` shall install all necessary modules and ROMs. See Gymnasium [introductory page](https://gymnasium.farama.org/main/introduction/basic_usage/) for description of the API to interface with the environment. ```py -import gym +import gymnasium as gym -env = gym.make('ALE/Breakout-v5') -``` -The `v5` environments follow the latest methodology set out in [Revisiting the Arcade Learning Environment by Machado et al.](https://jair.org/index.php/jair/article/view/11182). +env = gym.make('ALE/Breakout-v5', render_mode="human") # remove render_mode in training +obs, info = env.reset() +episode_over = False +while not episode_over: + action = policy(obs) # to implement - use `env.action_space.sample()` for a random policy + obs, reward, terminated, truncated, info = env.step(action) -The only major change difference from Gym's `AtariEnv` is that we'd recommend not using the `env.render()` method in favour of supplying the `render_mode` keyword argument during environment initialization. The `human` render mode will give you the advantage of: frame perfect rendering, audio support, and proper resolution scaling. For more information check out [docs/gym-interface.md](./docs/gym-interface.md). + episode_over = terminated or truncated +env.close() +``` -For more information on changes to the Atari environments in OpenAI Gym please check out [the following blog post](https://brosa.ca/blog/ale-release-v0.7). +For all the environments available and their description, see [gymnasium atari page](https://gymnasium.farama.org/environments/atari/). C++ --- diff --git a/pyproject.toml b/pyproject.toml index 7d1b9c2b0..bd8dd0d0a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,6 +20,7 @@ authors = [ {name = "Michael Bowling"}, ] maintainers = [ + { name = "Farama Foundation", email = "contact@farama.org" }, {name = "Jesse Farebrother", email = "jfarebro@cs.mcgill.ca"}, ] classifiers = [ @@ -27,7 +28,11 @@ classifiers = [ "Intended Audience :: Science/Research", "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", "Topic :: Scientific/Engineering", "Topic :: Scientific/Engineering :: Artificial Intelligence", ] @@ -42,13 +47,13 @@ dynamic = ["version"] [project.optional-dependencies] test = [ "pytest>=7.0", - "gymnasium==1.0.0a1", + "gymnasium>=1.0.0a1", ] [project.urls] -homepage = "https://github.com/mgbellemare/Arcade-Learning-Environment" -documentation = "https://github.com/mgbellemare/Arcade-Learning-Environment/tree/master/docs" -changelog = "https://github.com/mgbellemare/Arcade-Learning-Environment/blob/master/CHANGELOG.md" +homepage = "https://github.com/Farama-Foundation/Arcade-Learning-Environment" +documentation = "https://github.com/Farama-Foundation/Arcade-Learning-Environment/tree/master/docs" +changelog = "https://github.com/Farama-Foundation/Arcade-Learning-Environment/blob/master/CHANGELOG.md" [tool.setuptools] packages = [