Pular para o conteúdo principal

Redes com Proxy (BungeeCord / Waterfall / Velocity)

O ResourcePackManager funciona em redes com proxy. O plugin backend roda em cada backend, e um plugin de proxy separado (Velocity OU BungeeCord, nunca os dois) roda no proxy. As duas partes se encontram automaticamente por meio do arquivo compartilhado plugins/floodgate/key.pem.

O que o Plugin do Proxy Faz​

A função do plugin do proxy é a mesclagem e entrega do pack Bedrock. Em uma rede com vários backends, cada backend produz seu próprio pack Bedrock (a versão convertida do seu pack Java unificado). O plugin do proxy:

  1. Faz polling no pequeno servidor HTTP de cada backend a cada 5 segundos em busca de /bedrock.zip e /mappings.json, usando If-Modified-Since para que arquivos inalterados custem praticamente zero de banda.
  2. Aguarda o estado da caixa de entrada estabilizar entre dois pollings consecutivos.
  3. Mescla o pack Bedrock de cada backend em um único pack válido para toda a rede.
  4. Copia o arquivo de custom-mappings do Geyser unificado para plugins/Geyser-*/custom_mappings/ no proxy.
  5. Entrega o pack unificado a clientes Bedrock na conexão, via SessionLoadResourcePacksEvent do Geyser.

O plugin do proxy só é útil para jogadores Bedrock. A entrega de packs Java em redes continua acontecendo por backend através da API regular setResourcePack / addResourcePack — clientes Java veem o pack do backend em que estão, conforme o que esse backend escolheu enviar. Se a sua rede é exclusivamente Java, você não precisa do plugin do proxy.

Configuração — Dois Passos​

Passo 1: Instale o Floodgate no proxy e em cada backend​

O Floodgate é necessário para que jogadores Bedrock possam se autenticar no proxy. O RSPM se apoia no plugins/floodgate/key.pem do Floodgate para derivar a identidade da rede — esse arquivo precisa ser idêntico, byte a byte, no proxy E em cada backend. O Floodgate já exige isso para autenticação Bedrock, então se jogadores Bedrock já funcionam na sua rede, isso já está feito.

Se você ainda não tem o Floodgate, instale-o em cada componente e depois copie um key.pem canônico para todos os outros componentes antes de prosseguir.

Passo 2: Copie o jar de proxy correspondente a partir de qualquer backend​

Depois que o RSPM no backend tiver inicializado pelo menos uma vez, olhe em:

plugins/ResourcePackManager/proxy-extension/

Essa pasta vai conter:

ResourcePackManager-Velocity.jar
ResourcePackManager-BungeeCord.jar
README.md  (mais 9 arquivos README traduzidos)

O backend extrai os dois jars a cada inicialização, independentemente da topologia detectada, então estão sempre disponíveis. Copie exatamente um para a pasta plugins/ do seu proxy:

Software de proxyUse este jar
VelocityResourcePackManager-Velocity.jar
BungeeCordResourcePackManager-BungeeCord.jar
Waterfall (fork do Bungee)ResourcePackManager-BungeeCord.jar

Não instale os dois — apenas o correspondente. Instalar ambos vai causar erros de boot na plataforma que tentar carregar o jar errado.

Reinicie o proxy. Pronto.

Intencionalmente não há config para editar nem chave para colar. O plugin do proxy lê plugins/floodgate/key.pem no proxy durante o boot e deriva a identidade da rede a partir dele. Como o Floodgate já exige que esse arquivo seja o mesmo em cada backend e no proxy, a chave derivada coincide automaticamente com a de cada backend.

A primeira mesclagem normalmente é concluída em até ~10 segundos após todos os backends estarem no ar.

Verificando se Está Funcionando​

Console do proxy​

Em até ~10 segundos após o restart (assumindo que os backends estão rodando) você deve ver:

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, ...)
[ResourcePackManager] Merged pack ready at .../merged/Bedrock.zip (sha1 ...)
[ResourcePackManager] Geyser mappings deployed to .../custom_mappings
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1ABCD1234)

