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

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

Эта страница описывает только поведение, на данный момент подтверждённое в кодовой базе ResourcePackManager.

Самый полезный первый шаг для любой проблемы RSPM:

/rspm status

Он печатает версию, режим развёртывания (standalone vs network-backend), маскированный сетевой ключ, состояние Java + Bedrock-пака, активный путь доставки с URL, разрешённый внешний хост + авто-определённый публичный IP, все релевантные флаги конфига, напоминание о развёртывании прокси (сетевой прокси-jar — это тот же ResourcePackManager.jar) и обнаружение Floodgate / Geyser-Spigot. Такая же команда существует, когда jar работает на прокси, и печатает аналоги на стороне прокси (список бэкендов, результаты загрузки по каждому бэкенду, состояние объединённого пака).

Игроки не получают ресурс-пак​

Сначала проверьте следующее:

  • autoHost должен быть включён, если вы хотите, чтобы ResourcePackManager автоматически пушил URL
  • собранный пак должен существовать, и хотя бы один путь доставки (self-host или удалённый) должен был успешно отработать
  • игроки получают пак только при входе или через первоначальный broadcast загрузки, который срабатывает в момент готовности хостинга

При необходимости:

  1. Выполните /rspm status и посмотрите секцию «Hosting». Active delivery показывает, используется ли сейчас self-host, удалённый, или ни один.
  2. Если «active delivery: not yet ready» — сборка или загрузка ещё идут. Плагин громко предупреждает в консоли, когда игрок подключается слишком рано, и автоматически отправит пак, как только доставка будет готова.
  3. Если «active delivery: none — hosting disabled or failed» — autoHost отключён, либо проверки self-host и удалённая загрузка обе не прошли. См. «Self-host sanity checks failed» и «Auto-hosting cannot reach the remote server» ниже.
  4. Выполните /rspm reload, следите в консоли за результатами загрузки / проверки self-host, затем перезайдите тестовым игроком.

Если вы хостите самостоятельно через свой внешний конвейер (autoHost: false), RSPM не пушит ваш кастомный URL за вас. В такой настройке вам всё ещё нужен собственный серверный процесс доставки пака.

ItemsAdder установлен, но его содержимое отсутствует в итоговом паке​

Обычно это означает, что ItemsAdder всё ещё настроен так, что мешает ResourcePackManager читать или хостить его вывод.

Используйте:

/rspm itemsadder configure

Эта команда сейчас:

  • включает resource-pack.hosting.no-host.enabled
  • отключает protection_1, protection_2 и protection_3
  • устанавливает resource-pack.zip.compress-json-files: false
  • запускает /iareload, затем /iazip
  • примерно через 15 секунд перезагружает ResourcePackManager

Если команда сообщает, что ItemsAdder уже хостит собственный пак, сначала вручную отключите хостинг ItemsAdder и запустите команду снова.

Собранный пак некорректен или не загружается​

Интеграция авто-хоста ResourcePackManager явно обрабатывает следующие типы серверных ошибок:

  • отсутствуют требуемые файлы
  • файл слишком большой
  • неверный формат файла
  • отсутствующая сессия
  • удалённый сервер недоступен

Если вы столкнулись с одной из них:

  1. Выполните /rspm reload, чтобы пересобрать пак.
  2. Проверьте, не повреждён ли, не зашифрован ли или иначе нечитаем один из исходных паков.
  3. Проверьте, содержит ли итоговый собранный пак валидные pack.mcmeta и pack.png в корне.

Плагин пропускает паки, которые не может корректно извлечь, и пишет предупреждения в консоль, когда это происходит.

При ошибке SESSION_NOT_FOUND от удалённого авто-хоста RSPM очищает свой UUID сессии и пере-инициализируется на следующем keep-alive тике — ручное вмешательство не требуется.

Ассеты одного плагина перекрывают ассеты другого​

Это контролируется параметром priorityOrder в:

plugins/ResourcePackManager/config.yml

Записи выше побеждают записи ниже.

