retro-gamer: train agents to play retro games
retro-gamer is a Python package for training reinforcement learning
agents to play games implemented with the
retro-games
framework. It is designed as a learning tool: rather than writing the
learning algorithm yourself, you describe the game to the trainer in a
structured way, adjust the training parameters, and then observe—through
a detailed log—how the trainer uses your description to build and run a
learning model.
The central idea is that the game becomes an object to think with about reinforcement learning. The choices you make—which characters to tell the trainer about, what counts as a reward, whether to treat the board as a spatial scene or a readout—have direct, observable consequences for how learning proceeds. Working out why a training run behaves as it does is the kind of reasoning that leads to lasting understanding of the underlying concepts.
Installation
Prerequisites
retro-gamer requires Python 3.11 or higher and a game implemented
with retro-games.
The retro-games framework must also be installed; see its documentation
for instructions.
If you are working through a Making With Code lab, retro-gamer is
already installed in your project environment — skip ahead to
Installation.
Add to a project using uv or pip:
% uv add retro-gamer
% pip install retro-gamer
Install as a global tool (available everywhere, no project needed):
% uv tool install retro-gamer
Verify the installation by checking the command-line tool:
% retro-gamer --help
Usage: retro-gamer [OPTIONS] COMMAND [ARGS]...
Train and run RL agents for retro games.
Commands:
init Initialize a new training run directory with config.toml.
info Print a summary of a training run.
play Watch a trained agent play the game.
train Train (or resume training) a DQN agent.