Платно Плагин hSocialBotsRewards | Плагин на награду за подписку на ТГК, ДСК и ВК группы v2.7.2

О ПЛАГИНЕ

hSocialBotsRewards связывает Minecraft-сервер с Telegram, VKontakte и Discord и автоматически выдаёт игрокам награды после проверки заданных условий. Пользователь проходит короткий диалог с ботом, подтверждает участие в нужных сообществах, отправляет игровой ник и получает настроенную владельцем сервера награду.

Каждая площадка включается и настраивается независимо: собственный бот, список сообществ, сообщения, команды, задержка, защита и набор действий. Для Telegram и VK также доступны настраиваемые кнопки. Можно использовать одну социальную сеть, сочетание двух или все три одновременно.

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

Все три бота выключены в стандартной конфигурации и запускаются только после заполнения реквизитов и установки enable: true.


ОСНОВНЫЕ ВОЗМОЖНОСТИ

• Независимо настраиваемые боты Telegram, VKontakte и Discord
• Проверка всех настроенных Telegram-каналов
• Проверка всех настроенных сообществ VK
• Проверка участия во всех выбранных Discord-серверах
• Дополнительная проверка хотя бы одной заданной Discord-роли на каждом сервере
• Настраиваемая проверка минимального возраста Discord-аккаунта
• Строгая проверка Minecraft-ника: 3–16 латинских букв, цифр или знаков подчёркивания
• Отдельная задержка для каждой площадки с проверкой по ID соцаккаунта и Minecraft-нику
• Режим без задержки или одноразовая награда
• Защита от привязки одного социального аккаунта к разным никам
• Дополнительное ограничение повторных получений по IP
• Подтверждение собственного контакта в Telegram с HMAC-SHA256
• Награды игрокам онлайн и настраиваемая очередь для игроков офлайн
• Автоматическая обработка очереди после входа игрока
• Обычные и случайные альтернативные наборы наград
• Одноразовый бонус за выполнение условий на нескольких площадках
• 13 встроенных типов серверных действий
• MiniMessage, кликабельный текст и PlaceholderAPI в игровых действиях
• Автоматические сообщения в ботах, когда награда снова становится доступна
• Статистика пользователей и выдач по каждой площадке
• Общая история наград с фильтром по нику
• Подробный статус ботов, API, баз данных и очередей
• Команды проверки подключения каждой площадки
• Административная аналитика, рассылка и удаление записей наград в Telegram
• SQLite по умолчанию, MySQL и MariaDB через HikariCP
• Полностью настраиваемые сообщения, команды, действия и кнопки Telegram/VK

КАК ПРОИСХОДИТ ВЫДАЧА

1. Игрок открывает нужного бота. Команда /hsocialbotsrewards claim может выводить настроенные владельцем кликабельные ссылки.
2. Если для Telegram включено подтверждение телефона, пользователь сначала отправляет собственный контакт системной кнопкой.
3. Затем бот проверяет условия участия выбранной площадки: каналы Telegram, сообщества VK либо Discord-серверы и роли.
4. После успешной проверки бот запрашивает Minecraft-ник.
5. Плагин проверяет формат ника, задержки и включённые ограничения повторного получения.
6. После принятия запроса запись истории и ожидающая выдача сохраняются в базе одной транзакцией.
7. Для игрока онлайн очередь обрабатывается сразу. При разрешённых офлайн-наградах она сохраняется до его входа, а после окончания задержки бот может автоматически сообщить, что награда снова доступна.

Задержка настраивается отдельно для каждой площадки. Значение 0 отключает её, а -1 разрешает получить награду только один раз.


TELEGRAM

Telegram-модуль работает через Bot API Long Polling и проверяет статус пользователя во всех каналах из конфигурации. Поддерживаются публичные имена, ссылки вида https://t.me/... и обычные имена каналов. Для проверки бот должен иметь необходимый доступ Telegram к участникам выбранных каналов.

• Inline-кнопки перехода в каналы и проверки подписки
• Несколько вариантов подписей кнопок без повторов, пока доступны другие варианты
• Настраиваемые HTML, Markdown или MarkdownV2-сообщения
• Необязательное подтверждение собственного телефонного контакта
• Настраиваемая попытка удалить сообщение с контактом после обработки
• Основной и резервные адреса Telegram Bot API
• HTTP- и SOCKS-прокси с необязательными реквизитами; принимаются метки HTTP/HTTPS и SOCKS/SOCKS4/SOCKS5, при этом HTTPS использует режим HTTP-прокси
• Переключение после ошибок, временное отключение и восстановление прокси
• Настраиваемый антиспам команд

