Плагин hCodes [1.21-26.X] | Гибкая система промокодов! v1.0

О ПЛАГИНЕ

hCodes добавляет на сервер полностью настраиваемую систему промокодов. Игрок вводит /code <промокод>, плагин проверяет условия активации, сохраняет результат в базе данных и выполняет указанные владельцем сервера команды от имени консоли.

Каждый код создаётся отдельной секцией в config.yml. Для него можно задать дополнительные названия, личный и общий лимиты, проверку IP, минимальный наигрыш, постоянную задержку, взаимоисключающие промокоды, список наград и собственные сообщения.

hCodes не привязан к определённой экономике, магазину или системе кейсов. Наградой может стать всё, что выдаётся консольной командой: валюта, предметы, права, кейсы, ключи, опыт или запуск другой серверной механики.


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

• Каталог промокодов без жёстко заданного в коде количества
• Регистронезависимый поиск по основному имени и алиасам
• Несколько последовательных консольных команд в награде
• Плейсхолдеры {player} и {uuid} в командах
• Личный лимит активаций для каждого игрока
• Общий лимит уникальных игроков для каждой кампании
• Защита от повторной активации другим аккаунтом с того же IP
• Хранение SHA-256-хэша вместо исходной строки IP
• Минимальный наигрыш перед получением награды
• Постоянная задержка между активациями игрока
• Взаимоисключающие группы промокодов
• Отдельные MiniMessage-сообщения для каждого кода
• Глобальный топ и статистика конкретного промокода
• SQLite для одного сервера или MySQL для общей базы
• Асинхронные SQL-проверки на виртуальных потоках Java 21
• Транзакционная запись лимитов, ограничений и статистики
• Перезагрузка промокодов и сообщений без перезапуска сервера
• Отсутствие обязательных плагинов-интеграций

КАК ПРОХОДИТ АКТИВАЦИЯ

1. Игрок вводит /code <промокод>.
2. hCodes находит основное имя или алиас без учёта регистра.
3. Проверяется минимальное игровое время и доступность IP, если соответствующие функции включены.
4. Запрос отправляется в отдельный виртуальный поток, не задерживая основной игровой тик SQL-операциями.
5. В одной транзакции проверяются cooldown, группа связанных кодов, личный лимит, лимит уникальных игроков и IP.
6. Если хотя бы одно условие не выполнено, транзакция откатывается и неуспешная попытка не увеличивает статистику.
7. После принятой активации настроенные команды выполняются от имени консоли в указанном порядке, а оставшийся онлайн игрок получает сообщение об успехе.

Параллельные запросы одного UUID на одном сервере блокируются до завершения текущей активации. Запись общей статистики также упорядочивает одновременные попытки использовать один и тот же код.

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


ЗАЩИТА ОТ АБЬЮЗА

Личный лимит

limit.use определяет, сколько раз один UUID может активировать код:


Лимит уникальных игроков

limit.players ограничивает количество разных UUID, допущенных к промокоду. Это удобно для первых 100, 500 или 1000 участников акции. Значение -1 отключает ограничение.

Проверка IP

При ipCheck: true другой аккаунт не сможет активировать тот же промокод с уже использованного адреса. Исходный IP не записывается в базу — сохраняется его SHA-256-хэш и UUID владельца активации.

Если сервер работает за Velocity или BungeeCord, для корректной проверки требуется правильно настроенная передача реального IP игрока.

Минимальный наигрыш

minimumPlayTimeSeconds использует накопленную сервером статистику игрового времени. Так можно закрыть награды для только что созданных аккаунтов. Значение 0 отключает проверку.

Постоянный cooldown

cooldownSeconds задаёт задержку отдельно для игрока и промокода. Следующее доступное время хранится в базе и не сбрасывается после перезапуска. Значение 0 отключает задержку.

Взаимоисключающие коды

linkedCodes позволяет объединить альтернативные промокоды в одну группу: получив награду по одному коду, игрок уже не сможет выбрать другой из этой же группы. Для взаимной блокировки включите функцию у каждого кода и укажите одинаковый полный список группы.


ГИБКИЕ НАГРАДЫ

После успешной проверки hCodes выполняет все строки из commands от имени консоли. Команды запускаются сверху вниз; пустые строки пропускаются.


Доступные плейсхолдеры:

• {player} — текущее имя игрока
• {uuid} — UUID игрока

Благодаря этому hCodes может работать с командами любого установленного плагина без прямой зависимости от его API. Если нужная команда существует и доступна консоли, её можно использовать как награду.


СОЗДАНИЕ ПРОМОКОДА

Каждая секция settings.codes.<имя> создаёт отдельный промокод. Имена и алиасы сравниваются без учёта регистра. Для понятной конфигурации рекомендуется использовать короткие уникальные ID из латинских букв, цифр, дефиса и нижнего подчёркивания; при MySQL имя должно помещаться в 128 символов.


Изменённые коды и сообщения применяются командой /hcodes reload. История хранится по основному ID: удаление кода из YAML и последующее добавление того же ID не сбрасывает прежние использования, IP-записи, cooldown и статистику.


СТАРТОВАЯ КОНФИГУРАЦИЯ

В комплект входят два демонстрационных кода — toolrise и vipe. По умолчанию они:

