FAQ do Resource Pack Manager

Se sua dúvida não for respondida aqui, confira primeiro as outras páginas do ResourcePackManager na barra lateral.

Quais comandos o ResourcePackManager expõe atualmente?

No backend (Paper / Spigot), a superfície de comandos suportada pelo código é:

• /rspm setup — abre um menu de configuração em GUI no jogo (status de atualização do plugin, plugins recomendados, alternância de atualizações automáticas, links para wiki / Discord / conta Nightbreak)
• /rspm recommendedplugins — mostra o menu compartilhado de plugins recomendados da Nightbreak (ou uma lista em texto no console)
• /rspm downloadpluginupdate — baixa uma atualização disponível do ResourcePackManager para o próximo restart
• /rspm downloadall — baixa todas as atualizações disponíveis expostas por este plugin (atualmente, a atualização do ResourcePackManager)
• /rspm reload — reconstrói e re-hospeda o pack unificado
• /rspm status — dump completo de diagnóstico (estado do pack, modo de hospedagem, fingerprint da chave da rede, integrações)
• /rspm verbose [on|off] — liga ou desliga o log detalhado de diagnóstico. Sem argumento, alterna. O resultado é gravado de volta em verboseLogging no config.yml, então persiste entre reinícios. Também é aceito como /rspm verboselogging.
• /rspm itemsadder configure — configura o ItemsAdder para hospedagem via RSPM
• /rspm itemsadder dismiss — descarta permanentemente o aviso do ItemsAdder para o UUID do seu jogador
• /rspm data_compliance_request — baixa todos os dados armazenados remotamente para este servidor

O comando raiz é /resourcepackmanager, tendo /rspm como alias. Os comandos de atualização e de plugins recomendados acima são comandos compartilhados do MagmaCore/Nightbreak registrados pelo RSPM.

Permissões do backend:

• /rspm setup e /rspm recommendedplugins exigem resourcepackmanager.setup. O /rspm setup é exclusivo de jogadores porque abre uma GUI de inventário.
• /rspm downloadpluginupdate, /rspm downloadall, /rspm reload, /rspm status, /rspm verbose, /rspm itemsadder <configure|dismiss> e /rspm data_compliance_request exigem resourcepackmanager.*.

No plugin do proxy (Velocity / BungeeCord), só existem comandos de diagnóstico:

• /rspm status — snapshot do lado do proxy: lista de backends, resultados de fetch por backend, estado do pack unificado, detecção de Geyser/Floodgate
• /rspm debug bedrock [on|off] — Velocity e BungeeCord. Alterna as linhas de log detalhadas [RSPM-BedrockDebug] do GeyserBinder para diagnosticar casos de "jogador Bedrock entrou mas não viu o pack". Volta a desligada no restart do proxy. Executá-lo sem argumento imprime o estado atual.

No Velocity, os comandos do proxy aceitam resourcepackmanager.command.status ou resourcepackmanager.*. O BungeeCord registra exatamente o nó resourcepackmanager.command.status; um plugin de permissões ainda pode satisfazê-lo por expansão de wildcard. O console pode executar os comandos. A saída é segura para compartilhar — a chave da rede aparece apenas como um curto fingerprint de hash unidirecional, nunca a chave em si, e nenhum token é impresso — então conceder amplamente é tranquilo.

Quais plugins são suportados atualmente?

O ResourcePackManager já vem com entradas de integração prontas para estes plugins:

• BackpackPlus
• BetterHUD
• BetterStructures
• CannonRTP
• EliteMobs
• EternalTD
• FreeMinecraftModels
• InfiniteVehicles
• ItemsAdder
• MegaBlockSurvivors
• MMOInventory
• ModelEngine
• Nexo
• Nova
• Oraxen
• RealisticSurvival
• ResurrectionChest
• ValhallaMMO
• vane-core

Essas integrações só entram em vigor se o plugin estiver instalado e seu caminho local ou URL remota configurados forem utilizáveis.

Cada integração tem seu próprio arquivo YAML de configuração em plugins/ResourcePackManager/compatible_plugins/. Lá você pode personalizar isEnabled, pluginName, localPath, url, zips, cluster, additionalLocalPath e reloadCommand para cada plugin. A opção cluster informa ao ResourcePackManager que o caminho local deve ser tratado como um diretório contendo várias subpastas de resource pack que devem ser todas unidas.

Como excluo uma integração automática de plugin?

