# pokemon-emulator

Adopt this skill: https://proskills.md/skills/other/devvgwardo-openclaw-pokemon-emulator

Page: https://proskills.md/skills/other/devvgwardo-openclaw-pokemon-emulator
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 3254
upstream: https://github.com/devvgwardo/openclaw-pokemon-emulator/blob/HEAD/SKILL.md

````text
---
name: pokemon-emulator
description: "Play Pokemon and similar retro handheld games through Python-based and subprocess-based emulation on your machine. Provides scripts to launch games, manage save states, capture screenshots, and control gameplay through PyBoy (GB/GBC) and mGBA/VBA-M (GBA). Triggers when user wants to: play Pokemon games, play Game Boy/Color/Advance games, automate gameplay, capture screenshots, manage save states."
---

# Pokemon Emulator Skill

Play Pokemon and similar retro handheld games through Python-based and subprocess-based emulation.

## When to Use

Activate this skill when the user wants to:
- Play Pokemon games (any generation: GB/GBC/GBA)
- Play other Game Boy or Game Boy Color games via PyBoy
- Play Game Boy Advance games via mGBA or VBA-M
- Automate gameplay (AI-driven button presses)
- Capture screenshots or clips from games
- Manage save states during gameplay

## Available Emulators

### PyBoy (GB/GBC) — Python-native

Python library for Game Boy / Game Boy Color emulation. Scriptable, no external binary.

**Install:** `pip install pyboy pysdl2-dll numpy`
**Script:** `scripts/pyboy_interface.py`

```python
from pyboy_interface import PyBoyGame, A, B, UP, DOWN

game = PyBoyGame("pokemon_red.gb")
game.press_button(A)
x, y = game.get_position()
screen = game.get_screen()  # np.array (144, 160, 3)
```

### mGBA (GBA) — Recommended

Controls mGBA via PyAutoGUI (window focus + keypresses). HLE BIOS — no BIOS file needed.

**Install:** Download from https://mgba.io (portable .7z, no install needed)
**Script:** `scripts/mgba_control.py`

```python
from mgba_control import GBAEmulator, BUTTONS

gba = GBAEmulator("pokemon_ruby.gba", mgba_path="C:/mgba/mGBA.exe")
gba.press_button("A", frames=5)
gba.press_button("START", frames=3)
screen = gba.get_screen()  # PIL Image
gba.stop()
```

### PyBoyAdvance (GBA) — Pure Python fallback

Pure Python GBA emulator. Requires GBA BIOS file.

**Install:** `pip install pyboy-advance numpy pillow`
**Script:** `scripts/gba_interface.py`

## Key Scripts

| Script | Platform | Notes |
|--------|----------|-------|
| `scripts/pyboy_interface.py` | GB/GBC | Full API: RAM read/write, position, party, battle state |
| `scripts/mgba_control.py` | GBA | PyAutoGUI control of mGBA window |
| `scripts/gba_interface.py` | GBA | PyBoyAdvance wrapper (needs BIOS) |

## Common RAM Addresses (Pokemon Red/Blue)

| Data | Address |
|------|---------|
| Player X | 0xD362 |
| Player Y | 0xD361 |
| Map Number | 0xD35E |
| Money | 0xD47F |
| Party Count | 0xD163 |
| Badges | 0xD2F7 |
| First Pokemon HP | 0xD16C |
| Game State | 0xD057 (0=overworld, 1-6=battle) |

## Example Prompts

- "Play Pokemon Yellow on Game Boy"
- "Start Pokemon Ruby and navigate the intro"
- "Play Pokemon FireRed on GBA and show me the screen"
- "Run Pokemon Gold, get my party info"
- "Automate playing Tetris on Game Boy"
- "Save my Pokemon Red game state"

## Notes

- **ROM files not included** — user must provide their own legally-owned ROMs
- mGBA is the recommended GBA emulator (HLE, no BIOS required, fast)
- PyBoy is the recommended GB/GBC emulator (pure Python, scriptable)
- Save states stored in `assets/` directory
- Screenshots saved as PNG in working directory
````

## File: README.md
upstream: https://github.com/devvgwardo/openclaw-pokemon-emulator/blob/HEAD/README.md

````text
# 🎮 OpenClaw Pokemon Emulator Skill

> Play Pokemon, Game Boy, Game Boy Color, and Game Boy Advance games through OpenClaw!

