volandsz/DirtyLeague_Bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add setup and execution instructions and setup.bat script

Browse Source
This commit is contained in:
VolandSZ
2026-09-20 21:08:41 +03:00
parent f496f0e6a8
commit 7a9112cb9f
3 changed files with 319 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
README.md
View File

@ -1,2 +1,153 @@
# DirtyLeague_Bot
# DirtyLeague Autonomous FSM Bot
Автономный бот для игры **DirtyLeague** на движке Unity (Windows), основанный на конечном автомате (FSM), компьютерном зрении (OpenCV Template Matching) и Windows Native OCR.
Бот автоматически управляет экранами игры, отслеживает статистику матчей, собирает сундуки (нижние 4 слота и сундук корон), контролирует трофеи/MMR и выполняет мгновенную капитуляцию при достижении лимита побед или превышении порога кубков.
---
## 📋 Требования к системе
* **ОС:** Windows 10 или Windows 11 (64-bit) — необходима поддержка встроенного Windows Media OCR (`winsdk`).
* **Python:** версия 3.10, 3.11 или 3.12 (обязательно отметить галочку *"Add python.exe to PATH"* при установке).
* **Права:** Запуск командной строки / батника с правами **Администратора** (необходимо для перехвата глобального Kill Switch клавишей `Q` и корректной эмуляции кликов в окно Unity).
* **Игра:** Запущенная игра DirtyLeague (рекомендуемое разрешение: 1920×1080 или в окне с соотношением 16:9).
---
## 🚀 Быстрая установка на новом компьютере
### Шаг 1. Клонирование репозитория
Откройте командную строку (CMD или PowerShell) и выполните:
```bash
git clone https://gitem.volandsz.ru/volandsz/DirtyLeague_Bot.git
cd DirtyLeague_Bot
```
### Шаг 2. Автоматическая установка (Рекомендуется)
Запустите скрипт `setup.bat`:
* Двойным кликом по файлу **`setup.bat`**, либо через консоль:
```cmd
setup.bat
```
Скрипт автоматически проверит наличие Python, создаст виртуальное окружение `.venv` и установит все необходимые зависимости из `requirements.txt`.
### Альтернатива: Ручная установка через консоль
Если вы предпочитаете настроить окружение вручную:
```bash
# 1. Создание виртуального окружения
python -m venv .venv
# 2. Активация окружения (Windows CMD):
.venv\Scripts\activate.bat
# Или в PowerShell:
# .venv\Scripts\Activate.ps1
# 3. Обновление pip и установка пакетов
pip install --upgrade pip
pip install -r requirements.txt
```
---
## ⚙️ Конфигурация (`config.json`)
Основные параметры бота настраиваются в файле `config.json`:
```json
{
"target_window": {
"title": "DirtyLeague",
"process_name": "DirtyLeague.exe"
},
"bot": {
"max_wins_limit": 3,
"poll_interval_sec": 0.8,
"confidence_threshold": 0.8,
"action_delay_sec": 0.5,
"kill_switch_key": "q"
},
"league_retention": {
"upper_trophy_threshold": 2125,
"lower_trophy_threshold": 125,
"points_per_win": 50,
"points_per_loss": 50
},
"assets_dir": "assets",
"log_level": "INFO"
}
```
* **`max_wins_limit`**: Максимальное количество побед подряд до включения режима сброса рейтинга (слива боев).
* **`upper_trophy_threshold`**: Верхний порог кубков лиги (при превышении бот начинает быстро сдаваться).
* **`lower_trophy_threshold`**: Нижний порог кубков (при опускании ниже бот играет на победу).
* **`kill_switch_key`**: Клавиша для экстренного выключения бота (по умолчанию `q`).
---
## 🎮 Запуск бота
> ⚠️ **Важно:** Рекомендуется запускать от имени **Администратора**, чтобы бот мог перехватывать нажатие Kill Switch и посылать клики в окно игры.
### Способ 1: Быстрый запуск через батник
1. Запустите игру **DirtyLeague** и откройте главное лобби (экран башни).
2. Нажмите правой кнопкой мыши по **`start_bot.bat`** -> **Запуск от имени администратора** (или просто двойным кликом).
### Способ 2: Запуск через командную строку
```bash
# Активируйте виртуальное окружение
.venv\Scripts\activate
# Обычный запуск (бесконечный цикл до нажатия Q или Ctrl+C)
python run.py
# Ограничить работу по времени (например, 3600 секунд):
python run.py --duration 3600
# Ограничить работу количеством боев/циклов (например, 20 боев):
python run.py --cycles 20
```
---
## 🛑 Управление и безопасность
* **Экстренная остановка (Kill Switch):** Нажмите клавишу **`Q`** в любой момент времени (в том числе в свернутом режиме). Бот немедленно остановит клики и завершит работу.
* **Логирование:** Все действия бота подробно записываются в консоль и сохраняются в папку `logs/` в формате `bot_YYYYMMDD_HHMMSS.log`.
---
## 📂 Структура проекта
```text
DirtyLeague_Bot/
├── assets/ # Эталонные шаблоны UI (кнопки, баннеры, сундуки)
├── logs/ # Автоматические логи работы бота
├── bot_core.py # Главный конечный автомат (FSM) и логика принятия решений
├── window_utils.py # Захват экрана, фокус окна, масштабирование кликов (Unity Canvas Scaler)
├── ocr_utils.py # Windows Native Media OCR для считывания трофеев и счетчиков
├── calibrate_tool.py # Инструмент калибровки и нарезки шаблонов
├── run.py # Точка входа в программу с обработкой Kill Switch
├── config.json # Файл конфигурации параметров
├── requirements.txt # Список зависимостей Python
├── setup.bat # Скрипт автоматической установки окружения
├── start_bot.bat # Скрипт быстрого запуска бота
└── README.md # Инструкция по установке и запуску
```
---
## 🛠️ Возможные проблемы и решения
1. **`Target window 'DirtyLeague' not found`**
* Убедитесь, что игра запущена. Заголовок окна должен содержать `DirtyLeague`.
2. **`PermissionError` или не реагирует клавиша `Q`**
* Запустите консоль или `start_bot.bat` с правами **Администратора** (библиотека `keyboard` требует повышенных привилегий в Windows).
3. **Ошибки `winsdk` / OCR**
* Убедитесь, что в Windows установлен языковой пакет английского языка (Settings -> Time & Language -> Language & Region).

