Item-NBT-API (tr7zw/Item-NBT-API)
Добавляйте пользовательские NBT-теги к предметам/плиткам/сущностям без NMS!
Если вы когда-либо хотели добавить пользовательские данные к предметам Minecraft на вашем сервере без копания в серверные внутренности, вы, вероятно, столкнулись с проблемой. Либо вы используете сомнительные обходные пути, либо избегаете всего этого вообще. Item-NBT-API даёт администраторам серверов и разработчикам плагинов чистый способ прикреплять пользовательские NBT-теги к предметам, плиткам и мобам без касания хрупких внутренних компонентов, которые ломаются между версиями.
Что делает этот проект
NBT означает Named Binary Tag. Это способ хранения структурированных данных в предметах, сущностях и блоках Minecraft. Когда вы поднимаете алмазный меч с остротой V, это заклинание хранится как NBT-данные внутри предмета. Item-NBT-API позволяет вашим плагинам безопасно читать и записывать эти данные.
Ключевым здесь является слово "безопасно." Вместо того, чтобы копаться во внутреннем серверном коде Minecraft (который разработчики Java называют NMS), эта библиотека предоставляет стабильный интерфейс. Ваш код не сломается после следующего обновления игры от Mojang.
Вы также можете хранить NBT-данные в нескольких форматах. Выпадите их в файлы. Сериализуйте их в виде строк JSON для вашей базы данных. Упакуйте их в Redis. Библиотека обрабатывает работу по конвертации.
Почему вы бы использовали это
Представьте, что вы управляете сервером экономики выживания. Вы хотите, чтобы купцы продавали заколоченные лопаты с пользовательскими именами и легендами, а также скрытыми тегами, отслеживающими происхождение предмета и предотвращающими дублирование. Без инструмента, подобного этому, вы либо пишете опасный код, который ломается каждые несколько месяцев, либо управляете всем в отдельных базах данных и синхронизируете их постоянно.
Или вы строите пользовательский плагин для подземелья. НПС должны сбрасывать добычу с конкретными свойствами. Меч может иметь скрытый множитель урона, таймер отсчёта или маркер квеста, закодированный в виде NBT. Управление всем этим чисто требует чего-то, подобного Item-NBT-API.
Владельцы серверов и создатели плагинов выигрывают потому, что:
- Совместимость между версиями. Вы пишете код один раз, и он работает в Minecraft 1.20+ без переписывания.
- Нет "NMS-муки." Seriously. Обновления NMS - кошмар для разработчиков.
- Предметы сохраняют свои данные, когда игроки сбрасывают их, размещают или хранят в сундуках.
- Гибкое хранение. Сохраняйте на диск, в базу данных или держите в памяти.
Для игроков? Они просто видят предметы, которые "чувствуются" особенными. Технические знания не требуются.
Установка и начало работы
Предполагая, что вы строите плагин для Bukkit/Spigot/Paper, вы подключаете это через Maven или Gradle. Вот подход Maven:
<dependency>
<groupId>de.tr7zw</groupId>
<artifactId>item-nbt-api</artifactId>
<version>2.15.7</version>
</dependency>Добавьте это в блок вашего репозитория, и вы готовы. Поддерживаются recent версии Minecraft (26.1.x), хотя рекомендуется проверить страницу релизов на GitHub для вашей конкретной версии сервера, поскольку цикл обновлений стал немного запутанным.
Как только это импортировано, базовое использование простое. Вы берёте ItemStack, оборачиваете его с помощью библиотеки и начинаете читать или записывать теги. API чувствуется знакомо, если вы работали с другими библиотеками Bukkit.
Как это работает
Библиотека абстрагирует различия версий. Внутренний формат NBT Minecraft меняется регулярно. Код, который вы пишете, используя Item-NBT-API, компилируется в версию-специфичный сбор, который знает, как безопасно общаться с внутренними компонентами вашего сервера.
Предположим, вы хотите отметить меч как "связанный с душой", чтобы он не падал, когда игрок умирает. Вы устанавливаете пользовательский NBT-тег, затем подключаетесь к событию смерти игрока и проверяете этот тег. Легко.
Теги имеют структуру. Вы не просто храните случайные строки. Вы можете создавать сложные вложенные данные. Массивы чисел. Множественные уровни тегов внутри тегов. Если вы работали с JSON раньше, структура кажется похожей.
Здесь становится интересно: вы также можете сохранить эти данные. Сериализуйте весь NBT-компунд в строку, бросьте её в вашу базу данных, и восстановите её позже. Игрок выходит с пользовательским предметом, заходит обратно через неделю, и данные предмета остаются точно такими, какими они были.
Практические примеры, которые имеют значение
Давайте перейдём к конкретике. Один из распространённых случаев использования - создание косметических предметов. Представьте декоративный шлем, отображающий уникальное имя и описание игрокам:
NBTItem item = new NBTItem(helmet);
item.setString("customName", "Корона древних");
item.setString("customLore", "Создано в утерянном веке");
helmet = item.getItem();Предмет сохраняет эти теги навсегда. Когда кто-то открывает его в инвентаре, плагины могут читать эти теги и отображать специальное поведение.
Другой практический аспект: лидерборды. Вы можете маркировать предметы временными метками и UUID игроков, затем запрашивать вашу базу данных для нахождения самых ценных мечей, когда-либо созданных на вашем сервере. Отслеживайте цепочки владения. Строите целую экономику предметов на основе NBT-данных.
Вы также могли бы построить систему износа, не используя встроенную износность Minecraft. Храните оставшиеся использования в NBT, проверяйте их при каждом ударе и отображайте пользовательские полосы повреждений или эффекты частиц. Скайблок-серверы делают подобное всё время.
Если вы управляете пользовательской мини-игрой, вы можете маркировать снаряды UUID стрелка и отслеживать обнаружение попадания с помощью счётчиков предметов NBT. Добыча из подземелья может быть помечена по уровню сложности. Станции крафта могут отслеживать пользовательские рецепты в NBT без изменения системы рецептов игры.
Что сбивает с толку
Большой подвох? Совместимость версий. Библиотека обрабатывает это, но вам всё равно нужно перестраивать ваш плагин для новых версий Minecraft. Вы не можете просто положить тот же JAR на сервер 1.20 и сервер 1.21. (На самом деле, в последних патчах это улучшилось, давайте проверим заметки к выпуску... да, 2.15.7 добавила широкую поддержку сборок 26.1.x с предположением, что Mojang не сломит всё в патчах. Это полезно.)
Другая проблема: NBT-данные сохраняются только для предметов, которые вы трогали с помощью библиотеки. Если кто-то зачарует меч в обычной мастерской, библиотека видит это нормально. Но если они используют какой-то сторонний плагин для заклинаний, взаимодействие может стать странным. Всегда тестируйте со всей вашей стопкой плагинов.
Производительность обычно не является проблемой, но запись огромных NBT-компундов каждый тик определённо покажется в профайлинге. Кэшируйте, что можете. Не сериализуйте огромные структуры данных в вашу базу данных на каждом событии.
Ещё одна вещь: игроки не могут видеть NBT-теги напрямую, если вы не отображаете их специально. Это обычно то, что вы хотите. Но это означает, что ваша пользовательская система предметов невидима для клиентов vanilla Minecraft. Они не понимают вашу механику "связан с душой" без объяснения от вашего плагина.
Инструменты, которые хорошо работают вместе
Если вы строите косметические системы вместе с пользовательскими предметами, посмотрите на Создателя обёрток Minecraft, чтобы позволить игрокам проектировать пользовательские обёртки для своих персонажей. Для серверов с пользовательскими движениями или текстовой брендинговой информацией Создатель MOTD Minecraft помогает строить привлекательные описания сервера. NBT-данные для предметов хорошо сочетаются с настраиваемым представлением сервера.
Варианты, которые стоит знать
Если Item-NBT-API не подходит, несколько других проектов решают подобные проблемы. ConfigMe проще, но менее гибкий. Если вы готовы вручную использовать NMS, вы получаете больше контроля, но теряете совместимость. Некоторые серверы используют сырые командные блоки и системы счётчиков, которые работают для базовых случаев, но не масштабируются.
Большинство сообществ придерживаются Item-NBT-API, однако. Он существует достаточно долго (674 звёзд на GitHub, активная разработка), чтобы экосистема поддерживала его. Существуют уроки. Другие разработчики плагинов используют его. Вы не рискуете на заброшенном проекте.



