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

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

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

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

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

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

Взвешенная вероятность решает эту проблему, присваивая каждому предмету вес. Если у вас 100 предметов и каждый имеет вес 1, то все они имеют равный шанс — 1% — быть выбранными. Если вы добавите ещё один предмет, доведя общее количество до 101, и дадите последнему предмету вес 1, все предметы по-прежнему будут иметь примерно одинаковый шанс — ~0,99% — быть выбранными. Если вы дадите последнему предмету вес 2, шанс его выбора увеличится — новый общий вес 102, последний элемент имеет вес 2 и 100/102 = ~0,98%, то есть 0,98%+0,98% = 1,96% шанс выбора. Если вы дадите последнему предмету вес 100, новый вес будет 200, и поскольку половина этого веса — ваш новый предмет, он имеет 50% шанс быть выбранным.

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

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

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

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

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

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

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

Среднее

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

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

Представьте, что среднее количество предметов в сундуке — 5. standard deviation помогает определить, насколько это число может меняться от сундука к сундуку.

Малое Standard Deviation (напр., 1): Большинство сундуков будут иметь количество предметов, очень близкое к среднему, например 4, 5 или 6. Это более предсказуемый опыт. Например, при стандартном отклонении 1 почти все сундуки будут содержать от 4 до 6 предметов.

Среднее Standard Deviation (напр., 2): Здесь больше разнообразия. Сундуки могут содержать от 3 до 7 предметов. Хотя 5 предметов по-прежнему распространены, нередко можно найти сундуки с чуть большим или меньшим количеством. При стандартном отклонении 2 вы можете иногда найти сундук с всего 3 предметами или, если повезёт, с 7.

Большое Standard Deviation (напр., 3 и более): Теперь всё становится действительно неожиданным! Сундуки могут содержать от 2 до 8 и более предметов. Это означает, что вы можете найти сундук с парой предметов, но есть и шанс найти сундук, набитый сокровищами. Например, при стандартном отклонении 3 сундук может содержать от 2 до 8 предметов, делая каждое открытие захватывающей лотереей.

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

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

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

Гарантированный минимум предметов

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

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

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

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

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

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

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

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

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

isEnabled

Key	Values	Default
`isEnabled`	Boolean	`true`

mean

Key	Values	Default
`mean`	Double	`4`

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

standardDeviation

Key	Values	Default
`standardDeviation`	Double	`3`

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

vanillaTreasure

Key	Values	Default
`vanillaTreasure`	String	none

Устанавливает опциональную ванильную таблицу добычи Minecraft для использования в дополнение к пользовательской. Используются значения перечисления LootTables Bukkit (напр., BURIED_TREASURE, SHIPWRECK_TREASURE, SIMPLE_DUNGEON). При установке ванильная таблица добычи будет бросаться вместе с любыми пользовательскими предметами, определёнными в разделе items. Если не установлено, используется только пользовательская добыча.

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. Это редкости!

rarities

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

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

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

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

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

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

rarity items

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

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

Key	Values	Default
`amount`	min-max Integer	variable
`material`	Material	variable
`procedurallyGenerateEnchantments`	Boolean	variable
`weight`	Double	variable

amount

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

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

material

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

Особый случай — serialized

При использовании команды lootify вместо материала lootify предоставит настройку serialized. Она генерируется автоматически плагином и не должна создаваться вручную. Формат не читаем для человека.

mmoitem

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

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

Пример:

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

Примечание: для этого требуется установленный плагин 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

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

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

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

Key	Values	Default
`minlevel`	Integer	variable
`maxlevel`	Integer	variable
`chance`	Chance	variable

minlevel

Устанавливает минимальный уровень зачарования.

maxlevel

Устанавливает максимальный уровень зачарования.

chance

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

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

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

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

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

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

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

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

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

Этого не должно происходить, так как система гарантирует минимум один предмет. Если вы видите пустые сундуки, проверьте:

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

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

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

isEnabled

mean

standardDeviation

vanillaTreasure

items

rarities​

rarity items​

amount​

material​

Особый случай — serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​