Для не-объединяемых файлов ResourcePackManager заменяет файл с более низким приоритетом. Для объединяемых JSON-файлов он объединяет содержимое. Текущие объединяемые категории JSON:

  • sounds.json
  • языковые файлы
  • ванильные JSON моделей предметов в minecraft/models/item (нерекурсивное объединение: между паками комбинируется только массив overrides, остальная часть файла следует правилу «побеждает наивысший приоритет»)
  • файлы атласов
  • файлы шрифтов
  • определения моделей предметов формата 1.21.4+ в items/ (формат-зависимое объединение, учитывающее структуру дерева предикатов)

pack.mcmeta также объединяется особым образом: побеждает наивысший pack_format, диапазоны supported_formats расширяются (поддерживаются формы integer, массив из двух int и объект {min_inclusive, max_inclusive}), записи overlay объединяются, а нестандартные ключи верхнего уровня сохраняются. Записи overlay нормализуются для совместимости с 1.21.9+ добавлением полей min_format/max_format, если они отсутствуют. Источники базового атласа также сливаются в overlay-файлы атласа, чтобы overlay'и не затеняли базовые записи.

Если вам нужно изучить, что произошло при последнем объединении, проверьте:

plugins/ResourcePackManager/collision_log.txt

Текст GUI или элементы на основе шрифтов выглядят неправильно​

Файлы шрифтов — одна из категорий JSON, которые ResourcePackManager объединяет, но это не гарантирует, что две разные шрифтовые системы будут хорошо работать вместе в Minecraft.

Если меню или HUD на основе шрифта выглядит неправильно:

  1. Измените priorityOrder так, чтобы пак, который вы хотите видеть победителем, был выше.
  2. Выполните /rspm reload.
  3. Проверьте collision_log.txt, чтобы убедиться, что коллизии произошли там, где вы ожидали.

Изменения ресурс-пака не появляются сразу​

В ResourcePackManager есть watchdog для источников поддерживаемых паков.

Он ждёт, пока изменённый пак не останется неизменным в течение 3 секунд, и затем, как только все отслеживаемые паки стабильны, пересборка происходит немедленно.

Если вы активно перегенерируете пак другого плагина, дайте ему несколько секунд после окончания записи в файлы. Если сомневаетесь — выполните /rspm reload после того, как плагин-источник закончит.

Проверки self-host не прошли; откат на удалённый хостинг​

Это сообщение — нормальное поведение, когда preferSelfHost: true (по умолчанию), и одна из трёх проверок исправности self-host не прошла:

  1. Уровень 1 (эвристика) — разрешённый внешний хост — это RFC1918 / loopback / link-local. Либо установите selfHostExternalHost на ваше реальное публичное имя хоста, либо убедитесь, что плагин может достучаться до api.ipify.org / checkip.amazonaws.com.
  2. Уровень 2 (локальная самопроверка) — HEAD-запрос на http://127.0.0.1:<port>/rspm.zip не вернул 200 с непустым телом. Ловит коллизии при привязке порта или отсутствующие файлы пака.
  3. Уровень 3 (проверка внешней доступности) — magmaguy.com попытался забрать ваш анонсированный URL и не смог. Чаще всего: HTTP-порт не проброшен на роутере / файрволе. URL проверки и причина записываются в лог.

Исправления (в порядке предпочтительности): откройте HTTP-порт на вашем файрволе + роутере, установите selfHostExternalHost на маршрутизируемое имя хоста, либо установите preferSelfHost: false, чтобы полностью пропустить self-host.

Когда сама проверка magmaguy.com недостижима (RSPM не может с ней связаться, чтобы спросить), self-host оставляется, а не отбраковывается — обоснование в том, что резервному пути magmaguy.com тоже нужен, поэтому отказ из-за невозможности проверки был бы парадоксальным.

См. Самостоятельный хостинг для полного дерева решений.

Авто-хостинг не может достучаться до удалённого сервера​

Встроенный удалённый хост ResourcePackManager связывается с:

https://magmaguy.com/rsp/

Если это соединение не удаётся, плагин записывает предупреждения о связи и не может использовать удалённый резерв до успешного восстановления соединения.

