# 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) и эволюционной стратегией.

## Установка

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

## CLI

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

```bash
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 <имя>` — назначает игрока случайному агенту (можно указать несколько флагов) для режимов «человек против случайной модели».

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

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

## GUI

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

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

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

```python
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

```bash
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

```bash
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 доступны импорт/экспорт и пошаговый просмотр.

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

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

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

Авто-тесты:

```bash
pytest
```