Mafia Bot

Классическая «Мафия» в Telegram — от создания комнаты до ночных ходов и финального рейтинга.

Important

Проект находится в активной разработке. Базовый игровой цикл реализован, однако перед публичным запуском рекомендуется добавить тесты, миграции базы данных и production-конфигурацию.

О проекте

Mafia Bot переносит ведущего и игровую механику в Telegram. Игроки взаимодействуют с ботом в личных сообщениях, а общие события партии публикуются в привязанном групповом чате.

Сейчас бот поддерживает:

• приватные комнаты с кодом и паролем;
• лобби на 5–11 игроков, статусы готовности и управление участниками;
• классическое и настраиваемое распределение ролей;
• персональную выдачу ролей и карточек;
• последовательность ночных ходов с таймером;
• дневное голосование и автоматическое определение победителя;
• профиль игрока, рейтинг и статистику побед;
• проверку участия игроков в групповом чате.

Роли

В классическом режиме доступны мафия, комиссар, доктор, любовница, маньяк, ангел, призрак и мирный житель. Состав партии автоматически подбирается для 5–11 игроков; владелец комнаты также может настроить роли вручную.

Как проходит партия

Личное сообщение боту
        │
        ├── создание или вход в комнату
        ├── готовность игроков
        └── получение роли
                │
                ▼
        Групповой чат партии
                │
        ночь → действия ролей → итоги
                │
        день  → обсуждение → голосование
                │
                └── проверка победы → новый раунд или завершение

Быстрый старт

Требования

• Python 3.10 или новее;
• PostgreSQL 14 или новее;
• Telegram-бот, созданный через @BotFather.

1. Установка

git clone https://github.com/Weakmafaka/Mafia.git
cd Mafia

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Конфигурация

Скопируйте пример настроек и заполните токен бота:

cp .env.example .env

Переменная	Назначение	Значение по умолчанию
TOKEN	токен Telegram-бота	—
POSTGRES_USER	пользователь PostgreSQL	postgres
POSTGRES_PASSWORD	пароль PostgreSQL	пустая строка
POSTGRES_HOST	адрес PostgreSQL	localhost
POSTGRES_PORT	порт PostgreSQL	5432
POSTGRES_DB	имя базы данных	mafia_bot

Warning

Никогда не публикуйте настоящий токен бота. Файлы .env исключены из Git.

3. База данных

Самый быстрый вариант — запустить PostgreSQL через Docker:

docker compose up -d postgres

При старте приложение создаёт недостающие таблицы и синхронизирует каталог ролей.

4. Запуск бота

python main.py

Откройте личный чат с ботом и отправьте /start. Для полноценной партии добавьте бота в группу и выдайте ему право читать сообщения и отправлять сообщения.

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

Mafia/
├── core/                    # создание Bot и Dispatcher
├── database/
│   ├── controllers/         # комнаты, сессии, ходы и голосования
│   └── models/              # модели SQLAlchemy
├── game/
│   └── classic_mafia/       # роли, баланс и тексты ведущего
├── handlers/
│   └── game_rooms/          # Telegram-сценарии комнаты и партии
├── src/playerСards/         # изображения карточек ролей
├── utils/                   # логирование и проверка групп
└── main.py                  # точка входа

Архитектура

• aiogram 3 обрабатывает команды, callback-кнопки и FSM-состояния.
• SQLAlchemy AsyncIO + asyncpg хранят комнаты, игроков, игровые сессии и действия.
• Игровые правила отделены от Telegram-представления: роли и баланс лежат в game/, состояние — в database/, интерфейс — в handlers/.
• Бот работает через long polling; отдельный веб-сервер не требуется.

Разработка

Проверка синтаксиса всех Python-модулей:

python -m compileall -q .

Основные направления развития проекта:

• покрыть правила и переходы между стадиями автоматическими тестами;
• заменить SQL-команды инициализации на версионируемые миграции Alembic;
• добавить Dockerfile и production-развёртывание;
• вынести длительности стадий и правила рейтинга в конфигурацию;
• реализовать публичный список комнат и полноценные рассылки.

Безопасность

Если токен Telegram-бота когда-либо попадал в коммит, удаление файла из текущей версии недостаточно: перевыпустите токен через @BotFather. Не публикуйте дампы базы данных и содержимое .env.