/rspm status no proxy​

Mostra um snapshot: lista de backends, resultados de fetch por backend e por caminho (200 / 304 / 404 / CONNECT_FAILED), contador de polls vazios consecutivos, caminho e tamanho atuais do pack unificado, network-http-offset e presença de Floodgate / Geyser no proxy. Requer resourcepackmanager.command.status ou resourcepackmanager.*. O console sempre tem ambas; conceda uma a jogadores via seu plugin de permissões caso queira que eles possam executá-lo. A saída não revela segredos (a chave da rede aparece mascarada, nada de tokens de auth), então conceder amplamente é seguro.

/rspm status em um backend​

A linha Deploy mode deve aparecer como network-backend. A linha Network key deve mostrar uma chave mascarada (com os últimos 4 caracteres visíveis) — compare-a com a chave mascarada do proxy para confirmar que ambos os lados concordam.

Cliente Bedrock​

Conecte-se via Bedrock. Você deve ver o prompt de download do resource pack antes de entrar no mundo. Itens personalizados são renderizados com os modelos pretendidos, em vez de simples armor stands.

Referência de Configuração​

Backend plugins/ResourcePackManager/config.yml​

O modo de rede é detectado automaticamente — não existe uma flag networkMode: true para ativar. Sinais de detecção (qualquer um é suficiente):

  1. Floodgate presente, Geyser-Spigot ausente — sinal mais forte para o caso Bedrock-via-proxy.
  2. spigot.yml: settings.bungeecord: true — chave legada de IP forwarding do BungeeCord / Waterfall.
  3. paper-global.yml: proxies.velocity.enabled: true — forwarding moderno do Velocity.

O único ajuste que importa especificamente para o modo de rede é networkHttpOffset-v2, que controla a porta HTTP em que o proxy vai fazer polling em cada backend. O padrão 1 funciona em praticamente toda hospedagem. Veja Self-hosting para a história completa da resolução de portas.

Proxy plugins/ResourcePackManager/config.yml​

O plugin do proxy escreve um config padrão mínimo na primeira inicialização:

# Force clients to accept the pack (kick on decline). Default: false.
force-resource-pack: false

# Offset added to each backend's Minecraft port to derive the HTTP port
# this proxy will hit for /bedrock.zip and /mappings.json. Default 1.
# Must match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

Intencionalmente não há entrada network-key — ela foi removida antes do release porque a colagem manual era uma grande fonte de má configuração (erros de digitação quebravam silenciosamente o link proxy↔backend). A chave é derivada automaticamente de plugins/floodgate/key.pem.

Estabilidade e Cadência de Mesclagem​

O proxy aguarda o estado da caixa de entrada estabilizar entre dois pollings consecutivos antes de mesclar. Com o intervalo padrão de 5 s, isso significa que a primeira mesclagem acontece ~10 s depois que o proxy consegue ver pelo menos um backend produzindo conteúdo. Mesclagens posteriores só re-zipam quando o conjunto de SHA-1 dos arquivos da caixa de entrada muda, então um longo período de inatividade custa praticamente nada.

Direct Fetch vs Fallback por Relay​

O caminho padrão é o direct fetch: o proxy faz um HTTP GET para http://<backend-host>:<mcPort + offset><path> para cada backend.

Se o proxy não conseguir alcançar diretamente a porta HTTP de um backend (típico de hospedagens compartilhadas / gerenciadas de Minecraft, onde portas MC são expostas mas portas adjacentes são bloqueadas pelo firewall), o backend faz push do bedrock.zip e do mappings.json para um endpoint de relay em magmaguy.com, sob o namespace da rede (derivado da chave do Floodgate). O proxy lista e baixa do relay quando o direct fetch falha de forma definitiva.

Os dois caminhos alimentam a mesma etapa de mesclagem, então o operador nunca precisa escolher — o direct fetch é preferido (custo zero de banda para magmaguy.com), e o relay entra em ação de forma transparente quando necessário.

