v2.1.0: Extending Game Support

🚀 New Features

• Expanded Game Support
  • Added new Atari games to the OC_Atari framework, increasing the variety of available environments.
  • These additions enhance the framework's applicability for research and experimentation.

New/Improved Game Support For:

• Alien
• Pitfall
• Pitfall2
• Atlantis
• Pooyan
• AirRaid
• Kangaroo
• DemonAttack
• RiverRaid
• Seaquest
• Frostbite

🔄 Additional Changes

• No modifications to the core logic or object-centric representation.
• All existing functionalities remain unchanged.

🛠️ Developer Notes

• The newly added games are seamlessly integrated and ready for use.
• No API changes in this update.

---

This release focuses solely on expanding game support while maintaining stability and compatibility with previous versions.
Full Changelog: v2.0.0...v2.1.0

v2.0.0

🚀 Release Notes: Object-centric State Representation 2.0

🔑 Key Highlights

• Enhanced Modularity:

  • Transitioned to a modular design for object-centric state representation, enabling better scalability, flexibility, and maintainability.
  • Objects can now hold custom attributes like orientation or additional features beyond default properties (x_pos, y_pos, width, height).
  • The outdated "plane representation" is removed by time, enabling objects to adapt individually with richer representations.

• Improved Continuity in Object List Management:

  • Resolved the issue of "cascading objects", where positions of objects shifted in the list when new objects appeared or existing ones disappeared.
  • Object behavior is now consistent, ensuring a robust and reliable input representation for learning.

---

🛠 User Impact

• New State Shapes:
  • The object-centric state now introduces new shapes per game, requiring retraining of old models.
• Partial Update:
  • Some games still use the old representation. The list of updated games can be found in the README.
• Default Object Representation:
  • The new default includes only x_pos and y_pos. width and height are no longer included by default.
• Available in Vision and RAM Mode:
  • Object-centric state representation now supports both vision and RAM modes.

---

💻 Developer Updates

• Method Deprecations:
  • The get_object_state method is deprecated and replaced with self.ns_state.
  • Observations now save the whole state buffer instead of a single state observation. For this we added a new state buffer system.
  • Use get_object_state_size to access the object state size.
• Enhanced GameObject Representation:
  • New properties for GameObject: _nsrepr, _ns_meaning, _nslen, etc.
  • Instead of None, we now add NoObject objects to mark empty slots.
  • Developers can extend object state with additional features (e.g., orientation in Skiing).

---

🔄 Actions Required

1. Retrain models to accommodate the new object-centric state representation.
2. Replace usage of get_object_state with the default obs.
3. Replace specific step functions with the default step function
4. Refer to the updated README for a list of supported games.

---

Next Steps

• Support more games in the new Representation 2.0
• Add more games in general

This release marks a significant step towards a more modular, scalable, and robust object-centric state representation, improving flexibility for both users and developers.

Full Changelog: v0.1.0...v2.0.0

2024.01 Bring Object Centricity to the Atari Learning Environment

OCAtari v0.1.0

Inspired by the work of Anand et. al., we present OCAtari, an improved, extended and object-centric version of their ATARI ARI project.

OCAtari provides for over 40 Atari environemnts with extended object centric state representations and still counting.

Installation

Simply install ocatari by using pip install ocatari and pip install "gymnasium[atari, accept-rom-license]". As an alternative you can clone this repo and run: python setup.py install or if you want to modify the code python setup.py develop

Features

• Vision Extraction Mode (VEM): Return a list of objects currently on the screen with their X, Y, Width, Height, R, G, B Values, based on handwritten rules used on the visual representation.
• Ram Extraction Mode (REM): Uses the object values stored in the RAM to detect the objects currently on the screen.
• Gym wrapper: We provide an easy to use wrapper for gymnasium, making the adaptation of already existing code a simple as possible.
• Producing your own dataset: OCAtari can be used to generate datasets consisting of a representation of the current state in form of an RGB array and a list of all objects within the state.
• Scripts to look inside OCAtari: We provide a huge amount of scripts to help and test while implementing, extending or using OCAtari. Most are used to reverse engineer the RAM state, like searching for correlations within the RAM state.

Models and additional Information

• We do not provide any trained models yet. However, to test our framework we recommend to use the following models to start with: Atari-Agents.
• It is also possible to train own models, by e.g., using CleanRL

Usage

A basic example how to use our OCAtari environments:

from ocatari.core import OCAtari
import random

env = OCAtari("Pong", mode="ram", hud=True, render_mode="rgb_array")
observation, info = env.reset()
action = random.randint(env.nb_actions-1)
obs, reward, terminated, truncated, info = env.step(action)