Defina isEnabled: false no arquivo daquela integração em plugins/ResourcePackManager/compatible_plugins/ e depois execute /rspm reload (ou reinicie). O RSPM remove as entradas de resource pack que gerou ou registrou para aquela integração, incluindo as cópias geradas no mixer. Remover o plugin de priorityOrder não o exclui; isso apenas move aquele pack para a prioridade mais baixa. Para excluir um ZIP que você adicionou manualmente, remova ou mova o ZIP da pasta mixer.

O ResourcePackManager é compatível com o ItemsAdder?

Sim. O ResourcePackManager inclui um fluxo de auxiliar e de aviso integrado para o ItemsAdder.

Se o ItemsAdder estiver instalado e ainda precisar ser ajustado para hospedagem via ResourcePackManager, jogadores OP recebem um aviso clicável alguns segundos após entrar. Jogadores que descartaram o aviso permanentemente não o veem novamente. A partir daí você pode:

• executar /rspm itemsadder configure para definir resource-pack.hosting.no-host.enabled: true, desativar as três configurações de protect-file-from-unzip, definir compress-json-files: false, executar /iareload e depois /iazip, e em seguida recarregar o ResourcePackManager (~15s depois)
• executar /rspm itemsadder dismiss para descartar permanentemente esse aviso para o UUID do seu jogador

Se o ItemsAdder já estiver configurado para hospedar o próprio pack por meio de algum de seus modos de hospedagem, o comando auxiliar não substitui isso automaticamente. Ele informa que você deve desativar a hospedagem do ItemsAdder antes.

Posso adicionar meu próprio pack à união?

Sim, e há dois lugares para colocá-lo, dependendo do que você tem.

Um .zip pronto vai em:

plugins/ResourcePackManager/mixer

Se quiser controlar qual pack vence em conflitos de arquivos, adicione o nome exato do arquivo, incluindo o .zip, em priorityOrder no plugins/ResourcePackManager/config.yml.

Uma pasta de pack descompactada (uma árvore assets/ mais pack.mcmeta) vai em:

plugins/ResourcePackManager/resource_pack

O RSPM compacta essa pasta ele mesmo e a mescla sob a entrada ResourcePackManager em priorityOrder, que fica no topo da lista padrão — então, por padrão, os arquivos dela vencem conflitos contra todo pack de plugin. Mova ResourcePackManager para baixo na lista se preferir que ela perca.

A pasta relacionada plugins/ResourcePackManager/blueprint contém o pack.png e o pack.mcmeta com que o RSPM contribui em toda mesclagem. Edite esses dois arquivos para mudar o ícone do pack unificado ou a descrição dele no menu; a pasta é recompactada em blueprint.zip a cada inicialização.

Exemplo:

priorityOrder:
  - ResourcePackManager
  - EliteMobs
  - MyCustomPack.zip

Como funciona a prioridade?

priorityOrder define a prioridade mais alta no topo e a mais baixa embaixo.

Para arquivos não mescláveis, o pack de maior prioridade substitui o arquivo de menor prioridade. Para arquivos JSON mescláveis, o ResourcePackManager une os conteúdos em vez de substituí-los cegamente.

O código atualmente trata estes como mescláveis:

• sounds.json
• arquivos de idioma em lang ou languages
• JSON de modelo de item vanilla em minecraft/models/item (esses recebem uma mescla não recursiva: apenas o array overrides é combinado entre packs, enquanto 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: mantém intactas as árvores de predicados, sem recorrer cegamente para tipos de nó diferentes)

pack.mcmeta é mesclado de forma especial: o maior pack_format vence, intervalos de supported_formats são ampliados para cobrir todos os packs (suportam as formas inteira, array de dois inteiros e objeto {min_inclusive, max_inclusive}), entradas de overlay são combinadas, e chaves de topo não padronizadas (por exemplo, sodium) 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.

Após todos os packs serem unidos, o ResourcePackManager mescla as fontes do atlas base nos arquivos de overlay de atlas. Isso evita que overlays acidentalmente ocultem entradas de atlas base quando o Minecraft ativa um overlay (por exemplo, ia_overlay_modern_atlas / ia_overlay_legacy_atlas do ItemsAdder).

Outros arquivos JSON são substituídos em vez de mesclados.

Packs que não estão listados em priorityOrder ainda são incluídos na união, mas recebem a menor prioridade.

Entradas ZIP completas byte a byte idênticas são deduplicadas antes da mesclagem, mantendo a primeira cópia (de maior prioridade). Depois da mesclagem, o RSPM também repara dois defeitos comuns de modelos Java: adiciona uma textura particle ausente a partir da primeira textura concreta do modelo, quando possível, e limita coordenadas UV de modelo inválidas ao intervalo 0..16 do Minecraft.

