141 lines
6.4 KiB
Markdown
141 lines
6.4 KiB
Markdown
# 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
|
||
```
|