```
    .---.     .---.     .---.     .---.     .---.
   /     \   /     \   /     \   /     \   /     \
  | () () | | () () | | () () | | () () | | () () |
   \  ^  /   \  ^  /   \  ^  /   \  ^  /   \  ^  /
    |||||     |||||     |||||     |||||     |||||
    |||||     |||||     |||||     |||||     |||||
   Pokemon   Pokemon   Pokemon   Pokemon   Pokemon
    Red       Blue     Yellow     Gold     Emerald
```

## What Is This?

The **Pokemon Emulator Skill** lets you play classic handheld Pokemon games directly through OpenClaw. It wraps two emulation backends:

- **PyBoy** — A pure-Python Game Boy (GB) and Game Boy Color (GBC) emulator. Great for scripting, automation, and lightweight play.
- **GBA Emulators** — Game Boy Advance games via subprocess launchers that work with mGBA, VBA-M, or any CLI-capable GBA emulator.

Beyond just launching games, this skill gives you:
- �save Save state management (multiple slots per game)
- 📸 Screenshot capture at any time
- ⌨️ Keyboard-driven gameplay control
- 🔧 Per-game configuration and hotkey maps

---

## 📋 Prerequisites

Before installing and using this skill, make sure you have the following:

### Required for GB/GBC Games (PyBoy)

| Requirement | Version/Details |
|---|---|
| **Python** | 3.8 or higher |
| **PyBoy** | Install via `pip install pyboy` |
| **ROM Files** | `.gb` or `.gbc` files you legally own |

### Required for GBA Games

| Requirement | Version/Details |
|---|---|
| **A GBA Emulator** | One of: **mGBA** (recommended), **VBA-M**, or any emulator with CLI support |
| **ROM Files** | `.gba` files you legally own |

### Optional but Recommended

| Requirement | Why |
|---|---|
| **SDL2** (for PyBoy) | Provides better performance; install via your system package manager |
| **qtpynput** or **pynput** | For advanced keyboard automation features |

---

## 🔧 Installing the Emulators

### Installing PyBoy

```bash
# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
# OR
.venv\Scripts\activate        # Windows

# Install PyBoy
pip install pyboy
```

> **Note:** PyBoy runs entirely in Python — no additional emulator binary needed!

### Installing mGBA (Recommended for GBA)

