Расширение Geyser и кастомные сущности Bedrock

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

Скачивать его отдельно не нужно. Тот же самый ResourcePackManager.jar, который вы устанавливаете как плагин, и есть это расширение.

Один jar, три роли

ResourcePackManager.jar одновременно является:

• бэкенд-плагином Bukkit/Paper,
• прокси-плагином Velocity и BungeeCord,
• и расширением Geyser.

Каждый загрузчик использует свою точку входа. Старые релизы поставляли отдельный ResourcePackManager-GeyserBridge.jar, который теперь упразднён. Обнаружив его, установщик помещает универсальный jar в очередь обновлений Geyser для замены при перезапуске.

Как он устанавливается

RSPM устанавливает расширение за вас в тех случаях, когда это возможно. Что именно происходит, зависит от того, где находится Geyser:

Ваша конфигурация	Что делает RSPM
Geyser-Spigot на том же сервере	При первой установке копирует работающий jar в plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Если байты имеющегося jar отличаются, подготавливает замену в extensions/update/ с учётом защиты от понижения версии. Новая установка или подготовленная замена запрашивает перезапуск; идентичный актуальный jar копировать не требуется.
Geyser на прокси (Geyser-Velocity / Geyser-BungeeCord)	Прокси-роль делает то же самое в папку Geyser-*/extensions/ на прокси.
Floodgate локально, Geyser внешний (Geyser работает в отдельном процессе)	Экспортирует копию под plugins/ResourcePackManager/geyser-extension/. Используйте точный путь из консоли: при наличии старого экспорта он может указывать на подпапку update/. Скопируйте этот jar в extensions/ внешнего Geyser и перезапустите Geyser. Один экспорт расширения не настраивает внешнюю доставку пака или загрузку определений при запуске.
Нет ни Geyser, ни Floodgate	Делать нечего — RSPM выводит информационную строку и пропускает установку.

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

Установка всегда требует одного перезапуска. Geyser загружает расширения при старте, поэтому свежескопированный или размещённый в очереди jar ничего не делает, пока сервер или прокси не будут перезапущены.

Как отключить авто-установку

У каждой роли свой переключатель, и они независимы:

Где	Настройка	По умолчанию
Бэкенд plugins/ResourcePackManager/config.yml	geyserExtensionAutoInstall	true
Прокси config.yml	geyser-extension-auto-install	true

Установка любого из них в false прекращает установку расширения и подготовку обновлений для него этой ролью, и в лог пишется соответствующая строка. Внимательно прочтите семантику:

• Это предотвращает будущие установки и подготовку обновлений.
• Это не удаляет установленный jar и не отменяет уже подготовленное обновление. Чтобы отключить мост, задайте соответствующие настройки в false и полностью остановите Geyser. Удалите ResourcePackManager.jar из extensions/ и extensions/update/, а также оставшиеся там старые ResourcePackManager-GeyserBridge.jar, затем запустите Geyser. Копия, оставшаяся в очереди, может восстановить расширение при запуске. Удаляйте только эти файлы RSPM.
• Отключение настройки не влияет на преобразование и доставку пака или уже установленное расширение. Именно удаление расширения отключает интеграцию кастомных сущностей Bedrock; преобразование предметов и доставка пака остаются отдельными функциями.

Отключение на бэкенде также запрещает подготовку скачанного обновления RSPM в очереди локального Geyser-Spigot. Расширение и плагин могут разойтись по версии. Поддерживайте их файлы согласованными вручную; проверка ниже проверяет необходимые классы Geyser и бинарную совместимость, а не равенство версий плагина и расширения.

Что расширение делает на самом деле

• Регистрирует кастомные определения сущностей Bedrock от RSPM в Geyser при старте, считывая идентификаторы сущностей из сгенерированного Bedrock-пака. Свойства каждой сущности собираются из контроллеров анимации и рендера, на которые ссылается её клиентский файл сущности, с сопоставлением по идентификатору контроллера, поэтому комплекты, чьи длинные пути файлов были сокращены, всё равно регистрируют свои свойства и анимации.
• Подменяет Bedrock-определение появляющихся сущностей, чтобы смоделированная сущность появлялась как своя кастомная Bedrock-сущность, а не как ванильный запасной вариант.
• Применяет живые данные сущности и переопределения свойств, пока сущность существует.
• Заранее подготавливает сетевые ID рецептов Geyser, что позволяет избежать целого класса проблем со сталкивающимися ID рецептов на Geyser 2.11.

Ресурсы берутся из комплектов сущностей, описанных в разделе Преобразование в Bedrock. Плагин предоставляет нативные файлы сущностей Bedrock в assets/<namespace>/rspm_bedrock_pack/, а RSPM импортирует их в созданный пак. Создающий содержимое плагин должен также пометить соответствующие Java-сущности через мост; один комплект ресурсов не превращает произвольные сущности в кастомные модели.

