CLI tool
PWhiddy/PokemonRedExperiments avatar
PWhiddy/PokemonRedExperiments

Four save states at the root, and V2 trades a KNN for a reward

Playing Pokemon Red with Reinforcement Learning

7,937 stars786 forksJupyter NotebookMIT

At a glance

What is it?
This is a reinforcement learning project that teaches an agent to play Pokemon Red through PyBoy and Stable Baselines 3, and the README is written as a reproduction guide rather than a tutorial. It asks for a ROM you obtained legally with a printed sha1, tells you which directory must be your working directory, ships four emulator save states at the root, and documents a V2 script that replaces the frame KNN with a coordinate based exploration reward and reaches Cerulean.
Who is it for?
Take this repository when you want a complete, reproducible reinforcement learning environment with its own baseline and a pretrained agent you can drive yourself through the arrow keys. Leave it if you do not have a legally obtained copy of the ROM, because the whole project is built around one file whose sha1 the README prints.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 65 days ago.
What is it written in?
Mainly Jupyter Notebook, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • PWhiddy/PokemonRedExperiments7,937 ★ · +32
Star history
Repository2026-09-222026-11-15
PWhiddy/PokemonRedExperiments7.9k7.9k

32 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Four save states sit at the repository root

The top level of this repository contains something unusual for a machine learning project: four emulator save files.

They are init.state, has_pokedex.state, has_pokedex_nballs.state and fast_text_start.state, all committed at the root next to the README and the LICENSE.

These are PyBoy save states, which is to say snapshots of the game's memory at a position. Their names say what each one is for. One is the starting position, one is after the player has the pokedex, one is after the pokedex and the balls, and one is after some fast text.

Because they are committed, somebody else can pick up the repository with the same saved positions you have.

The other root entries follow from the same logic. There is baselines/ for the original training code and v2/ for the newer one, clip_experiment/ and jippity-6-test/ which are named after individual experiment runs, a visualization/ directory for the map code, a VisualizeProgress.ipynb notebook, an assets/ directory, and a windows-setup-guide.md.

V2 replaces a frame KNN with a coordinate based reward

There are two training paths in this project and the newer one is recommended, which the README states as: V2 is now recommended over the original version, and you may follow all steps below but replace baselines with v2.

The differences are four bullet points. It trains faster and with less memory. It reaches Cerulean. It streams to the map by default. And there are other improvements.

The one that explains the rest is stated separately: V2 replaces the frame KNN with a coordinate based exploration reward, as well as some other tweaks.

The README lists the new reward alongside the speed, memory and Cerulean claims but does not attribute them to it.

The run itself is two steps: the same setup as before but in the v2 directory, then one script.

bash
python baseline_fast_v2.py

The ROM must be legally obtained and its sha1 is printed

Step one of the setup is the part that makes this project reproducible rather than merely runnable, and it is worth reading closely.

You are asked to copy your legally obtained Pokemon Red ROM into the base directory. The README says you can find this using Google, that it should be 1MB, and to rename it to PokemonRed.gb if it is not already. Then it gives the expected hash:

bash
shasum PokemonRed.gb

The sha1 sum should be ea9bcae617fdf159b045185467ae58b2e4a48b9a.

That single line does two things. It tells you which file you are supposed to have, and it makes the setup verifiable rather than a matter of trust. A ROM with a different hash is not the cartridge the environment was tuned against, and every later result is then about your file rather than about the agent.

The remaining steps are short. Move into the baselines directory, install the dependencies, and run the interactive script. The README also notes that the Pokemon.gb file must be in the main directory and that your current directory must be the baselines directory, which is a path requirement rather than a suggestion.

ffmpeg is a prerequisite nobody expects

The prerequisites for running the pretrained model interactively are stated in three sentences and one of them surprises people.

Python 3.10+ is recommended, with the note that other versions may work but have not been tested. Windows users are pointed at a setup guide in the repository. AMD GPU users are pointed at a guide for installing PyTorch with ROCm support.

And then: you also need to install ffmpeg and have it available in the command line.

No explanation is offered for why a Game Boy emulator reinforcement learning project needs a video encoder, and the README does not say whether it is for recording frames, for the broadcast, or for both.

What it does say about the interactive session is concrete. You interact with the emulator using the arrow keys and the a and s keys, which map to the A and B buttons, and you can pause the AI's input during the game by editing a file called agent_enabled.txt.

That last detail is a nice piece of design for a demo. The agent is driving, you are watching, and when it does something absurd you can freeze it by touching a text file rather than killing the process.

The dependencies themselves come from a requirements.txt, with the note that in some cases you may need to install the SDL libraries separately.

Training streams to a shared map and the viewer lives elsewhere

One feature here has nothing to do with the agent and everything to do with demonstrating that many runs are happening at once.

