catan/README.md

Settlers of Catan in Python

Полная реализация «Колонизаторов» (Catan) на Python: ядро движка со всеми правилами базовой версии, SDK для обучения моделей, CLI для аналитики и GUI для ручной игры.

Возможности

• Полный набор правил: генерация поля, стартовые постройки в два раунда, добыча ресурсов, разбойник, торговля, развитие, карты развития, «Самая длинная дорога» и «Самая большая армия».
• Модели гекс/вершин/ребер в виде графа с проверками расстояния и связности.
• SDK (catan.sdk.CatanEnv) c перечислением допустимых действий и API, похожим на gym.
• CLI на Typer + Rich для пошаговых партий и дебага.
• GUI на Tkinter с визуализацией гексов, дорог и построек.
• ML-модуль с кодировщиками состояний/действий, случайным агентом, REINFORCE-тренером (PyTorch) и эволюционной стратегией.

Установка

python -m venv .venv
source .venv/bin/activate
pip install -e .

CLI

Запуск новой партии для трёх игроков:

catan-cli "Alice,Bob,Carla"

Основные команды в интерактивном режиме:

• state, board, corners, edges — вывод состояния.
• actions — список допустимых действий из текущего состояния (на базе SDK).
• roll, place <corner> <road>, build settlement|city|road <id> — действия на поле.
• buy dev, play knight|road|yop|monopoly, trade bank ..., trade player ....
• move robber <hex> [victim], discard <player> <resource> <amount> ..., end для завершения хода.
• --random-bot <имя> — назначает игрока случайному агенту (можно указать несколько флагов) для режимов «человек против случайной модели».

Пример игры против случайного соперника:

catan-cli "You,Bot" --random-bot Bot

GUI

catan-gui --players "Alice,Bob,Carla" --seed 42

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

SDK / Использование в обучении

from catan import GameConfig
from catan.sdk import CatanEnv, Action, ActionType

config = GameConfig(player_names=["Alice", "Bob", "Carla"], seed=123)
env = CatanEnv(config)
obs = env.reset()

for step in range(10):
    legal = env.legal_actions()
    action = next(a for a in legal if a.type == ActionType.ROLL)
    obs, reward, done, info = env.step(action)
    if done:
        break

legal_actions() возвращает список Action, содержащих тип действия и полезные параметры (например, доступные гексы для разбойника или список ребер для дороги). env.step() применяет действие к текущему Game, возвращает новое наблюдение, награду (дельта очков) и флаг завершения партии.

Структура проекта

• catan/data.py — перечисления и константы (ресурсы, карты, порты, стоимости).
• catan/board.py — генерация поля, гексов, перекрестков и портов.
• catan/player.py — модель игрока и операции с ресурсами.
• catan/game.py — движок игры, правила, учет победных очков.
• catan/sdk.py — окружение для обучения / автоматизации.
• catan/cli.py и catan/gui.py — интерфейсы для людей (CLI поддерживает ботов).
• catan/ml/ — агенты, кодировщики, обучающие циклы RL/эволюции.
• catan/learning.py — CLI-утилиты для запуска reinforcement learning (REINFORCE).

Reinforcement Learning

catan-learn reinforce --players "Alpha,Beta,Gamma,Delta" --episodes 100 --output policy.pt

По окончании обучения выводится история наград; при указании --output сохраняется state_dict PyTorch.

Web платформа (микросервисы)

Монорепозиторий содержит backend-сервисы и веб-интерфейс:

• services/api — gateway + auth + websockets.
• services/game — игровой сервер (правила + состояния + трейды).
• services/ai — инференс моделей (random / .pt).
• services/analytics — статистика, реплеи, экспорт/импорт.
• web — React-интерфейс (лобби, партии, реплеи).

Запуск в Docker

cp .env.example .env
docker compose up --build

По умолчанию UI доступен на http://localhost (если проксировать через Caddy), а API — на /api.

Caddy (пример)

catan.danosito.com {
  reverse_proxy /api/* api:8000
  reverse_proxy /ws/* api:8000
  reverse_proxy web:80
}

Реплеи

• Экспорт: /api/replays/{id}/export (JSON).
• Импорт: /api/replays/import (JSON).
• В UI доступны импорт/экспорт и пошаговый просмотр.

Тестирование

Минимальная проверка:

python -m catan.cli "Alice,Bob,Carla"
python -m catan.gui --players "Alice,Bob,Carla"

Авто-тесты:

pytest