stable-retro scripts

• Train models on retro games
• Pit two models against each other on PvP retro games such as NHL94, Mortal Kombat or WWF Wrestlemania: The Arcade Game
• Play against an improved AI opponent
• Emulator Frontend library using Pytorch C++ to able to play with or against stable-retro models in apps like RetroArch

Supported models

• MLPs
• Nature CNN (from DeepMind)
• Impala CNN (from DeepMind)
• Combined Input models (image + scalar)

Experimental:

• Attention MLPs

NHL94 (1 on 1)	Wrestlemania: The Arcade game	Virtua Fighter 1

Installation

Tested on Ubuntu 22.04/24.04 and Windows 11 WSL2 (Ubuntu 22.04 VM)

Requires:

• Python 3.10 through 3.12
• gymnasium
• stable-baselines3
• stable-retro (fork of gym-retro)

sudo apt update
sudo apt-get install python3 python3-pip python3-venv git zlib1g-dev libopenmpi-dev ffmpeg cmake libgl1-mesa-dev

python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

The manifest records minimum known-working versions and allows pip to select current compatible releases. To install lint tooling as well:

python3 -m pip install -r requirements-dev.txt

If you need an editable stable-retro checkout for emulator development, clone the pinned release beside this repository and replace the installed wheel:

git clone --branch v1.0.1 --depth 1 https://github.com/Farama-Foundation/stable-retro.git ../stable-retro
python3 -m pip install --no-deps -e ../stable-retro

Windows WSL2 + Ubuntu 22.04 setup guide: https://www.youtube.com/watch?v=vPnJiUR21Og

Install roms

You need to provide your own roms

In your rom directory exec this command, it will import the roms into stable-retro

python3 -m retro.import .

All command examples below assume you run them from the repository root.

Train a model

Note: Airstriker is a public domain rom and is already included in stable-retro

python3 scripts/train.py --env=Airstriker-Genesis --nn=CnnPolicy --num_env=8 --num_timesteps=1_000_000 --play --hyperparams=../hyperparams/default.json

Run a curriculum

python3 scripts/train_curriculum.py --curriculum curriculum/nhl94.json

Game specific Examples

• For NHL94 specific page click here
• For Wrestlemania the arcade game specific page click here

retro ai lib

C++ lib using Pytorch that runs models inside emulator frontends like retro arch to override player input. Which means you can play against a smarter opponent at NHL94 for example or let the AI play with you in COOP or play for you.

See README for build and install instructions

Tutorial video: