Extensão Geyser e Entidades Bedrock Personalizadas

Converter o resource pack dá aos jogadores Bedrock as texturas e os modelos corretos para itens. Já obter entidades personalizadas de verdade — um boss modelado que é renderizado e animado em vez de aparecer como um armor stand — exige código rodando dentro do próprio Geyser. É isso que a extensão Geyser do RSPM faz.

Você não a baixa separadamente. O mesmo ResourcePackManager.jar que você instala como plugin é a extensão.

Um Jar, Três Funções

O ResourcePackManager.jar é simultaneamente:

• o plugin de backend Bukkit/Paper,
• o plugin de proxy Velocity e BungeeCord/Waterfall,
• e uma extensão do Geyser.

Qualquer que seja o loader que o abra, ele escolhe o ponto de entrada correspondente. Versões mais antigas distribuíam um ResourcePackManager-GeyserBridge.jar separado; esse arquivo foi descontinuado e o RSPM limpa os resíduos automaticamente.

Como Ele é Instalado

O RSPM instala a extensão para você nos casos em que consegue. O que acontece depende de onde o Geyser está:

Sua configuração	O que o RSPM faz
Geyser-Spigot no mesmo servidor	Copia o jar em execução para plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Se já houver uma versão diferente lá, ele prepara a nova através da própria fila de atualização do Geyser em extensions/update/. De qualquer forma, você recebe uma linha no console pedindo que reinicie uma vez.
Geyser no proxy (Geyser-Velocity / Geyser-BungeeCord)	A função de proxy faz a mesma coisa na pasta Geyser-*/extensions/ do proxy.
Floodgate local, Geyser externo (o Geyser roda em um processo separado)	O RSPM não consegue alcançar esse processo. Ele exporta uma cópia para plugins/ResourcePackManager/geyser-extension/ e avisa você para copiar exatamente esse jar para a pasta extensions/ do Geyser externo e reiniciar o Geyser.
Nem Geyser nem Floodgate presentes	Nada a fazer — o RSPM registra uma linha informativa e pula a instalação.

Uma versão mais nova já presente em extensions/ nunca é sobrescrita por uma mais antiga.

A instalação sempre exige um reinício. O Geyser carrega extensões na inicialização, então um jar recém-copiado ou preparado não faz nada até o servidor ou o proxy reiniciar.

Desligando a Instalação Automática

Cada função tem sua própria chave, e elas são independentes:

Onde	Configuração	Padrão
Backend plugins/ResourcePackManager/config.yml	geyserExtensionAutoInstall	true
Proxy config.yml	geyser-extension-auto-install	true

Definir qualquer uma delas como false impede aquela função de instalar a extensão ou preparar uma atualização para ela, e registra uma linha dizendo isso. Leia a semântica com atenção:

• Isso impede instalações futuras e a preparação de atualizações.
• Isso não remove um jar de extensão que já está em extensions/. O Geyser tem esse arquivo aberto. Para realmente desativar a bridge, defina a flag como false, pare o Geyser, apague o jar do RSPM de extensions/ manualmente e inicie-o de novo.
• Desligar isso não tem efeito algum sobre a conversão ou a entrega do pack. Itens, texturas e modelos continuam sendo convertidos e servidos; apenas as entidades Bedrock personalizadas param de funcionar.

Desligar isso no backend também faz com que uma atualização baixada do RSPM não seja preparada na fila de atualização de um Geyser-Spigot local, de modo que a extensão e o plugin podem divergir de versão — que é exatamente o estado que a proteção de compatibilidade abaixo existe para detectar.

O Que a Extensão Realmente Faz

• Registra as definições de entidade Bedrock personalizadas do RSPM no Geyser na inicialização, lendo os identificadores de entidade a partir do pack Bedrock gerado.
• Troca a definição Bedrock das entidades que aparecem, para que uma entidade modelada apareça como sua entidade Bedrock personalizada em vez do fallback vanilla.
• Aplica dados de entidade e overrides de propriedades ao vivo enquanto a entidade existe.
• Prepara antecipadamente os IDs de rede de receitas do Geyser, o que evita uma classe de problemas de colisão de IDs de receita no Geyser 2.11.

Os assets do lado Bedrock aos quais essas definições se referem vêm dos bundles de entidade descritos em Conversão Bedrock — um plugin distribui arquivos nativos de entidade Bedrock em assets/<namespace>/rspm_bedrock_pack/ e o RSPM os leva para o pack gerado.

Requisitos de Versão do Geyser

A extensão tem como alvo o Geyser 2.11+.

