Формат предмета

Автор меню

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

Ищешь полный список свойств?

В Шпаргалке все свойства собраны в одном месте, удобно гонять Ctrl-F. На этой странице - полный справочник с примерами по каждому свойству.

Свойства по категориям

Слот и кулдаун

Имя	Тип данных	Пример	Описание
slot	Multiple	См. Слот ниже	Где лежит предмет. Используется только в предметах меню и в некоторых действиях / правилах.
clickCooldown	Number	clickCooldown: 500	Кулдаун клика по предмету в миллисекундах. Сбрасывается при закрытии или обновлении меню. Если значение меньше глобального click debounce floor, сработает глобальный порог - чтобы обойти его полностью, поставь clickCooldown: 0.

Material installers

Чтобы задать материал, ставится ровно одно из этих свойств. Всё остальное (отображение, механики) накладывается поверх.

Имя	Тип данных	Пример	Описание
material	String	material: "DIAMOND_SWORD"	Материал предмета по имени.
texture	String	См. Текстура	Кастомная текстура головы по id, url или base64. Каталог голов: https://minecraft-heads.com.
skullOwner	String	См. Skull Owner	Натянуть скин игрока на голову.
hdb	String	hdb: "2853"	Голова из HeadDatabase по id.
mmoitem	String	mmoitem: "WEAPON:MY_SWORD"	Предмет из MMOItems по типу и id.
itemsAdder	String	itemsAdder: "<namespaced id>"	Кастомный стак из реестра ItemsAdder.
oraxen	String	oraxen: "my_sword"	Кастомный стак из Oraxen.
equipItem	String или Object	См. Экипированный предмет	Взять предмет из слота инвентаря игрока.
serialized	String	См. Serialized	Восстановить предмет из base64-строки.

Отображение

Имя	Тип данных	Пример	Описание
name	String	name: "Peter Piper"	Отображаемое имя. Принимает коды &, <#RRGGBB> и (если useMiniMessage: true) теги MiniMessage.
lore	Список строк	См. Лор	Строки лора под именем. Цвета и MiniMessage - как в name.
nameLight	String	nameLight: "&aHi"	Legacy-вариант name: только коды &, MiniMessage не парсится. Подходит, если в имени есть символы <.
loreLight	Список строк	Как у lore	Legacy-вариант lore: только коды &.
glow	Boolean	glow: true	Свечение (через невидимое зачарование).
flags	Список строк	См. Флаг	Флаги предмета.
color	String	-	Цвет брони или зелья.
model	Number	model: 1234567	Custom model data.

Механики

Имя	Тип данных	Пример	Описание
count	Number	count: 64	Размер стака.
damage	Number	damage: 100	Урон (полоса под предметом) для предметов с прочностью. Больше = меньше прочности.
data	Number	data: 3	Legacy data-байт / значение прочности. На современном Bukkit эквивалентно damage; пригодится при переносе пре-1.13 конфигов.
unbreakable	Boolean	unbreakable: true	Делает предмет неразрушаемым.
enchantments	Object	См. Зачарования	Зачарования предмета.
enchantStore	Object	Как у enchantments	Положить зачарование в ENCHANTED_BOOK, чтобы потом перенести через наковальню.
attributeModifier	Список объектов	См. Модификатор атрибута	Модификаторы атрибутов (урон, броня, скорость и т.д.).
potionData	Список объектов	См. Эффект зелья	Эффекты зелья, если предмет - зелье.
fireworkData	Object	См. Фейерверк	Эффекты взрыва на FIREWORK_ROCKET.
bookData	Object	См. Книга	Автор, заголовок и страницы книги.
bannerData	Object	См. Баннер	Цвета и узоры баннера.
shieldData	Object	Как у bannerData	Цвета и узоры щита (формат баннера).
recipes	Список объектов	-	Кастомные рецепты на KNOWLEDGE_BOOK.
nbt	Object	См. NBT-теги	Сырые NBT-теги.

Условные

Имя	Тип данных	Пример	Описание
bindings	Список объектов	См. Биндинги	Подменить свойства, если правила прошли. Классика - показывать красным стеклом, когда у игрока не хватает денег.

Слот

Слот - это ячейка в инвентаре (меню или игрока), куда положить предмет. Задать его можно несколькими способами.

Способ 1. Координаты X, Y

slot: "4,3" // x,y

x и y - горизонтальная и вертикальная позиции, отсчёт с 1. Ниже картинка для наглядности.

Способ 2. Индекс

slot: 0

Слот можно задать прямым индексом. Шпаргалка с номерами:

Способ 3. Диапазон

slot: "0-6"

Чтобы положить один предмет сразу в несколько слотов, бери диапазон. Предмет окажется в ячейках с индексами 0, 1, …, 6. Удобно, когда нужно залить меню фоновым предметом и не хочется руками расставлять его по каждому слоту.

Способ 4. Матрица

items: [
  {
    slot: [
      "xxxxxxxxx",
      "x-------x",
      "x-------x",
      "x-------x",
      "x-------x",
      "xxxxxxxxx"
    ]
    material: BLACK_STAINED_GLASS_PANE
  }
]

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

Каждый символ матрицы - один слот.

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

Матрица может быть размером с меню или меньше - то есть слот можно задавать так же, как и размер самого меню:

slot: [
  "xxx",
  "x-x",
  "xxx"
]

Меню получится такое:

Заметка

Отсчёт в матрице всегда идёт от верхнего левого угла.

Осторожно

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

Skull Owner

Свойство, чтобы получить голову игрока по нику. Принимает имя игрока. Например:

skullOwner: "Notch"

Если нужна голова того, кто открыл меню, бери имя из плейсхолдера:

skullOwner: "%player_name%"

Осторожно

AbstractMenus подгружает скин игрока, когда тот заходит на сервер. Если в skullOwner указан игрок, который ещё не заходил, плагин попробует подтянуть скин на лету при открытии меню. Для статичных имён надёжнее использовать texture.

Заметка

Если скин не удалось загрузить (например, у игрока его нет), на голове окажется дефолтный Steve или Alex.

Текстура

Текстуру можно указать одним из форматов ниже.

URL текстуры

Прямая ссылка на изображение текстуры. Пример:

texture: "https://textures.minecraft.net/texture/a45d68aea87cc3fd20b96b21e18255db298b2eac986526473116bd3b5750b787"

Хэш текстуры

SHA-1 хэш изображения скина. Это хвост URL текстуры без префикса https://textures.minecraft.net/texture/. Пример:

texture: "a45d68aea87cc3fd20b96b21e18255db298b2eac986526473116bd3b5750b787"

Префикс плагин подставит сам, и финальный URL получится https://textures.minecraft.net/texture/a45d68aea87cc3fd20b96b21e18255db298b2eac986526473116bd3b5750b787.

Закодированная Base64

Так называемый “Texture value” - URL текстуры, упакованный в JSON и закодированный в Base64. Указывается с префиксом base64:. Пример:

texture: "base64:eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTQ1ZDY4YWVhODdjYzNmZDIwYjk2YjIxZTE4MjU1ZGIyOThiMmVhYzk4NjUyNjQ3MzExNmJkM2I1NzUwYjc4NyJ9fX0="

Экипированный предмет

Берёт предмет из инвентаря игрока. По умолчанию - из инвентаря того, кто открыл меню. Пример:

equipItem: HEAD

Совет

Все типы слотов смотри здесь

Можно взять предмет и у другого игрока - оформи свойство как объект и укажи имя. Плейсхолдеры тут работают. Пример:

equipItem {
  player: "%player_name_placeholder%"
  slot: HEAD
}

Десериализация из base64-строки

serialized восстанавливает предмет из base64-строки. Чаще всего такая строка приходит из плейсхолдера экстрактора item_serialized - например, в drag-and-drop сценариях. Пример:

{
  slot: 0
  serialized: "%moved_item_serialized%" // Плейсхолдер возвращает base64-строку
  name: "Новое имя предмета"
  lore: "Новый лор предмета"
}

Если рядом указать другие свойства предмета (например, name), они перезапишут соответствующие свойства десериализованного предмета.

Заметка

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

Лор

Лор - это список строк. Каждый элемент - одна строка лора. Например:

lore: [
  "Строка 1",
  "Строка 2",
  "Строка 3"
]

Зачарования

Зачарования имеют формат <enchantment>: <level>, где:

<enchantment>
Имя зачарования из Bukkit. Список здесь.

<level>
Уровень зачарования. Минимальный уровень - 1.

Пример:

enchantments {
  DAMAGE_ALL: 1
  DURABILITY: 2
}

Цвет

Используется для покраски предметов, у которых это поддерживается (кожаная броня, зелья). Задать цвет можно тремя способами - на примере белого:

Способ 1. RGB

Значения RGB (0-255) через запятую.

color: "255,255,255" // r,g,b

Способ 2. Имя цвета Spigot

Стандартные имена цветов Spigot.

color: WHITE

См. также

Список цветов есть здесь

Способ 3. HEX

Шестнадцатеричный формат, как в CSS.

color: "#FFFFFF"

Заметка

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

Флаг

Флаги управляют отображением свойств предмета. Это список строк, как lore. Например:

flags: [
  "HIDE_UNBREAKABLE",
  "HIDE_ENCHANTS",
]

Или если флаг один:

flags: "HIDE_ATTRIBUTES"

В Spigot сейчас доступны такие флаги:

• HIDE_ATTRIBUTES - скрыть атрибуты предмета (например, урон).

• HIDE_DESTROYS - скрыть инфу о прочности.

• HIDE_ENCHANTS - скрыть зачарования.

• HIDE_PLACED_ON - скрыть инфу о том, куда предмет можно ставить.

• HIDE_POTION_EFFECTS - скрыть эффекты зелий.

• HIDE_UNBREAKABLE - скрыть метку unbreakable.

Заметка

Набор флагов в разных версиях Spigot отличается. Сверяйся с актуальным списком на этой или похожих страницах. Список выше - ориентир, не источник истины.

Эффект зелья

Свойство - список объектов, один объект на эффект. Пример:

potionData: [
  {
    effectType: FAST_DIGGING
    duration: 100
    amplifier: 1
  },
  {
    effectType: SPEED
    duration: 100
    amplifier: 2
  }
]

У каждого эффекта три обязательных параметра:

• effectType - тип эффекта. Все типы - здесь.

• duration - длительность в тиках (1 секунда = 20 тиков).

• amplifier - уровень эффекта.

Заметка

potionData работает только если это поддерживает сам материал предмета.

Фейерверк

Цветной фейерверк собирается через fireworkData. Пример:

fireworkData {
  power: 2
  effects: [
    {
      type: BALL
      trail: false
      colors: [
        "#FFFFFF",
        "#FF0000"
      ]
      fadeColors: [
        "#000000",
        "#00FF00"
      ]
    }
  ]
}

power задаёт время жизни фейерверка. Опциональный, по умолчанию 1.

effects - список объектов, один объект на эффект:

• type - форма взрыва. Все типы - здесь.

• trail - есть ли след в полёте.

• colors - цвета в момент взрыва.

• fadeColors - цвета при затухании.

В fireworkData можно положить несколько эффектов - тогда фейерверк взорвётся всеми сразу.

Заметка

Свойство работает только если материал - FIREWORK_ROCKET.

Книга

Через это свойство собирается уже написанная книга со страницами. Пример:

bookData {
  author: "Питер Пайпер"
  title: "&e&lЗаголовок"
  pages: [
    "Содержимое первой страницы",
    "Содержимое второй страницы"
  ]
}

Параметры:

• author - отображаемый автор.

• title - отображаемый заголовок.

• pages - список строк. Каждый элемент - отдельная страница.

Заметка

bookData работает только для материала WRITTEN_BOOK.

Баннер

Декорированный баннер задаётся через bannerData. Есть два способа.

Способ 1. NBT

Можно собрать баннер в любом дизайнере, например этом, и вставить готовый NBT строкой. Пример:

bannerData: "{BlockEntityTag: {Base: 12, Patterns: [{Pattern: hh, Color: 6}, {Pattern: vh, Color: 6}, {Pattern: lud, Color: 7}, {Pattern: tts, Color : 6}, {Pattern: vh, Color: 14}, {Pattern: cre, Color: 2}]}}"

Способ 2. HOCON

Многословнее, но нагляднее - перечислить узоры списком объектов. Пример:

bannerData: [
  {
    type: BASE
    color: WHITE
  },
  {
    type: MOJANG
    color: RED
  }
]

Каждый элемент - один узор:

• type - тип узора. Все типы - здесь.

• color - цвет узора. Spigot принимает для баннеров только именованные цвета.

Модификатор атрибута

Накладывает на предмет записи Bukkit AttributeModifier. Удобно, когда нужен кастомный урон / броня / скорость без возни с сырым NBT.

attributeModifier: [
  {
    type: "generic.attack_damage"
    amount: 7
    operation: "add_number"
    slot: HAND
  },
  {
    type: "generic.armor"
    amount: 5
    operation: "add_number"
    slot: CHEST
  }
]

Параметры:

• type - ключ атрибута. Bukkit ждёт namespaced-форму, например generic.attack_damage, generic.armor, generic.movement_speed. Внутри плагин приводит её к нижнему регистру.
• amount - числовое значение модификатора. По умолчанию 0.
• operation - одно из add_number, add_scalar, multiply_scalar_1. По умолчанию add_number.
• slot - опционально. Ограничить модификатор одним слотом экипировки: HAND, OFF_HAND, HEAD, CHEST, LEGS, FEET. Без этого поля модификатор работает в любом слоте.

NBT-теги

Осторожно

Чтобы пользоваться этим свойством, сначала поставь плагин NBT_API.

Через NBT можно навешивать на предмет всё, чего ещё нет в самом плагине. Сами теги пишутся прямо в HOCON или строкой. Например, можно задать имя предмета через NBT:

{
  slot: 0
  material: IRON_PICKAXE
  nbt {
    display {
      Name: "&aМоя кирка"
    }
  }
}

Осторожно

Внутри NBT-тегов плейсхолдеры не работают - так сделано ради производительности, чтобы не пропускать каждое строковое значение через подстановку на лету.

Внутри nbt пиши любые HOCON-конструкции - при загрузке плагин превратит их в NBT-теги. Учти, что в разных версиях Minecraft NBT отличается. Если тег не работает - скорее всего, формат неверный для твоей версии. Ещё пример: навесим на предмет два зачарования:

{
  slot: 0
  material: IRON_PICKAXE
  nbt {
    display {
      Name: "Моя кирка"
    }
    ench: [
      {
        id: 34
        lvl: 2
      },
      {
        id: 35
        lvl: 3
      }
    ]
  }
}

ench - список объектов. Типы и имена тегов должны точно совпадать с тем, что Minecraft ждёт в финальном NBT.

И, разумеется, можно класть свои кастомные теги:

nbt {
  mytag1: "mytag"
  mytag2: 15
  mytag3 {
    mytag1: "hello"
  }
}

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