stable-retro 1.0.0

No project description provided

A fork of gym-retro ('lets you turn classic video games into Gymnasium environments for reinforcement learning') with additional games, emulators and supported platforms. Since gym-retro is in maintenance now, you can instead submit PRs with new games or features here in stable-retro.

• Supported emulators
• Supported games/envs

Emulated Systems

System	Linux	Windows	Apple
Atari 2600	✓	✓	✓
NES	✓	✓	✓
SNES	✓	✓	✓
Nintendo 64	✓†	✓†	—
Nintendo DS	✓	✓	✓
Gameboy/Color	✓	✓	✓*
Gameboy Advance	✓	✓	✓
Sega Genesis	✓	✓	✓
Sega Master System	✓	✓	✓
Sega CD	✓	✓	✓
Sega 32X	✓	✓	✓
Sega Saturn	✓	✓	✓
Sega Dreamcast	✓‡	—	—
PC Engine	✓	✓	✓
Arcade Machines	✓	✓	—

Supported Games

Currently over 1000 games are integrated including:

Category	Games
Platformers	Super Mario World, Sonic The Hedgehog 2, Mega Man 2, Castlevania IV
Fighters	Mortal Kombat Trilogy, Street Fighter II, Fatal Fury, King of Fighters '98
Sports	NHL94, NBA Jam, Baseball Stars
Puzzle	Tetris, Columns
Shmups	1943, Thunder Force IV, Gradius III, R-Type
BeatEmUps	Streets Of Rage, Double Dragon, TMNT 2: The Arcade Game, Golden Axe, Final Fight
Racing	Super Hang On, F-Zero, OutRun
RPGs (experimental)	Pokemon Red, Legend Of Zelda, Final Fantasy, Dragon Warrior

Note: If the game you want is not included but is supported by one of the systems in the list above, an integration tool is provided to help add new games.

Installation

pip3 install stable-retro

or if the above doesn't work for your platform:

pip3 install git+https://github.com/Farama-Foundation/stable-retro.git

If you plan to integrate new ROMs, states or emulator cores or plan to edit an existing env:

git clone https://github.com/Farama-Foundation/stable-retro.git
cd stable-retro
pip3 install -e .

For platform-specific instructions including building from source, optional core dependencies, and the Integration UI:

• Linux Installation - Ubuntu/Debian dependencies, N64 and Dreamcast core setup, WSL2 guide
• macOS Installation - Apple Silicon build instructions, Homebrew dependencies

Example

'Nature CNN' model trained using PPO on Airstriker-Genesis env (rom already included in the repo)

Tested on Ubuntu 20.04 and Windows 11 WSL2 (Ubuntu 20.04 VM)

sudo apt-get update
sudo apt-get install python3 python3-pip git zlib1g-dev libopenmpi-dev ffmpeg

You need to install a stable baselines 3 version that supports gymnasium

pip3 install git+https://github.com/Farama-Foundation/stable-retro.git
pip3 install stable_baselines3[extra]

Start training:

cd retro/examples
python3 ppo.py --game='Airstriker-Genesis-v0'

More advanced examples: https://github.com/MatPoliquin/stable-retro-scripts

Documentation & Tutorials

Documentation is available at https://stable-retro.farama.org/ (work in progress)

See LICENSES.md for information on the licenses of the individual cores.

Topic	Description
Windows WSL2 Setup	Step-by-step guide for setting up stable-retro on Windows 11 with WSL2 and Ubuntu 22.04
Game Integration Tool	Playlist covering how to use the integration tool to add new games
RetroArch + ML Models	Running a custom RetroArch build that supports overriding player input with trained models

ROMs and BIOS files

Each game integration has files listing memory locations for in-game variables, reward functions based on those variables, episode end conditions, savestates at the beginning of levels and a file containing hashes of ROMs that work with these files.

Please note that ROMs are not included and you must obtain them yourself. Most ROM hashes are sourced from their respective No-Intro SHA-1 sums.

Run this script in the roms folder you want to import. If the checksum matches it will import them in the related game folder in stable-retro.

python3 -m retro.import .

Some platforms like Sega Saturn and Dreamcast also need to be provided a BIOS. List of BIOS names and checksums.

The following non-commercial Sega Genesis ROM is included with Stable Retro for testing purposes:

• Airstriker by Electrokinesis

List of other included ROMs.

Contributing & Support

See CONTRIBUTING.md

There is an effort to get this project to the Farama Foundation Project Standards. These development efforts are being coordinated in the stable-retro channel of the Farama Foundation's Discord. Click here for the invite

Feel free to reach out to the above Discord for any issues/suggestions/discussions related to stable-retro

Supported specs:

Platforms:

• Windows 10, 11 (via WSL2)
• macOS 10.13 (High Sierra), 10.14 (Mojave)
• Linux (manylinux1). Ubuntu 22.04 is recommended

CPU with SSE3 or better

Supported Pythons: 3.7 to 3.12

Citation

@misc{stable-retro,
  author = {Poliquin, Mathieu},
  title = {Stable Retro, a maintained fork of OpenAI's gym-retro},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/Farama-Foundation/stable-retro}},
}

Papers

List of papers mentioning stable-retro. If you want your paper to be added here please open a github issue.

• Exploration-Driven Generative Interactive Environments
• Gymnasium: A Standardized Interface for Reinforcement Learning Environments
• IPR-1: Interactive Physical Reasoner
• SAFE-SMART: Safety Analysis and Formal Evaluation using STL Metrics for Autonomous RoboTs
• General Modular Harness for LLM Agents in Multi-Turn Gaming Environments