Платно Плагин hMasks [1.21-26.X] | Создай свои клёвые маски! v1.1

О ПЛАГИНЕ

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

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

Каталог полностью формируется в config.yml. Можно изменить стандартные маски или добавить собственные без пересборки плагина: задать название, описание, текстуру, редкость, чары, атрибуты, постоянные эффекты, условия срабатывания и перезарядку.


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

• Каталог масок без жёстко заданного в коде количества типов
• 7 полностью готовых масок в стандартном наборе
• Текстуры из Base64, имени игрока, UUID или ссылки textures.minecraft.net
• Названия, описание и сообщения в формате MiniMessage
• Редкость предмета: COMMON, UNCOMMON, RARE или EPIC
• Любые доступные атрибуты Paper с настраиваемым значением, операцией и группой слотов
• Зачарования с уровнями, в том числе выше стандартных ограничений Minecraft
• Постоянно поддерживаемые эффекты зелий
• Эффекты после получения урона с порогом здоровья и собственной перезарядкой
• Раздельное управление частицами, иконкой и ambient-режимом каждого эффекта
• Идентификация через Persistent Data Container, не зависящая от названия или lore предмета
• Выдача одной маски или сразу всех типов одному либо всем игрокам онлайн
• Автодополнение подкоманд, игроков, идентификаторов масок и количества
• Опциональная статистика выдач через SQLite или MySQL
• Асинхронный запуск базы, чтение и пакетная запись статистики
• Полностью изменяемые сообщения; поддерживаются оба формата: String и StringList
• Перезагрузка конфигов без полного перезапуска сервера

КАК РАБОТАЮТ МАСКИ

1. Администратор выбирает стандартную маску или создаёт новую секцию settings.masks.<id>.
2. Предмет выдаётся командой /hmasks give либо через внешнюю систему наград.
3. Игрок надевает текстурированную голову в обычный слот шлема — отдельная команда или меню экипировки не требуются.
4. Встроенные в предмет атрибуты и зачарования применяются средствами Minecraft.
5. hMasks распознаёт идентификатор предмета и поддерживает настроенные постоянные эффекты.
6. После непредотвращённого урона плагин рассчитывает запас здоровья с учётом finalDamage, проверяет условие маски и индивидуальную перезарядку способности.

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

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

Перезарядки способностей хранятся в памяти отдельно для игрока и ID маски. После полного перезапуска сервера они начинаются заново.


СЕМЬ ГОТОВЫХ МАСОК

Все стандартные маски имеют уникальную текстуру, редкость EPIC, Взрывоустойчивость IV и следующие атрибуты в слоте головы:


Маска Бастиона — bastion

• Защита IV
• После любого положительного урона выдаёт Сопротивление V на 4 секунды
• Перезарядка способности — 30 секунд

Маска Живоцвета — lifebloom

• Защита IV
• Когда расчётный запас здоровья с учётом finalDamage достигает 35% или ниже, выдаёт Регенерацию III на 5 секунд
• Перезарядка способности — 30 секунд

Маска Рудокопа — miner

• Защита IV
• Постоянная Спешка I
• Скорость атаки +4%

Маска Пожирателя — oni

• Защита III
• Урон +2.05

Маска Клыка — fang

• Защита III
• Урон +1.75

Маска Ютубера — youtuber

• Защита IV
• Урон +0.7
• Постоянное Сопротивление I
• Проклятие утраты I

Маска Тиктокера — tiktoker

• Характеристики Маски Ютубера
• Собственные название и текстура

Все значения являются стандартным шаблоном и полностью изменяются в config.yml. Любую способность можно убрать пустым списком или объектом.


СОЗДАНИЕ СОБСТВЕННЫХ МАСОК

Каждая секция settings.masks.<id> создаёт отдельный тип предмета. Идентификаторы приводятся к нижнему регистру и безопасному формату a-z, 0-9, _, -.

При использовании статистики MySQL ID не должен превышать 32 символа; безопаснее соблюдать этот предел для любого хранилища. Для наиболее предсказуемой и быстрой выдачи текстур используйте Base64 или прямую ссылку textures.minecraft.net: имя или UUID игрока могут потребовать обращения к Mojang.

Для маски настраиваются:

