Технический взгляд на Telegram-бота "Мини казино ✨MaxSlot✨"

Эта статья посвящена техническим аспектам разработки Telegram-бота, реализующего простое мини-казино со слотами. Мы рассмотрим использованные подходы, стек технологий и ключевые моменты реализации, основываясь на нашем опыте.

Введение

Наш бот "Мини казино ✨MaxSlot✨" @maxslot_bot предоставляет пользователям возможность сыграть в простые слоты непосредственно в Telegram. Бот предлагает два режима игры: на виртуальные очки и на условный "реальный" баланс, а также поддерживает несколько языков.

Стек технологий

Основу нашего бота составляет асинхронный фреймворк для разработки Telegram-ботов на Python – Aiogram 3.x. Выбор Aiogram обусловлен его гибкостью, асинхронностью и мощными инструментами для обработки обновлений от Telegram.

Для реализации многоязычности мы использовали библиотеку Fluent (спецификация Project Fluent), которая отлично подходит для гибкой локализации текстовых ресурсов.

Для хранения временного состояния пользователей (например, текущая ставка, режим игры) мы использовали Finite State Machine (FSM) от Aiogram, сконфигурированный для работы с Redis. Redis обеспечивает быстрое и энергонезависимое хранение состояния, что важно при перезапусках бота (хотя для полноценного сохранения баланса потребовалась база данных).

Таким образом, наш основной стек выглядит так:

Язык программирования: Python
Фреймворк бота: Aiogram 3.x
Локализация: Fluent
Хранилище состояний FSM: Redis (для персистентности) или MemoryStorage (для разработки)

Архитектура и Структура Кода

Код бота организован по модульному принципу для улучшения читаемости и поддерживаемости. Основные компоненты включают:

main.py (или bot/__main__.py): Главная точка входа в приложение. Здесь происходит инициализация бота, диспетчера, хранилища состояний, локализации и регистрация роутеров с обработчиками.
bot/config_reader.py: Модуль для чтения конфигурации бота (токен, настройки Redis, стартовые очки и т.д.).
bot/handlers/: Папка с модулями-обработчиками. Каждый файл в этой папке может содержать группу обработчиков, объединенных по функциональному признаку (например, default_commands.py для общих команд и меню, spin.py для логики игры).
bot/keyboards.py: Модуль для создания различных клавиатур бота (inline и reply).
bot/dice_check.py: Модуль с логикой проверки результата броска кубика и определения выигрышных комбинаций.
bot/filters.py: Модуль для определения кастомных фильтров сообщений.
bot/locales/: Папка с файлами локализации (.ftl) для разных языков.

Обработка Сообщений и Команд

В Aiogram обработка входящих обновлений (сообщений, callback-запросов и т.д.) осуществляется с помощью диспетчера (Dispatcher) и роутеров (Router).

Роутеры позволяют группировать обработчики.
Обработчики - это асинхронные функции, декорированные с помощью @router.message(), @router.callback_query() и т.д., которые определяют, какие типы обновлений они должны обрабатывать.
Фильтры (например, Command("start"), F.text, SpinTextFilter()) используются в декораторах для уточнения условий, при которых должен сработать обработчик.

Управление Состоянием Пользователя (FSM)

Для каждой сессии пользователя Aiogram предоставляет Конечный Автомат Состояний (FSM). Мы использовали FSM для хранения данных, специфичных для конкретного пользователя в течение его взаимодействия с ботом. К таким данным относятся:

score: баланс очков.
cash_balance: баланс реальных денег.
bet: текущая ставка в очках.
cash_bet: текущая ставка в реальных деньгах.
playing_for: текущий режим игры ("points" или "cash").
language: выбранный язык пользователя.

Эти данные сохраняются и извлекаются из FSMContext, который в свою очередь может использовать различные хранилища (MemoryStorage для простоты разработки, RedisStorage для персистентности).

Локализация

Реализация многоязычной поддержки с Fluent включала:

Создание файлов .ftl (например, strings_example_ru.ftl, strings_example_en.ftl) в папке locales, где для каждого текстового элемента интерфейса определяется уникальный ключ.
Использование FluentLocalization для загрузки ресурсов локализации.
Передача объекта l10n в обработчики и фильтры, где с помощью l10n.format_value("key") извлекаются локализованные строки.
Хранение выбранного языка пользователя в его состоянии (user_data["language"]).
Динамическое создание объекта l10n с нужным языком при обработке обновлений, используя функцию setup_localization.

Реализация Игровой Логики

Логика слот-машины достаточно проста:

Бот отправляет специальный эмодзи "🎰" (кубик). Telegram сам генерирует случайное значение от 1 до 64.
Функция get_score_change() в dice_check.py интерпретирует это значение как результат броска слот-машины и определяет коэффициент выигрыша на основе комбинаций (три семерки, две семерки, три одинаковых символа).
Функция get_combo_text() в dice_check.py преобразует значение кубика в текстовое представление выпавшей комбинации символов (BAR, Виноград, Лимон, 7).
В обработчике спина (handle_spin) на основе коэффициента выигрыша и текущей ставки рассчитывается изменение баланса.

Обработка Нажатий Кнопок

Бот использует два типа клавиатур:

Inline-клавиатуры: Для меню (например, /start) и выбора режима игры ("Игра на очки", "Игра на кэш", "Правила", "Баланс", "Сменить язык"). Нажатия на эти кнопки генерируют callback-запросы, которые обрабатываются соответствующими функциями (@router.callback_query()).
Reply-клавиатуры: Для действий внутри игры (кнопки "Крутить"). Нажатия на эти кнопки отправляют боту обычные сообщения с текстом кнопки. Эти сообщения перехватываются обработчиком handle_spin, используя фильтр SpinTextFilter.

Кастомный Фильтр SpinTextFilter

Для удобства обработки сообщений от кнопок "Крутить" был создан кастомный фильтр SpinTextFilter. Он проверяет, соответствует ли текст входящего сообщения локализованному тексту одной из кнопок спина (для очков или для кэша), игнорируя регистр и лишние пробелы. Этот фильтр помогает направлять сообщения от этих конкретных кнопок в нужный обработчик handle_spin.

Отладка и Тестирование

В процессе разработки отладка играла ключевую роль, особенно при работе с локализацией и фильтрами. Использование print() statements на различных этапах обработки сообщения (в фильтре, в начале обработчика) помогло точно определить, какие данные получает бот и почему та или иная часть кода не выполняется. Выявленная проблема с использованием неправильной локализации в фильтре была обнаружена именно благодаря детальному отладочному выводу.

Дальнейшее Развитие

Среди следующих логичных шагов по развитию бота, как мы обсуждали, можно выделить:

Интеграция платежных систем: Добавление возможности пополнения баланса с использованием реальных средств, возможно, через криптовалютные платежные шлюзы.

Заключение

Разработка Telegram-бота, даже с простой логикой, требует внимания к деталям, особенно при работе с состояниями пользователей и локализацией. Использование мощных библиотек, таких как Aiogram и Fluent, в сочетании с системным подходом к структуре кода и отладке, позволяет создать надежное и масштабируемое приложение.

Протестировать бота t.me/maxslot_bot