🚀 👉 Перейти к боту в Telegram

Морской Бой Бот 🌊

Морской Бой Бот — это увлекательный Telegram-бот для игры в классический морской бой между двумя игроками! 💥
Погрузитесь в атмосферу морского сражения и испытайте свои тактические навыки на поле боя! ⚔️

🚀 Перейти к боту в Telegram

🎮 Основные возможности

• 🆕 Создание новой игры и подключение к существующей.
• 👥 Дуэли между двумя игроками в реальном времени.
• 🤖 Дуэли с ботом разного уровня сложности: от новичка до профи.
• 🔥 Полноценная механика боя с интуитивным вводом координат.
• 🎯 Интерактивные кнопки для выстрелов по полю.
• 📡 Уведомления о ходе игры и результатах выстрелов.
• 🗺️ Отображение своего и вражеского поля.
• 📝 Подробные сообщения о ходе и результатах игры.
• 🏳️ Возможность сдаться в любой момент.
• 📋 Личная статистика – матчи, победы, поражения, рейтинг.
• 📊 Рейтинг игроков на основе системы Elo.
• 🏆️ Общие рекорды игры с информацией о самых активных.
• 🎖️ Ачивки с различными заданиями.
• 📢 Система рассылок для администратора (отправка сообщений всем пользователям).

🚀 Как начать игру

🚀 Перейти к боту в Telegram

Классическая игра в современном формате 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 для высокой производительности

📝 Установка и запуск

🔧 Вариант 1: Локальный запуск

1. 🗃️ Клонируйте репозиторий:

2. 📂 Перейдите в папку проекта:

3. 📦 Установите зависимости:

4. ⚙️ Создайте

   .env
   на основе
   .env.template
   :

   Добавьте в

   .env
   следующие переменные:

   BOT_TOKEN=your_bot_token_here
   DATABASE_URL=sqlite:///db.sqlite3
   ADMIN_ID=your_telegram_id_here
   

   Важно:

   ADMIN_ID
   - это ваш Telegram ID для доступа к функции рассылки.

5. 🛠️ Примените миграции базы данных:

6. 🚀 Запустите бота:

🐳 Вариант 2: Запуск через Docker

1. Клонируйте репозиторий:

2. Перейдите в папку проекта:

3. Создайте

   .env
   на основе
   .env.template
   :

   Добавьте в

   .env
   следующие переменные:

   BOT_TOKEN=your_bot_token_here
   DATABASE_URL=sqlite:///db.sqlite3
   ADMIN_ID=your_telegram_id_here
   

   Важно:

   ADMIN_ID
   - это ваш Telegram ID для доступа к функции рассылки.

4. Постройте и запустите контейнер:

💡 Подробнее про геймплей

Ты участвуешь в захватывающих морских сражениях, где важны стратегия, точность и удача! Ниже — всё, что нужно знать для побед.

📜 Правила игры

1. Цель игры — уничтожить все корабли противника раньше, чем он уничтожит твои.
2. Как играть:
   • Каждому игроку выдаётся 10×10 поле с размещёнными кораблями.
   • Ходы делаются поочерёдно.
   • Используйте клавиатуру, чтобы стрелять по координатам (A1, B7 и т.д.).
   • 💥 — попадание
     ❌ — мимо
     🚢 — ваш корабль
     ⬜ — пустая клетка
3. Сдаться можно в любой момент, но победа достанется противнику.
4. Игра завершается, когда один из игроков уничтожит все корабли соперника.

🤖 Игра против бота

Также можно играть не только с другими игроками, но и против бота с разными уровнями сложности!

Это отличный способ потренироваться, освоить механику игры и проверить свои стратегии перед дуэлью с реальными соперниками.

⚙️ Уровни сложности

Бот имеет 3 режима игры:

1. Легкий 🟢

   • Стреляет абсолютно случайно.
   • Не использует стратегию добивания.
   • Отлично подходит для новичков, чтобы изучить правила игры.

2. Средний 🟡

   • Иногда использует шахматную схему поиска (стреляет только по клеткам через одну).
   • Это позволяет быстрее находить корабли.
   • После попадания бот добивает корабль, стреляя в соседние клетки.

3. Сложный 🔴

   • Сочетает сразу несколько стратегий:
     • 🔍 Шахматная схема поиска
     • 🎲 Случайные выстрелы
     • 🕵️ Чуйка (бот «знает» позиции кораблей и иногда стреляет туда с небольшой вероятностью).
   • Умеет правильно добивать корабли по линии:
     • Определяет направление (горизонтально / вертикально).
     • Стреляет вдоль линии, меняя сторону, если промахнулся.
   • При первом попадании в корабль бот также стреляет в соседние клетки.

📌 Благодаря такой системе игра с ботом остаётся интересной даже на высоких уровнях — он не действует по одному и тому же сценарию, а постоянно вносит элемент случайности.

❗️ Игры с ботом в статистике и рейтинге не учитываются!

🧮 Как работает рейтинг (Elo)

Система рейтинга построена на алгоритме Elo — такой же используется в шахматах и киберспорте:

• 🏁 Начальный рейтинг:
  1000
