NES PLAYER
Запуск

Как это запустить

Всё работает локально: macOS на Apple Silicon и Linux x86_64 — из коробки, Windows — через WSL2. Проверено на macOS 26, Python 3.14, PyTorch 2.13 с Metal.

ROM-образы мы не распространяем — в проекте их нет. Свои образы импортируются в эмулятор одной командой.
Обученные модели лежат в релизе репозитория, скачиваются одной командой: uv run python scripts/fetch_models.py. Но они не обязательны: инстинкты играют без всякой модели, а обучить свою на новой игре — около получаса.
01

Установка

Нужен uv — менеджер пакетов и проектов Python от Astral; поставьте его первым (curl -LsSf https://astral.sh/uv/install.sh | sh на macOS и Linux).

git clone https://github.com/\
  Recluse/NES-Player.git
cd NES-Player
uv sync
02

Свои ROM

uv run python -m retro.import \
  /путь/к/ромам
03

Смотреть игру

./start.sh

Графическое меню: игра, режим, чекпоинт, запись видео.

Полный цикл на новой игре

Без единого готового прохождения: инстинкты играют сами, их партии становятся обучающей выборкой, на ней учится сеть. На ноутбуке это занимает около получаса.

# 1. Инстинкты играют и записывают эпизоды (headless, ~1000 кадров/с)
uv run nes-player explore --game Gradius-Nes-v0 \
    --record datasets/explore_gradius --loop --max-frames 3600

# 2. Клонирование поведения: видео + звук + подсказка вниманию
uv run nes-player train-bc --episode datasets/explore_gradius \
    --out runs/bc_gradius --audio --attn 1.0 --epochs 3

# 3. Играем обученной моделью, с окном и звуком
uv run nes-player play --game Gradius-Nes-v0 \
    --checkpoint runs/bc_gradius --window --realtime --hd --auto-start

Полезные ключи

--core nestopia      другое ядро эмуляции (fceumm по умолчанию)
--state default      старт со штатного снапшота: нужен играм,
                     чей титульник не проходится с холодного старта
--planner            планирование поверх модели мира
--ghost runs/ego_x   призрачная траектория на панели
--sound-loc runs/av  показывать, откуда идёт звук
--video-out out.mp4  записать прохождение со звуком
--loop               играть бесконечно (для стрима)

Воспроизвести эксперименты

Каждая цифра с этого сайта получена одним из этих скриптов.

# первое знакомство с игрой: инстинкты против случайного и против базы
uv run python scripts/experiments/zero_shot.py

# перенос на игры, которых не было в обучении
uv run python scripts/experiments/heldout_transfer.py

# куда смотрит модель: доля тепловой карты внутри объектов
uv run python scripts/experiments/cam_focus.py <эпизод> <чекпоинт>

# сравнение ядер эмуляции на чужих записях
uv run python scripts/experiments/core_compare.py

Проверка целостности

В проекте есть регрессионные тесты с золотыми хэшами кадра и звука фиксированного прогона. Именно они поймали молчаливую подмену ядра эмуляции, когда качество деградировало бы без единой ошибки в логах.

uv run pytest -q     # 48 тестов