Морской Бой Бот — это увлекательный Telegram-бот для игры в классический морской бой между двумя игроками! 💥
Погрузитесь в атмосферу морского сражения и испытайте свои тактические навыки на поле боя! ⚔️
- 🆕 Создание новой игры и подключение к существующей.
- 👥 Дуэли между двумя игроками в реальном времени.
- 🤖 Дуэли с ботом разного уровня сложности: от новичка до профи.
- 🔥 Полноценная механика боя с интуитивным вводом координат.
- 🎯 Интерактивные кнопки для выстрелов по полю.
- 📡 Уведомления о ходе игры и результатах выстрелов.
- 🗺️ Отображение своего и вражеского поля.
- 📝 Подробные сообщения о ходе и результатах игры.
- 🏳️ Возможность сдаться в любой момент.
- 📋 Личная статистика – матчи, победы, поражения, рейтинг.
- 📊 Рейтинг игроков на основе системы Elo.
- 🏆️ Общие рекорды игры с информацией о самых активных.
- 🎖️ Ачивки с различными заданиями.
- 📢 Система рассылок для администратора (отправка сообщений всем пользователям).
Классическая игра в современном формате Telegram — с дуэлями, ботами, рейтингом и достижениями!
🎮 Играй как хочешь:
- Против друга в режиме мультиплеера 1×1
- Или против бота — выбери уровень сложности: easy / medium / hard
📈 Прокачивай свой рейтинг:
Каждая победа влияет на твой Elo-рейтинг, по которому формируется таблица лидеров.
🎖 Открывай ачивки:
Выполняй игровые цели и получай уникальные достижения — от «Полного курса капитана» до «Скорострела» ⚡️
🏆 Сравнивай результаты:
Следи за рекордами игроков — самой быстрой победой, лучшей серией, самым активным игроком и другими достижениями.
🧭 Статистика под контролем:
В личном профиле можно посмотреть количество матчей, побед, поражений и текущий рейтинг.
⚓️ Собери все ачивки, победи ИИ на всех уровнях и докажи, что ты — настоящий капитан флота Морского Боя!
Бот реализован с использованием следующих технологий и библиотек:
-
Aiogram — асинхронный фреймворк для создания Telegram-ботов на Python.
Позволяет удобно обрабатывать команды, текстовые сообщения, инлайн- и reply-кнопки, а также работать с контекстом пользователей. Поддерживает фильтры, FSM и middlewares. -
SQLAlchemy — мощная ORM-библиотека для работы с базой данных.
Применяется для хранения информации об игроках, матчах и статистике. Используется как с декларативными моделями, так и с ручными запросами. -
Alembic — инструмент управления миграциями базы данных.
Позволяет отслеживать изменения в моделях и автоматически генерировать SQL-команды для обновления структуры БД без потери данных. -
SQLite — встроенная реляционная база данных.
Проста в использовании, не требует отдельного сервера и отлично подходит для небольших проектов. Все данные хранятся в одном.sqlite3файле. -
Asyncio — стандартная библиотека Python для асинхронного программирования.
Обеспечивает высокую производительность, параллельную обработку сообщений и работу с задержками (например, таймеры и автоудаление игр). -
Python-dotenv — утилита для загрузки переменных окружения из
.envфайла.
Упрощает конфигурацию: токены, секреты и параметры подключения удобно хранить вне кода. -
Logging — встроенный модуль логирования Python.
Используется для ведения журнала событий: действий игроков, ошибок и операций с базой. -
Docker — контейнеризация приложения.
Позволяет легко развернуть бота на любом сервере без ручной настройки окружения. -
Pydantic — для валидации конфигурации и моделей данных (может использоваться в
config.py).
Эта связка технологий обеспечивает стабильную, масштабируемую и легко расширяемую архитектуру бота.
Sea-Battle-Bot/
├── Dockerfile # Docker-конфигурация для сборки контейнера
├── README.md # Документация проекта
├── alembic.ini # Настройки Alembic для миграций
├── requirements.txt # Зависимости проекта
│── .env # Файл с токеном и настройками
│── .env.template # Шаблон .env для примера
│── .gitignore # Исключает .env, __pycache__, venv и др.
│── .dockerignore # Исключает ненужное из Docker-образа
│
├── photos/ # Папка с изображениями для README
│ ├── Example-photo1.png
│ ├── Example-photo2.png
│ └── Example-photo3.png
│
├── alembic/ # Миграции базы данных (Alembic)
│ ├── env.py # Основной файл окружения миграций
│ ├── script.py.mako # Шаблон для автогенерации миграций
│ └── versions/ # Конкретные версии миграций
│ ├── c2c59db636bb_init_db.py # Инициализация базы
│ ├── 9d9e_bot_game_stats.py # Добавление статистики игр с ботом
│ └── a1b2c3_achievements.py # Добавление системы достижений
│
├── app/ # Основная логика Telegram-бота
│ ├── __init__.py
│ ├── bot.py # Точка входа в приложение (run бот)
│ ├── config.py # Конфигурация окружения и переменных
│ ├── database.py # Подключение к БД через SQLAlchemy
│ ├── dependencies.py # Фабрики зависимостей (сессии, подключения)
│ ├── game_logic.py # Логика игрового процесса (ходы, победы, попадания)
│ ├── keyboards.py # Клавиатуры Telegram
│ ├── logger.py # Настройка логирования (bot.log)
│ ├── storage.py # In-memory хранилище активных сессий
│ │
│ ├── db_utils/ # Работа с БД: CRUD и аналитика
│ │ ├── achievements.py # Операции с достижениями (создание, получение)
│ │ ├── bot_stats.py # Статистика игр с ботами
│ │ ├── match.py # CRUD для матчей
│ │ ├── player.py # CRUD для игроков
│ │ ├── records.py # Подсчёт рекордов и аналитика
│ │ └── stats.py # Обновление общей статистики игрока
│ │
│ ├── handlers/ # Обработчики Telegram-команд и callback'ов
│ │ ├── base.py # /start, главное меню, помощь
│ │ ├── game.py # Игровой процесс в мультиплеере
│ │ ├── bot_game.py # Игры против бота
│ │ ├── matchmaking.py # Поиск и создание игр между игроками
│ │ ├── achievements.py # Вывод достижений игрока
│ │ ├── records.py # Показ рекордов и статистики
│ │ ├── stats.py # Общая статистика и рейтинг
│ │ ├── bot_analytics.py # Системная аналитика по ИИ
│ │ ├── broadcast.py # Админ-рассылка сообщений
│ │ └── register.py # Регистрация всех хендлеров
│ │
│ ├── messages/ # Текстовые сообщения и шаблоны
│ │ └── texts.py # Тексты приветствий, описаний и уведомлений
│ │
│ ├── models/ # SQLAlchemy ORM-модели
│ │ ├── base.py # Базовая модель (Base)
│ │ ├── player.py # Модель игрока
│ │ ├── match.py # Модель матча
│ │ ├── player_stats.py # Модель статистики игрока
│ │ ├── bot_game_stats.py # Модель статистики игр с ботом
│ │ └── achievements.py # Модели достижений и связей с игроками
│ │
│ ├── services/ # Бизнес-логика и обработка данных
│ │ ├── game_service.py # Управление in-memory играми
│ │ ├── matchmaking_service.py # Создание / подключение матчей
│ │ ├── player_service.py # Регистрация, обновление и получение игроков
│ │ ├── bot_game_service.py # Игры против ИИ и обновление статистики
│ │ ├── bot_ai.py # Логика поведения ИИ (easy / medium / hard)
│ │ └── achievements_service.py# Проверка и назначение достижений игрокам
│ │
│ ├── state/ # Глобальные состояния и константы
│ │ ├── constants.py # Константы проекта (настройки, лимиты)
│ │ └── in_memory.py # Словари in-memory (игры, очередь, таймеры)
│ │
│ └── utils/ # Вспомогательные утилиты
│ ├── game_cleanup.py # Удаление неактивных игр
│ ├── game_id.py # Генерация уникальных ID матчей
│ ├── none_username.py # Обработка пользователей без username
│ └── rating.py # Реализация рейтинга Elo
│
├── db.sqlite3 # Основная база данных (SQLite)
└── bot.log # Лог-файл работы бота
-
Чёткое разделение ответственности
Логика бота разбита по слоям: обработчики (handlers), бизнес-логика (services), работа с БД (db_utils), утилиты (utils), тексты (messages) — это упрощает навигацию и поддержку кода. -
Принцип единой ответственности (SRP)
Каждый модуль выполняет строго одну задачу — например,matchmaking_service.pyзанимается только матчмейкингом, аplayer_service.py— только регистрацией игроков. -
Масштабируемость
Проект легко расширяется: можно добавлять новые команды, функции, модели без риска "сломать" существующий функционал. -
Переиспользуемость кода
Повторяющаяся логика вынесена в сервисы и утилиты. Это повышает читаемость и снижает дублирование кода. -
Гибкая работа с БД
Используется SQLAlchemy + Alembic для управления схемой БД, что упрощает миграции и поддержку данных. -
Инфраструктура готова к деплою
В проекте предусмотреныDockerfile,.env,.dockerignore, что позволяет быстро развернуть бота на сервере или в контейнере. -
Удобство для команды разработки
Новым разработчикам будет просто разобраться в проекте — структура интуитивно понятна и документирована комментариями. -
Интеграция in-memory и persistent-хранилища
Используется in-memory-хранилище (state/in_memory.py) для быстрого доступа, а также SQL-база для долгосрочного хранения данных (статистика, рейтинги). -
Модульность
Благодаря модульной структуре можно писать unit-тесты на отдельные компоненты без запуска всего бота.
- 🐍 Язык программирования: Python
- 🤖 Фреймворк: Aiogram
- 🗃️ Хранение данных: SQLite с использованием SQLAlchemy и миграций через Alembic
- 🔄 Асинхронность: реализована через asyncio для высокой производительности
-
🗃️ Клонируйте репозиторий:
git clone https://github.com/vladelo-code/Sea-Battle-Bot.git
-
📂 Перейдите в папку проекта:
cd Sea-Battle-Bot -
📦 Установите зависимости:
pip install -r requirements.txt
-
⚙️ Создайте
.envна основе.env.template:cp .env.template .env
Добавьте в
.envследующие переменные:BOT_TOKEN=your_bot_token_here DATABASE_URL=sqlite:///db.sqlite3 ADMIN_ID=your_telegram_id_hereВажно:
ADMIN_ID- это ваш Telegram ID для доступа к функции рассылки. -
🛠️ Примените миграции базы данных:
alembic upgrade head
-
🚀 Запустите бота:
python app/bot.py
-
Клонируйте репозиторий:
git clone https://github.com/vladelo-code/Sea-Battle-Bot.git
-
Перейдите в папку проекта:
cd Sea-Battle-Bot -
Создайте
.envна основе.env.template:cp .env.template .env
Добавьте в
.envследующие переменные:BOT_TOKEN=your_bot_token_here DATABASE_URL=sqlite:///db.sqlite3 ADMIN_ID=your_telegram_id_hereВажно:
ADMIN_ID- это ваш Telegram ID для доступа к функции рассылки. -
Постройте и запустите контейнер:
docker run -it --env-file .env sea-battle-bot
Ты участвуешь в захватывающих морских сражениях, где важны стратегия, точность и удача! Ниже — всё, что нужно знать для побед.
- Цель игры — уничтожить все корабли противника раньше, чем он уничтожит твои.
- Как играть:
- Каждому игроку выдаётся 10×10 поле с размещёнными кораблями.
- Ходы делаются поочерёдно.
- Используйте клавиатуру, чтобы стрелять по координатам (A1, B7 и т.д.).
- 💥 — попадание
❌ — мимо
🚢 — ваш корабль
⬜ — пустая клетка
- Сдаться можно в любой момент, но победа достанется противнику.
- Игра завершается, когда один из игроков уничтожит все корабли соперника.
Также можно играть не только с другими игроками, но и против бота с разными уровнями сложности!
Это отличный способ потренироваться, освоить механику игры и проверить свои стратегии перед дуэлью с реальными соперниками.
Бот имеет 3 режима игры:
-
Легкий 🟢
- Стреляет абсолютно случайно.
- Не использует стратегию добивания.
- Отлично подходит для новичков, чтобы изучить правила игры.
-
Средний 🟡
- Иногда использует шахматную схему поиска (стреляет только по клеткам через одну).
- Это позволяет быстрее находить корабли.
- После попадания бот добивает корабль, стреляя в соседние клетки.
-
Сложный 🔴
- Сочетает сразу несколько стратегий:
- 🔍 Шахматная схема поиска
- 🎲 Случайные выстрелы
- 🕵️ Чуйка (бот «знает» позиции кораблей и иногда стреляет туда с небольшой вероятностью).
- Умеет правильно добивать корабли по линии:
- Определяет направление (горизонтально / вертикально).
- Стреляет вдоль линии, меняя сторону, если промахнулся.
- При первом попадании в корабль бот также стреляет в соседние клетки.
- Сочетает сразу несколько стратегий:
📌 Благодаря такой системе игра с ботом остаётся интересной даже на высоких уровнях — он не действует по одному и тому же сценарию, а постоянно вносит элемент случайности.
❗️ Игры с ботом в статистике и рейтинге не учитываются!
Система рейтинга построена на алгоритме Elo — такой же используется в шахматах и киберспорте:
- 🏁 Начальный рейтинг:
1000 - 🏆 Победитель получает очки
- 💥 Проигравший теряет очки
- 📊 Чем выше рейтинг противника, тем больше можно заработать (или потерять)
- 🔁 Перерасчёт происходит после каждой игры
Рейтинг показывает твой реальный уровень и помогает отслеживать прогресс!
В своём профиле ты найдёшь:
- 🎮 Количество сыгранных матчей
- 🏆 Победы
- 💥 Поражения
- 📈 Текущий рейтинг
- ⚡️ Место в рейтинге
- 📅 Дата регистрации
- 🕰️ Среднее время матча
- ⏳ Суммарное время игр
По команде 🥇 Рейтинг ты увидишь список 10 лучших и 3 худших игроков по рейтингу,
а также своё место в общем списке.
В рейтинге отображаются:
- 🥇 Место игрока
- 👤 Никнейм
- 📈 Текущий рейтинг
Это отличная возможность сравнить свои результаты с другими и побороться за лидерство!
В этом разделе собраны самые яркие достижения игроков:
- ⚡ Самая быстрая игра — показывает матч с минимальной продолжительностью.
- 🔥 Самый долгий стрик побед — игрок, который подряд одержал больше всего побед.
- 💥 Самый долгий стрик поражений — игрок, потерпевший наибольшее количество подряд идущих поражений.
- 🎮 Самый играющий игрок (по количеству игр) — тот, кто сыграл больше всего матчей.
- ⏰ Самый играющий игрок (по времени) — тот, кто провёл в игре больше всего минут.
Эти рекорды обновляются автоматически и отражают реальные достижения игроков!
Ачивки — это особые награды за достижения в игре.
Они помогают проверить свои силы, соревноваться с другими и открывать новые цели!
Каждая ачивка выдаётся автоматически, как только выполнено нужное условие.
В списке достижений можно видеть, какие уже разблокированы ✅, а какие ещё ждут своего часа ❌.
- 🏁 Полный курс капитана — сыграй хотя бы 1 матч с ботом на каждом уровне сложности
- 🌀 Марафонец флота — сыграй суммарно 50 матчей с ботом
- ⚡ Скорострел — выиграй матч в мультиплеере за 1 минуту или меньше
- 🌙 Ночной охотник — сыграй матч с другом между 0:00 и 3:00 по МСК
- 🌞 Утренний моряк — сыграй матч с другом между 5:00 и 8:00 по МСК
- 🔥 Серийный победитель — выиграй 10 матчей в мультиплеере подряд
- 😴 Лёгкий ветер — выиграй 20 матчей на уровне «easy»
- 🌊 Средний мастер морей — выиграй 10 матчей на уровне «medium»
- 🔱 Мастер сложности — выиграй 5 матчей на уровне «hard»
- 🏆 Отважный проигравший — проиграй (но не сдайся!) 5 раз подряд в мультиплеере
- 📅 Постоянный моряк — играй хотя бы 1 матч в мультиплеере каждый день в течение недели
- 🤩 Фанат — сыграй матч с разработчиком — @vladelo
Для администратора бота доступна функция рассылки сообщений всем зарегистрированным пользователям:
-
Добавьте ваш Telegram ID в
.envфайл:ADMIN_ID=your_telegram_id_here -
Как узнать свой Telegram ID:
- Напишите боту @userinfobot
- Запустите бота - в главном меню появится кнопка "📢 Рассылка"
- Нажмите "📝 Новое сообщение" для создания рассылки
- Отправьте текст сообщения боту
- Выберите действие:
- "📢 Отправить всем" - разослать сообщение всем пользователям
- "❌ Отменить" - отменить рассылку
- Ограничение скорости: 1 сообщение в секунду (защита от блокировки)
- Обработка ошибок: автоматическая обработка заблокированных пользователей
- Очистка клавиатур: все сообщения отправляются без клавиатур
- Призыв к действию: каждое сообщение заканчивается предложением начать игру
/start - Статистика: отображение количества успешно отправленных сообщений
- Доступ к рассылке только у администратора (проверка по
ADMIN_ID) - Защита от флуда с ограничением скорости отправки
- Обработка ошибок при отправке заблокированным пользователям
-
Чтобы скрыть
BOT_TOKEN, не загружайте.envв Git (он уже в.gitignore). -
Бот поддерживает InlineKeyboardMarkup и KeyboardButton для функционирования кнопок управления.
-
База данных SQLite создаётся автоматически при первом запуске миграций с помощью Alembic, поэтому никаких дополнительных действий по созданию базы не требуется.
-
Все изменения структуры базы данных управляются миграциями, которые необходимо применять перед запуском бота.
Автор: Владислав Лахтионов
GitHub: vladelo-code
Gitverse: vladelo
Telegram: @vladelo
💌 Не забудьте поставить звезду ⭐ на GitHub, если вам понравился бот! 😉