Кастомные предметы Minecraft: ItemsAdder, Oraxen, Nexo

Кастомные предметы на сервере Paper - это ванильные предметы в костюме. Сервер выдаёт игроку обычный предмет - бумагу, палку, алмазный меч - с меткой, которая велит клиенту нарисовать другую модель, а серверный ресурспак поставляет модель и текстуру. Плагины вроде ItemsAdder, Oraxen и Nexo автоматизируют обе половины: вы описываете предметы, блоки и мебель в YAML, плагин собирает ресурспак и отвечает за поведение, а игроки скачивают пак при входе. Это работает без клиентских модов, это действительно хорошо, и у этого есть три цены, о которых узнают поздно: пак нужно где-то разместить, чтобы игроки могли его скачать, игроки Bedrock через Geyser не видят его без дополнительной работы, а кастомные блоки и мебель используют трюки, которые обходятся серверу дороже обычных блоков.

В этом руководстве разобрано, как работает этот трюк, три основных плагина, хостинг пака и проблемы, с которыми вы столкнётесь. Основы серверных ресурспаков - ключи server.properties и хеш SHA-1 - описаны в статье MOTD, иконка и ресурспаки.

Как кастомные предметы работают без модов#

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

Много лет таким маркером было целое число CustomModelData. Ресурспак переопределял модель, скажем, paper и говорил: «если CustomModelData равен 1001, используй вместо этого вот эту модель». Плагины раздавали бумагу с этим числом, а игроки видели меч, монету или шляпу.

В Minecraft 1.20.5 NBT предметов заменили компонентами данных, а в версиях с 1.21.2 по 1.21.4 модели предметов переработали ещё сильнее:

• Компонент minecraft:item_model (1.21.2) позволяет предмету напрямую указывать на любую модель, так что кастомному предмету больше не нужно перехватывать переопределения чужого предмета.
• В 1.21.4 определения моделей предметов переехали в assets/<namespace>/items/, а custom_model_data стал компонентом со списками чисел с плавающей точкой, флагов, строк и цветов вместо одного целого числа.

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

Поведение - забота сервера. Кастомный меч с дополнительным уроном, кастомная еда, дающая эффект зелья, кастомный инструмент, копающий область 3x3, - всё это серверная логика в плагине. Ресурспак меняет только внешний вид.

Кастомные блоки и мебель: дорогая часть#

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

Трюки с состояниями блоков дешёвые: кастомная руда на состоянии нотного блока стоит столько же, сколько нотный блок. С мебелью иначе. Стул, лампа или стол обычно - это сущность (item display в современных версиях, стойка для брони в старых) плюс барьерные блоки или сущности взаимодействия для хитбокса. Таверна с шестьюдесятью предметами мебели - это шестьдесят с лишним сущностей в одном чанке, а город из таких зданий набирает много. У них нет ИИ, так что они гораздо дешевле мобов, но они учитываются, отправляются каждому клиенту поблизости и видны в /paper entity list.

Не злоупотребляйте постройками с обилием мебели, предпочитайте декор из блоков там, где он выглядит не хуже, и проверяйте число сущностей после того, как построено что-то крупное. Команды есть в статье Очистка сущностей и ClearLag - вместе с напоминанием никогда не запускать сплошной /kill на сервере с мебелью-сущностями.

Сравнение ItemsAdder, Oraxen и Nexo#

Доминируют три плагина. Все три платные, все три генерируют ресурспак, и все три поддерживаются небольшими командами, поэтому перед покупкой проверьте, поддерживает ли текущая версия вашу версию Minecraft.

Практические советы:

• Если хотите покупать готовый контент - наборы мебели, паки оружия, паки эмодзи, - больше всего его у ItemsAdder, его продают сторонние авторы.
• Если хотите проектировать предметы сами и предпочитаете читаемый YAML, в Oraxen или Nexo проще разобраться. Новые серверы, выбирающие между ними сегодня, обычно берут Nexo, потому что туда ушла активная разработка.
• Не запускайте два из них одновременно. Оба будут пытаться завладеть ресурспаком и состояниями блоков.

С ними интегрируются другие плагины: MythicMobs для кастомных мобов с кастомными моделями, MMOItems для RPG-характеристик предметов и разные плагины крафта и GUI. Прежде чем покупать целый набор, проверьте совместимость.

Настройка ItemsAdder#

ItemsAdder встречается чаще всего, поэтому вот его общая схема. Пути и команды меняются между мажорными версиями; читайте документацию к той версии, которую ставите.

1. Установите jar плагина и его зависимости. Проверьте список зависимостей на странице загрузки - исторически ему были нужны ProtocolLib и его собственный плагин-библиотека (LoneLibs).
2. Запустите сервер один раз. Он создаст plugins/ItemsAdder/ с файлом config.yml и папкой контента (plugins/ItemsAdder/contents/ в текущих версиях), где лежат определения предметов, каждый набор - в своей папке пространства имён.
3. Выберите в config.yml, как будет размещаться ресурспак (следующий раздел).
4. Добавьте или напишите контент, затем соберите пак:

/iazip/iareload/iaget <namespace:item>

/iazip компилирует все папки контента в один zip-ресурспак и, в зависимости от настроек хостинга, загружает его или раздаёт сам. /iareload перезагружает определения предметов. /iaget выдаёт вам предмет для проверки. После /iazip перезайдите, чтобы скачать новый пак.