O ResourcePackManager reconstrói automaticamente quando os packs mudam?

Sim. Ele monitora as fontes de pack suportadas em busca de mudanças.

Quando um pack monitorado para de mudar por 3 segundos, o ResourcePackManager o marca como estável. Quando todos os packs monitorados estão estáveis, o re-mix acontece imediatamente. Durante essa transição, jogadores OP online são notificados: "All resource packs are stable. Mixing and sending now."

Um re-mix cujas entradas são byte a byte idênticas às do anterior não é re-mesclado. O RSPM gera um fingerprint da lista ordenada de packs de origem (nome, tamanho, hash de conteúdo) e o guarda ao lado da saída como .rspm_mix_fingerprint; quando o fingerprint coincide e todo arquivo de saída esperado ainda está presente, ele republica o zip existente em vez de reconstruí-lo. Qualquer coisa duvidosa — uma saída ausente, um fingerprint ilegível, conversão Bedrock habilitada sem pack Bedrock no disco — cai para um mix completo. É também por isso que um /rspm reload que não muda nada pode terminar quase instantaneamente e reutilizar o registro de hospedagem existente.

O watchdog leva em conta a inicialização do plugin?

Sim. O watchdog tem ciência dos estados de inicialização de plugins Magmacore.

• Ele aguarda todos os plugins monitorados concluírem a inicialização Magmacore antes de iniciar as checagens de estabilidade.
• Se um plugin é recarregado enquanto o watchdog está em execução, ele detecta a mudança de estado, pausa, reseta todo o rastreamento de estabilidade e aguarda o plugin terminar de se reinicializar.
• Isso evita falsas detecções de "instabilidade" que ocorreriam durante sequências normais de inicialização ou reload de plugins.

Como os jogadores recebem o pack final?

Quando autoHost está habilitado (padrão), ou quando selfHostForce o sobrepõe explicitamente, o RSPM escolhe um caminho de entrega e envia essa URL a todo jogador Java que entrar. A árvore de decisão é:

1. Se selfHostForce: true, sempre faz self-host (pula todos os probes — principalmente para testes).
2. Caso contrário, se preferSelfHost: true (padrão), tenta o self-host primeiro, executa três checagens de sanidade (host externo resolvido não-LAN, self-probe em localhost, probe de alcançabilidade externa via magmaguy.com) e compromete-se com o self-host se as três passarem.
3. Se o self-host falhar ou estiver desabilitado, faz upload do pack para magmaguy.com/rsp/ e anuncia essa URL.

Uma vez de posse de uma URL, o RSPM usa a API de múltiplos packs, então ele coexiste com outros packs enviados pelo servidor. O descritor atual do plugin Bukkit exige Minecraft 1.21.4 ou mais recente.

A oferta no join tem cerca de um segundo de atraso. Uma resposta FAILED_DOWNLOAD ou DISCARDED é repetida automaticamente, até três tentativas para aquela sessão de jogador; um pack recusado ou uma URL inválida não são repetidos. Jogadores do Floodgate são pulados aqui porque o pack Bedrock deles é entregue pelo Geyser.

Se autoHost: false e selfHostForce: false, o RSPM não envia nenhuma URL — espera-se que você pegue o zip de plugins/ResourcePackManager/output/ e o sirva por meio do seu próprio pipeline.

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

Posso fazer self-host em vez de usar o auto-host integrado?

Sim — e a partir do RSPM v2, o servidor HTTP integrado é o caminho de self-host recomendado. selfHostEnabled: true e preferSelfHost: true vêm ambos ativados por padrão.

Se você quiser hospedar o zip por meio do seu próprio servidor web existente, em vez de qualquer um dos caminhos integrados:

• Defina autoHost: false.
• Opcionalmente defina resourcePackRerouting como um caminho de pasta existente relativo ao diretório plugins.
• Pegue o pack unificado de plugins/ResourcePackManager/output/ResourcePackManager_RSP.zip e o hospede por conta própria.

Se resourcePackRerouting estiver definido, o RSPM também grava uma cópia desse zip na pasta de redirecionamento. Esse caminho de redirecionamento é resolvido em relação ao diretório plugins, e a pasta de destino já deve existir.

Existe um comando para solicitar dados armazenados no host?

Sim. Use:

/rspm data_compliance_request

