Что такое файл сокровищ?

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

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

Статистические понятия

Прочитайте об этих концепциях здесь, остальная часть страницы предполагает, что вы их понимаете!

Взвешенная вероятность

BetterStructures и EliteMobs (другой плагин того же автора) используют концепцию взвешенной вероятности в своих системах добычи. Это решает простую проблему: как установить шанс выбора одного предмета из списка потенциально бесконечных предметов?

Взвешенная вероятность присваивает каждому предмету вес. У 100 предметов с весом 1 вероятность выбора каждого равна 1%. Если добавить ещё один предмет с весом 1, вероятность каждого из 101 предмета составит около 0,99%. Если вес последнего предмета равен 2, общий вес станет 102, а вероятность его выбора составит 2/102, около 1,96%. При весе последнего предмета 100 общий вес станет 200. Этот предмет займёт половину общего веса, поэтому вероятность его выбора составит 50%.

Как видите, это хорошо подходит для списков из сотен вещей для рандомизации.

Гауссово распределение

Гауссово распределение — это колоколообразная математическая функция.

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

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

Как работает гауссово распределение?

К счастью, вам не нужно разбираться в математике, и можно сосредоточиться на двух настройках: среднее и стандартное отклонение.

Среднее

mean задаёт центр гауссова распределения, используемого для числа попыток выдачи добычи. Реализация округляет результат вверх, заменяет отрицательные значения нулём и добавляет одну попытку. Поэтому среднее 5 не означает в среднем ровно пять размещённых стопок предметов.

Стандартное отклонение

standardDeviation управляет разбросом начального результата. До округления около 68% значений находятся в пределах одного стандартного отклонения от среднего, а около 95% в пределах двух. При среднем 5 и стандартном отклонении 1 около 68% исходных результатов лежат между 4 и 6. Изменение стандартного отклонения меняет этот разброс.

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

Среднее по умолчанию — 4, стандартное отклонение по умолчанию — 3.

Детали реализации

Понимание внутренней работы системы сокровищ поможет настроить её более эффективно:

Минимальное число попыток

Для непустого списка пользовательских редкостей число попыток равно max(ceil(gaussian(mean, standardDeviation)), 0) + 1. Дополнительная попытка означает, что настроенное среднее не равно среднему итоговому числу стопок. Выполняется хотя бы одна попытка, но недопустимая или пустая таблица предметов, ошибка создания предмета либо отменённое событие заполнения могут оставить сундук пустым.

Случайное размещение в слотах

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

Обработка ошибок

Если материал предмета не существует в вашей версии Minecraft (например, при использовании старой конфигурации на новой версии, где предметы были переименованы), этот предмет будет молча пропущен, а не вызовет ошибки. Записи зачарований, которые не сопоставляются с реальным ключом зачарования minecraft:, также молча пропускаются, а блок procedurallyGeneratedItemSettings, привязанный к несуществующему материалу, выводит предупреждение с указанием файла.

Отсутствующее или недопустимое значение amount вызывает предупреждение. Прочитанный минимум повышается как минимум до 1, а максимум как минимум до этого минимума. Отсутствующее количество становится равным 1, а 5-2 превращается в фиксированное количество 5. Некорректный диапазон может сохранить успешно прочитанный минимум. Исправьте файл, не полагаясь на такую коррекцию.

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

Специальный формат

Файлы сокровищ имеют специальный формат, который выглядит так:

isEnabled: true
mean: 4.0
standardDeviation: 3.0
vanillaTreasure: BURIED_TREASURE
items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0
  epic:
    weight: 10
    items:
    - amount: 2-10
      material: DIAMOND
      weight: 1.0
    - amount: 1-1
      material: DIAMOND_AXE
      weight: 6.0
procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

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

isEnabled

Ключ	Значения	По умолчанию
`isEnabled`	Boolean	`true`

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

mean

Ключ	Значения	По умолчанию
`mean`	Double	`4`

Устанавливает mean. Подробности здесь.

standardDeviation

Ключ	Значения	По умолчанию
`standardDeviation`	Double	`3`

Устанавливает standardDeviation. Подробности здесь.

vanillaTreasure

Ключ	Значения	По умолчанию
`vanillaTreasure`	String	нет, кроме поставляемых файлов `vanilla_*`

Задаёт необязательную ванильную таблицу добычи в дополнение к пользовательской. Используются значения перечисления Bukkit LootTables, например BURIED_TREASURE, SHIPWRECK_TREASURE или SIMPLE_DUNGEON, без учёта регистра. Ванильная добыча выбирается после пользовательской и использует оставшиеся пустые слоты. Без этой настройки используется только пользовательская добыча. Недопустимые имена вызывают предупреждение и отключают ванильную часть.

Поставляемые файлы ванильных сокровищ при отсутствии ключа используют соответствующую таблицу: vanilla_bastion_treasure.yml — BASTION_TREASURE, vanilla_buried_treasure.yml — BURIED_TREASURE, vanilla_end_city_treasure.yml — END_CITY_TREASURE, vanilla_fishing_treasure.yml — FISHING_TREASURE, а vanilla_shipwreck_treasure.yml — SHIPWRECK_TREASURE. В любом другом файле поле нужно задать явно: одно лишь имя vanilla_* не выбирает таблицу добычи.

items

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

items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0

Здесь видно, что под ключом конфигурации items находится карта с common и rare. Это редкости!

