Pular para o conteúdo principal

Solução de Problemas do Resource Pack Manager

Esta página cobre apenas comportamentos atualmente confirmados na base de código do ResourcePackManager.

O primeiro passo mais útil para qualquer problema do RSPM é:

/rspm status

Ele imprime versão, modo de deploy (standalone vs network-backend), chave da rede mascarada, estado dos packs Java + Bedrock, o caminho de entrega ativo com URL, o host externo resolvido + IP público auto-detectado, todas as flags de config relevantes, um lembrete de deploy de proxy (o jar de proxy da rede é o mesmo ResourcePackManager.jar) e a detecção de Floodgate / Geyser-Spigot. O mesmo comando existe quando o jar roda em um proxy e imprime os equivalentes do lado do proxy (lista de backends, resultados de fetch por backend, estado do pack unificado).

Os jogadores não estão recebendo o resource pack​

Verifique primeiro estes pontos:

  • autoHost deve estar habilitado se você quiser que o ResourcePackManager envie uma URL automaticamente
  • o pack unificado deve existir e pelo menos um caminho de entrega (self-host ou remoto) deve ter tido sucesso
  • jogadores só recebem o pack ao entrar, ou via o broadcast de primeiro upload que dispara no momento em que a hospedagem fica pronta

Se necessário:

  1. Execute /rspm status e olhe a seção "Hosting". Active delivery mostra se self-host, remoto ou nenhum está em uso no momento.
  2. Se "active delivery: not yet ready" — o mix ou upload ainda está em andamento. O plugin avisa de forma destacada no console quando um jogador entra cedo demais e enviará o pack automaticamente no momento em que a entrega estiver pronta.
  3. Se "active delivery: none — hosting disabled or failed" — autoHost está desligado, ou os probes de self-host e o upload remoto falharam ambos. Veja "As checagens de sanidade do self-host falharam" e "A hospedagem automática não consegue alcançar o servidor remoto" abaixo.
  4. Execute /rspm reload, observe o console em busca dos resultados de upload / probe de self-host, e depois reentre com um jogador de teste.

Se você estiver fazendo self-host por meio do seu próprio pipeline externo (autoHost: false), o RSPM não envia sua URL personalizada por você. Nessa configuração, ainda é preciso ter seu próprio fluxo de entrega de pack pelo lado do servidor.

O ItemsAdder está instalado, mas seu conteúdo está ausente do pack final​

Geralmente isso significa que o ItemsAdder ainda está configurado de uma forma que impede o ResourcePackManager de ler ou hospedar sua saída.

Use:

/rspm itemsadder configure

Esse comando atualmente:

  • habilita resource-pack.hosting.no-host.enabled
  • desabilita protection_1, protection_2 e protection_3
  • define resource-pack.zip.compress-json-files: false
  • executa /iareload, depois /iazip
  • recarrega o ResourcePackManager cerca de 15 segundos depois

Se o comando informar que o ItemsAdder já está hospedando o próprio pack, desabilite a hospedagem do ItemsAdder manualmente antes e execute o comando novamente.

O pack unificado é inválido ou falha ao enviar​

A integração de auto-host do ResourcePackManager trata explicitamente os seguintes tipos de erro do lado do servidor:

  • arquivos obrigatórios ausentes
  • arquivo muito grande
  • formato de arquivo inválido
  • sessão ausente
  • servidor remoto indisponível

Se você se deparar com um destes:

  1. Execute /rspm reload para reconstruir o pack.
  2. Verifique se um dos packs de origem está malformado, criptografado ou ilegível por algum motivo.
  3. Verifique se o pack unificado final ainda contém um pack.mcmeta e um pack.png válidos na raiz.

O plugin ignora packs que não consegue extrair corretamente e registra avisos no console quando isso ocorre.

Em um erro SESSION_NOT_FOUND do auto-host remoto, o RSPM limpa seu UUID de sessão e se reinicializa no próximo tick de keep-alive — nenhuma intervenção manual é necessária.

Os assets de um plugin estão sobrescrevendo os de outro plugin​

Isso é controlado por priorityOrder em:

plugins/ResourcePackManager/config.yml

Entradas mais altas vencem entradas mais baixas.

