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 encontram automaticamente por meio do arquivo compartilhado plugins/floodgate/key.pem — sem jar de proxy separado, sem proxy-extension para extrair, 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, usando If-Modified-Since para que arquivos inalterados custem 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. 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 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.

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.

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.

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.

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, 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: 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 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 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

# 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

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.

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 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 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: 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 mesmo ResourcePackManager.jar para a pasta plugins/ do proxy e reinicie o proxy. É o mesmo jar em cada backend e no proxy, então mantenha todos os componentes na mesma versão.

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