Перейти к основному содержимому

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

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

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

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

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

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

Какой бы загрузчик его ни открыл, он выбирает подходящую точку входа. В более старых релизах поставлялся отдельный ResourcePackManager-GeyserBridge.jar; этот файл упразднён, и RSPM автоматически удаляет его остатки.

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

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

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

Более новая версия, уже лежащая в extensions/, никогда не перезаписывается более старой.

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

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

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

ГдеНастройкаПо умолчанию
Бэкенд plugins/ResourcePackManager/config.ymlgeyserExtensionAutoInstalltrue
Прокси config.ymlgeyser-extension-auto-installtrue

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

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

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

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

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

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

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

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

Его дескриптор намеренно объявляет более низкий уровень API Geyser (2.9.0), поэтому более старый Geyser спокойно загрузит его, а не откажется от jar сразу. Настоящее требование проверяется во время выполнения: расширение проверяет наличие нужных ему классов и отключает себя, когда их нет, что даёт понятное сообщение вместо отказа при загрузке, который администратор не сможет интерпретировать.

Оно спроектировано так, чтобы при несовместимости классов/связывания отказывать безопасно, а не тянуть 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.

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

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

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

Geyser регистрирует определения сущностей в собственном окне запуска. Если RSPM завершает генерацию Bedrock-пака после того, как это окно закрылось — а именно так и происходит при совершенно новой установке, когда на момент загрузки пака ещё нет, — определения приходят слишком поздно, чтобы попасть в уже замороженные реестры Geyser. 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, после первой успешной генерации пака. Одного лишь переподключения недостаточно, чтобы активировать определения, пропустившие окно запуска. При последующих загрузках порядок правильный, потому что пак уже существует к моменту, когда Geyser открывает свои окна регистрации.

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

  1. Убедитесь, что целевая папка extensions/ действительно содержит ResourcePackManager.jar.
  2. При загрузке Geyser должен показать расширение как загруженное, а RSPM выводит в лог, сколько кастомных определений сущностей Bedrock он зарегистрировал.
  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 автоматическая подписка расширений Geyser не срабатывает так, как на других платформах, поэтому прокси-плагин сам ретранслирует события жизненного цикла. Это обрабатывается внутренне и не требует настройки.

Что дальше​