При включённой проверке телефона плагин принимает только системный контакт самого отправителя, нормализует номер и вместо исходного номера сохраняет в базе 64-символьное HMAC-SHA256-значение. Номер в исходном виде в базу плагина не записывается. Для конечной задержки можно включить автоматическое удаление HMAC-значения после её завершения; срок хранения подтверждения без полученной награды настраивается отдельно. В режиме одноразовой награды -1 HMAC-значение сохраняется для контроля уникальности.

Административные функции Telegram:

• Аналитика за день, 7, 30, 90 дней или всё время
• Удаление записей истории Telegram у конкретного ника; вариант * с подтверждением очищает все обычные, одноразовые и ожидающие Telegram-награды
• Массовая рассылка с предпросмотром, подтверждением и итоговой статистикой
• Рассылка текста, фото, видео, GIF, аудио, голосовых сообщений, документов и стикеров
• Собственные списки команд и Telegram ID администраторов

VKONTAKTE

VK-модуль использует Group Long Poll и проверяет участие пользователя во всех сообществах из списка groups. Токен сообщества, версия API, команды начала, проверки и отмены, ответы бота и кнопки изменяются в socials/vkontakte.yml.

• Проверка нескольких обязательных сообществ
• Поддержка ID, коротких имён, @name и ссылок vk.com
• Диалог проверки, ввода ника и отмены
• Необязательная клавиатура VK с настраиваемыми подписями
• Текстовый запасной сценарий, если клавиатура недоступна
• Автоматическое переподключение к Long Poll после временных ошибок

Для работы нужны токен сообщества с правами на сообщения и управление ботом и включённый в сообществе Group Long Poll. При использовании кнопок в личных сообщениях сообщества также включите функцию чат-бота в настройках VK.


DISCORD

Discord-модуль работает через JDA и принимает обычные текстовые команды в личных сообщениях боту. После команды проверки плагин убеждается, что пользователь состоит во всех указанных guildIds. Если задан список requiredRoleIds, на каждом проверяемом сервере достаточно иметь хотя бы одну роль из этого списка.

• Несколько обязательных Discord-серверов
• Необязательная проверка ролей
• Настраиваемые команды начала и подтверждения
• Проверка минимального возраста Discord-аккаунта
• Выдача, сообщения об ошибках и уведомления о завершении задержки через ЛС
• Игнорирование сообщений других ботов

Команды Discord являются текстовыми алиасами, а не зарегистрированными slash-командами. Бота необходимо добавить на каждый проверяемый сервер и включить Message Content Intent в Discord Developer Portal.


НАГРАДЫ И СИСТЕМА ДЕЙСТВИЙ

Каждая площадка имеет собственный список стандартных действий actions.giveReward. Дополнительно можно включить несколько альтернативных наборов с процентными шансами от 0.0 до 100.0. Плагин делает один случайный выбор по накопительным шансам; их общая сумма не должна превышать 100%. За одну выдачу выбирается не более одного варианта, а оставшаяся до 100% вероятность приводит к стандартной награде.

Параметр giveDefaultReward определяет, заменяет ли выбранный редкий набор стандартную награду или добавляется к ней.

Доступные типы действий:

• [CONSOLE] — выполнить команду от имени консоли
• [PLAYER] — выполнить команду от имени игрока
• [MESSAGE] — отправить личное MiniMessage-сообщение
• [BROADCAST] — отправить объявление всему серверу
• [TITLE] — показать Title и Subtitle
• [ACTIONBAR] — показать или динамически обновлять ActionBar
• [BOSSBAR] — показать или динамически обновлять BossBar
• [SOUND] — воспроизвести звук
• [PARTICLE] — создать частицы
• [EFFECT] — запустить Bukkit-эффект
• [FIREWORK] — создать настраиваемый фейерверк
• [VAULT] — добавить, снять, очистить или установить баланс
• [CLOSE] — закрыть открытый инвентарь

Во встроенных действиях доступны переменные:


Для игрока онлайн текстовые и командные действия также обрабатывают плейсхолдеры PlaceholderAPI. Действия выполняются сверху вниз.

Пример собственного набора:


Консольные действия запускаются с полными правами сервера, поэтому изменять списки наград должны только доверенные администраторы.


ЗАЩИТА ОТ ПОВТОРНЫХ ПОЛУЧЕНИЙ

Для Telegram, VK и Discord предусмотрены независимые параметры защиты:

• Задержка одновременно по ID социального аккаунта и Minecraft-нику
• Привязка одного социального аккаунта к одному игровому нику
• Запрет выдачи с одного IP для другого ID соцаккаунта или Minecraft-ника
• Настраиваемая строгая проверка ника: 3–16 латинских букв, цифр или знаков подчёркивания
• Ограничение частоты команд каждого пользователя
• Подтверждение контакта для Telegram
• Минимальный возраст аккаунта для Discord

