Pular para o conteúdo principal

Conversão Java-para-Bedrock

O ResourcePackManager pode converter o resource pack Java unificado em um resource pack Bedrock, para que clientes do GeyserMC vejam o mesmo conteúdo personalizado que clientes Java. Esse recurso vem habilitado por padrão.

O Que é Convertido​

O conversor não é mais exclusivo do FreeMinecraftModels. Ele executa dois pipelines em sequência sobre o pack Java unificado:

  1. Scanner de ossos do FreeMinecraftModels — detecta modelos de ossos do FMM em assets/freeminecraftmodels/models/ e converte cada osso em um attachable Bedrock.
  2. Pipeline genérico de definições de itens — percorre todo arquivo assets/<namespace>/items/*.json no formato 1.21.4+ (pulando os namespaces minecraft e freeminecraftmodels). Para cada modelo folha, ele:
    • emite um ícone de inventário Bedrock plano (para minecraft:item/generated e parentes flat-builtin semelhantes), ou
    • emite geometria Bedrock, um attachable, um arquivo de animação e um ícone de inventário 2D renderizado por software (para modelos 3D propriamente ditos).

Um identificador Bedrock único é gerado por par (modelo × item base), então, por exemplo, um único modelo de espada registrado contra múltiplos itens base não colide do lado do Geyser.

Conjuntos de armadura personalizada são detectados quando existe um irmão assets/<namespace>/equipment/<material>.json. O conversor cria um attachable de armadura que combina a geometria de armadura vanilla com a textura Java como camada visível, para que os jogadores Bedrock vejam a textura de armadura correta ao usar o item.

O UUID do manifest do pack Bedrock é derivado determinísticamente do nome do pack, mantendo-se estável entre reconstruções; apenas o trio de versão é incrementado por build (token cache-bust derivado do tempo de build).

Serviço Ao Vivo Por Sessão​

Quando o Geyser-Spigot é detectado, o ResourcePackManager registra um subscriber de SessionLoadResourcePacksEvent. Cada jogador Bedrock que entrar após uma nova mescla recebe o pack Bedrock mais recente servido diretamente do disco, sem necessidade de reiniciar o servidor para edições de textura ou modelo.

Os mapeamentos de itens personalizados do Geyser (o JSON em custom_mappings/) ainda são congelados na inicialização, então adicionar novos itens personalizados ou remover existentes exige reinício do servidor antes que clientes Bedrock vejam essas mudanças. O RSPM pré-implanta o arquivo de mapeamento da execução anterior no início da inicialização para que o registro de itens personalizados do Geyser no boot o detecte automaticamente.

Jogadores Bedrock atualmente conectados mantêm o pack que receberam quando entraram — isso é uma restrição do protocolo Bedrock, não algo que o plugin possa contornar em meio à sessão.

Arquivos de Saída​

Após uma mescla bem-sucedida, os arquivos Bedrock ficam em:

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json

Se o auto-deploy estiver ativado e o Geyser tiver sido detectado, o arquivo de mapeamento também é copiado para:

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

O zip do pack Bedrock não é copiado para <geyser-folder>/packs/ — ele é servido ao vivo por sessão. O RSPM também remove qualquer cópia legada deixada nessa pasta por versões antigas do plugin, para que o Geyser não acabe servindo o pack duas vezes (UUIDs duplicados confundiriam o cliente Bedrock).

Configurações em config.yml​

# Alterna por completo a conversão Java-para-Bedrock.
bedrockConversionEnabled: true

# Copia o arquivo de custom mappings do Geyser para o diretório custom_mappings/
# da pasta Geyser detectada em cada mescla.
bedrockAutoDeployToGeyser: true

# Substituição manual para a pasta de dados do Geyser. Vazio = auto-detecção.
# Pode ser absoluto ou relativo ao diretório plugins/.
bedrockGeyserFolder: ""

A auto-detecção observa, nesta ordem:

  1. bedrockGeyserFolder se estiver definido (tratado primeiro como caminho absoluto, depois como caminho relativo a plugins/).
  2. plugins/Geyser-Spigot/
  3. plugins/Geyser-*/ (qualquer variante)
  4. config/Geyser-*/ (para configurações Fabric/NeoForge)

Ajustando a Exibição de Itens Segurados: bedrock_display_offsets.yml​

O Bedrock renderiza o item segurado por meio de um osso pai cuja pose de descanso difere das transformações de primeira/terceira pessoa do Java, então a conversão algorítmica precisa aplicar um offset base sobre o que quer que a transformação display do modelo Java especifique. Os offsets padrão funcionam para modelos Java típicos destros, mas casos atípicos podem precisar de ajuste.

Primeira pessoa e terceira pessoa são duas passagens de renderização Bedrock completamente separadas (ossos pais diferentes, poses de descanso diferentes), então cada uma tem seu próprio conjunto independente de seis parâmetros. Ajustar uma não afeta a outra.

# ===== Primeira pessoa (mão direita, vista pelo portador) =====
firstPersonBaseRotationX: -90.0   # pitch (inclinação na direção da câmera/contrária). O padrão cancela a rotação do pai.
firstPersonBaseRotationY: 0.0     # yaw (rotação em torno da linha vertical)
firstPersonBaseRotationZ: 0.0     # roll (em torno do eixo frente-câmera)
firstPersonBasePositionX: 0.0     # vertical na tela (positivo = para cima)
firstPersonBasePositionY: 12.5    # profundidade (positivo = mais adentro da cena)
firstPersonBasePositionZ: 0.0     # horizontal na tela (positivo = para a direita)

# ===== Terceira pessoa (mão direita, vista por outros jogadores / F5) =====
thirdPersonBaseRotationX: 90.0    # pitch como os observadores veem
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # roll em torno do eixo longitudinal do item
thirdPersonBasePositionX: 0.0     # horizontal em relação ao corpo do portador (positivo = para fora)
thirdPersonBasePositionY: 12.5    # vertical (positivo = eleva o modelo)
thirdPersonBasePositionZ: 0.0     # profundidade em relação ao portador (positivo = para frente)

Os valores de posição são em pixels, onde 1 pixel = 1/16 de bloco. As rotações são em graus.

O cliente Bedrock recarrega ao vivo o JSON de attachable sem precisar reiniciar. Se um cliente Bedrock de teste estiver logado, altere o valor, execute /rspm reload, e o próximo join Bedrock (ou, em alguns casos, o mesmo jogador conectado após uma pequena ação no mundo que faça o re-bind do attachable) mostra o novo offset. Itere até ficar certo.

Limitações e Comportamentos Conhecidos​

  • Ícones de inventário 3D são renderizados por software a partir da transformação display.gui do modelo Java. A renderização é razoável, mas não pixel-perfect; se o ícone parecer errado, a causa mais comum é um arquivo de textura ausente/com nome incorreto referenciado pelo modelo.
  • Texturas de flipbook usadas como ícones de itens são cortadas ao frame 0 — o item_texture.json do Bedrock não suporta ícones animados, apenas texturas animadas de bloco/terreno via flipbook_textures.json.
  • A versão de formato da geometria de attachable está fixada em 1.21.0 (era 1.16.0 em versões antigas do plugin); atualize o Geyser se sua instalação não conseguir analisá-la.
  • Modelos de itens vanilla (shield.json, crossbow.json) não são mesclados recursivamente entre packs para evitar corrupção de árvore de predicados entre packs; a cópia do pack de maior prioridade vence para esses dois especificamente.
  • Se o conversor não conseguir resolver um arquivo de textura ou modelo referenciado, essa folha é pulada e um aviso [BedrockConverter] é registrado; o restante do pipeline continua.