Para arquivos não mescláveis, o ResourcePackManager substitui o arquivo de menor prioridade. Para arquivos JSON mescláveis, ele mescla o conteúdo em vez disso. As categorias de JSON atualmente mescláveis são:

  • sounds.json
  • arquivos de idioma
  • JSON de modelo de item vanilla em minecraft/models/item (mescla não recursiva: apenas o array overrides é combinado entre packs, o restante do arquivo segue o critério de maior-prioridade-vence)
  • arquivos de atlas
  • arquivos de fonte
  • definições de modelo de item 1.21.4+ em items/ (mescla ciente do formato que respeita a estrutura da árvore de predicados)

pack.mcmeta também é mesclado de forma especial: o maior pack_format vence, intervalos de supported_formats são ampliados (formas inteira, array de dois inteiros e objeto {min_inclusive, max_inclusive} são todas suportadas), entradas de overlay são combinadas e chaves de topo não padronizadas são preservadas. As entradas de overlay são normalizadas para compatibilidade com 1.21.9+ pela adição dos campos min_format/max_format quando ausentes. As fontes de atlas base também são mescladas nos arquivos de overlay de atlas para evitar que overlays ocultem entradas base.

Se precisar inspecionar o que aconteceu durante a última mescla, veja:

plugins/ResourcePackManager/collision_log.txt

Texto de GUI ou elementos baseados em fonte parecem errados​

Arquivos de fonte são uma das categorias JSON que o ResourcePackManager mescla, mas isso não garante que dois sistemas de fonte diferentes se comportarão bem juntos no Minecraft.

Se um menu ou HUD baseado em fonte parecer errado:

  1. Altere priorityOrder para que o pack que deve vencer esteja em posição superior.
  2. Execute /rspm reload.
  3. Verifique o collision_log.txt para confirmar que as colisões ocorreram onde você esperava.

Alterações no resource pack não estão aparecendo imediatamente​

O ResourcePackManager tem um watchdog para fontes de pack suportadas.

Ele espera até que um pack alterado permaneça inalterado por 3 segundos; uma vez que todos os packs monitorados estejam estáveis, o re-mix acontece imediatamente.

Se você estiver regenerando ativamente o pack de outro plugin, aguarde alguns segundos após as gravações de arquivo pararem. Em caso de dúvida, execute /rspm reload depois que o plugin upstream terminar.

As checagens de sanidade do self-host falharam; recorrendo à hospedagem remota​

Esta mensagem é comportamento normal quando preferSelfHost: true (o padrão) e uma das três checagens de sanidade do self-host falhou:

  1. Camada 1 (heurística) — o host externo resolvido é RFC1918 / loopback / link-local. Ou defina selfHostExternalHost como seu hostname público real, ou garanta que o plugin consiga alcançar api.ipify.org / checkip.amazonaws.com.
  2. Camada 2 (self-probe em localhost) — uma requisição HEAD para http://127.0.0.1:<port>/rspm.zip não retornou 200 com um corpo não vazio. Captura colisões de bind de porta ou arquivos de pack ausentes.
  3. Camada 3 (probe de alcançabilidade externa) — o magmaguy.com tentou buscar a URL que você anunciou e não conseguiu alcançá-la. Mais comumente: a porta HTTP não está encaminhada no roteador / firewall. A URL do probe e o motivo são registrados.

Soluções (em ordem de preferência): abra a porta HTTP no seu firewall + roteador, defina selfHostExternalHost como um hostname roteável, ou defina preferSelfHost: false para pular o self-host por completo.

Quando o próprio probe do magmaguy.com está inacessível (o RSPM não consegue falar com ele para perguntar), o self-host é mantido em vez de falhar — o raciocínio é que o caminho de fallback também precisa do magmaguy.com, então recusar o comprometimento por incapacidade de fazer o probe seria paradoxal.

Consulte Self-hosting para a árvore de decisão completa.

A hospedagem automática não consegue alcançar o servidor remoto​

O host remoto integrado do ResourcePackManager se comunica com:

https://magmaguy.com/rsp/

Se essa conexão falhar, o plugin registra avisos de comunicação e não consegue usar o fallback remoto até reconectar com sucesso.