Каждая защита включается отдельно. При отключённой строгой проверке действует базовый формат ника: 1–32 латинские буквы, цифры или знаки подчёркивания. Ограничение по IP требует, чтобы Minecraft-игрок находился онлайн: при его включении офлайн-выдача этой площадки недоступна даже с offlineRewards: true.


ОФЛАЙН-НАГРАДЫ И ОБЩИЙ БОНУС

Параметр offlineRewards настраивается для каждой площадки. Когда он включён, подтверждённая награда для игрока офлайн сохраняется в базе. Плагин пытается выдать её после входа игрока и повторно обрабатывает очередь с заданным интервалом. Пока для ника уже ожидается награда этой площадки, новый запрос не принимается.

Игрок также может вручную забрать ожидающую награду соответствующей командой:


Необязательная межплатформенная награда выполняет отдельный список действий, когда игрок находится онлайн, завершил получение награды на каждой выбранной площадке и ни одна из этих наград не остаётся в очереди. Требуется минимум две площадки; условия на них можно выполнить в разное время. Общий бонус выдаётся одному игровому нику только один раз и не возобновляется после завершения платформенных задержек.


УПРАВЛЕНИЕ И ДИАГНОСТИКА

• Количество зарегистрированных пользователей и принятых запросов на награду по каждой площадке
• Общие суммы пользователей и наград
• История Telegram, VK и Discord в едином списке от новых записей к старым
• Фильтр истории по Minecraft-нику и настраиваемый лимит вывода
• Состояние ботов, API, соединений и конфигурации
• Состояние платформенных баз и размеры очередей
• Время работы, последнее успешное действие и последняя ошибка каждого бота
• Отдельный тест Telegram, VK или Discord
• Проверка конфигурации при запуске и перезагрузке

Отчёты, требующие обращения к базе, и обновление статистики PlaceholderAPI выполняются асинхронно, поэтому при каждом отображении плейсхолдера новый запрос к базе не выполняется.


PLACEHOLDERAPI

• totalusers — суммарное количество пользовательских записей трёх площадок
• totalrewards — суммарное количество зарегистрированных выдач наград
• Платформенные варианты возвращают соответствующее значение Telegram, VK или Discord

Снимок значений обновляется асинхронно. Стандартный интервал составляет 5 секунд и изменяется в config.yml.


ХРАНЕНИЕ ДАННЫХ

По умолчанию используются четыре локальные SQLite-базы:


Первые три базы хранят данные о пользователях площадок, выдачах и ожидающих наградах. Общая база rewards.db используется для межплатформенного бонуса и очереди уведомлений об окончании задержки.

Платформенные базы хранят ID социальных аккаунтов и видимые данные профиля, Minecraft-ники, время выдачи, состояния ожидающих и одноразовых наград, а для онлайн-выдач — текущий IP-адрес. Если защита от повторов по IP выключена, совпадения не проверяются, однако IP по-прежнему записывается в историю наград. Предоставляйте доступ к базам и право просмотра истории только доверенным администраторам.

Для каждой базы можно независимо выбрать SQLite, MySQL или MariaDB. Соединения с серверной базой работают через HikariCP; размеры пула, таймауты, keepalive и JDBC-параметры изменяются в соответствующем YAML. Для SQLite предусмотрены WAL, busy timeout, foreign keys, memory-mapped I/O и оптимизация при запуске.

При выборе серверного хранилища storage/rewards.yml может автоматически объединить существующую локальную rewards.db с MySQL/MariaDB, если включён storage.migration.sqliteToServer.enable. Исходный SQLite-файл остаётся на месте. Платформенные базы Telegram, VK и Discord автоматически не переносятся.

