Платно Плагин hDungeonsLootEditor | Настрой СВОЙ кастомный лут в ВАНИЛЬНЫХ данжах v1.0

hDungeonsLootEditor — административный плагин для визуальной настройки лута ванильных контейнерных таблиц на Paper. Откройте постраничный GUI, выберите нужный данж, добавьте готовые предметы из инвентаря и отдельно задайте шанс, минимальное и максимальное количество каждой награды.

Плагин поддерживает два режима генерации: MERGE дополняет исходный лут, а REPLACE заменяет его для настроенных таблиц. В отдельном меню можно запретить выбранные ванильные материалы, скопировать готовый профиль в другую таблицу или сразу во все остальные доступные таблицы.

Предметы сохраняются как полные сериализованные ItemStack, поэтому их название, описание, зачарования, атрибуты, CustomModelData, PersistentDataContainer и другие поддерживаемые сервером метаданные не приходится переносить вручную. По умолчанию используется локальная SQLite, при необходимости доступна MySQL.


Основные возможности

• Визуальный редактор ванильных контейнерных таблиц лута.
• 60 таблиц в комплектной конфигурации: 56 сундуков, 3 раздатчика и 1 украшенный горшок; translate.yml помечает этот набор как Minecraft 1.21.11.
• Автоматическая проверка таблиц, реально доступных на установленной версии сервера.
• Постраничные меню таблиц, настроенных предметов и ванильных материалов.
• Режим MERGE для дополнения исходного лута.
• Режим REPLACE для замены исходного лута настроенным профилем.
• Независимый процент выпадения для каждого предмета.
• Отдельный диапазон количества от 1 до 2304 для каждой записи.
• Поддержка дробных процентов и настраиваемых шагов GUI.
• Добавление, замена и удаление предметов без ручного описания их метаданных.
• Сохранение полного ItemStack через бинарную сериализацию Bukkit.
• Поддержка готовых зачарованных и созданных другими плагинами предметов.
• Автоматическое разделение большого количества по максимальному размеру стака.
• Отдельный список запрещённых материалов для каждой таблицы.
• Копирование профиля в одну или во все остальные таблицы.
• Поиск связанных структур в текущем мире по радиусу.
• Координаты, расстояние, состояние лута и кликабельная телепортация в результатах поиска.
• Уважение границы мира и настраиваемый предел результатов.
• SQLite по умолчанию и опциональная MySQL через HikariCP.
• Последовательная асинхронная очередь записи изменений в базу данных.
• MiniMessage для сообщений, названий, описаний и интерфейса.
• Шесть отдельных файлов гибкой настройки GUI.
• Настраиваемые сообщения и переводы названий таблиц.
• Горячая перезагрузка основных конфигураций.
• Автодополнение подкоманд, ID таблиц и аргументов.
• Нет обязательных зависимостей от других плагинов.
• Нет телеметрии, проверки обновлений, лицензии или удалённой активации.

Как работает hDungeonsLootEditor

1. Администратор выбирает режим MERGE или REPLACE в config.yml.
2. Игрок с правом hdungeonslooteditor.admin открывает редактор в творческом режиме.
3. В общем списке выбирается одна из доступных ванильных контейнерных таблиц.
4. Предметы копируются в профиль из инвентаря, после чего для каждого задаются шанс и диапазон количества.
5. Каждое изменение сразу применяется к рабочему кэшу и ставится в очередь сохранения базы данных.
6. При следующей генерации лута плагин находит профиль по NamespacedKey таблицы и формирует новый результат.
7. После добавления наград применяется список запрещённых материалов и при включённой настройке перемешивается итоговый список.

hDungeonsLootEditor обрабатывает LootGenerateEvent. Поэтому настройки действуют на будущую генерацию лута, но не изменяют уже открытые или ранее заполненные контейнеры.

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


Поддерживаемые таблицы

Встроенная конфигурация содержит 60 контейнерных таблиц. Комментарий в translate.yml помечает этот набор как подготовленный для Minecraft 1.21.11:

• Заброшенные шахты, обычные данжи, сокровища и бонусные сундуки.
• Пустынные пирамиды, храмы в джунглях и иглу.
• Крепости Нижнего мира, бастионы и разрушенные порталы.
• Города Края, древние города, крепости и лесные особняки.
• Аванпосты разбойников, затонувшие корабли и подводные руины.
• Все встроенные контейнерные таблицы деревень.
• Сундуки, раздатчики и украшенные горшки камер испытаний.

Список GUI создаётся из доступных серверу значений Bukkit LootTables и включает ванильные ключи minecraft:chests/, minecraft:dispensers/trial_chambers/ и minecraftots/trial_chambers/*. Мобы, рыбалка, торговля, археология вне перечисленного набора и пользовательские таблицы datapack в редактор не добавляются.

Пример полного ID:


В командах можно использовать полный ID, путь без minecraft: или локализованный псевдоним, предлагаемый автодополнением.


Визуальный редактор

Основное меню показывает название таблицы, её технический ID и состояние: ванильный лут либо количество сохранённых предметов. На одной странице размещается до 28 таблиц.

Управление списком таблиц:

• ЛКМ по таблице — открыть пользовательский профиль.
• Shift + ПКМ — открыть список найденных ванильных материалов и их запретов.
• Кнопки по краям меню — перейти между страницами или закрыть интерфейс.

В редакторе одной таблицы отображается до 28 записей на страницу. Добавить новую запись можно несколькими способами:

• Взять предмет на курсор и нажать им по свободному слоту редактора.
• Shift-кликнуть предмет в собственном инвентаре.
• Перетащить предмет в свободный слот области лута.

Предмет копируется и не забирается из инвентаря. Дубликаты разрешены и считаются отдельными независимыми записями.

Управление сохранённым предметом:

• Q или Ctrl + Q — удалить запись.
• ЛКМ — открыть экран замены предмета.
• ПКМ — изменить шанс выпадения.
• СКМ — изменить минимальное и максимальное количество.
• Shift на кнопках шанса и количества — использовать увеличенный шаг.
• Shift + ЛКМ по кнопке сброса — выполнить сброс без подтверждения: в MERGE профиль удаляется, а в REPLACE сразу создаётся новая случайная стартовая выборка.

Общей кнопки Save, отмены или истории изменений нет: успешное действие сразу обновляет рабочий кэш и ставит сохранение в очередь базы данных.


MERGE и REPLACE

MERGE

Режим по умолчанию сохраняет исходный список LootGenerateEvent и добавляет к нему все пользовательские записи, прошедшие проверку шанса:


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


REPLACE

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


Для таблицы без сохранённого профиля сохраняется исходный лут, хотя отдельные запреты материалов по-прежнему действуют. При первом открытии такой таблицы в GUI режим REPLACE один раз вызывает ванильную таблицу и импортирует получившуюся выборку как стартовый пользовательский профиль.

Важно: этот импорт является одним случайным результатом populateLoot, а не точным восстановлением ванильных пулов, весов, условий и функций. Исходное количество выпавших стаков также не переносится: каждый импортированный предмет получает текущие chance.default и min/max своей таблицы. Сброс таблицы в режиме REPLACE создаёт новую такую выборку.

Сохранённый пустой профиль в REPLACE означает пустой итог: из этой таблицы ничего не выпадет.


Шансы и количество

Каждая пользовательская запись выполняет собственный процентный бросок один раз на событие генерации. Это не вес внутри пула и не выбор только одной награды.

Например, если два предмета имеют шанс 50%, могут выпасть оба, только один или ни одного.

• default — шанс, назначаемый новой записи; по умолчанию 5%.
• min — нижняя граница редактора; по умолчанию 1%.
• Верхняя граница всегда равна 100%.
• Дробные значения поддерживаются.
• Обычный шаг GUI по умолчанию равен 1%, с Shift — 25%.

После успешного броска выбирается равномерное целое количество от min до max включительно. Для новой записи стартовый диапазон берётся из раздела конкретной таблицы:


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

Допустимое количество — от 1 до 2304. Обычный шаг GUI равен 1, с Shift — 5. Большой результат делится на несколько ItemStack с учётом максимального размера стака предмета.


Сохранение данных предмета

При добавлении hDungeonsLootEditor клонирует ItemStack, устанавливает размер шаблонного стака в 1 и сохраняет его через ItemStack.serializeAsBytes(). Количество исходного стака не используется — за него отвечает отдельный диапазон min/max.

В рамках сериализации сервера сохраняются:

• Материал, имя и описание предмета.
• Зачарования, прочность и атрибуты.
• CustomModelData и современные item components.
• PersistentDataContainer и другие данные ItemMeta.

При генерации создаётся точная копия сохранённого шаблона, меняется только количество. Плагин не применяет к пользовательской записи ванильные loot functions, случайные зачарования или дополнительные условия.

Обычные метаданные предмета восстанавливает Bukkit. Если специальное поведение кастомного предмета реализовано кодом другого плагина, для работы этой логики исходный плагин всё равно может требоваться. Перед крупным обновлением Minecraft рекомендуется сделать резервную копию базы.


Фильтр материалов

Shift + ПКМ по таблице открывает отдельное меню. Плагин постепенно вызывает ванильную LootTable, собирает найденные уникальные Bukkit Material и показывает их постранично. ПКМ переключает разрешение выбранного материала.

Запрет хранится отдельно для каждой таблицы и применяется после формирования всего результата:

• Удаляются все ItemStack выбранного Material независимо от их имени, зачарований и других метаданных.
• Фильтр действует и на ванильные, и на добавленные hDungeonsLootEditor предметы того же материала.
• При processPluginGeneratedLoot: false запреты всё равно применяются к луту, помеченному как созданный другим плагином.
• Сброс пользовательского профиля не очищает список запретов.
• Команда копирования переносит предметы, шансы и количество, но не переносит запреты.

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


Копирование профилей

Готовый профиль можно перенести без повторной ручной настройки:


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

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

Команда доступна из консоли и не требует творческого режима.


Поиск структур

Команда locate ищет в текущем мире структуры, связанные с выбранной таблицей лута:

• Радиус по умолчанию — 5000 блоков.
• Значение -1 снимает радиус от игрока и использует границы мира или WorldBorder; это не полный перебор каждой структуры.
• Граница мира учитывается при respectWorldBorder: true.
• По умолчанию возвращается не более 10 результатов.
• На странице чата показывается до 5 структур.
• Во время длительного поиска выводится прогресс и число найденных результатов.
• Результаты сортируются по горизонтальному расстоянию до игрока.
• Координаты помечаются цветом: зелёный означает, что внутри границ структуры найден хотя бы один Lootable с назначенной таблицей лута; красный — что такой объект не найден.
• Кликабельная кнопка выполняет обычную команду /tp X Y Z.

Плагин старается выбрать безопасную позицию около контейнера или внутри структуры. Это точка назначения, а не обязательно origin структуры или точные координаты контейнера выбранной таблицы. При выборе позиции и статуса проверяется любой подходящий Lootable внутри границ структуры без сравнения его ключа с запрошенной таблицей. Для телепортации игроку всё равно требуется право на используемую сервером команду /tp.

Не для каждой контейнерной таблицы существует однозначно определяемая структура. Для таких ID команда честно сообщает, что поиск не поддерживается.

Поиски кэшируются на 30 минут, а состояние лута структуры — на короткое время. При уточнении позиции и статуса чанки могут загружаться или генерироваться. Большие радиусы и особенно -1 следует использовать с учётом мощности и размера мира.


Лут, созданный другими плагинами


При processPluginGeneratedLoot: false пользовательские записи и режим REPLACE не применяются к LootGenerateEvent, помеченному Bukkit как созданный плагином. Исходный список сохраняется, но запреты материалов всё равно фильтруют результат.

При значении true такой лут обрабатывается теми же правилами, что и обычная генерация. Эта настройка не является интеграцией с конкретным плагином: совместимость зависит от того, создаёт ли он стандартный LootGenerateEvent с известным ключом таблицы.

shuffleResult перемешивает порядок итогового списка после добавления предметов и фильтрации. Это не отдельная система выбора слотов и не ограничитель количества наград.


SQLite и MySQL

По умолчанию hDungeonsLootEditor создаёт локальную базу plugins/hDungeonsLootEditor/loot.db:


Для общей внешней базы можно выбрать MySQL:


Соединения MySQL обслуживает HikariCP. Размер пула, тайм-ауты, срок жизни и keepalive настраиваются в storage.yml. Для SQLite плагин использует WAL, NORMAL synchronous, busy timeout и включённые foreign keys.

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

storage.yml применяется только после полного перезапуска сервера. Переключение SQLite/MySQL не переносит существующие данные автоматически. Общая MySQL является вариантом хранения, но не системой мгновенной межсерверной синхронизации кэша.


MiniMessage и настройка интерфейса

Все сообщения, названия меню, предметов и lore используют Adventure MiniMessage:


Шесть файлов в каталоге guis отвечают за отдельные экраны:


В них настраиваются размер меню, заголовок, слоты, материалы кнопок, названия, описания, приоритет наложения и шаги изменения шанса или количества. Название секции может быть любым; функциональное назначение задаётся параметром type.

Сообщения находятся в messages.yml, префикс — в config.yml, а переводы названий таблиц — в translate.yml. Встроенный язык файлов — русский; их можно перевести вручную.

PlaceholderAPI не используется. Плейсхолдеры {prefix}, {id}, {source}, {destination}, {progress}, {x}, {y}, {z} и другие переменные интерфейса обрабатываются самим плагином только в соответствующих строках.


Команды

• /hdungeonslooteditor или open — открыть список таблиц; только игрок, только творческий режим.
• reload — перечитать основные конфигурации и заново загрузить данные; доступно из консоли.
• copy — скопировать сохранённый профиль в выбранную таблицу или во все остальные доступные таблицы; доступно из консоли.
• locate — найти связанные структуры в текущем мире; только игрок, творческий режим не требуется.

У основной команды нет алиасов. Автодополнение предлагает подкоманды, доступные ID и псевдонимы таблиц, *, стандартный радиус и -1.


Права

• hdungeonslooteditor.admin — открытие GUI, копирование и поиск структур.
• hdungeonslooteditor.reload — перезагрузка основных файлов.

Оба права по умолчанию доступны операторам. Право hdungeonslooteditor.admin включает hdungeonslooteditor.reload как дочернее.


Конфигурация и перезагрузка

Плагин создаёт следующие файлы:


/hdungeonslooteditor reload:

• Закрывает открытые GUI плагина у игроков.
• Перечитывает config.yml, messages.yml, translate.yml и все шесть GUI-файлов.
• Очищает кэш MiniMessage.
• Ожидает очередь записей базы и заново загружает профили и запреты.
• Обновляет список доступных таблиц и параметры генерации.

Тип базы, адрес, учётные данные и настройки пула из storage.yml команда не перечитывает. Для них требуется перезапуск.

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


Производительность и жизненный цикл

Обычная генерация не сканирует миры или базу данных. Готовые неизменяемые снимки профилей и наборы запретов находятся в памяти, а обработчик проходит только по записям конкретного NamespacedKey.

Записи в SQLite/MySQL выполняются одной последовательной асинхронной очередью. Это сохраняет порядок изменений и не блокирует каждое нажатие GUI ожиданием SQL. При штатном выключении очередь сбрасывается в базу; при аварийном завершении последние ожидающие операции теоретически могут быть потеряны.

Определение списка ванильных материалов выполняется порциями по 64 попытки за тик и кэшируется до перезапуска. Поиск структур также разбит на шаги, использует асинхронную загрузку или генерацию чанков Paper и 30-минутный кэш, но сам вызов поиска структуры и очень большие области всё равно могут создавать нагрузку.

Ошибка подключения или создания схемы базы при запуске отключает плагин, чтобы он не работал с несохранёнными профилями.


Требования

• Paper 1.21.x или совместимое ядро на Paper API. Метаданные плагина указывают api-version 1.21, а комплектный translate.yml помечает набор таблиц как Minecraft 1.21.11.
• Java 21.
• Доступ сервера к загрузке объявленных Maven-библиотек при первом запуске, если их ещё нет в кэше.

Дополнительные плагины не требуются. HikariCP, SQLite JDBC и MySQL Connector/J объявлены как runtime-библиотеки и загружаются сервером.

Обычный Spigot/CraftBukkit не поддерживается из-за прямого использования Paper Registry API, асинхронной загрузки чанков и Adventure API. Folia также не поддерживается.


Поддержка