• 🏆 Победитель получает очки
• 💥 Проигравший теряет очки
• 📊 Чем выше рейтинг противника, тем больше можно заработать (или потерять)
• 🔁 Перерасчёт происходит после каждой игры

Рейтинг показывает твой реальный уровень и помогает отслеживать прогресс!

👤 Мой профиль

В своём профиле ты найдёшь:

• 🎮 Количество сыгранных матчей
• 🏆 Победы
• 💥 Поражения
• 📈 Текущий рейтинг
• ⚡️ Место в рейтинге
• 📅 Дата регистрации
• 🕰️ Среднее время матча
• ⏳ Суммарное время игр

🥇 Рейтинг

По команде

В рейтинге отображаются:

• 🥇 Место игрока
• 👤 Никнейм
• 📈 Текущий рейтинг

Это отличная возможность сравнить свои результаты с другими и побороться за лидерство!

🏆 Рекорды игры

В этом разделе собраны самые яркие достижения игроков:

• ⚡ Самая быстрая игра — показывает матч с минимальной продолжительностью.
• 🔥 Самый долгий стрик побед — игрок, который подряд одержал больше всего побед.
• 💥 Самый долгий стрик поражений — игрок, потерпевший наибольшее количество подряд идущих поражений.
• 🎮 Самый играющий игрок (по количеству игр) — тот, кто сыграл больше всего матчей.
• ⏰ Самый играющий игрок (по времени) — тот, кто провёл в игре больше всего минут.

Эти рекорды обновляются автоматически и отражают реальные достижения игроков!

🎖 Ачивки Морского Боя

Ачивки — это особые награды за достижения в игре.
Они помогают проверить свои силы, соревноваться с другими и открывать новые цели!
Каждая ачивка выдаётся автоматически, как только выполнено нужное условие.

В списке достижений можно видеть, какие уже разблокированы ✅, а какие ещё ждут своего часа ❌.

📜 Список всех ачивок:

1. 🏁 Полный курс капитана — сыграй хотя бы 1 матч с ботом на каждом уровне сложности
2. 🌀 Марафонец флота — сыграй суммарно 50 матчей с ботом
3. ⚡ Скорострел — выиграй матч в мультиплеере за 1 минуту или меньше
4. 🌙 Ночной охотник — сыграй матч с другом между 0:00 и 3:00 по МСК
5. 🌞 Утренний моряк — сыграй матч с другом между 5:00 и 8:00 по МСК
6. 🔥 Серийный победитель — выиграй 10 матчей в мультиплеере подряд
7. 😴 Лёгкий ветер — выиграй 20 матчей на уровне «easy»
8. 🌊 Средний мастер морей — выиграй 10 матчей на уровне «medium»
9. 🔱 Мастер сложности — выиграй 5 матчей на уровне «hard»
10. 🏆 Отважный проигравший — проиграй (но не сдайся!) 5 раз подряд в мультиплеере
11. 📅 Постоянный моряк — играй хотя бы 1 матч в мультиплеере каждый день в течение недели
12. 🤩 Фанат — сыграй матч с разработчиком — @vladelo

📢 Система рассылок

Для администратора бота доступна функция рассылки сообщений всем зарегистрированным пользователям:

🔧 Настройка рассылки

1. Добавьте ваш Telegram ID в

   .env
   файл:

   ADMIN_ID=your_telegram_id_here
   

2. Как узнать свой Telegram ID:

   • Напишите боту @userinfobot

📱 Использование рассылки

1. Запустите бота - в главном меню появится кнопка "📢 Рассылка"
2. Нажмите "📝 Новое сообщение" для создания рассылки
3. Отправьте текст сообщения боту
4. Выберите действие:
   • "📢 Отправить всем" - разослать сообщение всем пользователям
   • "❌ Отменить" - отменить рассылку

⚡ Особенности рассылки

• Ограничение скорости: 1 сообщение в секунду (защита от блокировки)
• Обработка ошибок: автоматическая обработка заблокированных пользователей
• Очистка клавиатур: все сообщения отправляются без клавиатур
• Призыв к действию: каждое сообщение заканчивается предложением начать игру
  /start
• Статистика: отображение количества успешно отправленных сообщений

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

• Доступ к рассылке только у администратора (проверка по
  ADMIN_ID
  )
• Защита от флуда с ограничением скорости отправки
• Обработка ошибок при отправке заблокированным пользователям

🛠 Дополнительно

• Чтобы скрыть

  BOT_TOKEN
  , не загружайте
  .env
  в Git (он уже в
  .gitignore
  ).

• Бот поддерживает InlineKeyboardMarkup и KeyboardButton для функционирования кнопок управления.

• База данных SQLite создаётся автоматически при первом запуске миграций с помощью Alembic, поэтому никаких дополнительных действий по созданию базы не требуется.

• Все изменения структуры базы данных управляются миграциями, которые необходимо применять перед запуском бота.

📬 Контакты

🚀 Перейти к боту в Telegram

Автор: Владислав Лахтионов
GitHub: vladelo-code
Gitverse: vladelo
Telegram: @vladelo

💌 Не забудьте поставить звезду ⭐ на GitHub, если вам понравился бот! 😉