Redes com Proxy (BungeeCord / Waterfall / Velocity)

O ResourcePackManager funciona em redes com proxy. Há um único jar — ResourcePackManager.jar — e você instala o mesmo jar em cada backend e no proxy. Em um backend ele roda no papel de backend (mesclar, hospedar, enviar, converter); em um proxy Velocity ou BungeeCord/Waterfall, o mesmo jar detecta automaticamente o loader da plataforma e roda no papel de proxy (entrega Bedrock do lado da rede). Os dois papéis se conectam sozinhos: o proxy é o dono da chave da rede e a envia para cada backend na primeira vez que um jogador se conecta a ele — sem jar de proxy separado por plataforma, sem chave para colar.

Ao longo desta página, "o plugin do proxy" é uma forma abreviada de se referir a esse mesmo ResourcePackManager.jar rodando no papel de proxy.

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, preferindo ETags fortes com If-None-Match e mantendo compatibilidade com If-Modified-Since para backends mais antigos. Arquivos inalterados retornam 304, então custam praticamente zero de banda. Cada backend anuncia a porta HTTP exata em que se vinculou, então o proxy normalmente acerta a porta automaticamente (veja Resolução de porta HTTP do backend).
2. Aguarda o estado da caixa de entrada estabilizar — ele mescla assim que dois pollings adjacentes observam o mesmo conjunto de hashes de arquivo.
3. Mescla o pack Bedrock de cada backend em um único pack válido para toda a rede.
4. Quando existem mappings de itens, 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 — Um Passo (Mais o Floodgate, Se Você Quiser Bedrock)

Floodgate

O Floodgate é necessário para que jogadores Bedrock se autentiquem no proxy. Ele não é necessário para que o RSPM ligue o proxy aos seus backends — uma rede exclusivamente Java pode rodar o plugin do proxy sem Floodgate nenhum.

Se o Floodgate estiver instalado no proxy no momento em que o RSPM inicia lá pela primeira vez, o RSPM usa plugins/floodgate/key.pem como semente da chave da rede uma única vez, de modo que uma rede existente que já funcionava mantém a mesma identidade após a atualização. Depois desse primeiro boot, a chave passa a viver no próprio arquivo network-key do RSPM e o key.pem nunca mais é lido.

Copie o ResourcePackManager.jar para o proxy

Há apenas um jar. O mesmo ResourcePackManager.jar que você instala em backends Bukkit/Paper também é o plugin do proxy — ele inclui as implementações Velocity e BungeeCord/Waterfall juntas em um único jar shaded e detecta automaticamente em qual plataforma está rodando. Não há um jar de proxy separado por plataforma para extrair.

Se você já iniciou os backends sem colocar o RSPM no proxy, não precisa sair caçando o download: cada backend atrás de proxy e sem chave prepara uma cópia byte a byte idêntica do seu próprio jar em plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar e imprime esse caminho exato no console. Copiar esse arquivo garante que proxy e backend nunca fiquem em versões diferentes.

Copie o mesmo ResourcePackManager.jar para a pasta plugins/ do seu proxy:

Software de proxy	Use este jar
Velocity	ResourcePackManager.jar
BungeeCord	ResourcePackManager.jar
Waterfall (fork do Bungee)	ResourcePackManager.jar

Você pode confirmar isso a partir de um backend a qualquer momento executando /rspm status; a seção Proxy deployment imprime Network proxy jar: ResourcePackManager.jar e Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall.

Reinicie o proxy. Pronto.

Não há nenhuma config obrigatória para editar nem chave para colar. O proxy estabelece a chave da rede sozinho no boot e provisiona cada backend com ela automaticamente — veja Como o proxy e os backends se conectam abaixo. O config.yml gerado no proxy contém apenas duas configurações opcionais, ambas descritas mais adiante.

O primeiro polling do proxy dispara ~2 segundos após o boot, depois a cada 5 segundos. Combinado com o gate de estabilidade de ciclo único, a primeira mesclagem é publicada cerca de 7 segundos depois que o proxy consegue ver pelo menos um backend já produzindo conteúdo.

Como o Proxy e os Backends se Conectam

Tudo o que se segue acontece sem configuração. Está documentado aqui porque, quando uma rede não se conecta, conhecer a sequência é o diagnóstico inteiro.

1. O proxy estabelece a chave. No boot ele resolve exatamente um valor, nesta ordem:

1. seu arquivo network-key salvo, na pasta de dados do próprio plugin do proxy — o estado normal em todo boot depois do primeiro;
2. uma semente única derivada de plugins/floodgate/key.pem no proxy, se esse arquivo existir;
3. uma chave aleatória recém-gerada.

Qualquer que seja o ramo executado, o resultado é gravado em network-key e reutilizado para sempre. O console do proxy diz o que aconteceu (Network key loaded ✓, adopted from Floodgate key.pem ou New network key generated). Se o arquivo não puder ser gravado, o proxy registra um erro em nível [ERROR] — esse estado não é fatal para o boot atual, mas o próximo restart gera uma chave diferente e desconecta silenciosamente todos os backends, então corrija as permissões da pasta.

2. O proxy envia a chave para cada backend. Assim que um jogador se conecta a um backend, o proxy envia a chave para ele pelo canal de plugin rspm:network. A direção é deliberada: um backend fisicamente não consegue pedir, porque um proxy não encaminha uma mensagem de plugin em um canal que o próprio cliente do jogador nunca registrou.

3. O backend adota e persiste a chave. Ele salva a chave em seu data.yml e reporta Network key received from the proxy; this backend is now linked. As concessões só são aceitas enquanto o backend não tiver chave alguma — um backend já estabelecido registra um aviso e mantém o que tem, em vez de deixar que uma mensagem o redirecione para outra rede.

No Velocity com forwarding moderno, as concessões são assinadas com um HMAC sobre o forwarding.secret do proxy, e um backend configurado para forwarding moderno exige essa assinatura. No BungeeCord, no Waterfall e no forwarding legado não existe segredo compartilhado para assinar, então as concessões são não assinadas e aceitas assim mesmo.

Um backend que chega ao passo 2 mas nunca ao passo 3 mantém sua fonte de chave em not set. Esse é exatamente o estado que dispara o staging em proxy-extension/ e o banner de aviso específico do Bedrock.

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 loaded ✓
[ResourcePackManager] Network key provisioning ready on rspm:network; backends are keyed as players connect.
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/rspm status no proxy

Imprime um snapshot: fingerprint da chave da rede, lista de backends, resultados de fetch por backend e por caminho (200 / 304 / 404 / CONNECT_FAILED) para /bedrock.zip, /mappings.json e /rspm-update.jar, os anúncios de endpoint que ele recebeu, as entradas de relay que consegue ver, o contador de pollings vazios consecutivos, se o pack Bedrock unificado e os mappings unificados estão em disco (com seus tamanhos) mais o prefixo SHA-1 do pack unificado atual, o fallback network-http-offset, a pasta do plugin Geyser detectada e o arquivo de mappings implantado, e a presença de Floodgate / Geyser no proxy. O Velocity aceita resourcepackmanager.command.status ou resourcepackmanager.*; o BungeeCord registra exatamente o nó resourcepackmanager.command.status, que plugins de permissão podem satisfazer por expansão de wildcard. O console pode executá-lo. A saída não revela segredos (a chave da rede aparece apenas como um curto fingerprint de hash unidirecional, e nenhum token de auth é impresso), então conceder amplamente é seguro.

/rspm status em um backend

A linha Deploy mode deve aparecer como network-backend. Network key fingerprint deve mostrar um hash curto — ele precisa coincidir com o fingerprint que o proxy imprime. Network key source diz como este backend a obteve:

Linha de origem	Significado
provided by the proxy	O estado normal de rede conectada. O proxy concedeu a chave em uma conexão de jogador.
saved on this server	Já tinha chave de um boot anterior (ou é um servidor standalone que gerou a sua própria).
adopted from Floodgate's key	Semeada uma única vez a partir do plugins/floodgate/key.pem local deste backend.
not set — the proxy sends one when a player next connects here	Não conectado. Ou nenhum jogador se conectou desde que o proxy subiu, ou o proxy está sem o RSPM / é um proxy não suportado.

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 de fallback em que o proxy fará polling em cada backend (a porta que o proxy adivinha antes de um backend ter anunciado a porta em que efetivamente se vinculou). O padrão 1 funciona em praticamente toda hospedagem. Veja Self-hosting para a história completa da resolução de portas.

Em operação normal, cada backend anuncia automaticamente ao proxy sua porta HTTP real (via o registro de endpoints em magmaguy.com), então o offset só é consultado como fallback de inicialização/falha. Veja Resolução de porta HTTP do backend abaixo.

Proxy config.yml

O plugin do proxy escreve um config padrão mínimo na primeira inicialização. A pasta difere conforme a plataforma, porque cada proxy a deriva do seu próprio identificador de plugin:

Software de proxy	Caminho da config
Velocity	plugins/resourcepackmanager/config.yml
BungeeCord / Waterfall	plugins/ResourcePackManager/config.yml

Ele contém exatamente duas configurações, ambas opcionais:

# FALLBACK offset added to each backend's Minecraft port to derive the HTTP
# port this proxy will hit for /bedrock.zip and /mappings.json BEFORE that
# backend has announced its real ResourcePackManager HTTP port. Default 1.
# In normal operation the backend announces the exact port it bound, so this
# value is only used at startup or if announcement fails — but if it IS used,
# it should match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

# Installs and updates this universal ResourcePackManager.jar in the proxy's
# Geyser extensions folder, which is what makes custom Bedrock ENTITIES render.
# Default true. Setting it to false stops future installation and update
# staging; it does not delete an extension jar that is already installed —
# remove that by hand while Geyser is stopped.
geyser-extension-auto-install: true

Os equivalentes no backend são networkHttpOffset-v2 e geyserExtensionAutoInstall no config.yml do backend. Os dois lados são configurações separadas — desligar a instalação da extensão no proxy não a desliga nos backends, e vice-versa.

Ao lado do config.yml, o plugin do proxy também grava um arquivo network-key na mesma pasta. Isso é estado gerado, não configuração: não edite e não copie entre redes diferentes. Apagá-lo faz o proxy gerar uma chave totalmente nova no próximo boot, o que desconecta todos os backends já provisionados (cada backend mantém a chave antiga e não adota uma substituta). Copiá-lo é a atitude correta em um único caso: dois proxies à frente do mesmo conjunto de backends, que precisam compartilhar uma chave.

Não existe uma configuração force-resource-pack do lado do proxy. Forçar a aceitação do pack é uma decisão do lado do backend (forceResourcePack no config.yml do backend), porque o plugin do proxy só trata da entrega do pack Bedrock — ele nunca envia packs Java. Se um config.yml de proxy mais antigo ainda tiver uma linha force-resource-pack, ela é simplesmente ignorada e pode ser removida.

Intencionalmente não existe uma entrada de config network-key — uma chave colável foi descontinuada antes do release porque erros de digitação quebravam silenciosamente o link proxy↔backend sem nenhum erro em lugar algum. A chave é estabelecida pelo proxy e provisionada aos backends automaticamente, como descrito em Como o proxy e os backends se conectam.

Resolução de Porta HTTP do Backend

O proxy precisa saber em qual porta HTTP fazer polling em cada backend para /bedrock.zip e /mappings.json. Ele resolve essa porta nesta ordem:

1. Endpoint anunciado pelo backend (preferido). Cada backend faz upload da porta HTTP exata em que se vinculou para o registro de endpoints em magmaguy.com, chaveado pela chave da rede. A cada polling, o proxy atualiza essa lista e associa a porta anunciada de um backend à entrada da lista de servidores pela porta Minecraft (e pelo host, quando disponível). Isso significa que um admin que define um selfHostPort explícito em um backend, ou cujo backend cai automaticamente em mcPort + 1, é tratado de forma idêntica — o proxy usa o que quer que o backend efetivamente tenha vinculado.
2. mcPort + network-http-offset-v2 (fallback). Usado apenas quando nenhum anúncio correspondente está disponível (por exemplo, no primeiro polling antes de qualquer backend ter anunciado, ou se o registro de endpoints está brevemente inacessível). É por isso que os dois offsets ainda devem coincidir se você depender do fallback.

O proxy deliberadamente não faz port-scan em um backend como fallback — isso parece comportamento abusivo para o host. Quando o direct fetch não consegue funcionar de jeito nenhum, o caminho de relay (abaixo) é a resposta categórica.

/rspm status no proxy mostra, por backend, qual porta foi escolhida e se ela veio de um anúncio ou do fallback de offset.

Estabilidade e Cadência de Mesclagem

O proxy aguarda o estado da caixa de entrada estabilizar antes de mesclar: o primeiro polling define o conjunto-base de hashes de arquivo, e o polling seguinte que observar o mesmo conjunto dispara a mesclagem (um gate de estabilidade de um ciclo). Com o atraso inicial de ~2 s e o intervalo de polling de 5 s, isso coloca a primeira mesclagem ~7 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.

