About this project

stable-retro-scripts is a collection of Python scripts for training reinforcement-learning models to play retro console games. It builds on stable-retro (a fork of gym-retro) and stable-baselines3, and is aimed at users who want to train agents on emulated titles, run model-vs-model matches, or export models for use in emulator frontends. Main capabilities described in the README: - Train models on retro games using scripts such as scripts/train.py, with options for environment, policy network, number of parallel environments, timesteps, and hyperparameters. - Run curriculum-based training through scripts/train_curriculum.py and JSON curriculum files. - Pit two trained models against each other in player-vs-player games, with examples including NHL94, Mortal Kombat, and WWF Wrestlemania: The Arcade Game. - Play against an improved AI opponent. - Export models for use in emulator frontends via the separate retro-ai-runtime project. Supported model architectures listed: MLPs, Nature CNN, Impala CNN, and combined input models (image plus scalar). Attention MLPs are marked experimental. Installation notes: 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, and stable-retro. System packages include python3, pip, venv, git, zlib1g-dev, libopenmpi-dev, ffmpeg, cmake, and libgl1-mesa-dev. Dependencies are installed from requirements.txt, with optional lint tooling in requirements-dev.txt. An editable stable-retro checkout can be installed for emulator development. ROM handling: users must supply their own ROMs; the README notes Airstriker is a public-domain ROM already included in stable-retro. ROMs are imported with python3 -m retro.import. Example commands include training on Airstriker-Genesis with CnnPolicy, 8 environments, 1,000,000 timesteps, and playback enabled, plus running the NHL94 curriculum. The C++ inference library has moved to the retro-ai-runtime repository, which runs exported models inside emulator frontends such as RetroArch to control player input. Training, evaluation, and model export remain in this repository. RetroArch-side integration lives in RetroArchAI. The README also links game-specific pages for NHL94 and WWF Wrestlemania, a WSL2 setup video, and a tutorial video on RetroArch and PyTorch.