Item API

Item API в NextLib нужен, чтобы перестать писать шумный и хрупкий код вокруг ItemMeta.

1. Что закрывает модуль

• Fluent-сборка ItemStack через ItemBuilder.
• Работа со служебными метками через PersistentDataContainer.
• Сравнение предметов без зависимости от количества (ItemUtil.isSimilar).

2. Конструкторы ItemBuilder

new ItemBuilder(Material.DIAMOND)
new ItemBuilder(Material.DIAMOND, 3)
new ItemBuilder(Material.DIAMOND, colorUtil)
new ItemBuilder(Material.DIAMOND, 3, colorUtil)

Когда нужен custom ColorUtil

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

3. Полный разбор методов

setName(String name)

• форматирует строку,
• устанавливает displayName.

Рекомендация: никогда не кодируйте в имени служебные идентификаторы.

setLore(String... lore) / setLore(List<String>)

• задаёт lore построчно,
• каждый элемент форматируется.

Рекомендация: lore для UX, не для бизнес-логики.

addEnchant(Enchantment, int level, boolean ignoreLevelRestriction)

• применяет чары,
• может игнорировать vanilla-лимиты.

Используйте ignoreLevelRestriction=true только осознанно.

addEnchants(Map<Enchantment, Integer>)

Пакетный вариант для набора чар.

setUnbreakable(boolean)

Удобно для декоративных UI-предметов.

addFlags(ItemFlag...)

Скрывает лишние атрибуты, делая item визуально «чистым».

setSkullOwner(String playerName)

Работает только на соответствующем meta-типе (голова).

setPersistentData(plugin, key, value)

Перегрузки:

• value: String
• value: int

Это главный механизм стабильной идентификации предмета в коде.

build()

Финализирует и возвращает ItemStack.

4. Production-пример

ItemStack reward = new ItemBuilder(Material.TRIPWIRE_HOOK)
    .setName("&bЛедяной скин")
    .setLore(List.of(
        "&7Редкость: &bRare",
        "&7Категория: &eTrap Skin",
        "",
        "&eНажмите для активации"
    ))
    .addEnchant(Enchantment.DURABILITY, 1, true)
    .addFlags(ItemFlag.HIDE_ENCHANTS, ItemFlag.HIDE_ATTRIBUTES)
    .setPersistentData(plugin, "reward_type", "trap_skin")
    .setPersistentData(plugin, "reward_id", 101)
    .build();

5. ItemUtil: чтение и сравнение

hasPersistentData(item, plugin, key)

Проверяет, есть ли метка STRING или INTEGER.

getStringData(item, plugin, key)

Возвращает строку или null.

getIntData(item, plugin, key)

Возвращает int или null.

isSimilar(first, second)

Сравнивает предметы без учёта amount.

Это полезно для:

• GUI-кнопок,
• токенов/купонов,
• сервисных предметов.

6. Архитектура предметов в больших проектах

ItemFactory

Создайте класс фабрики:

• createMainMenuButton()
• createQuestRewardItem(...)
• createAdminTool()

Плюсы:

• повторное использование,
• единый стиль,
• легче тестировать.

ItemIdentityPolicy

Используйте единый префикс для PDC ключей:

• nextlib:gui_action
• nextlib:reward_type
• nextlib:reward_id

Это снижает риск конфликтов.

7. Безопасность и анти-чит

Никогда не доверяйте только displayName/lore.

Проверяйте служебные PDC-теги:

if (!ItemUtil.hasPersistentData(item, plugin, "reward_id")) {
    return;
}

Сервер должен определять легитимность предмета по данным, которые клиенту сложно подделать.

8. Производительность

Для массовой генерации предметов:

• кешируйте шаблоны,
• не форматируйте одинаковые строки в tight-loop без нужды,
• избегайте лишних clone/meta-операций на горячем пути.

9. Частые ошибки

Несовпадение типа метки

Записали String, читаете как Integer.

Разные plugin namespace

Записали ключ одним plugin instance, читаете другим.

Сравнение только по имени

Игрок может подделать похожий предмет. Сравнивайте PDC.

10. Антипаттерны

• Бизнес-логика через lore-парсинг.
• Хранение критичных данных в имени предмета.
• Огромные цепочки builder прямо в listener-коде.

11. Большой FAQ

Можно ли хранить JSON в PDC?

Да, как строку, если объём небольшой и вы контролируете парсинг.

Что делать, если нужен сложный объект в метке?

Лучше хранить только id и подтягивать объект из сервиса/БД.

Можно ли использовать ItemBuilder для боевых предметов, а не только GUI?

Да. Но для боевой механики внимательно следите за балансом enchant/unbreakable.

12. Чеклист качества Item-слоя

• Все служебные предметы имеют PDC-метку.
• Есть фабрика предметов, а не хаос по listeners.
• Сравнение ключевых предметов идёт через isSimilar + PDC.
• Игроку всегда видно понятное назначение предмета.

При таком подходе Item API становится надёжной опорой для GUI, квестов, экономики и админ-инструментов.