# ТЕХНИЧЕСКОЕ ЗАДАНИЕ ДЛЯ АВТОНОМНОГО АГЕНТА: UI State Machine Bot для Unity

## 1. Цель проекта
Разработать легковесного локального Python-бота на базе конечного автомата (FSM), который управляет поведением в игре на Unity (ОС Windows 10).
Бот не должен вычислять игровые ходы. Его задача — контролировать экраны игры, отслеживать статистику матчей, принудительно сдаваться при достижении лимита побед (для контроля MMR/рейтинга) и перезапускать матчи.

---

## 2. Стек технологий
* **Python:** 3.10+
* **Захват окна / Ввод:** `pyautogui`, `pydirectinput` (для надежного клика в Unity), `win32gui`, `ctypes`
* **Компьютерное зрение:** `opencv-python`, `pillow`
* **Распознавание текста (опционально при динамическом счетчике):** `pytesseract` или `easyocr`
* **Безопасность:** `keyboard` (глобальный аварийный выключатель / Kill Switch)

---

## 3. Архитектура состояний (FSM)

Бот должен опрашивать состояние игры раз в 0.5–1.0 сек и находиться в одном из состояний:

1. **TOWER_LOBBY:**
   * Считывание трофеев через Windows Native OCR (сравнение с верхним/нижним порогом лиги).
   * Проверка прогресса большого сундука с коронами (`read_crown_chest`, счетчик `#/# 👑`). При достижении `5/5` выполняется клик по сундуку для перехода на экран открытия.
   * Сканирование 4 слотов нижних сундуков (`BOTTOM_CHESTS`). Если есть слот `OPEN` -> клик по слоту для открытия и забора наград.
   * Если готовых сундуков нет -> клик по кнопке `FIGHT`. Переход в `IN_GAME`.

2. **IN_GAME (Экран боя):**
   * **FORCED DERANK (Сверхбыстрая капитуляция)**:
     - Сразу после клика `FIGHT` в лобби запускается высокочастотный конвейер `fast_surrender_pipeline` (опрос ROI каждые 20 мс).
     - В первую же миллисекунду после завершения загрузки боя нажимается `Exit` (`btn_exit.png`) через `click_client_pos_fast` (без задержек).
     - Мгновенно опрашивается диалог подтверждения `Leave` (`btn_leave.png`) и нажимается подтверждение.
     - Полный цикл сдачи занимает **< 0.15–0.2 сек** от появления экрана боя, исключая случайную победу автобоя.
   * **NORMAL PLAY**:
     - Ожидание естественного исхода боя (автобой побеждает или терпит поражение).
     - Бот не вмешивается и ожидает `VICTORY_SCREEN` или `DEFEAT_SCREEN`.

3. **VICTORY_SCREEN:**
   * Зафиксировать: `current_wins += 1`, `total_games += 1`.
   * Записать лог: `[WIN] Серия побед: {current_wins}/{max_wins_limit}`.
   * Нажать кнопку `Collect` (`btn_collect_victory.png`).
   * Если были свободные ячейки (`VACANT`) -> переход в `TOWER_LOBBY`.
   * Если свободных ячеек не было -> переход в `NO_FREE_SLOTS_SCREEN`.

4. **DEFEAT_SCREEN:**
   * Зафиксировать: `current_wins = 0` (сброс серии), `total_games += 1`.
   * Записать лог: `[LOSS] Серия сброшена. Всего игр: {total_games}`.
   * Нажать кнопку `Ok` (`btn_ok.png`). Переход в `TOWER_LOBBY`.

5. **CHEST_OPEN_SCREEN (Экран открытия сундуков - нижних и сундука побед с коронами):**
   * Срабатывает при клике по готовому сундуку (`OPEN`) или сундуку с коронами (`5/5 👑`).
   * Шаг 1: Нажать «Turn all cards over» (`btn_turn_all_cards.png`). Ожидание анимации переворота карт.
   * Шаг 2: Нажать «Collect» (`btn_collect.png`). Забор наград и возврат в `TOWER_LOBBY`.

6. **NO_FREE_SLOTS_SCREEN:**
   * Появляется после нажатия `Collect` при отсутствии свободных ячеек сундуков ("You have no slot available for this chest").
   * Опция `Open chest` (`btn_open_chest.png`) обнаруживается ботом (задел на будущее).
   * Нажимается кнопка `Remove chest` (`btn_remove_chest.png`) для сброса лишнего сундука и возврата в `TOWER_LOBBY`.

7. **GLOBAL MODAL / SPECIAL OFFER (Заглушка):**
   * Всплывающее рекламное предложение покупки, появляющееся рандомно или после наград.
   * Проверяется глобально на каждом шаге цикла FSM (`check_and_dismiss_offer_popup`).
   * При обнаружении нажимается кнопка закрытия `X` (`btn_close.png`).

---

## 4. Структура проекта

```text
game_bot/
├── assets/
│   ├── btn_fight.png         # Кнопка старта боя в лобби
│   ├── btn_exit.png          # Кнопка выхода во время боя
│   ├── btn_leave.png         # Кнопка подтверждения выхода (Leave)
│   ├── btn_ok.png            # Кнопка OK на экране поражения
│   ├── btn_close.png         # Кнопка X закрытия рекламных предложений
│   ├── text_defeat.png       # Маркер экрана поражения
│   ├── banner_victory.png    # Маркер экрана победы (баннер)
│   ├── text_victory.png      # Маркер экрана победы (текст)
│   ├── btn_collect_victory.png # Кнопка Collect на экране победы
│   ├── btn_remove_chest.png  # Кнопка Remove chest при отсутствии слотов
│   ├── btn_open_chest.png    # Кнопка Open chest при отсутствии слотов
│   ├── status_open.png       # Маркер готового к открытию сундука
│   ├── status_vacant.png     # Маркер пустого слота сундука
│   ├── btn_turn_all_cards.png# Кнопка открытия всех карт в сундуке
│   └── btn_collect.png       # Кнопка сбора наград сундука
├── config.json               # Конфигурация лимитов и задержек
├── window_utils.py           # Фокусировка и нормализация окна Unity
├── ocr_utils.py              # OCR чтение трофеев (рейтинга)
├── bot_core.py               # Реализация FSM, логики кликов и проверки заглушек
├── calibrate_tool.py         # Утилита для нарезки шаблонов и проверки ROI
└── run.py                    # Точка входа с Kill Switch
```