Os backends escrevem seu bedrock.zip em um arquivo temporário e o renomeiam atomicamente, então a rota /bedrock.zip sempre serve um zip completo — o proxy nunca precisa se defender contra leituras pela metade, e é por isso que o gate é de um único ciclo, em vez de dois.

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 seu bedrock.zip e do mappings.json para um endpoint de relay em magmaguy.com, sob o namespace da rede (derivado da chave da rede). 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

Um backend nunca recebe uma chave de rede

Sintoma: /rspm status no backend mostra Network key source: not set — the proxy sends one when a player next connects here, e o console do backend repete:

[ResourcePackManager] This backend is behind a proxy but has no network key yet, so it is not linked to the proxy.
[ResourcePackManager] The proxy sends one automatically the first time a player connects to this server.

Verifique estes pontos, nesta ordem:

1. Alguém realmente se conectou àquele backend desde que o proxy iniciou? A concessão pega carona em uma conexão de jogador. Um lobby que ninguém visitou ainda está legitimamente sem chave.
2. O RSPM está no proxy? O backend prepara uma cópia do seu próprio jar em plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar exatamente para esse caso. Copie-a para a pasta plugins/ do proxy e reinicie o proxy.
3. Forwarding moderno do Velocity: o segredo de forwarding do backend coincide com o do proxy? Um backend configurado para forwarding moderno rejeita de propósito uma concessão não assinada ou assinada incorretamente — essa verificação é a única coisa que impede um proxy não autorizado de chavear seus backends. O log do backend informa qual dos dois casos ocorreu. Corrija o segredo dos dois lados e a próxima conexão de jogador tenta novamente de forma automática; não é preciso reiniciar nenhum dos lados para rearmar.
4. O proxy é um proxy não suportado? Apenas Velocity e BungeeCord/Waterfall rodam o papel de proxy.

Note que o key.pem do Floodgate não faz mais parte disso. Um plugins/floodgate/key.pem ausente no proxy é um estado totalmente suportado — o proxy gera a própria chave. O Floodgate continua sendo necessário para que jogadores Bedrock consigam alcançar o proxy.

Dois proxies à frente dos mesmos backends

Ambos os proxies precisam apresentar a mesma chave de rede, senão cada backend se conecta ao primeiro que o alcançou e rejeita o outro (registrando A proxy offered a network key that differs from the one this backend already uses). Copie o arquivo network-key da pasta de dados do RSPM no proxy principal para a do outro proxy e reinicie-o.

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 a porta HTTP do backend está aberta entre proxy e backend. O aviso imprime o host:porta HTTP exato que ele tentou para cada backend e se essa porta veio do anúncio do backend ou do fallback mcPort + networkHttpOffset-v2. 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: nenhum mapping de item convertível ou bundle de entidade 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

É o mesmo jar em cada backend e no proxy, então mantenha todos os componentes na mesma versão.

O caminho manual é: atualizar o jar do backend, copiar novamente esse mesmo ResourcePackManager.jar para a pasta plugins/ do proxy e reiniciar o proxy.

O RSPM também consegue fazer a parte do proxy sozinho. Cada backend oferece seu jar universal do plugin ao proxy por uma rota autenticada (/rspm-update.jar, protegida por um token derivado da chave de rede compartilhada — a chave em si nunca é transmitida). O proxy valida que o arquivo oferecido é um jar universal completo do RSPM, com versões de descritor de plataforma coincidentes e os entry points esperados, recusa downgrades e verifica os bytes preparados contra o tamanho e o SHA-256 anunciados antes de substituir qualquer coisa. Ele prepara o mesmo jar para o plugin do proxy e, quando detecta um Geyser hospedado no proxy, também a extensão Geyser embutida; esses arquivos são aplicados no desligamento do proxy e os arquivos anteriores são mantidos como cópias de rollback.

Isso é uma fronteira de confiança de rede autenticada, não uma verificação independente de proveniência contra a Nightbreak: qualquer backend provisionado com a chave de rede compartilhada é considerado confiável para oferecer um jar do RSPM estruturalmente válido e de versão igual ou mais nova. Proteja essa chave e trate todo backend que a compartilha como infraestrutura confiável.

Então, na prática, atualizar os backends e depois reiniciar o proxy costuma ser suficiente — o proxy já terá preparado o jar correspondente para si mesmo. Uma atualização recusada registra Rejected backend-offered ResourcePackManager update: ... com o motivo.

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.
• Rotação em tempo real da chave da rede. Um backend adota uma chave exatamente uma vez e não aceita uma substituta vinda de uma mensagem. Rotacionar significa apagar o arquivo network-key do proxy e limpar networkKey do data.yml de cada backend, e depois reiniciar tudo.