jeffscrum/qbot repository overview

⁠Telegram Quest Bot by JetCoder

Данный бот использует файл игрового сценария (скрипт) для автоматического проведения квестов. Он написан на Java и может работать в любой операционной системе с установленным пакетом Java Runtime Environment версии Java 8 и выше, включая Windows, Linux и Mac OS.

Руководствуясь программой скрипта, бот может отправлять игрокам текстовые задания, изображения, аудиозаписи и другие файлы, выдавать подсказки, принимать ответы (коды), подсчитывать время, вести статистику и т.д. Бот автоматически сохраняет состояние игры в виде файлов сохранений и загружает их при последующем запуске. Подробная инструкция по настройке бота и созданию игровых сценариев⁠.

• GitHub Page: https://github.com/jeffscrum/qbot⁠
• DockerHub Page: https://hub.docker.com/r/jeffscrum/qbot⁠

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

⁠Общая структура файлов бота

/bot
├── bot.cfg
├── game_files
├── game_script.cfg
├── libs
│   ├── log4j-api-2.7.jar
│   ├── log4j-core-2.7.jar
│   ├── slf4j-simple-1.7.30.jar
│   └── telegrambots-6.0.1-jar-with-dependencies.jar
├── logs
├── qbot.jar
└── saves

Файл bot.cfg содержит параметры авторизации бота на сервере Telegram, а также параметры прокси-сервера (если он используется).

Файл game_script.cfg содержит программу сценария игры (можно загрузить через Telegram или подключить локальный, добавив -v $(pwd)/game_script.cfg:/qbot/game_script.cfg при создании контейнера). Это текстовый файл в формате UTF8, использующий специальный синтаксис, напоминающий тэговую разметку на Интернет-форумах.

Каталог game_files содержит загружаемые файлы игрового сценария (картинки заданий, звук, документы и т.п.). Имена этих файлов указываются в качестве значений параметров [ФАЙЛ] в скрипте (см. ниже). Необходимо особо отметить файл fids.bin, который создается ботом в этой папке автоматически – этот файл содержит сохраненные идентификаторы файлов в системе Telegram. При отправке любого файла ботом игрокам, вначале он попадает на сервер, и сервер создает ссылку (идентификатор) для этого файла, позволяя впоследствии не загружать его повторно, если он будет отправлен вновь (другому игроку или другой команде). Эти идентификаторы как раз и сохраняются в файле fids.bin, чтобы не повторять загрузку игровых файлов при каждом запуске бота.

Каталог saves создается автоматически и содержит файлы сохранений игры. Имена файлов представляют собой увеличивающиеся номера, но наиболее старые файлы удаляются ботом автоматически. Сохранения создаются при переходе команд на новые уровни, а также через каждые 5 минут. При запуске бот загружает самое последнее сохранение.

Каталог logs создается автоматически и содержит журнал событий (лог) бота. Следует учесть, что файл лога обновляется с небольшой задержкой (3-5 минут). Время записей лога соответствует часам сервера, на котором запущен бот, поэтому для удобства чтения логов можно заранее настроить местный часовой пояс в операционной системе (если используется удаленный сервер).

Каталог libs содержит исполняемые файлы библиотек. Они необходимы для работы бота.

⁠Регистрация нового бота в Telegram

Для создания бота в Telegram, в первую очередь, нужно зарегистрировать его в системе и получить данные для авторизации (имя и токен). Для этого нужно сделать следующее:

• Найти в Telegram бот @BotFather⁠ (можно использовать только этот официальный бот, остерегайтесь клонов!).
• Ввести команду /newbot – бот предложит ввести название нового бота. Введите желаемое название своего бота, можно на русском языке.
• Затем бот попросит ввести логин (имя пользователя) нового бота – это должно быть уникальное имя бота в Telegram, написанное латиницей, по которому его будут находить и добавлять игроки. Следует обратить внимание, что логин бота должен заканчиваться суффиксом bot (далее для примера MyNewCoolGameBot).
• Если введенное имя не занято, бот поздравит вас с успешной регистрацией нового бота и укажет его имя (MyNewCoolGameBot) и токен (что-то вроде 23402934:ARBNYTry8LAHSDrcffY9dzXV7FA) – необходимо записать эти параметры, их нужно будет указать в файле bot.cfg.
• Введите команду /mybots – появится список зарегистрированных ботов, в нем нужно выбрать только что созданный MyNewCoolGameBot, затем нажать кнопку Bot Settings (настройки бота) – Allow Groups (Разрешать группы) и выбрать Turn Groups Off (Отключить группы). Это необходимо, чтобы бот нельзя было добавлять в группы – бот реализует работу с командами самостоятельно и не поддерживает работу в группах.
• Нажимая кнопку Back (Назад), вернуться к меню созданного бота и выбрать команду Edit Bot (Редактировать бот). В открывшемся меню можно, например, изменить описание или загрузить аватар бота (по желанию).
• На этом регистрация бота завершена!

⁠Запуск бота

• Создать или скопировать файл bot.cfg⁠:

[BOT_USERNAME]
имя_бота

[BOT_TOKEN]
токен_бота

[ADMIN_PASSWORD]
пароль_организатора

• Создать каталоги: mkdir -p {game_files,saves,logs}
• Запустить бота:

docker run -d \
  --name qbot1 \
  --restart=unless-stopped \
  -v $(pwd)/bot.cfg:/bot/bot.cfg:ro \
  -v $(pwd)/game_files:/bot/game_files \
  -v $(pwd)/saves:/bot/saves \
  -v $(pwd)/logs:/bot/logs \
  -v /etc/localtime:/etc/localtime:ro \
  jeffscrum/qbot:1.12.0

• Обратиться к боту в ЛС и ввести пароль администратора (Пароль вводится с учетом регистра!).
• Если требуется, произвести дополнительную настройку согласно документации⁠.