216
concept.md
View File

@ -1,93 +1,123 @@
# ТЕХНИЧЕСКОЕ ЗАДАНИЕ ДЛЯ АВТОНОМНОГО АГЕНТА: 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
```
# ТЕХНИЧЕСКОЕ ЗАДАНИЕ ДЛЯ АВТОНОМНОГО АГЕНТА: 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
├── setup.bat # Скрипт быстрой автоматической установки (.venv + requirements)
├── start_bot.bat # Скрипт быстрого запуска бота
└── run.py # Точка входа с Kill Switch
```
---
## 5. Инструкции по установке и запуску на новом ПК
### Системные требования
* **ОС:** Windows 10/11 x64 (поддержка Windows Media OCR `winsdk`).
* **Python:** 3.10+ (с добавлением в `PATH`).
* **Права:** Запуск от имени Администратора (для `keyboard` Kill Switch и эмуляции кликов в Unity).
### Установка (в 1 клик)
1. Склонировать репозиторий:
```bash
git clone https://gitem.volandsz.ru/volandsz/DirtyLeague_Bot.git
cd DirtyLeague_Bot
```
2. Запустить скрипт **`setup.bat`** (создаст `.venv` и установит все зависимости из `requirements.txt`).
### Запуск
1. Запустить игру **DirtyLeague** в окне или полноэкранном режиме (1920x1080 / 16:9).
2. Запустить бота:
* Через **`start_bot.bat`** (ПКМ -> Запуск от имени администратора).
* Либо через командную строку:
```bash
.venv\Scripts\activate
python run.py
```
3. **Экстренная остановка:** Нажатие клавиши **`Q`** в любой момент.

44
setup.bat Normal file
View File

@ -0,0 +1,44 @@
@echo off
chcp 65001 > nul
echo ========================================================
echo DirtyLeague Bot - Setup and Installation
echo ========================================================
echo.
echo [1/3] Checking Python installation...
python --version > nul 2>&1
if %ERRORLEVEL% neq 0 (
echo [ERROR] Python not found in PATH!
echo Please install Python 3.10 or newer and make sure to check "Add python.exe to PATH".
pause
exit /b 1
)
echo [2/3] Creating virtual environment (.venv)...
if not exist ".venv" (
python -m venv .venv
if %ERRORLEVEL% neq 0 (
echo [ERROR] Failed to create virtual environment!
pause
exit /b 1
)
) else (
echo Virtual environment already exists (.venv).
)
echo [3/3] Installing dependencies from requirements.txt...
call .venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -r requirements.txt
if %ERRORLEVEL% neq 0 (
echo [ERROR] Failed to install requirements!
pause
exit /b 1
)
echo.
echo ========================================================
echo Installation completed successfully!
echo You can now launch the bot using start_bot.bat
echo ========================================================
pause