**Windows:**
1. Download mGBA from [https://mgba.io/downloads.html](https://mgba.io/downloads.html)
2. Extract the ZIP to a folder (e.g., `C:\Emulators\mGBA`)
3. Add that folder to your system `PATH`, or note the full path to `mgba.exe`

**Linux (Ubuntu/Debian):**
```bash
sudo add-apt-repository ppa:felis/linux-mgba
sudo apt update
sudo apt install mgba
```

**macOS:**
```bash
brew install mgba
```

### Installing VBA-M (Alternative GBA Emulator)

**Windows:**
1. Download VBA-M from [https://github.com/visualboyadvance-m/visualboyadvance-m/releases](https://github.com/visualboyadvance-m/visualboyadvance-m/releases)
2. Extract and place the executable somewhere convenient
3. Note the path to `visualboyadvance-m.exe`

**Linux:**
```bash
sudo apt install visualboyadvance-m
```

---

## 📦 Installing the Skill into OpenClaw

### Method 1: Via OpenClaw CLI (Recommended)

```bash
openclaw skill install pokemon-emulator
```

### Method 2: Manual Installation

If you need to install from a local path:

```bash
openclaw skill install --source C:\path\to\pokemon-emulator
```

### Method 3: Symlink for Development

If you're working on the skill itself:

```bash
# On Windows (PowerShell)
New-Item -ItemType SymbolicLink -Path "openclaw\skills\pokemon-emulator" -Target "C:\path\to\pokemon-emulator"

# On Linux/macOS
ln -s /path/to/pokemon-emulator ~/AppData/Roaming/openclaw/skills/pokemon-emulator
```

### Verify Installation

```bash
openclaw skill list | Select-String pokemon
# or
openclaw skill list | grep pokemon
```

---

## 🎮 Usage Examples

### Launch a Game

**Game Boy / Game Boy Color:**
```bash
python scripts/pyboy/launch.py "C:\ROMs\Pokemon\Pokemon - Red Version.gb"
```

**Game Boy Advance:**
```bash
python scripts/gba/launch.py "C:\ROMs\Pokemon\Pokemon - Emerald Version.gba"
```

### Or just ask OpenClaw naturally:

- *"Play Pokemon Yellow"*
- *"Start Pokemon Gold"*
- *"Launch Pokemon Emerald"*

### Save Your Game

```bash
# Save to slot 1
python scripts/pyboy/save_state.py "PokemonRed.gb" 1

# Save to slot 2
python scripts/pyboy/save_state.py "PokemonRed.gb" 2
```

### Load a Save State

```bash
# Load from slot 1
python scripts/pyboy/load_state.py "PokemonRed.gb" 1

# Load from slot 2
python scripts/pyboy/load_state.py "PokemonRed.gb" 2
```

### List Available Save Slots

```bash
python scripts/pyboy/list_states.py "PokemonRed.gb"
```

### Take a Screenshot

**PyBoy (GB/GBC):**
```bash
python scripts/pyboy/screenshot.py "PokemonRed.gb" "screenshots/pokedex.png"
```

**GBA:**
```bash
python scripts/gba/screenshot.py "PokemonEmerald.gba" "screenshots/battle.png"
```

### Or just ask OpenClaw:

- *"Take a screenshot of my Pokemon game"*
- *"Save my game in slot 3"*
- *"Show me my save states for Pokemon Blue"*

---

## 🎯 Gameplay Screenshot (PyBoy in Action)

```
┌─────────────────────────────────────────┐
│  ┌───────────────────────────────────┐  │
│  │                                   │  │
│  │   POKéMON RED                     │  │
│  │   ─────────────                   │  │
│  │                                   │  │
│  │   ┌─────┐                         │  │
│  │   │ ASH │  ♥♥♥♥♥♥♥♥  HP           │  │
│  │   └─────┘                         │  │
│  │                                   │  │
│  │        ┌────┐                     │  │
│  │        │BULB│                     │  │
│  │        │BASA│  Lv.5               │  │
│  │        └────┘                     │  │
│  │                                   │  │
│  │   ┌──────┐   ┌──────┐             │  │
│  │   │ POKE │   │ BAG  │             │  │
│  │   └──────┘   └──────┘             │  │
│  │                                   │  │
│  │   ┌──────┐   ┌──────┐             │  │
│  │   │ RUN  │   │FIGHT│             │  │
│  │   └──────┘   └──────┘             │  │
│  │                                   │  │
│  └───────────────────────────────────┘  │
│                                         │
│  [Arrow Keys] Move   [Z] A   [X] B      │
│  [Enter] Start       [Backspace] Select │
└─────────────────────────────────────────┘
```

---

## 📜 Supported Games

### Game Boy (GB) — via PyBoy

| Game | File Extension | Status |
|------|---------------|--------|
| Pokemon Red | `.gb` | ✅ Fully Supported |
| Pokemon Blue | `.gb` | ✅ Fully Supported |
| Pokemon Yellow | `.gb` | ✅ Fully Supported |
| Pokemon Green (JP) | `.gb` | ✅ Fully Supported |
| Tetris | `.gb` | ✅ Fully Supported |
| The Legend of Zelda: Link's Awakening | `.gb` | ✅ Fully Supported |
| Super Mario Land | `.gb` | ✅ Fully Supported |

### Game Boy Color (GBC) — via PyBoy

| Game | File Extension | Status |
|------|---------------|--------|
| Pokemon Gold | `.gbc` | ✅ Fully Supported |
| Pokemon Silver | `.gbc` | ✅ Fully Supported |
| Pokemon Crystal | `.gbc` | ✅ Fully Supported |
| The Legend of Zelda: Oracle of Ages | `.gbc` | ✅ Fully Supported |
| The Legend of Zelda: Oracle of Seasons | `.gbc` | ✅ Fully Supported |
| Pokemon Pinball (GBC) | `.gbc` | ✅ Fully Supported |

### Game Boy Advance (GBA) — via mGBA / VBA-M

| Game | File Extension | Status |
|------|---------------|--------|
| Pokemon Ruby | `.gba` | ✅ Fully Supported |
| Pokemon Sapphire | `.gba` | ✅ Fully Supported |
| Pokemon Emerald | `.gba` | ✅ Fully Supported |
| Pokemon FireRed | `.gba` | ✅ Fully Supported |
| Pokemon LeafGreen | `.gba` | ✅ Fully Supported |
| Pokemon Mystery Dungeon (Red/Blue) | `.gba` | ✅ Fully Supported |

> ⚠️ **Important:** ROM files are **not included** with this skill. You must own and provide your own legally-obtained ROM files. This skill does not distribute or encourage piracy.

---

## 📁 Directory Structure

```
pokemon-emulator/
├── README.md     
````