При запуске расширение читает идентификаторы из записей entity/*.entity.json в локально созданном паке RSPM. Оно проверяет стандартные пути вывода прокси plugins/resourcepackmanager/work/merged/Bedrock.zip и plugins/ResourcePackManager/work/merged/Bedrock.zip, затем вывод бэкенда plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip, относительно рабочего каталога Geyser. Внешний процесс Geyser не может автоматически прочитать вывод другой машины. Проверьте в журнале, какой пак был предварительно загружен; копирование расширения само по себе не предоставляет определения.

Требования к версии Geyser

Расширение рассчитано на Geyser 2.11+.

Дескриптор объявляет уровень API Geyser 2.9.0. Этот более низкий уровень не доказывает совместимость со старым Geyser. Во время выполнения расширение проверяет нужные классы и отключает мост, если они отсутствуют.

Оно спроектировано так, чтобы при несовместимости классов/связывания отказывать безопасно, а не тянуть Geyser за собой. Оболочка расширения ссылается только на давно существующие типы API Geyser; классы, зависящие от версии, проверяются до запуска ядра. Если ваша сборка Geyser не содержит класса, нужного мосту, мост отключает сам себя и сообщает об этом:

Disabled the RSPM custom Bedrock entity bridge: this Geyser build does not ship <class>. Geyser itself is unaffected, but custom Bedrock entities will not appear until a ResourcePackManager update matches this Geyser version.

Отключение моста не отключает отдельный конвертер предметов или поставщик паков. Им по-прежнему нужны собственные совместимые API Geyser и успешная доставка пака. Используйте совместимую пару RSPM/Geyser для восстановления кастомных сущностей.

Более ранние версии RSPM добивались того же результата, подменяя в реестре Geyser копию одного из его внутренних трансляторов пакетов. Эта подмена транслятора убрана: расширение теперь использует публичные события и жизненный цикл сущностей Geyser 2.11 для регистрации и подмены определения при спавне. Ядро по-прежнему проверяет ограниченный набор внутренностей Geyser, используемых для построения экземпляров определений и получения плагин-сообщений с бэкенда, — поэтому проверка совместимости и точное соответствие версий RSPM/Geyser всё ещё имеют значение.

Порядок загрузки: почему иногда нужен перезапуск

Geyser регистрирует определения сущностей во время своего окна запуска. Если RSPM создаёт первый пак Bedrock после закрытия этого окна, определения опаздывают для работающих реестров. RSPM просит перезапустить процесс, чтобы предварительно загрузить созданный пак при следующем запуске:

RSPM custom Bedrock entity definitions became available after Geyser closed its startup registration windows ... restart the proxy once to activate the newly generated custom models.

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

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

Проверка работоспособности

1. Убедитесь, что целевая папка extensions/ действительно содержит ResourcePackManager.jar.
2. При запуске проверьте строку RSPM Geyser bridge health. Она содержит версию расширения, artifactSha256, activationRoute, loadedDefinitions, packUuid и definitionWindows. Для пака с кастомными сущностями ожидаются зарегистрированные определения, нужный UUID пака и definitionWindows=observed. MISSED или RSPM GEYSER BRIDGE UNHEALTHY означает пропущенное окно регистрации; статуса загруженного расширения недостаточно.
3. Зайдите с Bedrock и проверьте внешний вид и анимацию сущности с моделью. Если она осталась ванильным носителем, например стойкой для брони, проверьте активацию моста, доставку пака клиенту, зарегистрированные определения и интеграцию создающего плагина. Успешный журнал запуска сам по себе не доказывает отображение сущности клиентом.

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

«Расширение загружено, но сущности всё равно стойки для брони». Пак и расширение — две отдельные половины. Сначала убедитесь, что сам Bedrock-пак дошёл до клиента (см. Преобразование в Bedrock); без ассетов сущностей из пака определениям нечего отображать.

«Работало, потом я обновил Geyser, и сущности сломались». Поищите сообщение о самоотключении, приведённое выше. Обновление Geyser может сдвинуть ту часть API, которую проверяет мост.

«В extensions/ вообще ничего не устанавливалось». Проверьте консоль на Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall (бэкенд) или ... by geyser-extension-auto-install (прокси). Кто-то выключил переключатель. Если и Geyser, и Floodgate локально отсутствуют, вы вместо этого увидите Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation — это RSPM правильно решает, что устанавливать не во что.

«Я обновил RSPM, но расширение всё ещё старой версии». Расширение заменяется только при перезапуске, а если RSPM разместил его через очередь обновлений Geyser, для подмены нужен один перезапуск. Держите jar плагина и jar расширения на одной версии — это один и тот же файл, поэтому достаточно заново скопировать плагин.

Расширение устанавливает ранние программные подписки на жизненный цикл наряду с обработчиками с аннотациями. На Velocity прокси-плагин также пересылает события жизненного цикла и сессии, покрывая варианты запуска с пропущенными автоматическими подписками. Настройка не нужна. Для диагностики сбоев активации используйте строку состояния при запуске и предупреждения о регистрации или пересылке.

Что дальше

• Преобразование в Bedrock / Geyser — что именно преобразуется и как раздаётся пак
• Прокси-сети — Geyser на прокси
• Устранение неполадок