• активируются один раз на игрока;
• не имеют общего лимита участников;
• проверяют повторное использование IP;
• требуют 180 секунд наигрыша;
• входят в одну взаимоисключающую группу;
• не используют cooldown.

У toolrise также настроены алиасы tool, 13w, 13w_ и he3hauka.

Стандартные награды вызывают команды eco, p и hcases как примеры. Перед использованием замените их на команды, реально существующие на вашем сервере.


СТАТИСТИКА

hCodes сохраняет количество принятых активаций по основному ID промокода. Активация через алиас относится к тому же коду и не создаёт отдельную строку статистики.

• Глобальный топ сортируется по количеству активаций, затем по имени кода
• Размер топа задаётся через settings.topSize в диапазоне от 1 до 100
• Можно отдельно запросить общее количество активаций конкретного кода
• Чтение статистики выполняется асинхронно
• История остаётся в базе даже после удаления кода из текущей конфигурации

Статистика отражает активации, прошедшие все проверки и зафиксированные в базе. Отказ по лимиту, IP, cooldown или связанной группе в счётчик не попадает.


КОМАНДЫ

• /code <промокод> — активировать код; команда доступна только игроку
• /hcodes stats — показать глобальный топ по количеству активаций
• /hcodes stats <промокод> — показать статистику конкретного кода
• /hcodes reload — перечитать config.yml, промокоды и messages.yml

Административные команды работают как от игрока, так и из консоли. Для /hcodes доступно автодополнение с учётом прав; после stats предлагаются основные имена настроенных кодов. Алиасы принимаются при ручном вводе, но не выводятся в подсказках.

Для /code список промокодов намеренно не публикуется через отдельное автодополнение.


ПРАВА

• hcodes.use — активация промокодов; по умолчанию доступно всем
• hcodes.admin.stats — просмотр топа и статистики; по умолчанию только операторам
• hcodes.admin.reload — перезагрузка кодов и сообщений; по умолчанию только операторам

MINIMESSAGE И СООБЩЕНИЯ

Общие ответы находятся в messages.yml, а сообщения конкретного промокода — рядом с ним в config.yml. Для каждого ключа принимается одна строка или список строк. Если ключ отсутствует либо список пуст, соответствующее сообщение не отправляется.

Поддерживается Adventure MiniMessage: современные HEX-цвета, градиенты, оформление и другие стандартные теги. Legacy-цвета через & автоматически не преобразуются.

Основные плейсхолдеры сообщений:


Набор доступных значений зависит от конкретного сообщения. Стандартная конфигурация написана на русском, но все ответы игрокам можно перевести вручную без изменения JAR.


SQLITE И MYSQL

Для постоянных лимитов hCodes всегда использует базу данных. По умолчанию ничего дополнительно устанавливать не нужно: SQLite создаёт локальный файл dataPlayers.db. Для сети серверов можно выбрать MySQL.

• Автоматическое создание необходимых таблиц
• SQLite с одним соединением, WAL по умолчанию и настраиваемым busy timeout
• MySQL с настраиваемым пулом HikariCP
• Prepared statements для пользовательских значений
• Одна транзакция для всех проверок по базе и фиксации активации
• Постоянное хранение использований, IP-хэшей, связанных групп и cooldown
• Асинхронные активации и запросы статистики

При использовании одной MySQL-базы несколькими серверами лимиты и статистика становятся общими для всей сети. Конфигурации промокодов на таких серверах следует поддерживать одинаковыми.

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

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


ПРОИЗВОДИТЕЛЬНОСТЬ

• Нет игровых обработчиков, сканирований игроков или собственных повторяющихся Bukkit-задач
• Основные операции активации и статистики запускаются командами
• Поиск основного имени или алиаса выполняется через готовую карту
• SQL-операции активации и чтения статистики выполняются вне основного игрового потока на виртуальных потоках Java 21
• Наградные команды и сообщения безопасно возвращаются на основной поток Paper
• Один игрок не может одновременно запустить несколько активаций на экземпляре сервера
• MiniMessage-компоненты кэшируются до 8192 уникальных строк
• HikariCP управляет SQLite- и MySQL-соединениями

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

• config.yml — префикс, размер топа, промокоды, лимиты, награды и индивидуальные сообщения
• messages.yml — общие ответы команд и оформление статистики
• storage.yml — SQLite/MySQL, HikariCP и параметры драйверов

config.yml и storage.yml содержат русские комментарии с описанием основных параметров. Новый файл копируется из JAR только при отсутствии локального аналога, поэтому после обновлений рекомендуется самостоятельно сверять новые параметры.


ТРЕБОВАНИЯ И СОВМЕСТИМОСТЬ

• Сервер: Paper 1.21.x
• Java: 21
• Обязательные плагины: отсутствуют
• Хранилище: SQLite или MySQL

УСТАНОВКА

1. Запустите Paper 1.21.x на Java 21.
2. Поместите hCodes-1.0.jar в папку plugins.
3. Запустите сервер и дождитесь создания конфигураций и SQLite-базы.
4. Откройте config.yml и замените демонстрационные коды и команды наград своими.
5. При необходимости переведите или измените ответы в messages.yml.
6. Для MySQL остановите сервер, заполните storage.yml и запустите его снова.
7. Проверьте каждую наградную команду от имени консоли.
8. Активируйте тестовый код через /code <промокод>.