OWMixDiscordBot

Discord-бот для проведения миксов по Overwatch.

Описание проекта

Миксы — формат дружеских состязаний: в назначенное время в Discord-канал приходят все желающие, регистрируются в боте (указывают BattleTag и рейтинг по ролям) и участвуют в игровом сеансе. Подробнее о формате можно узнать на Discord-сервере проекта.

Бот берёт на себя рутину такого вечера:

• регистрацию игроков и хранение их рейтинга по ролям (танк/урон/поддержка);
• чек-ин/чек-аут перед стартом и во время вечера — играет только тот, кто отметился;
• автоматическую сборку сбалансированных лобби (10 игроков на лобби: 2 танка, 4 урона, 4 саппорта) с учётом рейтинга и приоритетной роли каждого игрока — если валидный состав из 10 отметившихся игроков математически существует, лобби гарантированно соберётся (двухуровневый алгоритм: быстрый подбор по близости рейтинга, а если он не нашёл состав — точный резервный алгоритм);
• очередь для тех, кто не попал в текущее лобби, — они автоматически попадают в следующее;
• защиту от однообразных составов: бот помнит недавние пары "играли вместе"/"играли друг против друга" и старается не повторять их слишком часто в пределах одного вечера.

Требования

• Python 3.12+
• PostgreSQL (база данных для игроков и очереди)
• Токен Discord-бота (Discord Developer Portal)

Установка

git clone https://github.com/nmkyt/OWMixDiscordBot.git
cd OWMixDiscordBot
python -m venv venv
venv\Scripts\activate       # Windows
# source venv/bin/activate  # Linux/macOS
pip install -r requirements.txt

Скопируйте .env.example в .env и заполните своими значениями:

cp .env.example .env

Переменная	Описание
BOT_TOKEN	Токен Discord-бота
DATABASE_URL	Строка подключения к PostgreSQL, напр. postgresql://user:pass@localhost:5432/owmix
ADMIN_IDS	Discord ID администраторов через запятую (кому доступны !check, !create_lobby, !mix_stop и т.д.)

Таблицы (players, queue) создаются автоматически при первом запуске.

Чтобы стать администратором бота (и получить доступ к проведению миксов), добавьте свой Discord ID в ADMIN_IDS в .env и перезапустите бота — править исходный код для этого не нужно. Узнать свой Discord ID: Настройки пользователя → Расширенные настройки → Режим разработчика, затем ПКМ по себе → «Копировать ID».

Запуск

python -m src.bot_controller

Команды бота

Для всех участников

Команда	Описание
!register BattleTag TankRating DPSRating SupportRating	Регистрация (то же самое — !registration). Рейтинг — число (500-5000) или дивизион (b5…chm1); 0, если роль не играется.
!update TankRating DPSRating SupportRating	Обновление своего рейтинга по ролям. Если обнулить рейтинг на приоритетной роли (или на любой роли при Flex), приоритетной станет первая роль с рейтингом — танк, урон, саппорт; бот об этом сообщит.
!my_rank	Показать свой текущий рейтинг.
!mix_help	Список команд.

Во время чек-ина (!check) участники выбирают приоритетную роль кнопками 🛡️ Tank / 🏹 DPS / 💉 Support / 🎲 Flex, и только после этого могут нажать ✅ Check-in — без выбранной роли бот откажет и попросит сначала выбрать роль. ❌ Check-out работает всегда, без ограничений.

На любую ошибку ввода (неизвестная команда, не хватает или лишние аргументы, неверный рейтинг, нет прав на команду и т.п.) бот отвечает в едином формате — что не так и пример правильной команды:

❌ Танк: неверный рейтинг «abc» — укажите число от 500 до 5000, дивизион (например, d2 или gm3) или 0, если роль не играется.
Пример: `!register Sacr1ficed#2456 4000 d2 3700`

Сбои на стороне бота (например, недоступна БД) помечаются ⚠️.

Для администраторов

Команда	Описание
!check	Открыть чек-ин на вечер миксов.
!create_lobby N	Собрать N сбалансированных лобби из отметившихся игроков.
!queue	Показать текущую очередь ожидания.
!queue_add discord_id	Добавить игрока в очередь вручную.
!queue_remove discord_id	Убрать игрока из очереди.
!queue_clear	Полностью очистить очередь.
!mix_status	Статус миксов: регистрации, чек-ин, приоритетные роли, очередь, на сколько лобби хватает игроков и каких ролей не хватает.
!players	Список отметившихся (checked-in) игроков.
!uncheck discord_id	Снять чек-ин и убрать игрока из очереди.
!user_update discord_id TankRating DPSRating SupportRating	Изменить рейтинг любого игрока.
!mix_stop	Завершить вечер — снять чек-ин со всех игроков и очистить историю анти-повтора.

Типичный сценарий вечера

1. Админ запускает !check — открывается чек-ин.
2. Участники выбирают приоритетную роль, затем нажимают ✅ Check-in.
3. Админ запускает !create_lobby N — бот собирает N лобби из отметившихся игроков; кто не поместился, уходит в очередь и попадёт в следующий вызов !create_lobby в первую очередь.
4. Шаги 3 повторяются весь вечер по мере того, как заканчиваются матчи.
5. В конце вечера админ запускает !mix_stop — все игроки переводятся в статус "не в чек-ине", и очищается история анти-повтора (data/recent_pairs.json), чтобы она не "утекала" в следующий вечер.

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

src/
  bot_controller.py  — команды бота и кнопки чек-ина: разбор аргументов, ответы в чат
  config.py           — конфигурация: Discord-клиент, подключение к БД, run_db()
  models.py           — модели SQLAlchemy (Player, Queue) и ограничения БД
  balancer.py          — сборка сбалансированных лобби, анти-повтор составов
  sync_logic.py        — работа с данными: регистрация и рейтинги игроков, чек-ин, очередь, статистика, карты
tests/                 — юнит-тесты (pytest), см. ниже
data/
  recent_pairs.json    — история недавних составов (создаётся автоматически, не в git)

Тесты

Тесты полностью изолированы от боевого бота и БД: используют одноразовый временный SQLite-файл вместо реального PostgreSQL и не трогают .env / Discord.

pip install -r requirements-dev.txt
pytest