Extensão do Geyser e entidades Bedrock personalizadas

A conversão do pacote fornece as texturas e modelos de objetos suportados. As entidades personalizadas, como um boss com aparência e animações próprias, também precisam de código no Geyser. A extensão Geyser do RSPM fornece essa integração aos plugins produtores compatíveis e aos seus recursos de entidades Bedrock.

Não precisa de uma transferência separada: o mesmo ResourcePackManager.jar instalado como plugin também é a extensão.

Um JAR, três funções

ResourcePackManager.jar funciona simultaneamente como:

• Plugin de backend Bukkit/Paper.
• Plugin de proxy Velocity e BungeeCord.
• Extensão do Geyser.

Cada carregador usa o seu ponto de entrada. As versões antigas distribuíam um ResourcePackManager-GeyserBridge.jar separado, entretanto retirado. Se o instalador o encontrar, prepara o JAR universal na fila de atualizações do Geyser para o substituir no reinício.

Instalação da extensão

O RSPM instala a extensão automaticamente quando consegue aceder à instalação do Geyser:

Instalação	Ação do RSPM
Geyser-Spigot no mesmo servidor	Na primeira instalação, copia o JAR em execução para plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Se o JAR existente tiver bytes diferentes, prepara a substituição em extensions/update/, respeitando a proteção contra versões anteriores. Uma instalação nova ou substituição preparada pede um reinício; um JAR atual idêntico não precisa de cópia.
Geyser no proxy, Geyser-Velocity ou Geyser-BungeeCord	O plugin do proxy faz o equivalente na pasta Geyser-*/extensions/ do proxy.
Floodgate local e Geyser externo, num processo separado	Exporta uma cópia sob plugins/ResourcePackManager/geyser-extension/. Siga o caminho exato da consola, que pode apontar para a subpasta update/ quando existe uma exportação antiga. Copie esse JAR para extensions/ do Geyser externo e reinicie-o. Exportar apenas a extensão não configura a entrega externa do pacote nem o carregamento das definições no arranque.
Sem Geyser nem Floodgate	Regista uma mensagem informativa e ignora a instalação.

O instalador preserva uma versão válida mais recente encontrada no JAR universal instalado, na integração antiga ou numa atualização preparada. Compara também as somas de verificação, pelo que bytes diferentes com a mesma versão podem exigir substituição.

A instalação exige sempre um reinício. O Geyser carrega as extensões no arranque; um JAR acabado de copiar ou preparar só entra em funcionamento quando o servidor ou proxy reiniciar.

Desativar a instalação automática

O backend e o proxy têm opções independentes:

Local	Definição	Predefinição
Backend, plugins/ResourcePackManager/config.yml	geyserExtensionAutoInstall	true
Proxy, config.yml	geyser-extension-auto-install	true

Definir uma opção como false impede esse componente de instalar a extensão ou preparar atualizações e gera uma mensagem informativa. Tenha em conta:

• Impede instalações e atualizações futuras.
• Não remove um JAR instalado nem cancela uma atualização já preparada. Para desativar a integração, defina as opções relevantes como false e pare completamente o Geyser. Remova ResourcePackManager.jar de extensions/ e extensions/update/, bem como qualquer ResourcePackManager-GeyserBridge.jar antigo nessas pastas, e volte a iniciar. Uma cópia que fique na fila pode restaurar a extensão no arranque. Remova apenas estes ficheiros RSPM.
• Desligar a opção não afeta a conversão, a entrega dos pacotes nem uma extensão já instalada. Remover a extensão desativa a integração de entidades Bedrock personalizadas; a conversão de objetos e a entrega de pacotes são independentes.

No backend, desativar esta opção também impede preparar atualizações RSPM transferidas na fila do Geyser-Spigot local. A extensão e o plugin podem ficar em versões diferentes. Mantenha os seus ficheiros alinhados manualmente; a proteção abaixo verifica as classes Geyser necessárias e a compatibilidade binária, não a igualdade das versões do plugin e da extensão.

Funções da extensão

• Regista as definições de entidades Bedrock personalizadas do RSPM no Geyser durante o arranque, lendo os identificadores do pacote Bedrock gerado. As propriedades de cada entidade são recolhidas dos controladores de animação e de renderização referidos pelo seu ficheiro de entidade do cliente, associados pelo identificador do controlador, pelo que os conjuntos cujos caminhos longos foram abreviados continuam a registar as suas propriedades e animações.
• Substitui a definição Bedrock das entidades ao aparecerem, para usar a entidade personalizada em vez da alternativa normal.
• Aplica dados e substituições de propriedades em tempo real enquanto a entidade existe.
• Prepara antecipadamente os identificadores de rede das receitas do Geyser, evitando uma categoria de conflitos de identificadores no Geyser 2.11.

Os recursos vêm dos conjuntos de entidades descritos em Conversão Bedrock. Um plugin fornece ficheiros nativos de entidades Bedrock em assets/<namespace>/rspm_bedrock_pack/, e o RSPM importa-os para o pacote gerado. O produtor também deve marcar as entidades Java correspondentes através da integração; um conjunto de recursos isolado não transforma entidades arbitrárias em modelos personalizados.