O relay tem TTL de 30 minutos no servidor. Os backends fazem push a cada 25 minutos para manter a entrada viva; o desligamento limpo derruba a entrada imediatamente, em vez de esperar o TTL.

Solução de Problemas Comuns​

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

O plugin do proxy não conseguiu encontrar plugins/floodgate/key.pem e ficou ocioso. O RSPM não consegue se conectar a nenhum backend sem ele.

Solução: instale o Floodgate no proxy e depois garanta que plugins/floodgate/key.pem no proxy seja idêntico, byte a byte, ao mesmo arquivo em cada backend. O Floodgate gera chaves diferentes por instalação por padrão — copie um key.pem canônico de qualquer backend para todos os outros componentes e reinicie tudo.

Aviso "No merged pack content" após ~20 segundos​

Após 4 ciclos de polling consecutivos vazios, o proxy registra um aviso multilinha único listando cada backend que ele consultou, a URL tentada e o resultado. O aviso explica as soluções mais comuns:

  • CONNECT_FAILED em cada backend — o proxy não consegue alcançar a porta HTTP do backend de forma alguma. Verifique se o endereço em velocity.toml / config.yml é um que o proxy realmente consiga alcançar (não um nome interno de Docker que não resolve a partir da rede do proxy) e se mcPort + networkHttpOffset-v2 está aberto entre proxy e backend. Se você não tem como abrir essa porta (hospedagem gerenciada), veja a seção de fallback por relay acima — o backend deve estar enviando para o relay automaticamente.
  • 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ê (mais comumente: nenhuma definição de itens no pack unificado, ou o primeiro ciclo de mix ainda não terminou).

O aviso dispara uma vez por período de paralisação. Uma linha NetworkSync: recovered é registrada quando pelo menos um backend volta a retornar conteúdo.

Jogadores Bedrock não veem modelos personalizados 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.

Solução: reinicie o proxy uma vez depois que o backend tiver registrado sua primeira linha Merged Bedrock pack published. O RSPM pré-implanta os mappings da execução anterior a cada 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.

Avisos "Duplicate bedrock_identifier" no boot do proxy​

Dois backends emitiram o mesmo identificador Bedrock para o mesmo item base. Vale o último a escrever; é inofensivo se você só precisa que um backend forneça aquele item. Se ambos os backends devem hospedar itens personalizados distintos sob o mesmo item base, renomeie um dos modelos Java de origem para que os hashes gerados automaticamente sejam diferentes.

Jogador Bedrock conectou mas não vê o pack​

O proxy dispara um banner no chat para todos os jogadores Java online quando uma sessão Bedrock carrega sem um pack RSPM utilizável:

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

O próprio jogador Bedrock também recebe um popup modal, e o console do proxy recebe um banner. Se você precisar investigar mais a fundo, ative o stream de debug (disponível tanto no Velocity quanto no BungeeCord):

/rspm debug bedrock on

Isso liga linhas de log detalhadas [RSPM-BedrockDebug] vindas do GeyserBinder. Reproduza o problema, e depois desligue:

/rspm debug bedrock off

A configuração retorna a desligada no restart do proxy, então não pode ser deixada ligada por acidente.

Atualizando o RSPM em uma Rede​

Depois de atualizar o jar do RSPM no backend, copie novamente o jar de proxy correspondente de plugins/ResourcePackManager/proxy-extension/ em qualquer backend para o proxy e reinicie o proxy. O backend regenera esses jars a cada boot, então eles estão sempre sincronizados com a versão do backend.

O que Ainda Não é Suportado​

  • Packs Java em redes via o plugin do proxy. Clientes Java recebem packs de cada backend diretamente pela API regular. Não existe um mixer de pack Java do lado do proxy.
  • Mesclagem de pack Java entre backends. O pack Java de cada backend é independente. Se um jogador trocar de backend, ele recebe o pack do novo backend.
  • Reconfiguração em tempo real da chave da rede. A chave está atrelada ao key.pem do Floodgate. Mudá-la exige reiniciar o proxy E cada backend (que é o que você faria de qualquer forma ao rotacionar a chave do Floodgate).