c89609fe77
- Rename `retro-gamer create` to `retro-gamer init` with positional args (GAME OUTPUT) instead of --game/--output flags - Add [tool.retro-gamer].factory = "module:attr" to declare the game factory function from pyproject.toml instead of relying on a hard-coded create_game attribute - Remove extras_size from user-facing config; it is now measured automatically from a sample observation and never declared - Update docs throughout: create→init, runs/→training/, add factory field documentation, clarify [model] vs [training] hyperparameter sections, remove stale version-history explanations - Bump version to 0.3.0; require retro-games>=2.5.0
78 lines
2.3 KiB
ReStructuredText
78 lines
2.3 KiB
ReStructuredText
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 <https://retro-games.readthedocs.io/en/latest/>`__
|
|
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:
|
|
|
|
Installation
|
|
------------
|
|
|
|
Prerequisites
|
|
~~~~~~~~~~~~~
|
|
|
|
``retro-gamer`` requires Python 3.11 or higher and a game implemented
|
|
with `retro-games <https://retro-games.readthedocs.io/en/latest/>`__.
|
|
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
|
|
:ref:`installation`.
|
|
|
|
**Add to a project** using ``uv`` or ``pip``:
|
|
|
|
.. code-block:: console
|
|
|
|
% uv add retro-gamer
|
|
% pip install retro-gamer
|
|
|
|
**Install as a global tool** (available everywhere, no project needed):
|
|
|
|
.. code-block:: console
|
|
|
|
% uv tool install retro-gamer
|
|
|
|
Verify the installation by checking the command-line tool:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:caption: Contents:
|
|
|
|
introduction
|
|
background
|
|
walkthrough
|
|
troubleshooting
|
|
reference
|
|
integration
|
|
api
|
|
contributing
|