openenv/atari_env
3
1---2title: Atari Environment Server3emoji: 🕹️4colorFrom: blue5colorTo: green6sdk: docker7pinned: false8app_port: 80009base_path: /web10tags:11 - openenv-0.2.312 - openenv13---14 15## Hugging Face Space Deployment16 17This Space is built from OpenEnv environment `atari_env`.18 19- Space URL: `https://huggingface.co/spaces/openenv/atari_env`20- OpenEnv pinned ref: `0.2.3`21- Hub tag: `openenv`22 23### Connecting from Code24 25```python26from envs.atari_env import AtariEnv27 28env = AtariEnv(base_url="https://huggingface.co/spaces/openenv/atari_env")29```30 31# Atari Environment32 33Integration 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.34 35## Supported Games36 37ALE supports 100+ Atari 2600 games including:38 39### Popular Games40- **Pong** - Classic two-player tennis41- **Breakout** - Break bricks with a ball42- **Space Invaders** - Shoot descending aliens43- **Pac-Man / Ms. Pac-Man** - Navigate mazes and eat pellets44- **Asteroids** - Destroy asteroids in space45- **Defender** - Side-scrolling space shooter46- **Centipede** - Shoot segmented centipede47- **Donkey Kong** - Jump over barrels to save princess48- **Frogger** - Cross road and river safely49- **Q*bert** - Jump on pyramid cubes50 51And many more! For a complete list, see [ALE documentation](https://ale.farama.org/environments/complete_list/).52 53## Architecture54 55```56┌────────────────────────────────────┐57│ RL Training Code (Client) │58│ AtariEnv.step(action) │59└──────────────┬─────────────────────┘60 │ HTTP61┌──────────────▼─────────────────────┐62│ FastAPI Server (Docker) │63│ AtariEnvironment │64│ ├─ Wraps ALEInterface │65│ ├─ Handles observations │66│ └─ Action execution │67└────────────────────────────────────┘68```69 70## Installation & Usage71 72### Option 1: Local Development (without Docker)73 74**Requirements:**75- Python 3.11+76- ale-py installed: `pip install ale-py`77 78The client is **async by default**:79 80```python81import asyncio82from atari_env import AtariEnv, AtariAction83 84async def main():85 # Start local server manually: python -m atari_env.server.app86 async with AtariEnv(base_url="http://localhost:8000") as env:87 # Reset environment88 result = await env.reset()89 print(f"Screen shape: {result.observation.screen_shape}")90 print(f"Legal actions: {result.observation.legal_actions}")91 92 # Take actions93 for _ in range(10):94 result = await env.step(AtariAction(action_id=2, game_name="pong"))95 print(f"Reward: {result.reward}, Done: {result.done}")96 if result.done:97 break98 99asyncio.run(main())100```101 102For **synchronous usage**, use the `.sync()` wrapper:103 104```python105from atari_env import AtariEnv, AtariAction106 107with AtariEnv(base_url="http://localhost:8000").sync() as env:108 result = env.reset()109 result = env.step(AtariAction(action_id=2, game_name="pong"))110 print(f"Reward: {result.reward}")111```112 113### Option 2: Docker (Recommended)114 115**Build Atari image:**116 117```bash118cd OpenEnv119 120# Build the image121docker build \122 -f envs/atari_env/server/Dockerfile \123 -t atari-env:latest \124 .125```126 127**Run specific games:**128 129```bash130# Pong (default)131docker run -p 8000:8000 atari-env:latest132 133# Breakout134docker run -p 8000:8000 -e ATARI_GAME=breakout atari-env:latest135 136# Space Invaders with grayscale observation137docker run -p 8000:8000 \138 -e ATARI_GAME=space_invaders \139 -e ATARI_OBS_TYPE=grayscale \140 atari-env:latest141 142# Ms. Pac-Man with full action space143docker run -p 8000:8000 \144 -e ATARI_GAME=ms_pacman \145 -e ATARI_FULL_ACTION_SPACE=true \146 atari-env:latest147```148 149**Use with from_docker_image():**150 151```python152import asyncio153import numpy as np154from atari_env import AtariEnv, AtariAction155 156async def main():157 # Automatically starts container158 client = await AtariEnv.from_docker_image("atari-env:latest")159 160 async with client:161 result = await client.reset()162 result = await client.step(AtariAction(action_id=2)) # UP163 164 # Reshape screen for visualization165 screen = np.array(result.observation.screen).reshape(result.observation.screen_shape)166 print(f"Screen shape: {screen.shape}") # (210, 160, 3) for RGB167 168asyncio.run(main())169```170 171## Observation Types172 173### 1. RGB (Default)174- **Shape**: [210, 160, 3]175- **Description**: Full-color screen observation176- **Usage**: Most realistic, good for vision-based learning177 178```python179docker run -p 8000:8000 -e ATARI_OBS_TYPE=rgb atari-env:latest180```181 182### 2. Grayscale183- **Shape**: [210, 160]184- **Description**: Grayscale screen observation185- **Usage**: Reduced dimensionality, faster processing186 187```python188docker run -p 8000:8000 -e ATARI_OBS_TYPE=grayscale atari-env:latest189```190 191### 3. RAM192- **Shape**: [128]193- **Description**: Raw 128-byte Atari 2600 RAM contents194- **Usage**: Compact representation, useful for specific research195 196```python197docker run -p 8000:8000 -e ATARI_OBS_TYPE=ram atari-env:latest198```199 200## Action Spaces201 202### Minimal Action Set (Default)203Game-specific minimal actions (typically 4-9 actions).204- Pong: 6 actions (NOOP, FIRE, UP, DOWN, etc.)205- Breakout: 4 actions (NOOP, FIRE, LEFT, RIGHT)206 207```python208docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=false atari-env:latest209```210 211### Full Action Set212All 18 possible Atari 2600 actions:2130. NOOP2141. FIRE2152. UP2163. RIGHT2174. LEFT2185. DOWN2196. UPRIGHT2207. UPLEFT2218. DOWNRIGHT2229. DOWNLEFT22310. UPFIRE22411. RIGHTFIRE22512. LEFTFIRE22613. DOWNFIRE22714. UPRIGHTFIRE22815. UPLEFTFIRE22916. DOWNRIGHTFIRE23017. DOWNLEFTFIRE231 232```python233docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=true atari-env:latest234```235 236## Configuration237 238### Environment Variables239 240- `ATARI_GAME`: Game name (default: "pong")241- `ATARI_OBS_TYPE`: Observation type - "rgb", "grayscale", "ram" (default: "rgb")242- `ATARI_FULL_ACTION_SPACE`: Use full action space - "true"/"false" (default: "false")243- `ATARI_MODE`: Game mode (optional, game-specific)244- `ATARI_DIFFICULTY`: Game difficulty (optional, game-specific)245- `ATARI_REPEAT_ACTION_PROB`: Sticky action probability 0.0-1.0 (default: "0.0")246- `ATARI_FRAMESKIP`: Frames to skip per action (default: "4")247 248### Example: Breakout with Custom Settings249 250```bash251docker run -p 8000:8000 \252 -e ATARI_GAME=breakout \253 -e ATARI_OBS_TYPE=grayscale \254 -e ATARI_FULL_ACTION_SPACE=true \255 -e ATARI_REPEAT_ACTION_PROB=0.25 \256 -e ATARI_FRAMESKIP=4 \257 atari-env:latest258```259 260## API Reference261 262### AtariAction263 264```python265@dataclass266class AtariAction(Action):267 action_id: int # Action index to execute268 game_name: str = "pong" # Game name269 obs_type: str = "rgb" # Observation type270 full_action_space: bool = False # Full or minimal action space271```272 273### AtariObservation274 275```python276@dataclass277class AtariObservation(Observation):278 screen: List[int] # Flattened screen pixels279 screen_shape: List[int] # Original screen shape280 legal_actions: List[int] # Legal action indices281 lives: int # Lives remaining282 episode_frame_number: int # Frame # in episode283 frame_number: int # Total frame #284 done: bool # Episode finished285 reward: Optional[float] # Reward from last action286```287 288### AtariState289 290```python291@dataclass292class AtariState(State):293 episode_id: str # Unique episode ID294 step_count: int # Number of steps295 game_name: str # Game name296 obs_type: str # Observation type297 full_action_space: bool # Action space type298 mode: Optional[int] # Game mode299 difficulty: Optional[int] # Game difficulty300 repeat_action_probability: float # Sticky action prob301 frameskip: int # Frameskip setting302```303 304## Example Script305 306```python307#!/usr/bin/env python3308"""Example training loop with Atari environment."""309 310import asyncio311import numpy as np312from atari_env import AtariEnv, AtariAction313 314async def train():315 # Start environment316 client = await AtariEnv.from_docker_image("atari-env:latest")317 318 async with client:319 # Training loop320 for episode in range(10):321 result = await client.reset()322 episode_reward = 0323 steps = 0324 325 while not result.done:326 # Random policy (replace with your RL agent)327 action_id = np.random.choice(result.observation.legal_actions)328 329 # Take action330 result = await client.step(AtariAction(action_id=action_id))331 332 episode_reward += result.reward or 0333 steps += 1334 335 # Reshape screen for processing336 screen = np.array(result.observation.screen).reshape(337 result.observation.screen_shape338 )339 340 # Your RL training code here341 # ...342 343 print(f"Episode {episode}: reward={episode_reward:.2f}, steps={steps}")344 345asyncio.run(train())346```347 348## Testing349 350### Local Testing351 352```bash353# Install dependencies354pip install ale-py fastapi uvicorn requests355 356# Start server357export PYTHONPATH=src:envs358python -m atari_env.server.app359 360# Test from another terminal (using sync wrapper for simplicity)361python -c "362from atari_env import AtariEnv, AtariAction363with AtariEnv(base_url='http://localhost:8000').sync() as env:364 result = env.reset()365 print(f'Initial obs: {result.observation.screen_shape}')366 result = env.step(AtariAction(action_id=2))367 print(f'After step: reward={result.reward}, done={result.done}')368"369```370 371### Docker Testing372 373```bash374# Build and run375docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .376docker run -p 8000:8000 atari-env:latest377 378# Test in another terminal379curl http://localhost:8000/health380curl -X POST http://localhost:8000/reset381```382 383## Popular Games and Their Characteristics384 385| Game | Minimal Actions | Lives | Difficulty | Notes |386|------|----------------|-------|-----------|-------|387| Pong | 6 | 1 | Low | Good for learning basics |388| Breakout | 4 | 5 | Medium | Classic RL benchmark |389| Space Invaders | 6 | 3 | Medium | Shooting game |390| Ms. Pac-Man | 9 | 3 | High | Complex navigation |391| Asteroids | 14 | 3 | Medium | Continuous shooting |392| Montezuma's Revenge | 18 | 5 | Very High | Exploration challenge |393| Pitfall | 18 | 1 | High | Platformer |394| Seaquest | 18 | 3 | High | Submarine rescue |395 396## Limitations & Notes397 398- **Frame perfect timing**: Some games require precise timing399- **Exploration**: Games like Montezuma's Revenge are notoriously difficult400- **Observation delay**: HTTP adds minimal latency vs local gym401- **Determinism**: Set `ATARI_REPEAT_ACTION_PROB=0.0` for deterministic behavior402- **ROMs**: All ROMs are bundled with ale-py package403 404## References405 406- [Arcade Learning Environment Paper (2013)](https://jair.org/index.php/jair/article/view/10819)407- [ALE GitHub](https://github.com/Farama-Foundation/Arcade-Learning-Environment)408- [ALE Documentation](https://ale.farama.org/)409- [Gymnasium Atari Environments](https://gymnasium.farama.org/environments/atari/)410 411## Citation412 413If you use ALE in your research, please cite:414 415```bibtex416@Article{bellemare13arcade,417 author = {{Bellemare}, M.~G. and {Naddaf}, Y. and {Veness}, J. and {Bowling}, M.},418 title = {The Arcade Learning Environment: An Evaluation Platform for General Agents},419 journal = {Journal of Artificial Intelligence Research},420 year = "2013",421 month = "jun",422 volume = "47",423 pages = "253--279",424}425```426