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

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

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

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

/rspm status

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

Консоль молчит намеренно​

RSPM печатает одну строку при каждой свежей инициализации пути доставки — результат:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

Всё остальное — каждый подготовленный пак, каждый объединённый кластер, каждая проверка стабильности, каждая проба self-host и её результат — по умолчанию подавляется. Условие, из которого RSPM восстанавливается сам, не сообщается как предупреждение. Если проба self-host не прошла и RSPM молча переключился на удалённый хостинг — это успех, а не сбой, и консоль об этом ничего не говорит.

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

/rspm verbose on

затем выполните /rspm reload. Эта команда сама записывает verboseLogging: true в plugins/ResourcePackManager/config.yml, и настройка переживает перезапуски, поэтому выполните /rspm verbose off, когда закончите. Ручное редактирование ключа делает то же самое. У Bedrock-конвертера отдельный переключатель — bedrockConverterDebug, доступный только через конфиг.

Предупреждения, которые вы можете законно увидеть, — это настоящие сбои: повторяющийся отказ доставки пака конкретному игроку, клиент, сообщающий INVALID_URL, HTTP-порт, к которому не удалось привязаться, отказ обоих путей доставки или прокси, который отработал несколько циклов опроса, а ни один бэкенд не выдал контент.

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

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

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

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

  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. Задайте verboseLogging: true, выполните /rspm reload, следите в консоли за результатами загрузки / проверки self-host, затем перезайдите тестовым игроком. (Без этого флага шаги проб не печатаются — только итоговая строка результата «Resource pack is live via ...».)

Предложение пака при входе задерживается примерно на одну секунду. Если Java-клиент сообщает FAILED_DOWNLOAD или DISCARDED, RSPM автоматически повторяет попытку до трёх раз для этой сессии игрока. Он не повторяет попытку при отказе игрока или при INVALID_URL; исчерпание повторов и некорректные URL логируются как настоящие сбои.

Если вы хостите самостоятельно через свой внешний конвейер (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 в корне.

Если включённый пак не удаётся извлечь или подготовить, текущая сборка прерывается, и консоль называет проблемный пак. Почините этот пак, удалите добавленный вручную ZIP или задайте isEnabled: false в его конфиге автоматической интеграции перед перезагрузкой.

Один сломанный пак больше не блокирует всё навсегда​

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

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

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

Исключение снимается само. Запись о сбое привязана к размеру и времени модификации файла, поэтому починка или замена файла автоматически снимает карантин, и пак возвращается в следующее объединение — без команды, без перезапуска. /rspm reload также сбрасывает все записи карантина с нуля. Счётчики сбоев, не достигшие трёх, обнуляются после любой успешной сборки, поэтому не связанные между собой кратковременные сбои за долгий аптайм не могут накопиться в исключение.

При ошибке 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 после того, как плагин-источник закончит.

/rspm status говорит «удалённый хостинг», а я ожидал self-host​

Это нормальное поведение, когда preferSelfHost: true (по умолчанию), и одна из трёх проверок исправности self-host не прошла. RSPM не предупреждает об этом — откат на удалённый хостинг является успешным результатом, поэтому непрошедшая проверка логируется на уровне деталей с явным «This is OK.» и остаётся скрытой, пока не задан verboseLogging: true. Единственная строка, которую вы получаете по умолчанию, — Resource pack is live via automatic hosting — ....

Выполните /rspm verbose on (или задайте verboseLogging: true) и /rspm reload, чтобы увидеть, какой из трёх уровней не прошёл:

  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 проверки и код причины (PRIVATE_HOST_REJECTED, CONNECT_TIMEOUT, ECONNREFUSED, RATE_LIMITED, ...) печатаются при verboseLogging.

Исправления (в порядке предпочтительности): откройте 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-порт, задать selfHostExternalHost на ваше публичное имя хоста и оставить preferSelfHost: true. Явное имя хоста пропускает авто-определение публичного IP, но RSPM всё равно пытается выполнить проверку Уровня 3. Если сам сервис проверки недоступен, RSPM продолжает self-host, а не считает этот сбой связи доказательством того, что ваш URL недостижим.

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

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

  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/data.zip

RSPM также записывает ReadMe.md в ту же папку 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: живой провайдер пропущен, потому что существует устаревший пак​

Если консоль сообщает Legacy RSPM Bedrock pack detected, значит Geyser уже просканировал старый ResourcePackManager_Bedrock.zip из своей папки паков при загрузке. Удаление этого файла во время работы процесса оставило бы Geyser с кодеком в памяти для пути, которого больше нет, поэтому RSPM намеренно пропускает свой живой провайдер пака на эту загрузку.

Полностью остановите сервер, удалите только тот точный путь к устаревшему файлу, который напечатал RSPM, и запустите сервер снова. Не используйте /reload для этой миграции. Текущий пак остаётся в plugins/ResourcePackManager/output/ и раздаётся посессионно; ему не место в папке packs/ Geyser.

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

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

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

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

Прокси: бэкенд говорит, что у него нет сетевого ключа​

На бэкенде /rspm status показывает Network key source: not set — the proxy sends one when a player next connects here, а консоль повторяет «This backend is behind a proxy but has no network key yet».

Отсутствие plugins/floodgate/key.pem — не причина; теперь этот файл необязателен. Ключом владеет прокси: он загружает собственный файл network-key, либо один раз берёт зерно из key.pem Floodgate, если тот есть, либо генерирует свежий ключ, а затем отправляет его каждому бэкенду, когда туда подключается игрок.

Проверьте по порядку:

  1. Подключался ли игрок к этому бэкенду с момента запуска прокси? Выдача ключа едет вместе с подключением игрока.
  2. Есть ли ResourcePackManager.jar на прокси? Бэкенд сам выкладывает для вас копию собственного jar в plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar и печатает этот путь — скопируйте его в plugins/ прокси и перезапустите прокси.
  3. На Velocity с современным форвардингом: совпадает ли forwarding secret бэкенда с секретом прокси? Бэкенд на современном форвардинге намеренно отклоняет неподписанную или неверно подписанную выдачу; его лог говорит, какой именно случай. Исправьте секрет с обеих сторон, и следующее подключение игрока повторит попытку само.
  4. Сравните строки Network key fingerprint из /rspm status с обеих сторон. Одинаковые отпечатки означают, что связь в порядке; сам ключ никогда не печатается.

См. Прокси-сети для полной последовательности.

Прокси: «Could not save the network key»​

Прокси разрешил ключ, но не смог записать его в свой файл network-key. Текущая загрузка при этом работает. Следующий перезапуск сгенерирует другой ключ, а каждый уже снабжённый бэкенд сохранит старый и откажется от нового — вся сеть молча отвяжется.

Исправьте права файловой системы на папку данных прокси-плагина перед перезапуском.

Прокси: «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 работает с пустой таблицей маппингов и остаётся такой до конца сессии.

Исправление — перезапустить прокси после того, как прокси записал Merged Bedrock pack published at .... 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 сидит в вашем конфиге как безвредный артефакт, пока вы не уберёте его вручную.