No arranque, a extensão procura identificadores nas entradas entity/*.entity.json do pacote local gerado pelo RSPM. Verifica as saídas habituais do proxy plugins/resourcepackmanager/work/merged/Bedrock.zip e plugins/ResourcePackManager/work/merged/Bedrock.zip, depois a saída do backend plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip, relativamente à pasta de trabalho do Geyser. Um processo Geyser externo não consegue ler automaticamente a saída de outra máquina. Confirme no registo qual foi o pacote pré-carregado; copiar a extensão não fornece automaticamente as definições.

Versões exigidas do Geyser

A extensão destina-se ao Geyser 2.11 ou posterior.

O descritor declara o nível de API Geyser 2.9.0. Esse nível inferior não demonstra compatibilidade com um Geyser antigo. Durante a execução, a extensão verifica as classes necessárias e desativa a integração quando faltam.

As incompatibilidades de classes ou ligações desativam a extensão sem derrubar o Geyser. A camada externa usa apenas tipos estáveis da API; as classes sensíveis à versão são verificadas antes de iniciar o núcleo. Se faltar uma classe necessária, a integração desativa-se e informa, em termos equivalentes:

A integração RSPM de entidades Bedrock personalizadas foi desativada: esta versão do Geyser não inclui <class>. O Geyser continua a funcionar, mas as entidades personalizadas não aparecerão até uma atualização do ResourcePackManager corresponder a esta versão do Geyser.

Desativar a integração não desativa o conversor de objetos nem o fornecedor de pacotes, que são independentes. Estes continuam a precisar das suas próprias APIs Geyser compatíveis e de uma entrega bem-sucedida do pacote. Use uma combinação RSPM/Geyser compatível para recuperar as entidades personalizadas.

As versões anteriores do RSPM substituíam um tradutor interno de pacotes do Geyser por uma cópia incluída. Essa substituição foi removida. A extensão usa agora os eventos públicos de entidades do Geyser 2.11 para registo e substituição da definição de geração. O núcleo ainda verifica um conjunto limitado de componentes internos para construir definições e receber mensagens de plugins a jusante. Por isso, a proteção de compatibilidade e a correspondência exata das versões continuam a ser necessárias.

Ordem de carregamento e necessidade de reinício

O Geyser regista as definições de entidades durante a sua janela de arranque. Se o RSPM gerar o primeiro pacote Bedrock depois de essa janela fechar, as definições chegam demasiado tarde para os registos em execução. O RSPM pede um reinício para pré-carregar o pacote gerado no próximo arranque:

As definições RSPM de entidades Bedrock personalizadas ficaram disponíveis depois de o Geyser fechar as janelas de registo. Reinicie o proxy uma vez para ativar os novos modelos personalizados.

O aviso aparece quando um novo identificador de entidade ou um tipo de propriedade novo ou alterado chega depois de fechar o registo. Exportar novamente as mesmas definições e tipos de propriedades não exige reinício.

Reinicie o servidor ou proxy que executa o Geyser após a primeira geração bem-sucedida do pacote. Voltar a ligar o cliente não ativa definições que chegaram tarde. No próximo arranque, o pacote deve estar no caminho local lido pela extensão e ambas as janelas de registo devem ser recebidas. A linha de estado do arranque indica se isso aconteceu.

Verificar o funcionamento

1. Confirme que a pasta extensions/ de destino contém ResourcePackManager.jar.
2. No arranque, consulte a linha RSPM Geyser bridge health. Inclui a versão da extensão, artifactSha256, activationRoute, loadedDefinitions, packUuid e definitionWindows. Para um pacote com entidades personalizadas, devem existir definições registadas, o UUID do pacote pretendido e definitionWindows=observed. MISSED ou RSPM GEYSER BRIDGE UNHEALTHY significa que uma janela de registo foi perdida; a indicação de extensão carregada não basta.
3. Entre em Bedrock e verifique a aparência e animação de uma entidade com modelo. Se continuar a aparecer como entidade normal, por exemplo um suporte de armadura, verifique a ativação da integração, a entrega ao cliente, as definições registadas e a integração do produtor. Um registo de arranque correto não prova, por si só, que o cliente apresentou a entidade.

Resolução de problemas

A extensão está carregada, mas as entidades continuam como suportes de armadura. O pacote e a extensão são componentes separados. Primeiro confirme que o cliente recebeu o pacote Bedrock, conforme Conversão Bedrock. Sem os recursos de entidades do pacote, as definições não têm modelos para apresentar.

Funcionava, mas as entidades deixaram de funcionar após atualizar o Geyser. Procure a mensagem de desativação descrita acima. Uma atualização do Geyser pode alterar as APIs verificadas pela integração.

Nada foi instalado em extensions/. Procure Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall no backend ou ... by geyser-extension-auto-install no proxy: a opção foi desativada. Sem Geyser nem Floodgate locais, aparece Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation, indicando que não existe um destino local para instalar.

Atualizei o RSPM, mas a extensão continua antiga. A extensão só é substituída ao reiniciar. Uma versão preparada na fila de atualizações do Geyser também exige esse reinício. Mantenha o plugin e a extensão na mesma versão; são o mesmo ficheiro, pelo que basta voltar a copiar o JAR do plugin.

A extensão instala subscrições antecipadas do ciclo de vida por código, além dos seus métodos anotados. No Velocity, o plugin do proxy também retransmite eventos do ciclo de vida e de sessão para cobrir arranques em que as subscrições automáticas foram perdidas. Não exige configuração. Use a linha de estado do arranque e os avisos de registo ou retransmissão para diagnosticar falhas de ativação.

Próximas páginas

• Conversão Bedrock/Geyser: recursos convertidos e entrega do pacote.
• Redes com proxy: Geyser num proxy.
• Resolução de problemas.