Se o auto-host remoto do magmaguy.com tiver uma sessão 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 ativa (por exemplo, se você estiver fazendo self-host), o comando informa que não há dados remotos a solicitar.

Quais opções de configuração estão disponíveis?

O plugins/ResourcePackManager/config.yml expõe o seguinte:

Geral

• priorityOrder — lista que controla quais packs vencem em conflitos de arquivos (maior prioridade primeiro)
• autoHost — se o ResourcePackManager auto-hospeda e envia o pack unificado (boolean, padrão true)
• forceResourcePack — se os jogadores devem ser forçados a aceitar o pack (boolean, padrão false)
• resourcePackPrompt — o prompt exibido quando o pack é oferecido (padrão "Use recommended resource pack?")
• resourcePackRerouting — caminho opcional de pasta (relativo a plugins) para gravar uma cópia extra do zip unificado
• verboseLogging — imprime cada etapa da preparação do pack e do handshake de hospedagem (boolean, padrão false). Desligado por padrão para que o console mostre apenas o resultado final; ative ao diagnosticar um problema de mesclagem ou de hospedagem. /rspm verbose on|off altera essa mesma chave em tempo de execução e a salva. É separado de bedrockConverterDebug, que cobre o pipeline Bedrock.
• nightbreak.autoDownloadPluginUpdates — se o RSPM baixa automaticamente suas próprias atualizações de plugin na inicialização (boolean, padrão false; ainda é necessário um restart para aplicar uma atualização baixada). Esta é uma chave aninhada sob a seção nightbreak:, não uma chave de topo — procurar no config.yml por uma linha autoDownloadPluginUpdates solta só a encontrará indentada sob nightbreak:. É a mesma alternância exposta na GUI de /rspm setup.

Self-hosting

• selfHostEnabled — se o servidor HTTP integrado pode ser usado (boolean, padrão true)
• selfHostPort — porta do servidor HTTP de self-host. -1 (padrão) auto-deriva como mcPort + networkHttpOffset-v2. Defina qualquer inteiro positivo para forçar uma porta explícita.
• networkHttpOffset-v2 — offset de fallback adicionado à porta do servidor Minecraft quando selfHostPort = -1. Padrão 1 (por exemplo, MC 25565 → HTTP 25566). Em uma rede, você não precisa mais manter isso em sincronia com o proxy: o backend auto-anuncia ao proxy a porta HTTP exata em que efetivamente se vinculou, e o proxy só usa seu próprio network-http-offset-v2 como palpite antes que esse anúncio chegue.
• selfHostExternalHost — hostname ou IP público que os clientes usam para alcançar seu servidor de self-host. Vazio (padrão) = auto-detecção via api.ipify.org / checkip.amazonaws.com.
• selfHostForce — pula todas as checagens de sanidade E o upload remoto, sempre faz self-host (boolean, padrão false — para testes).
• preferSelfHost — tenta o self-host primeiro com checagens de sanidade antes de recorrer ao upload remoto (boolean, padrão true).

Bedrock

• bedrockConversionEnabled — converte o pack Java unificado em um pack Bedrock para o GeyserMC (padrão true)
• bedrockAutoDeployToGeyser — copia o arquivo de custom mappings do Geyser para a pasta Geyser detectada (padrão true)
• bedrockGeyserFolder — substituição manual de caminho para a pasta do Geyser; vazio = auto-detecção
• bedrockConverterDebug — linhas de log detalhadas por item / por osso do pipeline Bedrock (padrão false)
• geyserExtensionAutoInstall — instala e atualiza o ResourcePackManager.jar universal como extensão do Geyser, para que entidades Bedrock personalizadas sejam renderizadas (padrão true). Defini-lo como false impede instalações e preparações de atualização futuras; não apaga um jar de extensão que já esteja lá — remova-o à mão com o Geyser parado. O plugin do proxy tem a mesma chave sob outro nome, geyser-extension-auto-install.

Um segundo arquivo, plugins/ResourcePackManager/bedrock_display_offsets.yml, expõe doze parâmetros ajustáveis pelo usuário para refinar onde os jogadores Bedrock veem os itens segurados em relação à mão (seis para primeira pessoa, seis para terceira pessoa). Consulte a conversão Bedrock para detalhes.

Intencionalmente não há opção de configuração network-key, nem no backend nem no proxy. Colar uma chave à mão era a maior fonte isolada de má configuração — um erro de digitação quebrava silenciosamente o link proxy↔backend sem nenhum erro em lugar algum.

Em vez disso, o proxy é o dono da chave da rede e a distribui:

• O proxy resolve sua chave uma única vez: ele lê seu arquivo network-key salvo, se houver um; caso contrário, usa plugins/floodgate/key.pem como semente, se esse arquivo existir (para que uma rede existente mantenha sua identidade após a atualização); caso contrário, gera uma nova. De qualquer forma, salva o resultado em network-key, na pasta de dados do próprio plugin do proxy, e nunca mais olha para o key.pem.
• Cada backend recebe essa chave pelo canal de plugin rspm:network na primeira vez que um jogador se conecta a ele, e então a persiste em seu próprio data.yml. Um backend que já tem uma chave ignora concessões posteriores — redirecionar um backend para outra rede é uma ação do operador, não algo que uma mensagem possa fazer.
• O Floodgate não é necessário para isso. Ele é necessário para que jogadores Bedrock cheguem ao proxy, mas uma rede exclusivamente Java pode usar os recursos de proxy do RSPM sem ele.
• Um servidor standalone (sem proxy) gera e mantém sua própria chave, porque ele é a sua própria rede de um servidor só.

O /rspm status, em qualquer um dos lados, imprime um curto fingerprint de hash unidirecional da chave, nunca a chave em si. Fingerprints coincidentes no proxy e no backend significam que o link está bom.

Por que o console é tão silencioso? Ele está fazendo alguma coisa?

Por design. Preparar um pack é um pipeline longo — preparar o pack de cada plugin contribuinte, mesclar clusters, esperar que parem de mudar, mixar, converter para Bedrock, entregar o resultado a um host. Narrar tudo isso produzia cerca de sessenta linhas de console por inicialização e enterrava as únicas duas coisas que alguém lê: se os jogadores vão receber o pack e o que fazer se não forem.

Então uma inicialização normal imprime uma linha:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

Se você vê essa linha, funcionou.

O RSPM também deliberadamente não avisa sobre condições que ele mesmo corrige. Se um probe de self-host falha e o RSPM recorre à hospedagem remota, isso é um sucesso — o console relata o resultado, não o desvio. Avisar sobre algo já tratado passa a impressão de falha e faz as pessoas perseguirem um problema inexistente.

Para ver a narração completa, execute /rspm verbose on (ou defina verboseLogging: true no config.yml) e depois /rspm reload. Para o conversor Bedrock especificamente, use bedrockConverterDebug: true em vez disso.

Outros plugins podem registrar seus packs via código?

Sim. O ResourcePackManager expõe uma API Java para registro programático de packs. Consulte a página da API para detalhes.

A conversão Bedrock só funciona para o FreeMinecraftModels?

Não, não mais. O conversor atual lida recursivamente com qualquer plugin cujo pack inclua definições de itens 1.21.4+ em assets/<namespace>/items/**/*.json. Isso cobre modelos de ossos do FreeMinecraftModels, equipamentos do EliteMobs, itens personalizados do Oraxen/Nexo, conjuntos de armadura personalizada e qualquer pack que você monte por conta própria nesse formato. Itens 2D simples personalizados são emitidos como ícones Bedrock planos; itens 3D personalizados emitem geometria/attachables Bedrock e um ícone de inventário renderizado por software.

Preciso reiniciar o servidor sempre que o pack Bedrock mudar?

Ajustes de textura e modelo em itens personalizados já existentes entram em vigor para o próximo jogador Bedrock que entrar — o RSPM serve o pack Bedrock ao vivo por sessão via API do Geyser. O reinício só é necessário quando o conjunto de itens personalizados muda (adicionar novos ou remover existentes), pois o Geyser registra seus identificadores de itens personalizados na inicialização.

O ResourcePackManager funciona em BungeeCord / Velocity?

Sim — é uma topologia suportada de primeira classe. É o mesmo ResourcePackManager.jar em todos os lugares: coloque-o em cada backend e coloque uma cópia no proxy. O único jar agrupa os pontos de entrada Bukkit, Velocity e BungeeCord/Waterfall, então ele carrega corretamente seja o host um backend ou um proxy. Não há jars de proxy separados por plataforma para compilar ou extrair — e se você esquecer a cópia no proxy, um backend atrás de proxy prepara uma para você em plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar e avisa isso no console.

Rodando como plugin de proxy, ele une o pack Bedrock convertido de cada backend e o serve a clientes Bedrock por meio do Geyser do proxy. A entrega do pack Java ainda é tratada por cada backend diretamente — clientes Java veem packs por backend.

Os passos de configuração, solução de problemas e verificação estão em Redes com Proxy.