🧩 Telegram Bot — Квест с Excel

Telegram-бот для проведения квестов, викторин и интерактивных игр.
Инструмент подходит для корпоративных мероприятий, онлайн-квестов и игр с друзьями.
Основные возможности:

• Простая регистрация команд.
• Выдача вопросов с подсказками и пропуском.
• Начисление баллов и формирование рейтинга.
• Управление процессом через команды администратора.
• Хранение данных в Excel для гибкой настройки.

📑 Оглавление

• Механика игры
• 📂 Структура проекта
• ⚙ Требования
• 🛠 Установка и настройка
• ▶ Запуск бота
• ✅ Команды для игроков
• 🛠 Команды администратора
• 🔧 Как работает автоподсказка команд
• 📌 Примечания
• ✅ Контрибьютинг

🎮 Механика игры

👤 Игрок

• Регистрируется через /register и указывает название команды.
• Получает вопросы последовательно.
• Может:
  • Отправлять ответы в чат (бот проверяет автоматически).
  • Использовать подсказки (каждая стоит определённое количество баллов).
  • Пропускать вопрос (минус 3 балла).
• После последнего вопроса бот сообщает об окончании игры.

🛠 Администратор

• Управляет процессом:
  • Запускает игру (/startgame) — вопросы рассылаются участникам.
  • Останавливает (/stopgame) — начисляет бонусы за скорость.
  • Сбрасывает игру (/resetgame) — очищает данные участников.
  • Делает рассылки (/broadcast) — отправляет сообщение всем.
  • Сменяет лидера команды (/changeleader).
• Админские права выдаются через /setadmin <пароль>.
• При остановке игры (/stopgame) бот фиксирует время завершения команд и автоматически начисляет бонусы за скорость:
  • 1 место: +3 балла
  • 2 место: +2 балла
  • 3 место: +1 балл

---

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

project/
├── main.py                 # Главный файл для запуска бота
├── config.py               # Конфигурация (TOKEN, пути, настройки)
├── excel_utils.py          # Работа с Excel
├── keyboards.py            # Генерация inline-кнопок
├── state_manager.py        # Хранение временного состояния игроков
├── handlers/
│   ├── user.py             # Логика игроков
│   └── admin.py            # Логика администратора
├── media/
│   └── QustData.xlsx       # Файл с вопросами и участниками
├── requirements.txt        # Зависимости
└── README.md               # Инструкция по установке

---

⚙ Требования

• Python 3.10+
• Установленные зависимости из requirements.txt

---

🛠 Установка и настройка

🔑 Настройка кода

1. В файле config.py:
   • Укажите токен бота:

   TOKEN = "ВАШ_ТОКЕН"

   • Задайте пароль администратора:

   ADMIN_PASSWORD = "MySecret123"

📄 Настройка Excel

1. В папке media/ находится QustData.xlsx.
2. Листы:
   • Участники: оставить только заголовки.
   • База: заполнить:
     • A1 — название квеста.
     • Вопросы (строки 2), подсказки, их стоимость, ответы (строка "Ответы").
3. Перед запуском убедитесь, что лист Участники пуст (нет старых игроков).

---

▶ Запуск бота

python main.py

---

✅ Команды для игроков

• /start — начать работу с ботом.
• /register — зарегистрировать команду.
• /rating — посмотреть рейтинг.
• /help — список команд.

---

🛠 Команды администратора

• /setadmin <пароль> — получить права админа.
• /startgame — запустить игру.
• /stopgame — завершить игру.
• /resetgame — сбросить игру.
• /broadcast <текст> — сделать рассылку.
• /changeleader <old_id> <new_id> — сменить лидера команды.

---

🔧 Как работает автоподсказка команд

• При старте бот регистрирует команды для всех.
• После /setadmin админ получает свои команды.
• Для добавления автоподсказок используется метод:

await bot.set_my_commands(commands)

---

📌 Примечания

• Все действия игроков логируются в Excel.
• Для корректной работы убедитесь, что структура Excel сохранена.
• Обработчики сообщений удаляют пользовательские ответы (чат остаётся чистым).

---

✅ Контрибьютинг

Pull requests приветствуются! Если нашли баг или хотите улучшить проект — создайте issue или PR.

---