Apppublic

openenv/atari_env

sourceHugging Faceupdated 6mo agoView on Hugging Face

3likes

App README

Hugging Face Space Deployment

This Space is built from OpenEnv environment atari_env.

—Space URL: https://huggingface.co/spaces/openenv/atari_env
—OpenEnv pinned ref: 0.2.3
—Hub tag: openenv

Connecting from Code

python

from envs.atari_env import AtariEnv

env = AtariEnv(base_url="https://huggingface.co/spaces/openenv/atari_env")

Atari Environment

Integration of Atari 2600 games with the OpenEnv framework via the Arcade Learning Environment (ALE). ALE provides access to 100+ classic Atari games for RL research.

Supported Games

ALE supports 100+ Atari 2600 games including:

Popular Games

—Pong - Classic two-player tennis
—Breakout - Break bricks with a ball
—Space Invaders - Shoot descending aliens
—Pac-Man / Ms. Pac-Man - Navigate mazes and eat pellets
—Asteroids - Destroy asteroids in space
—Defender - Side-scrolling space shooter
—Centipede - Shoot segmented centipede
—Donkey Kong - Jump over barrels to save princess
—Frogger - Cross road and river safely
—*Qbert** - Jump on pyramid cubes

And many more! For a complete list, see ALE documentation.

Architecture

┌────────────────────────────────────┐
│ RL Training Code (Client)          │
│   AtariEnv.step(action)            │
└──────────────┬─────────────────────┘
               │ HTTP
┌──────────────▼─────────────────────┐
│ FastAPI Server (Docker)            │
│   AtariEnvironment                 │
│     ├─ Wraps ALEInterface          │
│     ├─ Handles observations        │
│     └─ Action execution            │
└────────────────────────────────────┘

Installation & Usage

Option 1: Local Development (without Docker)

Requirements:

—Python 3.11+
—ale-py installed: pip install ale-py

The client is async by default:

python

import asyncio
from atari_env import AtariEnv, AtariAction

async def main():
    # Start local server manually: python -m atari_env.server.app
    async with AtariEnv(base_url="http://localhost:8000") as env:
        # Reset environment
        result = await env.reset()
        print(f"Screen shape: {result.observation.screen_shape}")
        print(f"Legal actions: {result.observation.legal_actions}")

        # Take actions
        for _ in range(10):
            result = await env.step(AtariAction(action_id=2, game_name="pong"))
            print(f"Reward: {result.reward}, Done: {result.done}")
            if result.done:
                break

asyncio.run(main())

For synchronous usage, use the .sync() wrapper:

python

from atari_env import AtariEnv, AtariAction

with AtariEnv(base_url="http://localhost:8000").sync() as env:
    result = env.reset()
    result = env.step(AtariAction(action_id=2, game_name="pong"))
    print(f"Reward: {result.reward}")

Option 2: Docker (Recommended)

Build Atari image:

bash

cd OpenEnv

# Build the image
docker build \
  -f envs/atari_env/server/Dockerfile \
  -t atari-env:latest \
  .

Run specific games:

bash

# Pong (default)
docker run -p 8000:8000 atari-env:latest

# Breakout
docker run -p 8000:8000 -e ATARI_GAME=breakout atari-env:latest

# Space Invaders with grayscale observation
docker run -p 8000:8000 \
  -e ATARI_GAME=space_invaders \
  -e ATARI_OBS_TYPE=grayscale \
  atari-env:latest

# Ms. Pac-Man with full action space
docker run -p 8000:8000 \
  -e ATARI_GAME=ms_pacman \
  -e ATARI_FULL_ACTION_SPACE=true \
  atari-env:latest

Use with from_docker_image():

python

import asyncio
import numpy as np
from atari_env import AtariEnv, AtariAction

async def main():
    # Automatically starts container
    client = await AtariEnv.from_docker_image("atari-env:latest")

    async with client:
        result = await client.reset()
        result = await client.step(AtariAction(action_id=2))  # UP

        # Reshape screen for visualization
        screen = np.array(result.observation.screen).reshape(result.observation.screen_shape)
        print(f"Screen shape: {screen.shape}")  # (210, 160, 3) for RGB

asyncio.run(main())

Observation Types

1. RGB (Default)

—Shape: [210, 160, 3]
—Description: Full-color screen observation
—Usage: Most realistic, good for vision-based learning

python

docker run -p 8000:8000 -e ATARI_OBS_TYPE=rgb atari-env:latest

2. Grayscale

—Shape: [210, 160]
—Description: Grayscale screen observation
—Usage: Reduced dimensionality, faster processing

python

docker run -p 8000:8000 -e ATARI_OBS_TYPE=grayscale atari-env:latest

3. RAM

—Shape: [128]
—Description: Raw 128-byte Atari 2600 RAM contents
—Usage: Compact representation, useful for specific research

python

docker run -p 8000:8000 -e ATARI_OBS_TYPE=ram atari-env:latest

Action Spaces

Minimal Action Set (Default)

Game-specific minimal actions (typically 4-9 actions).

—Pong: 6 actions (NOOP, FIRE, UP, DOWN, etc.)
—Breakout: 4 actions (NOOP, FIRE, LEFT, RIGHT)

python

docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=false atari-env:latest

Full Action Set

All 18 possible Atari 2600 actions:

1.NOOP
2.FIRE
3.UP
4.RIGHT
5.LEFT
6.DOWN
7.UPRIGHT
8.UPLEFT
9.DOWNRIGHT
10.DOWNLEFT
11.UPFIRE
12.RIGHTFIRE
13.LEFTFIRE
14.DOWNFIRE
15.UPRIGHTFIRE
16.UPLEFTFIRE
17.DOWNRIGHTFIRE
18.DOWNLEFTFIRE

python

docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=true atari-env:latest

Configuration

Environment Variables

—ATARI_GAME: Game name (default: "pong")
—ATARI_OBS_TYPE: Observation type - "rgb", "grayscale", "ram" (default: "rgb")
—ATARI_FULL_ACTION_SPACE: Use full action space - "true"/"false" (default: "false")
—ATARI_MODE: Game mode (optional, game-specific)
—ATARI_DIFFICULTY: Game difficulty (optional, game-specific)
—ATARI_REPEAT_ACTION_PROB: Sticky action probability 0.0-1.0 (default: "0.0")
—ATARI_FRAMESKIP: Frames to skip per action (default: "4")

Example: Breakout with Custom Settings

bash

docker run -p 8000:8000 \
  -e ATARI_GAME=breakout \
  -e ATARI_OBS_TYPE=grayscale \
  -e ATARI_FULL_ACTION_SPACE=true \
  -e ATARI_REPEAT_ACTION_PROB=0.25 \
  -e ATARI_FRAMESKIP=4 \
  atari-env:latest

API Reference

AtariAction

python

@dataclass
class AtariAction(Action):
    action_id: int                  # Action index to execute
    game_name: str = "pong"         # Game name
    obs_type: str = "rgb"           # Observation type
    full_action_space: bool = False # Full or minimal action space

AtariObservation

python

@dataclass
class AtariObservation(Observation):
    screen: List[int]               # Flattened screen pixels
    screen_shape: List[int]         # Original screen shape
    legal_actions: List[int]        # Legal action indices
    lives: int                      # Lives remaining
    episode_frame_number: int       # Frame # in episode
    frame_number: int               # Total frame #
    done: bool                      # Episode finished
    reward: Optional[float]         # Reward from last action

AtariState

python

@dataclass
class AtariState(State):
    episode_id: str                      # Unique episode ID
    step_count: int                      # Number of steps
    game_name: str                       # Game name
    obs_type: str                        # Observation type
    full_action_space: bool              # Action space type
    mode: Optional[int]                  # Game mode
    difficulty: Optional[int]            # Game difficulty
    repeat_action_probability: float     # Sticky action prob
    frameskip: int                       # Frameskip setting

Example Script

python

#!/usr/bin/env python3
"""Example training loop with Atari environment."""

import asyncio
import numpy as np
from atari_env import AtariEnv, AtariAction

async def train():
    # Start environment
    client = await AtariEnv.from_docker_image("atari-env:latest")

    async with client:
        # Training loop
        for episode in range(10):
            result = await client.reset()
            episode_reward = 0
            steps = 0

            while not result.done:
                # Random policy (replace with your RL agent)
                action_id = np.random.choice(result.observation.legal_actions)

                # Take action
                result = await client.step(AtariAction(action_id=action_id))

                episode_reward += result.reward or 0
                steps += 1

                # Reshape screen for processing
                screen = np.array(result.observation.screen).reshape(
                    result.observation.screen_shape
                )

                # Your RL training code here
                # ...

            print(f"Episode {episode}: reward={episode_reward:.2f}, steps={steps}")

asyncio.run(train())

Testing

Local Testing

bash

# Install dependencies
pip install ale-py fastapi uvicorn requests

# Start server
export PYTHONPATH=src:envs
python -m atari_env.server.app

# Test from another terminal (using sync wrapper for simplicity)
python -c "
from atari_env import AtariEnv, AtariAction
with AtariEnv(base_url='http://localhost:8000').sync() as env:
    result = env.reset()
    print(f'Initial obs: {result.observation.screen_shape}')
    result = env.step(AtariAction(action_id=2))
    print(f'After step: reward={result.reward}, done={result.done}')
"

Docker Testing

bash

# Build and run
docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
docker run -p 8000:8000 atari-env:latest

# Test in another terminal
curl http://localhost:8000/health
curl -X POST http://localhost:8000/reset

Popular Games and Their Characteristics

Game	Minimal Actions	Lives	Difficulty	Notes
Pong	6	1	Low	Good for learning basics
Breakout	4	5	Medium	Classic RL benchmark
Space Invaders	6	3	Medium	Shooting game
Ms. Pac-Man	9	3	High	Complex navigation
Asteroids	14	3	Medium	Continuous shooting
Montezuma's Revenge	18	5	Very High	Exploration challenge
Pitfall	18	1	High	Platformer
Seaquest	18	3	High	Submarine rescue

Limitations & Notes

—Frame perfect timing: Some games require precise timing
—Exploration: Games like Montezuma's Revenge are notoriously difficult
—Observation delay: HTTP adds minimal latency vs local gym
—Determinism: Set ATARI_REPEAT_ACTION_PROB=0.0 for deterministic behavior
—ROMs: All ROMs are bundled with ale-py package

References

Citation

If you use ALE in your research, please cite:

bibtex

@Article{bellemare13arcade,
    author = {{Bellemare}, M.~G. and {Naddaf}, Y. and {Veness}, J. and {Bowling}, M.},
    title = {The Arcade Learning Environment: An Evaluation Platform for General Agents},
    journal = {Journal of Artificial Intelligence Research},
    year = "2013",
    month = "jun",
    volume = "47",
    pages = "253--279",
}