/hsocialbotsrewards reload перечитывает сообщения и обычные настройки, но не перезапускает работающих ботов и не пересоздаёт пулы подключений к базам. После изменения токенов, включения модулей или параметров storage/*.yml выполните полный перезапуск сервера.


КОМАНДЫ

• /hsocialbotsrewards — показать справку
• /hsocialbotsrewards reload — перечитать конфигурацию и обновить расписание уведомлений
• /hsocialbotsrewards stats — показать статистику пользователей и наград
• /hsocialbotsrewards claim — выполнить настраиваемые действия со ссылками на ботов; только для игрока
• /hsocialbotsrewards status — показать состояние ботов, API, баз и очередей
• /hsocialbotsrewards history [ник|*] [лимит] — вывести общую историю наград
• /hsocialbotsrewards test <telegram|vkontakte|discord> — проверить подключение площадки
• /hsocialbotsrewards gettg — забрать ожидающую Telegram-награду; только для игрока
• /hsocialbotsrewards getvk — забрать ожидающую VK-награду; только для игрока
• /hsocialbotsrewards getdc — забрать ожидающую Discord-награду; только для игрока

У основной команды нет короткого алиаса. По умолчанию история выводит 15 записей, а её настраиваемый максимальный объём составляет 50 записей. Оба значения изменяются в конфигурации. Чтобы указать лимит, сначала передайте ник или *. Tab Completion показывает только те подкоманды, на которые у отправителя есть право, а после test предлагает три названия площадок.


ПРАВА


Все права по умолчанию доступны только операторам. Чтобы обычные игроки могли открывать ссылки и вручную забирать ожидающие награды, выдайте им hsocialbotsrewards.claim и те из прав hsocialbotsrewards.gettg, hsocialbotsrewards.getvk и hsocialbotsrewards.getdc, которые соответствуют включённым площадкам.


ФАЙЛЫ КОНФИГУРАЦИИ

• config.yml — префикс, действия команды claim, общий бонус, сообщения игровых команд, форматы времени и runtime-параметры
• socials/telegram.yml — Telegram-бот, каналы, прокси, подтверждение телефона, администраторы, рассылка, аналитика, сообщения, кнопки и награды
• socials/vkontakte.yml — VK-бот, сообщества, команды, клавиатура, сообщения, задержки, защита и награды
• socials/discord.yml — Discord-бот, серверы, роли, возраст аккаунта, команды, сообщения, задержки, защита и награды
• storage/telegram.yml — хранилище Telegram
• storage/vkontakte.yml — хранилище VK
• storage/discord.yml — хранилище Discord
• storage/rewards.yml — общее хранилище бонусов и уведомлений об окончании задержки

Сообщения находятся внутри основного и платформенных YAML; отдельного messages.yml нет.


ТРЕБОВАНИЯ И ИНТЕГРАЦИИ

Обязательно:

• Paper 1.21.x или совместимое Paper-ядро
• Java 21
• PlaceholderAPI
• Исходящий доступ сервера к API выбранных социальных сетей

Сборка напрямую использует API Paper и Adventure. Обычные Spigot/CraftBukkit и Folia не поддерживаются.

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

• Vault и зарегистрированный провайдер экономики — только для действий [VAULT]

JDA, Telegram-клиент, OkHttp, HikariCP и JDBC-драйверы объявлены как runtime-библиотеки и загружаются сервером. При первом запуске ему потребуется доступ к репозиториям зависимостей.

Команды hCases, LuckPerms и других серверных систем в стандартных действиях приведены только как примеры. Эти плагины не объявлены обязательными зависимостями: замените команды на используемые вашим сервером.


УСТАНОВКА И ПЕРВИЧНАЯ НАСТРОЙКА

1. Остановите сервер и убедитесь, что он работает на Paper 1.21.x с Java 21.
2. Установите обязательный PlaceholderAPI, поместите JAR в папку plugins и один раз запустите сервер для создания файлов.
3. Остановите сервер. Выберите нужные площадки и настройте параметры enable, токены, идентификаторы и списки обязательных сообществ каждой выбранной площадки.
4. Для Telegram создайте бота через BotFather, укажите собственные каналы и предоставьте боту доступ, необходимый для getChatMember. Отключите демонстрационный прокси либо замените его собственными проверенными адресами; не передавайте токен и трафик бота через недоверенный публичный прокси.
5. Для VK укажите ID и токен сообщества с правами на сообщения и управление ботом, включите Group Long Poll и при необходимости функцию чат-бота.
6. Для Discord создайте бота, включите Message Content Intent, добавьте его на все проверяемые серверы и заполните guildIds и requiredRoleIds.
7. Перед включением Telegram удалите стандартные adminChatIds и добавьте только ID личных чатов доверенных администраторов. Эти аккаунты могут запускать рассылку, смотреть аналитику и удалять записи выдач Telegram; вариант очистки * также удаляет все одноразовые и ожидающие Telegram-награды.
8. Замените стандартные имена ботов, каналы, ссылки, упоминания ToolRise и все демонстрационные серверные команды своими значениями. Сообщения ботов должны описывать только те условия, которые действительно проверяет ваша конфигурация.
9. Настройте обычные и альтернативные награды, задержки, офлайн-выдачу, ограничения повторного получения и при необходимости общий бонус.
10. Оставьте SQLite или настройте MySQL/MariaDB в файлах storage/*.yml. Не публикуйте токены и реквизиты базы данных.
11. Полностью перезапустите сервер, выдайте игрокам нужные права и выполните /hsocialbotsrewards test <площадка>.
12. Проверьте весь пользовательский сценарий на тестовом аккаунте, затем используйте /hsocialbotsrewards status и stats для контроля работы.