The Training Broadcast wrapper streams a training session to a shared global game map, and the README shows it as a single call with an optional metadata block:

python
env = StreamWrapper(
            env,
            stream_metadata = { # All of this is part is optional
                "user": "super-cool-user", # choose your own username
                "env_id": id, # environment identifier
                "color": "#0033ff", # choose your color :)
                "extra": "", # any extra text you put here will be displayed
            }
        )

A username, an environment identifier, a colour and free text, all optional. That is everything needed to put one agent on a shared map next to everybody else's.

The viewing client is not in this repository. The README links a hosted version and says you can hack on the broadcast viewing client or set up your own local stream with a separate repository.

For local progress there is a simpler path. The current state of each game is rendered to images in the session directory, and you can track progress in TensorBoard by moving into that directory and running:

bash
tensorboard --logdir .

then navigating to localhost:6006. Weights and Biases integration is one flag, by changing use_wandb_logging in the training script to True.

Two requirement files, and a platform split nobody documents

The installation section has one dependency instruction and one platform note, and between them they explain most of what you will hit on a first run.

Install dependencies is pip install -r requirements.txt. Then: it may be necessary in some cases to separately install the SDL libraries. And: for V2 MacOS users should use macos_requirements.txt instead of requirements.txt.

So the supported platforms named in the README are Windows, Linux and macOS, and macOS on the V2 path needs a different requirements file. Nothing explains the difference, which is the kind of detail you discover by trying.

The SDL remark is the other one. SDL is the windowing and input library underneath a Game Boy emulator, so it is load-bearing rather than optional, and the README treats its absence as a case you might hit rather than a requirement it states.

The interactive run itself is one command:

bash
python run_pretrained_interactive.py

which is why the prerequisites section is short. There is no configuration file, no manifest and no model download step in the README's own account of getting started, which for a project with a pretrained agent and a fixed ROM hash is a smaller setup than that usually implies.

The paper is follow-up work, not this repository

The last section of the README points at three things, and the first of them reframes what this repository is.

A paper titled Pokemon Red via Reinforcement Learning, on arXiv as 2502.19920, by Marco Pleines, Daniel Addis, David Rubinstein, Frank Zimmer, Mike Preuss and Peter Whidden, dated 2025 and classified under cs.LG.

Then a browser edition of the work, hosted at a drubinstein.github.io address, and PokeGym, a separate repository under the PufferAI organisation.

So the paper, the playable edition and the reusable environment are three artefacts, and the README treats them as follow up to what is here. That is a reasonable way to structure a research repository.

The supporting libraries section names the two this depends on: PyBoy, the emulator, and Stable Baselines 3, the reinforcement learning library. Both are credited rather than vendored, which means the version of the emulator you install is part of your result.

Editorial conclusion

Take this repository when you want a complete, reproducible reinforcement learning environment with its own baseline and a pretrained agent you can drive yourself through the arrow keys. Leave it if you do not have a legally obtained copy of the ROM, because the whole project is built around one file whose sha1 the README prints. Verify three things. Check that ffmpeg is on your command line, since the README calls it out alongside the Python version and the interactive viewer needs it. Work from the right directory, because the notes say the ROM file must be in the main directory while your current directory must be the baselines directory, or v2 if that is the path you are following. And note the four emulator save states at the root: init.state, has_pokedex.state, has_pokedex_nballs.state and fast_text_start.state.

Frequently asked questions

is reinforcement learning hard

The README does not answer that directly, but it is written as a reproduction guide rather than a tutorial: four numbered steps, a ROM you obtained legally with a stated sha1, a working directory requirement, two requirement files depending on platform, and one script to run. The follow-up section points at a paper, a browser edition and a separate gym project for anyone who wants the longer version.

has pokémon ever used ai

This repository is one attempt. It trains reinforcement learning agents to play Pokemon Red, using PyBoy as the emulator and Stable Baselines 3, and it ships a pretrained model you can play yourself with the arrow keys and the a and s keys. The follow-up work lists a paper on Pokemon Red via reinforcement learning, a browser edition, and PokeGym.

is pokémon emulation illegal

The README gives no legal advice. What it does is require a legally obtained ROM as the first step of setup, say you should find it using Google and that it should be 1MB, and print the sha1 sum so you can confirm the file is the expected one. That is a distribution constraint rather than a claim about legality.

Official sources

  1. Issues
  2. License: MIT
  3. PWhiddy/PokemonRedExperiments on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pwhiddy-pokemonredexperiments.svg)](https://hysenlabs.com/projects/pwhiddy-pokemonredexperiments)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pwhiddy-pokemonredexperiments.svg)](https://hysenlabs.com/projects/pwhiddy-pokemonredexperiments)

Was this useful?