O descritor dela declara deliberadamente um nível de API do Geyser mais baixo (2.9.0), para que um Geyser mais antigo carregue a extensão de bom grado em vez de recusar o jar de imediato. O requisito real é aplicado em tempo de execução: a extensão sonda as classes de que precisa e se desativa quando elas estão ausentes, o que produz uma mensagem clara em vez de uma rejeição no carregamento que o operador não consegue interpretar.

Ela foi projetada para falhar de forma fechada diante de incompatibilidade de classes/linkagem, em vez de derrubar o Geyser junto. A casca da extensão referencia apenas tipos da API do Geyser de longa data; classes sensíveis à versão são sondadas antes de o núcleo iniciar. Se a sua build do Geyser não incluir uma classe de que a bridge precisa, a bridge se desativa e informa isso:

Disabled the RSPM custom Bedrock entity bridge: this Geyser build does not ship <class>. Geyser itself is unaffected, but custom Bedrock entities will not appear until a ResourcePackManager update matches this Geyser version.

Itens, texturas e modelos continuam a ser convertidos e servidos normalmente nesse estado — apenas as entidades personalizadas são afetadas. A solução é atualizar o Geyser, ou aguardar a versão do RSPM que corresponda à sua build do Geyser.

Versões anteriores do RSPM obtinham o mesmo resultado trocando uma cópia embutida de um dos tradutores de pacotes internos do Geyser dentro do registro do Geyser. Essa substituição de tradutor acabou: a extensão agora usa os eventos/ciclo de vida públicos de entidade do Geyser 2.11 para registro e substituição de definição de spawn. O núcleo ainda sonda um conjunto limitado de internos do Geyser usados para construir instâncias de definição e receber mensagens de plugin downstream, e é por isso que a proteção de compatibilidade e a correspondência exata de versões RSPM/Geyser continuam importando.

Ordem: Por Que às Vezes é Preciso Reiniciar

O Geyser registra definições de entidade durante sua própria janela de inicialização. Se o RSPM terminar de gerar o pack Bedrock depois que essa janela fechou — que é exatamente o que acontece em uma instalação novinha, onde não existe pack algum no boot — as definições chegam tarde demais para entrar nos registros já congelados do Geyser. O RSPM as guarda para a próxima inicialização e avisa você:

RSPM custom Bedrock entity definitions became available after Geyser closed its startup registration windows ... restart the proxy once to activate the newly generated custom models.

Reinicie uma vez o processo de servidor ou proxy que hospeda o Geyser, após a primeira geração bem-sucedida do pack. Apenas reconectar não consegue ativar definições que perderam a janela de inicialização. A ordem fica correta nos boots seguintes porque o pack já existe quando o Geyser abre suas janelas de registro.

Verificando Se Está Funcionando

1. Verifique se a pasta extensions/ de destino realmente contém o ResourcePackManager.jar.
2. No boot, o Geyser deve listar a extensão como carregada, e o RSPM registra quantas definições de entidade Bedrock personalizadas ele registrou.
3. Entre no Bedrock e olhe para uma entidade modelada. Armor stands em vez de modelos significam que ou a extensão não está carregada, ou o pack não chegou ao cliente, ou as definições chegaram atrasadas — verifique os avisos acima nessa ordem.

Resolução de Problemas

"A extensão carregou, mas as entidades continuam sendo armor stands." O pack e a extensão são metades separadas. Confirme primeiro se o próprio pack Bedrock chegou ao cliente (veja Conversão Bedrock); sem os assets de entidade do pack não há nada para as definições renderizarem.

"Funcionava, aí eu atualizei o Geyser e as entidades quebraram." Procure pela mensagem de autodesativação acima. Uma atualização do Geyser pode mover a superfície de API que a bridge sonda.

"Nunca foi instalado nada em extensions/." Verifique no console se aparece Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall (backend) ou ... by geyser-extension-auto-install (proxy). Alguém desligou a chave. Se o Geyser e o Floodgate estiverem ambos ausentes localmente, você verá em vez disso Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation — isso é o RSPM decidindo corretamente que não há nada em que instalar.

"Atualizei o RSPM mas a extensão continua na versão antiga." A extensão só é substituída no reinício, e se o RSPM a preparou através da fila de atualização do Geyser ela precisa de um reinício para ser trocada. Mantenha o jar do plugin e o jar da extensão na mesma versão — eles são o mesmo arquivo, então recopiar o plugin é suficiente.

No Velocity, a inscrição automática de extensões do Geyser não é disparada da forma como é em outras plataformas, então o plugin do proxy retransmite os eventos de ciclo de vida por conta própria. Isso é tratado internamente e não exige configuração.

Para Onde Ir Em Seguida

• Conversão Bedrock / Geyser — o que é convertido e como o pack é servido
• Redes com Proxy — Geyser em um proxy
• Resolução de Problemas