Suas opções são:

  1. corrigir a conectividade HTTPS de saída do servidor
  2. aguardar até que o serviço remoto volte a estar acessível
  3. desabilitar autoHost e fazer self-host do zip gerado por conta própria
  4. abrir sua porta HTTP e manter preferSelfHost: true para que o RSPM use self-hosting sem precisar do magmaguy.com de jeito nenhum (nesse cenário, defina também selfHostExternalHost como seu hostname público para que o probe externo da Camada 3 seja desnecessário — o RSPM mantém o self-host em caso de IOException no probe)

Quero fazer self-host do pack unificado por meio do meu próprio servidor web​

A configuração suportada pelo código é:

  1. Definir autoHost: false.
  2. Definir resourcePackRerouting se quiser que o ResourcePackManager grave uma cópia extra em uma pasta existente.
  3. Hospedar o ResourcePackManager_RSP.zip você mesmo.

resourcePackRerouting é resolvido em relação ao diretório plugins, e a pasta de destino já deve existir.

Se, em vez disso, você quiser usar o servidor HTTP de self-host integrado do RSPM (coisa diferente — mesma JVM do plugin), consulte Self-hosting.

Preciso inspecionar quais dados remotos estão armazenados para este servidor​

Use:

/rspm data_compliance_request

Se houver uma sessão de hospedagem remota ativa, o ResourcePackManager baixa a resposta para:

plugins/ResourcePackManager/data_compliance

Se não houver sessão remota (por exemplo, se você estiver usando self-host), o comando informa que não há dados remotos a solicitar.

O pack Bedrock não está sendo gerado​

bedrockConversionEnabled tem valor padrão true, então ele deve rodar automaticamente. Execute /rspm status primeiro — a seção Bedrock Pack vai dizer por que o pack não está no disco:

  • "No Bedrock target detected" — sem Geyser-Spigot local, sem Floodgate local e não está em modo de rede. A conversão é pulada intencionalmente. Instale o Floodgate (para configurações com proxy) ou o Geyser-Spigot (para configurações standalone) e /rspm reload.
  • "Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing" — geralmente o primeiro ciclo de mix ainda não terminou (aguarde ~30s após o boot), ou o scanner encontrou zero definições de itens no pack unificado, ou a conversão lançou um erro. Procure no console por avisos [BedrockConverter] ou por Generic scanner: discovered 0 items definition files.

Se a auto-detecção do Geyser falhar:

  1. Defina bedrockGeyserFolder em config.yml como o caminho da pasta de dados do seu Geyser (por exemplo, Geyser-Spigot).
  2. O caminho pode ser absoluto ou relativo ao diretório plugins.

O conversor faz auto-detecção do Geyser em plugins/Geyser-Spigot/, em qualquer variante plugins/Geyser-*/ ou em config/Geyser-*/ para configurações Fabric/NeoForge.

Para saída de log por item / por osso, defina bedrockConverterDebug: true e recarregue.

Jogadores Bedrock veem os itens segurados na posição errada​

Isso é uma questão de ajuste, não um bug de conversão. Abra plugins/ResourcePackManager/bedrock_display_offsets.yml e ajuste o eixo relevante. Primeira pessoa e terceira pessoa são independentes — ajustar uma não afeta a outra. O cliente Bedrock recarrega ao vivo o JSON de attachable sem precisar reiniciar, então a iteração é rápida. Consulte a conversão Bedrock para a lista completa de parâmetros e o que cada um controla.

Texturas de armadura personalizadas estão faltando em jogadores Bedrock​

Armaduras personalizadas são renderizadas no Bedrock combinando a geometria de armadura vanilla com a textura Java como camada visível. Para que isso funcione, o pack do plugin de origem deve definir um arquivo de equipamento em assets/<namespace>/equipment/<material>.json ao lado da definição do item. Se o log de conversão mostrar o item, mas nenhuma textura de armadura aparecer no jogo, verifique se esse arquivo existe no pack unificado.

Proxy: "Floodgate key.pem missing" no boot do proxy​