• name и lore — оформление MiniMessage
• texture — пустая голова, Base64, имя, UUID или ссылка на текстуру
• rarity — редкость предмета Minecraft 1.21
• hideFlags — скрытие стандартной информации об атрибутах и чарах
• enchantments — тип и уровень каждого зачарования
• attributes — уникальный ID, тип, значение, операция и группа слотов
• effects.passive — постоянно обновляемые эффекты
• effects.onDamage — порог здоровья, задержка и список эффектов после урона

Поддерживаемые операции атрибутов:


Группы слотов включают HEAD, CHEST, LEGS, FEET, HAND, MAINHAND, OFFHAND, ARMOR, BODY и ANY. Сам предмет всегда создаётся как PLAYER_HEAD; группа слотов определяет, когда активен добавленный к этой голове модификатор атрибута.

После /hmasks reload новые определения начинают использоваться сразу. Уже выданные предметы физически не перестраиваются: их название, описание, текстура, чары и встроенные атрибуты остаются прежними. Изменённые постоянные и реактивные эффекты определяются по ID маски и применяются к существующему предмету; для полного обновления предмет следует выдать заново.


ВЫДАЧА И АВТОДОПОЛНЕНИЕ

* означает все настроенные типы масок. Количество по умолчанию равно 1; команда принимает любое целое значение от 1 до 64.

При переполненном инвентаре остаток не пропадает — предметы естественно выпадают около получателя.

Автодополнение учитывает права отправителя и предлагает:

• доступные подкоманды;
• игроков онлайн;
• все идентификаторы масок и *;
• настраиваемые варианты количества — стандартно 1, 8, 16, 32, 64.

КОМАНДЫ

• /hmasks и /hmasks list — показать все доступные ID и названия; право не требуется
• /hmasks give — выдать один или все типы указанному игроку онлайн
• /hmasks giveall — выдать один или все типы каждому игроку онлайн
• /hmasks stats — показать накопленное количество масок, выданных через команды плагина
• /hmasks reload — перечитать все три конфигурации и перезапустить выбранное хранилище

Команды give и stats <игрок> работают с игроками онлайн. Игрок может вызвать /hmasks stats без цели для собственной статистики, но право hmasks.stats всё равно требуется. Консоль всегда должна указывать игрока.


ПРАВА

• hmasks.give — команды give и giveall
• hmasks.admin — перезагрузка конфигурации
• hmasks.stats — просмотр своей или чужой статистики выдач

Все три права по умолчанию доступны операторам. Команда списка открыта всем игрокам.


СТАТИСТИКА SQLITE / MYSQL

Хранение статистики является опциональным и по умолчанию выключено через storage.enable: false. После включения доступны:

• SQLite — локальный hmasks.db, один connection, WAL и оптимизированные параметры записи
• MySQL — удалённая база с настраиваемым пулом HikariCP
• Асинхронная инициализация, чтение и запись без JDBC-запросов в основном потоке
• Объединение повторных выдач и пакетный flush — стандартно каждые 20 тиков
• Безопасный возврат неотправленной пачки в очередь при ошибке SQL
• Переподключение при /hmasks reload

Статистика накапливает количество масок, выданных командами give и giveall, отдельно для UUID игрока и ID маски. Она не пытается считать обмены, выброшенные предметы, текущее владение или время ношения.

Если база недоступна, основная механика масок продолжает работать; команда статистики выводит настраиваемое сообщение об ошибке.


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

• Один общий проход по игрокам раз в 40 тиков вместо отдельной задачи на каждую маску
• Проверяется только предмет в слоте шлема и его компактный PDC-идентификатор
• MiniMessage-компоненты повторно используются из кэша до 8192 записей
• Запуск базы, чтение статистики и JDBC-запись выполняются асинхронно
• Частые выдачи объединяются по игроку и маске до одного пакетного запроса
• Для SQLite используется один connection; параметры MySQL-пула настраиваются

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

• config.yml — каталог масок, префикс и варианты количества для автодополнения
• messages.yml — 22 изменяемых сообщения MiniMessage
• storage.yml — включение статистики, SQLite/MySQL, HikariCP и интервал batch-записи

Сообщения принимают одиночную строку либо список строк. Удалённый ключ ничего не отправляет. Доступны плейсхолдеры {prefix}, {player}, {mask}, {id}, {amount} и {recipients} в соответствующих событиях.

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


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

• Paper 1.21.x
• Java 21

УСТАНОВКА

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