Редкости

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

Обратите внимание, что то, что делает эти таблицы редкости более или менее редкими — это weight таблицы добычи!

По умолчанию:

common имеет weight по умолчанию 60
rare имеет weight по умолчанию 30
epic имеет weight по умолчанию 10

Что делает обычные предметы в 6 раз более вероятными для выпадения, чем эпические. Подробнее о weight здесь!

Помимо веса, каждая таблица редкости имеет собственный список items.

Предметы редкости

Предметы редкости — это список карт, перечисляющий все предметы таблицы редкости.

Эти предметы имеют следующие настройки:

Ключ	Значения	По умолчанию
`amount`	минимум-максимум Integer	зависит от записи
`material`	Material	зависит от записи
`procedurallyGenerateEnchantments`	Boolean	зависит от записи
`weight`	Double	зависит от записи

amount

Устанавливает количество для выпадения. Может быть выражено как диапазон amount: MIN-MAX или как единственное значение amount: VALUE для фиксированного количества. Примеры:

Переменное количество: amount: 1-5 (выпадает от 1 до 5 предметов)
Фиксированное количество: amount: 3 (всегда выпадает ровно 3)

material

Устанавливает материал с использованием имён Spigot API потенциально выпадающего предмета.

Особенности serialized

/bs lootify записывает карту serialized через сериализацию предметов Bukkit, сохраняя данные предмета в руке. Создавайте её командой, а не вручную. Указывайте только один источник предмета на запись: material, serialized или mmoitem. Если одновременно указан допустимый material, он имеет приоритет над сериализованным предметом или предметом MMOItems. Процедурные зачарования применяются только к записям с материалом.

mmoitem

Устанавливает пользовательский предмет из плагина MMOItems. Это альтернатива полю material для использования пользовательских предметов вместо ванильных материалов Minecraft.

Формат: mmoitem: TYPE@ITEMNAME

Пример:

- amount: 1-1
  mmoitem: SWORD@Excalibur
  weight: 1.0

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

info

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

Пример:

- amount: 1-1
  material: DIAMOND_SWORD
  weight: 1.0
  info: "Rare drop for completing the dungeon"

weight

Устанавливает вес для взвешенной вероятности. Подробнее здесь.

procedurallyGenerateEnchantments

Устанавливает, должен ли предмет генерироваться процедурно на основе настроек в procedurallyGeneratedItemSettings. Обратите внимание, что в зависимости от настроек это может привести к генерации предмета без зачарований.

procedurallyGeneratedItemSettings

Рассмотрим ещё раз наш пример конфигурации:

procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

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

Раздел принимает материалы Bukkit и зарегистрированные зачарования в пространстве имён minecraft:. Другие пространства имён пропускаются. Чтобы сохранить предмет другого плагина, используйте сериализованную запись предмета.

Если в файле сокровищ нет раздела procedurallyGeneratedItemSettings, BetterStructures записывает в файл свою таблицу зачарований по умолчанию. Файл, в котором этот раздел уже есть, использует только перечисленные в нём записи.

Настройки зачарований:

Ключ	Значения	По умолчанию
`minlevel`	Integer	зависит от записи
`maxlevel`	Integer	зависит от записи
`chance`	Chance	зависит от записи

minlevel

Задаёт минимальный уровень зачарования. Он должен быть не меньше 1 и не больше maxlevel.

maxlevel

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

chance

Устанавливает вероятность применения зачарования как десятичное значение от 0.0 (никогда) до 1.0 (всегда). Например, значение 0.2 означает 20% шанс. Используется простая проверка вероятности, а не взвешенная вероятность, как в системе выбора предметов.

Устранение неполадок

Предметы не появляются в сундуках

Убедитесь, что постройка и генератор включены и ссылаются на допустимый файл сокровищ. Даже переопределение в schematic требует допустимой таблицы сокровищ у генератора
Проверьте консоль на предупреждения о недопустимых материалах или предметах
Убедитесь, что MMOItems установлен, если используются пользовательские предметы
Материалы должны использовать точные имена API Spigot

Зачарования не применяются

Установите procedurallyGenerateEnchantments: true для предмета
Убедитесь, что имена зачарований соответствуют Namespaced Keys Minecraft
Проверьте, что уровни min/max находятся в допустимых диапазонах для этого зачарования
Помните, что значения chance — это вероятности (0.2 = 20%), а не гарантии

Пользовательские зачарования плагинов не работают

Читаются только зачарования, зарегистрированные в ванильном пространстве имён minecraft:. Всё остальное в блоке procedurallyGeneratedItemSettings пропускается без предупреждения, поэтому пользовательское зачарование, которое тихо ничего не делает, — это ожидаемый симптом, а не баг. Уточните совместимость у автора плагина зачарований.

Появляются пустые сундуки

Минимум относится к попыткам выдачи добычи, а не к успешно размещённым предметам. Если вы видите пустые сундуки, проверьте:

Заполняется ли сундук BetterStructures (а не другим плагином)
Все ли предметы в вашем файле сокровищ допустимы (проверьте предупреждения консоли)
Загружается ли файл сокровищ (проверьте логи запуска)

Статистические понятия​

Детали реализации

Специальный формат

isEnabled

mean

standardDeviation

vanillaTreasure

items

Редкости​

Предметы редкости​

amount​

material​

Особенности serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​