O plugin do proxy não conseguiu encontrar plugins/floodgate/key.pem no host do proxy e ficou ocioso. O RSPM deriva a identidade da rede a partir desse arquivo, então sem ele o proxy não consegue se conectar a nenhum backend. Solução:

  1. Instale o Floodgate no proxy. Ele é necessário para que jogadores Bedrock cheguem ao proxy de qualquer forma, então é algo de que você precisa independentemente do RSPM.
  2. Garanta que plugins/floodgate/key.pem no proxy seja idêntico, byte a byte, ao mesmo arquivo em cada backend. Copie um key.pem canônico para cada componente (outros backends + o proxy) e reinicie tudo. O Floodgate já exige isso para autenticação Bedrock, então se jogadores Bedrock já funcionam na sua rede, isso já está feito.

Proxy: "no merged pack" após vários ciclos de polling​

Após ~20 segundos de ciclos de polling vazios (4 ciclos × intervalo padrão de 5 s) no proxy, o RSPM registra um banner de diagnóstico único listando cada backend que ele consultou, a URL HTTP tentada e o resultado (200 / 304 / 404 / CONNECT_FAILED / etc.). O banner explica as soluções mais comuns:

  • CONNECT_FAILED em cada backend → o proxy não consegue alcançar a porta HTTP do backend. Verifique se o endereço em velocity.toml / config.yml é um que o proxy realmente consiga alcançar (não, por exemplo, um nome interno de Docker que não resolve a partir da rede do proxy) e se a porta HTTP anunciada pelo backend está aberta entre proxy e backend. O banner imprime a URL exata que ele tentou; antes de um backend ter anunciado sua porta, o proxy recorre a mcPort + network-http-offset-v2, então um CONNECT_FAILED precoce também pode significar que essa porta de fallback ainda não está acessível.
  • NOT_FOUND_404 em cada backend → os backends estão no ar mas não estão produzindo um pack Bedrock. Rode /rspm status em cada backend; o bloco de diagnóstico Bedrock Pack vai dizer por quê.

O banner dispara uma vez por período de paralisação e uma linha "NetworkSync: recovered" é registrada quando pelo menos um backend volta a retornar conteúdo. Veja Redes com Proxy para mais detalhes.

Proxy: Jogadores Bedrock não veem modelos no primeiro boot do proxy​

O Geyser registra sua tabela de itens personalizados apenas na inicialização do proxy. Se o proxy iniciou antes de qualquer backend produzir um pack Bedrock, o Geyser está rodando com uma tabela de mappings vazia e fica assim pelo resto da sessão.

A solução é reiniciar o proxy depois que o backend tiver registrado Wrote merged Geyser mappings: N entries. O RSPM pré-implanta os mappings da execução anterior no boot do proxy, então isso só pega em instalações totalmente novas — boots subsequentes têm algo pronto antes do Geyser fazer o scan.

Backend: "Backend HTTP server failed to bind on port X"​

Em modo de rede, o backend expõe suas saídas Bedrock por meio de um pequeno servidor HTTP. Se a porta estiver em uso ou indisponível, você verá um bloco [ERROR] de várias linhas no console. Soluções:

  • Defina selfHostPort como um valor positivo diferente em config.yml.
  • Ou altere networkHttpOffset-v2 para afastar a porta auto-derivada da colisão (por exemplo, RCON em mcPort + 1? defina como 2 ou 3). Você não precisa atualizar o proxy para coincidir: uma vez que o backend se vincula com sucesso, ele anuncia sua porta HTTP real ao proxy automaticamente, então o próprio network-http-offset-v2 do proxy só importa como palpite pré-anúncio.

Enquanto o servidor HTTP do backend está fora do ar, o pack Bedrock deste backend não chegará ao proxy via direct fetch. O fallback por relay do magmaguy.com ainda funciona (o backend faz push de seus arquivos para o relay e o proxy os busca por lá).

Limpando uma config v1 desatualizada​

Operadores que estão atualizando a partir do RSPM v1 podem ter uma chave morta networkHttpOffset (sem o -v2) no seu config.yml. O RSPM v2 intencionalmente não lê a chave antiga — você recebe o padrão v2 (1) escrito na config no próximo boot automaticamente. A chave morta v1 fica na sua config como um artefato inofensivo até que você a limpe manualmente.