Минимальное определение предмета в формате ItemsAdder выглядит так, хотя схема менялась, и копировать лучше из актуальных примеров, а не отсюда:

info:  namespace: myserveritems:  ruby:    display_name: "Ruby"    resource:      material: EMERALD      generate: true      textures:        - item/ruby.png

Текстура кладётся в папку textures/item/ пространства имён. generate: true велит ItemsAdder собрать модель из текстуры. Базовый материал - то, к чему откатывается ванильное поведение: здесь это изумруд, поэтому предмет складывается по 64 и может заинтересовать жителей. Выбирайте базовые материалы осознанно: кастомная еда на основе хлеба ведёт себя как хлеб, если плагин это не переопределит.

Хостинг ресурспака#

Каждый клиент должен скачать пак, а Minecraft скачивает его по HTTP или HTTPS с URL, который присылает сервер. Значит, zip должен лежать по какому-то URL. Вариантов три.

• Хостинг, который предоставляет плагин. У ItemsAdder есть собственный вариант хостинга, который загружает пак за вас. Удобно; вы зависите от того, работает ли сторонний сервис.
• Раздача с самого сервера Minecraft. Плагин запускает внутри сервера Minecraft небольшой веб-сервер на дополнительном порту и сам раздаёт zip. Нужен ещё один выделенный и открытый порт. Загрузки идут с адреса вашего сервера, так что большой пак и много входов расходуют ваш трафик.
• Внешний хостинг. Загрузите zip на веб-хостинг, в объектное хранилище или на статический сайт и укажите плагину URL. Самый надёжный вариант для публичного сервера.

Что бы вы ни выбрали, пак должен быть доступен из сетей игроков, а URL должен отдавать сам файл, а не HTML-страницу загрузки. Файлообменники, которые ставят перед файлом страницу «нажмите, чтобы скачать», не подходят.

Держите пак небольшим. Каждый входящий игрок скачивает его один раз после каждого изменения, и пак на 100 МБ из несжатых текстур делает вход медленным для игроков с плохим соединением. Сжимайте PNG, удаляйте неиспользуемые контент-паки и не поставляйте звуки, которыми не пользуетесь. Принудительный пак (require-resource-pack=true в server.properties или аналогичная настройка плагина) означает, что отказавшиеся игроки не смогут играть - это правильно для сервера, чьи предметы без пака невидимы, но убедитесь, что запрос объясняет причину.

Bedrock, прокси и другие сложности#

Игроки Bedrock. Если вы запускаете Geyser, чтобы могли заходить игроки Bedrock, они не получают ресурспаки Java. У Geyser свой механизм кастомных предметов и блоков - через маппинги и сконвертированный пак Bedrock, - а у ItemsAdder, Oraxen и Nexo разный уровень поддержки или вспомогательные инструменты для его создания. Готовьтесь к настоящей работе и неидеальным результатам, особенно для мебели и кастомных блоков. Основы есть в статье Geyser для кроссплея с Bedrock.

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

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

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

Без плагина#

Для горстки косметических предметов платный плагин может вообще не понадобиться. Датапак или несколько команд могут выдавать предметы с компонентом модели, а ресурспак вы напишете сами:

/give @p minecraft:paper[minecraft:item_model="myserver:ruby"]

Такая форма требует 1.21.2 или новее (для отображаемого имени добавьте компонент item_name; синтаксис текста в нём изменился в 1.21.5, так что сверьтесь с вики для своей версии) и ресурспак, в котором определена модель myserver:ruby. Для простых косметических предметов и трофеев это чисто и устойчиво к будущим изменениям. Кастомных блоков, мебели, кастомного крафта с поведением или GUI это не даёт - и именно здесь плагин отрабатывает свою цену. Сторона датапаков разобрана в статье Датапаки для серверов.

На RE:NODE загрузка контент-пака - это перетаскивание zip в файловый менеджер, который распаковывает архивы на месте, а консоль показывает вывод /iazip и перезагрузки без фильтров, так что ошибки в вашем YAML видны сразу. Если раздаёте пак с сервера сами, добавьте порт на вкладке Network. Перед крупным изменением контента или обновлением Minecraft сделайте backup из панели; восстановление - одна кнопка.

FAQ#

Нужны ли игрокам моды, чтобы видеть кастомные предметы?

Нет. Им нужен ресурспак сервера, который клиент скачивает при входе. Игроки Java на ванильном лаунчере видят кастомные предметы, блоки и мебель, если принимают пак.

Стоит ли платить за ItemsAdder?

Если вам нужно много кастомного контента - мебель, блоки, GUI, эмодзи - и особенно если вы хотите покупать готовые паки, то да. Для нескольких косметических предметов хватит датапака и самодельного ресурспака с компонентом item_model.

Почему игроки видят фиолетово-чёрные или обычные предметы?

Пак не загрузился. Либо игрок от него отказался, либо URL недоступен или не отдаёт файл напрямую, либо пак собран для другой версии Minecraft. Проверьте URL в браузере и пересобирайте пак после любого обновления.

Вызывают ли кастомные блоки лаги?

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

Могут ли игроки Bedrock пользоваться предметами ItemsAdder?

Только с дополнительной работой через маппинги кастомных предметов Geyser и сконвертированный пак Bedrock, и результаты зависят от типа предмета. Рассчитывайте, что игроки Bedrock будут видеть некоторые предметы как их базовый материал, если вы не вложитесь в конвертацию.