Pokemon Player

Pokémon Player Skill

Play Pokémon games autonomously via headless emulation. Uses the pokemon-agent package to run a game server, then interacts via HTTP API.

Setup (First Time Only)

# Install the package + emulator + dashboard
pip install pokemon-agent[dashboard] pyboy

# User must provide their own ROM file
# The agent CANNOT download or distribute ROMs

Ask the user for the ROM file path if not provided. Common locations:

• ~/roms/pokemon_red.gb
• ~/pokemon_red.gb

Starting a Game

# Start the game server as a background process
pokemon-agent serve --rom <ROM_PATH> --port 8765 &

# Verify it's running
curl -s http://localhost:8765/health

Tell the user: "Dashboard available at http://localhost:8765/dashboard"

Gameplay Loop

Each turn, follow this cycle:

1. Observe — Read Game State

curl -s http://localhost:8765/state | python3 -m json.tool

Parse the JSON to understand:

• Where am I? (map name, position)
• What's happening? (overworld, battle, dialog, menu)
• Party status? (HP, levels, any fainted?)
• Bag contents? (potions, pokeballs?)
• Badges earned?

2. Decide — What To Do

Priority order: 1. If in dialog → press A to advance (a_until_dialog_end) 2. If in battle → choose best move (see Battle Strategy) 3. If party needs healing → navigate to Pokémon Center 4. If ready for next gym → navigate toward it 5. Otherwise → explore, train, catch Pokémon

Use Hermes memory to track:

• Current objective: PKM:OBJECTIVE: Defeat Brock in Pewter City
• Map knowledge: PKM:MAP: Viridian Forest has bug catchers, exit north to Pewter
• Strategy notes: PKM:STRATEGY: Brock's Onix is weak to Water — use Bubble

3. Act — Send Commands

# Single action
curl -s -X POST http://localhost:8765/action \
  -H "Content-Type: application/json" \
  -d '{"actions": ["press_a"]}'

# Movement sequence
curl -s -X POST http://localhost:8765/action \
  -H "Content-Type: application/json" \
  -d '{"actions": ["walk_up", "walk_up", "walk_right", "press_a"]}'

# Advance dialog
curl -s -X POST http://localhost:8765/action \
  -H "Content-Type: application/json" \
  -d '{"actions": ["a_until_dialog_end"]}'

4. Verify — Check Result

After each action, the response includes state_after. Check:

• Did I move? (position changed)
• Did the dialog advance? (new text or cleared)
• Did the battle state change? (HP, turn)

If stuck (same state after 3+ actions), try: 1. Press B to cancel menus 2. Try different direction 3. Load last save

Action Reference

Battle Strategy (Gen 1)

Type Effectiveness — Key Matchups

• Water beats: Fire, Ground, Rock
• Fire beats: Grass, Bug, Ice
• Grass beats: Water, Ground, Rock
• Electric beats: Water, Flying
• Ground beats: Fire, Electric, Rock, Poison
• Ice beats: Grass, Ground, Flying, Dragon
• Fighting beats: Normal, Rock, Ice
• Psychic beats: Fighting, Poison (VERY strong in Gen 1)

Decision Tree

1. Can I one-shot? → Use strongest super-effective move 2. Am I at type disadvantage? → Switch if possible, or use neutral STAB 3. Is enemy HP high? → Consider stat moves first (Growl, Tail Whip) 4. Should I catch? → Weaken to red HP, use Poké Ball 5. Wild battle, don't need it? → Run (press_b or use "Run" option)

Gen 1 Quirks

• Special stat is BOTH Special Attack and Special Defense
• Psychic type has NO effective counters (Ghost moves bugged, Bug moves weak)
• Critical hit rate based on Speed stat
• Wrap/Bind/Fire Spin prevent the opponent from acting

Saving

# Save before important battles
curl -s -X POST http://localhost:8765/save \
  -d '{"name": "before_brock"}'

# Load if things go wrong
curl -s -X POST http://localhost:8765/load \
  -d '{"name": "before_brock"}'

# List available saves
curl -s http://localhost:8765/saves

Save before: Gym battles, catching rare Pokémon, entering dungeons.

Progression Milestones

Track these in memory as you complete them:

1. ☐ Get starter Pokémon from Oak 2. ☐ Deliver Oak's Parcel, get Pokédex 3. ☐ Reach Pewter City through Viridian Forest 4. ☐ Boulder Badge (Brock — Rock type, use Water/Grass) 5. ☐ Reach Cerulean City via Mt. Moon 6. ☐ Cascade Badge (Misty — Water type, use Grass/Electric) 7. ☐ Board SS Anne, get HM01 Cut 8. ☐ Thunder Badge (Lt. Surge — Electric, use Ground) 9. ☐ Clear Rock Tunnel to Lavender Town 10. ☐ Rainbow Badge (Erika — Grass, use Fire/Ice/Flying) 11. ☐ Clear Team Rocket Hideout, get Silph Scope 12. ☐ Soul Badge (Koga — Poison, use Ground/Psychic) 13. ☐ Marsh Badge (Sabrina — Psychic, use Bug... but good luck in Gen 1) 14. ☐ Volcano Badge (Blaine — Fire, use Water/Ground) 15. ☐ Earth Badge (Giovanni — Ground, use Water/Grass/Ice) 16. ☐ Victory Road 17. ☐ Elite Four + Champion

Memory Conventions

Use these prefixes in Hermes memory for Pokémon-related entries:

• PKM:OBJECTIVE: — Current goal
• PKM:MAP: — Map/navigation knowledge
• PKM:STRATEGY: — Battle/team strategy notes
• PKM:PROGRESS: — Milestone completion
• PKM:STUCK: — Notes about stuck situations and how they were resolved

Taking Screenshots

# Save screenshot for vision analysis
curl -s http://localhost:8765/screenshot -o /tmp/pokemon_screen.png

Use vision_analyze on the screenshot when:

• You're unsure what's on screen (menus, NPCs)
• You need to read in-game text that RAM doesn't capture well
• You want to verify your position visually

Stopping

When done playing: 1. Save the game: curl -X POST localhost:8765/save -d '{"name": "session_end"}' 2. Kill the background server process 3. Save progress notes to memory