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), um curto fingerprint não secreto da chave da rede mais a origem dessa chave, 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).

O console é silencioso de propósito

O RSPM imprime uma linha cada vez que inicializa do zero um caminho de entrega — o resultado:

[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>

Todo o resto — cada pack preparado, cada cluster mesclado, cada checagem de estabilidade, cada probe de self-host e seu resultado — é suprimido por padrão. Uma condição da qual o RSPM se recupera sozinho não é reportada como aviso. Se um probe de self-host falha e o RSPM muda silenciosamente para hospedagem remota, isso é um sucesso, não uma falha, e o console não diz nada a respeito.

Portanto: a ausência de avisos não é evidência de que nada aconteceu, e a presença da linha de resultado significa que os jogadores estão recebendo um pack. Antes de relatar um bug de hospedagem ou mesclagem, ative a narração:

/rspm verbose on

e depois /rspm reload. Esse comando grava verboseLogging: true em plugins/ResourcePackManager/config.yml por você e a configuração sobrevive a reinícios, então use /rspm verbose off quando terminar. Editar a chave à mão faz a mesma coisa. O conversor Bedrock tem uma chave separada, bedrockConverterDebug, que só existe na config.

Avisos que você pode legitimamente ver são falhas genuínas: falha repetida de entrega do pack a um jogador específico, um cliente reportando INVALID_URL, uma porta HTTP que não conseguiu se vincular, ambos os caminhos de entrega falhando, ou um proxy que passou vários ciclos de polling sem que nenhum backend produzisse conteúdo.

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

Verifique primeiro estes pontos:

• autoHost deve estar habilitado se você quiser a entrega automática normal (selfHostForce é a substituição explícita para testes)
• 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
• jogadores do Floodgate são intencionalmente pulados pela entrega Java, porque o Geyser é o dono da sessão de pack Bedrock deles

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. Defina verboseLogging: true, execute /rspm reload, observe o console em busca dos resultados de upload / probe de self-host, e depois reentre com um jogador de teste. (Sem essa flag, as etapas do probe não são impressas — apenas a linha final de resultado "Resource pack is live via ...".)

A oferta de pack no join tem cerca de um segundo de atraso. Se um cliente Java reportar FAILED_DOWNLOAD ou DISCARDED, o RSPM tenta novamente de forma automática, até três tentativas para aquela sessão de jogador. Ele não tenta de novo após uma recusa do jogador nem após um INVALID_URL; esgotamento repetido de tentativas e URLs inválidas são registrados como falhas reais.

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.

Se um pack habilitado não puder ser extraído ou preparado, o mix atual é abortado e o console nomeia o pack que falhou. Repare esse pack, remova um ZIP adicionado manualmente, ou defina isEnabled: false na config de integração automática dele antes de recarregar.

Um pack quebrado já não bloqueia tudo para sempre

Um pack que não consegue ser preparado falha da mesma forma em toda tentativa, então, deixado por conta própria, ele travaria a entrega permanentemente — a mesclagem nunca termina e o mesmo erro se repete indefinidamente. Após três falhas consecutivas do mesmo arquivo, o RSPM remove esse pack da mesclagem para que os demais packs possam ser entregues, e avisa uma vez, de forma bem visível:

[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 ...

Interprete isso como pretendido: os jogadores agora estão recebendo um pack que está sem o conteúdo daquele plugin. A causa habitual é um zip corrompido ou gravado pela metade.

A exclusão se resolve sozinha. O registro de falha é chaveado pelo tamanho e pela data de modificação do arquivo, então reparar ou substituir o arquivo automaticamente encerra a quarentena e o pack volta à próxima mesclagem — sem comando, sem restart. /rspm reload também zera todos os registros de quarentena. Contagens de falha que nunca chegaram a três são descartadas após qualquer mix bem-sucedido, de modo que soluços transitórios não relacionados espalhados por um longo uptime não podem se acumular até virar uma exclusão.

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.

O /rspm status diz hospedagem remota, mas eu esperava self-host

Isso é comportamento normal quando preferSelfHost: true (o padrão) e uma das três checagens de sanidade do self-host falhou. O RSPM não avisa sobre isso — recorrer à hospedagem remota é um resultado bem-sucedido, então a checagem que falhou é registrada em nível de detalhe com um explícito "This is OK." e fica oculta a menos que verboseLogging: true. A única linha que você recebe por padrão é Resource pack is live via automatic hosting — ....

Execute /rspm verbose on (ou defina verboseLogging: true) e /rspm reload para ver qual das três camadas 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 um código de motivo (PRIVATE_HOST_REJECTED, CONNECT_TIMEOUT, ECONNREFUSED, RATE_LIMITED, ...) são impressos sob verboseLogging.

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, definir selfHostExternalHost como seu hostname público e manter preferSelfHost: true. O hostname explícito pula a auto-detecção de IP público, mas o RSPM ainda tenta o probe da Camada 3. Se o próprio serviço de probe estiver inacessível, o RSPM mantém o self-host em vez de tratar essa falha de comunicação como prova de que sua URL está inacessível.

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

O RSPM também grava um ReadMe.md na mesma pasta 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 a conversão não encontrou nem mappings de item convertíveis nem bundles de entidade permitidos, 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. Caminhos absolutos funcionam. Um caminho relativo é tentado primeiro a partir do diretório de trabalho do servidor, depois em relação 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.

Bedrock: provider ao vivo pulado porque existe um pack legado

Se o console reportar Legacy RSPM Bedrock pack detected, o Geyser já escaneou um ResourcePackManager_Bedrock.zip antigo no seu diretório de packs durante o boot. Apagar esse arquivo com o processo rodando deixaria o Geyser segurando em memória um codec para um caminho que não existe mais, então o RSPM deliberadamente pula seu provider de pack ao vivo naquele boot.

Pare o servidor completamente, apague apenas o caminho exato do arquivo legado que o RSPM imprimiu, e então inicie o servidor de novo. Não use /reload para essa migração. O pack atual continua em plugins/ResourcePackManager/output/ e é servido por sessão; ele não pertence ao diretório packs/ do Geyser.

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, ajuste o eixo relevante, execute /rspm reload e reconecte o cliente Bedrock de teste para que a próxima entrada receba o pack reconstruído. Primeira pessoa e terceira pessoa são independentes — ajustar uma não afeta a outra. 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: um backend diz que não tem chave de rede

No backend, /rspm status mostra Network key source: not set — the proxy sends one when a player next connects here, e o console repete "This backend is behind a proxy but has no network key yet".

Um plugins/floodgate/key.pem ausente não é a causa — esse arquivo agora é opcional. O proxy é o dono da chave: ele carrega seu próprio arquivo network-key, ou usa o key.pem do Floodgate como semente uma única vez se ele existir, ou gera uma chave nova, e então a envia para cada backend quando um jogador se conecta lá.

Verifique, nesta ordem:

1. Algum jogador se conectou àquele backend desde que o proxy iniciou? A concessão pega carona em uma conexão de jogador.
2. O ResourcePackManager.jar está realmente no proxy? O backend prepara uma cópia do próprio jar para você em plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar e imprime esse caminho — copie-a para o plugins/ do proxy e reinicie o proxy.
3. No Velocity com forwarding moderno, o segredo de forwarding do backend coincide com o do proxy? Um backend com forwarding moderno rejeita deliberadamente uma concessão não assinada ou assinada incorretamente; o log dele diz qual dos casos foi. Corrija o segredo dos dois lados e a próxima conexão de jogador tenta novamente sozinha.
4. Compare as linhas Network key fingerprint do /rspm status nos dois lados. Fingerprints idênticos significam que o link está bom; a chave em si nunca é impressa.

Veja Redes com Proxy para a sequência completa.

Proxy: "Could not save the network key"

O proxy resolveu uma chave mas não conseguiu gravá-la em seu arquivo network-key. Este boot ainda funciona. O próximo restart gera uma chave diferente, e todo backend já provisionado mantém a antiga e recusa a nova — a rede inteira se desconecta silenciosamente.

Corrija as permissões de sistema de arquivos da pasta de dados do plugin no proxy antes de reiniciar.

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 proxy tiver registrado Merged Bedrock pack published at .... 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.