Ваши варианты:

  1. починить исходящую HTTPS-связность сервера
  2. подождать, пока удалённый сервис снова станет доступным
  3. отключить autoHost и самостоятельно хостить сгенерированный zip
  4. открыть ваш HTTP-порт и оставить preferSelfHost: true, чтобы RSPM использовал self-host вообще без необходимости в magmaguy.com (в этом сценарии также установите selfHostExternalHost на ваше публичное имя хоста, чтобы внешняя проверка Уровня 3 была не нужна — RSPM оставляет self-host при IOException на проверке)

Я хочу хостить собранный пак через свой собственный веб-сервер​

Поддерживаемый кодом сценарий:

  1. Установите autoHost: false.
  2. Установите resourcePackRerouting, если хотите, чтобы ResourcePackManager записывал дополнительную копию в существующую папку.
  3. Самостоятельно хостите ResourcePackManager_RSP.zip.

resourcePackRerouting разрешается относительно каталога plugins, и целевая папка должна уже существовать.

Если вместо этого вы хотите использовать встроенный self-host HTTP-сервер RSPM (другое дело — та же JVM, что и плагин), см. Самостоятельный хостинг.

Мне нужно проверить, какие удалённые данные хранятся для этого сервера​

Используйте:

/rspm data_compliance_request

Если есть активная удалённая сессия хостинга, ResourcePackManager скачивает ответ в:

plugins/ResourcePackManager/data_compliance

Если удалённой сессии нет (например, вы используете self-host), команда сообщит, что удалённых данных для запроса нет.

Bedrock-пак не генерируется​

bedrockConversionEnabled по умолчанию true, поэтому он должен запускаться автоматически. Сначала запустите /rspm status — секция Bedrock Pack скажет вам, почему пака нет на диске:

  • «No Bedrock target detected» — нет локального Geyser-Spigot, нет локального Floodgate и нет сетевого режима. Преобразование намеренно пропускается. Установите Floodgate (для прокси-настроек) или Geyser-Spigot (для отдельностоящих настроек) и выполните /rspm reload.
  • «Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing» — обычно первый цикл сборки ещё не завершился (подождите ~30 с после загрузки), либо сканер нашёл ноль определений предметов в собранном паке, либо преобразование выбросило ошибку. Поищите в консоли предупреждения [BedrockConverter] или Generic scanner: discovered 0 items definition files.

Если авто-определение Geyser не срабатывает:

  1. Задайте bedrockGeyserFolder в config.yml в путь к папке данных вашего Geyser (например, Geyser-Spigot).
  2. Путь может быть абсолютным или относительным к каталогу plugins.

Конвертер авто-определяет Geyser в plugins/Geyser-Spigot/, в любом варианте plugins/Geyser-*/ или в config/Geyser-*/ для установок Fabric/NeoForge.

Для логирования по каждому предмету / каждой кости установите bedrockConverterDebug: true и перезагрузите.

Игроки Bedrock видят предметы в руке в неправильной позиции​

Это вопрос настройки, а не баг конвертации. Откройте plugins/ResourcePackManager/bedrock_display_offsets.yml и подкрутите нужную ось. Виды от первого и третьего лица независимы — настройка одного не влияет на другой. Bedrock-клиент перечитывает JSON attachable вживую без перезапуска, поэтому итерация быстрая. См. страницу преобразования Bedrock с полным списком параметров и описанием их назначения.

Кастомные текстуры брони отсутствуют у игроков Bedrock​

Кастомная броня рендерится на Bedrock путём комбинирования ванильной геометрии брони с Java-текстурой в качестве видимого слоя. Чтобы это работало, пак исходного плагина должен определять equipment-файл в assets/<namespace>/equipment/<material>.json рядом с определением предмета. Если лог конвертации показывает предмет, но в игре текстура брони не появляется — убедитесь, что этот файл присутствует в собранном паке.

Прокси: «Floodgate key.pem missing» при загрузке прокси​

