--- title: Atari Environment Server emoji: 🕹ī¸ colorFrom: blue colorTo: green sdk: docker pinned: false app_port: 8000 base_path: /web tags: - openenv-0.2.3 - openenv --- ## 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 - **Q*bert** - Jump on pyramid cubes And many more! For a complete list, see [ALE documentation](https://ale.farama.org/environments/complete_list/). ## 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: 0. NOOP 1. FIRE 2. UP 3. RIGHT 4. LEFT 5. DOWN 6. UPRIGHT 7. UPLEFT 8. DOWNRIGHT 9. DOWNLEFT 10. UPFIRE 11. RIGHTFIRE 12. LEFTFIRE 13. DOWNFIRE 14. UPRIGHTFIRE 15. UPLEFTFIRE 16. DOWNRIGHTFIRE 17. 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 - [Arcade Learning Environment Paper (2013)](https://jair.org/index.php/jair/article/view/10819) - [ALE GitHub](https://github.com/Farama-Foundation/Arcade-Learning-Environment) - [ALE Documentation](https://ale.farama.org/) - [Gymnasium Atari Environments](https://gymnasium.farama.org/environments/atari/) ## 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", } ```