Прокси-плагин не смог найти plugins/floodgate/key.pem на хосте прокси и перешёл в режим ожидания. RSPM выводит сетевую идентичность из этого файла, поэтому без него прокси не может связаться ни с одним бэкендом. Исправление:

  1. Установите Floodgate на прокси. Он и так нужен, чтобы Bedrock-игроки могли достучаться до прокси, поэтому это нужно независимо от RSPM.
  2. Убедитесь, что plugins/floodgate/key.pem на прокси побайтово идентичен такому же файлу на каждом бэкенде. Скопируйте один канонический key.pem на каждый компонент (другие бэкенды + прокси) и перезапустите всё. Floodgate и так требует это для Bedrock-аутентификации, поэтому если Bedrock-игроки сейчас работают в вашей сети, это уже сделано.

Прокси: «no merged pack» после нескольких циклов опроса​

После ~20 секунд пустых циклов опроса (4 цикла × 5 с по умолчанию) на прокси RSPM записывает однократный диагностический баннер, перечисляющий каждый опрошенный бэкенд, HTTP-URL, который он пытался запросить, и результат (200 / 304 / 404 / CONNECT_FAILED / и т. д.). Баннер объясняет наиболее распространённые исправления:

  • CONNECT_FAILED на каждом бэкенде → прокси не может достучаться до HTTP-порта бэкенда. Проверьте, что адрес в velocity.toml / config.yml — это адрес, до которого прокси действительно может дозваниться (а не, например, внутрисетевое Docker-имя, которое не резолвится из сети прокси), и что объявленный HTTP-порт бэкенда открыт между прокси и бэкендом. Баннер печатает точный URL, который он пробовал; до того как бэкенд объявил свой порт, прокси откатывается на mcPort + network-http-offset-v2, поэтому ранний CONNECT_FAILED может также означать, что этот запасной порт ещё недоступен.
  • NOT_FOUND_404 на каждом бэкенде → бэкенды работают, но не производят Bedrock-пак. Запустите /rspm status на каждом бэкенде; диагностический блок Bedrock Pack скажет вам, почему.

Баннер срабатывает один раз за период «застоя», и строка «NetworkSync: recovered» записывается, когда хотя бы один бэкенд снова начинает возвращать контент. См. Прокси-сети для подробностей.

Прокси: Bedrock-игроки не видят моделей при первой загрузке прокси​

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

Исправление — перезапустить прокси после того, как бэкенд записал Wrote merged Geyser mappings: N entries. RSPM заранее раскладывает маппинги предыдущего запуска при загрузке прокси, поэтому это бьёт только на абсолютно новой установке — последующие загрузки имеют что-то готовое до того, как Geyser сканирует.

Бэкенд: «Backend HTTP server failed to bind on port X»​

В сетевом режиме бэкенд выставляет свои Bedrock-выводы через небольшой HTTP-сервер. Если порт занят или недоступен, вы увидите многострочный блок [ERROR] в консоли. Исправления:

  • Установите selfHostPort в другое положительное значение в config.yml.
  • Или измените networkHttpOffset-v2, чтобы сместить авто-выводимый порт от коллизии (например, RCON на mcPort + 1? установите 2 или 3). Вам не нужно обновлять прокси для совпадения: как только бэкенд успешно привязался, он автоматически объявляет прокси свой реальный HTTP-порт, поэтому собственный network-http-offset-v2 прокси имеет значение только как догадка до объявления.

Пока HTTP-сервер бэкенда упал, Bedrock-пак этого бэкенда не доходит до прокси через прямую загрузку. Резервная ретрансляция magmaguy.com по-прежнему работает (бэкенд пушит свои файлы на ретранслятор, и прокси забирает их оттуда).

Очистка устаревшего конфига v1​

Администраторы, обновляющиеся с RSPM v1, могут иметь мёртвый ключ networkHttpOffset (без -v2) в своём config.yml. RSPM v2 намеренно не читает старый ключ — вы получите дефолт v2 (1), записанный в конфиг при следующей загрузке автоматически. Мёртвый ключ v1 сидит в вашем конфиге как безвредный артефакт, пока вы не уберёте его вручную.