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.

Quando a Conversão Roda​

A conversão é condicionada à presença de um alvo Bedrock. O RSPM considera que há um alvo presente se qualquer uma destas condições for verdadeira:

  1. O Geyser-Spigot está instalado neste backend (jogadores Bedrock chegam pelo Geyser localmente).
  2. O Floodgate está instalado neste backend (configuração típica de proxy-backend — o Floodgate roda localmente, o Geyser está em outro lugar).
  3. O modo de rede está ativo — o RSPM detectou que está por trás de um proxy Velocity / BungeeCord / Waterfall. O backend produz seu pack Bedrock e o expõe em um pequeno servidor HTTP, para que o plugin do proxy possa buscá-lo.

Se nenhuma dessas condições for atendida, o conversor é puro overhead e é pulado silenciosamente. /rspm status explica exatamente o porquê quando o pack não foi gerado.

O Que é Convertido​

O conversor é agnóstico de namespace. Ele percorre todo arquivo assets/<namespace>/items/**/*.json no formato de definição de itens 1.21.4+, recursivamente e incluindo o namespace minecraft.

Roteamento flat vs 3D​

Para cada modelo folha, o conversor decide qual dos dois pipelines usar. Modelos enraizados em minecraft:item/generated ou minecraft:builtin/generated permanecem no caminho flat. Para qualquer outra cadeia de parents, um modelo segue o pipeline 3D somente quando o modelo mesclado carrega um array elements não vazio; um modelo sem geometria é um sprite 2D.

  • Flat — a textura layer0 do modelo é copiada diretamente para textures/items/<hash>.png e registrada como ícone do Geyser. No Bedrock, o item exibe o sprite 2D correto no inventário e na mão, exatamente como o Java o renderiza.
  • 3D — o conversor costura um atlas de texturas, converte os cuboides Java em geometria Bedrock, gera animações de mão/cabeça, renderiza por software um ícone de inventário 64×64 e escreve um attachable por mapeamento (modelo × item base × forma do predicado).

Por que a verificação de geometria importa: uma ferramenta handheld plana (parent minecraft:item/handheld com apenas uma textura layer0 e sem elements) ainda é um sprite 2D. Versões anteriores empurravam itens handheld planos para o pipeline 3D, onde falhavam na etapa de geometria e sumiam no Bedrock ou caíam de volta no ícone vanilla do item base. Isso afetava especialmente packs do ItemsAdder, que trazem muitos itens handheld planos. Como elements é lido da cadeia de parents mesclada, um modelo não gerado que herda geometria de um parent continua sendo roteado para 3D.

Um identificador Bedrock único é gerado por mapeamento (modelo × item base × forma do predicado), então um único modelo de espada registrado contra múltiplos itens base ou ramos de predicado não colide do lado do Geyser. Os nomes de arquivo gerados são hashes curtos de conteúdo em vez de nomes legíveis, porque nomes completos de namespace+caminho ultrapassavam rotineiramente o limite de 80 caracteres do Geyser para caminhos dentro do pack.

Packs legados anteriores à 1.21.4​

Packs que ainda usam o formato antigo assets/minecraft/models/item/*.json + overrides[].predicate.custom_model_data também são detectados e sintetizados na forma moderna de range dispatch. Isso é best-effort: o console informa quantos itens usaram o formato legado, já que eles frequentemente não renderizam corretamente no Bedrock. Migrar o pack de origem para o formato de definição de itens 1.21.4+ é a correção de verdade.

Bundles de entidade Bedrock escritos à mão​

Um plugin pode entregar assets nativos de entidade Bedrock diretamente colocando-os em assets/<namespace>/rspm_bedrock_pack/ dentro do seu pack Java. O RSPM copia esses arquivos literalmente para o pack Bedrock gerado. Apenas diretórios relacionados a entidades são aceitos (entity, models/entity, animations, animation_controllers, render_controllers, materials, textures/entity), de modo que um plugin contribuinte não consiga sobrepor o manifest do pack nem o atlas de ícones. Caminhos longos demais são encurtados automaticamente, com as referências cruzadas de JSON reescritas para corresponder, para que referências de geometria e textura continuem resolvendo. Dois namespaces gravando bytes diferentes no mesmo destino é um erro fatal, e não uma sobrescrita silenciosa.

Esse é o mecanismo por trás das entidades Bedrock verdadeiramente personalizadas — veja Extensão do Geyser e entidades personalizadas. Um pack contendo apenas bundles de entidade e zero mapeamentos de item ainda é entregue.

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.

Os UUIDs de header/módulo do manifest do pack Bedrock são derivados deterministicamente da string de versão do plugin (sementes rspm_bedrock_header:<pluginVersion> e rspm_bedrock_module:<pluginVersion>), de modo que permanecem estáveis entre reconstruções da mesma versão do plugin e só mudam quando a versão do plugin muda. O nome de header visível é o valor fixo ResourcePackManager Bedrock Pack; ele não faz parte do UUID. O trio de versão é incrementado por build a partir de um token cache-bust derivado de um digest de conteúdo SHA-256 do pack Bedrock preparado — conteúdos idênticos produzem a mesma versão (para que reconstruções sem mudanças não afetem o cache do Geyser), enquanto mudanças reais de conteúdo invalidam o cache de pack do Bedrock, que é chaveado por (uuid, version). O tempo de build (System.currentTimeMillis()) só é usado como fallback quando o digest de conteúdo não pode ser computado.

Serviço Ao Vivo Por Sessão (Standalone)​

Quando o Geyser-Spigot é detectado no mesmo backend, o RSPM 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 em itens já existentes.

Os mappings 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.

Como Funciona no Modo Proxy​

Em uma rede com proxy, o próprio backend não registra um subscriber de SessionLoadResourcePacks (não há Geyser local ao qual se inscrever). Em vez disso:

  1. O backend produz output/ResourcePackManager_Bedrock.zip e, quando existem mappings de itens, output/rspm_geyser_mappings.json.
  2. O backend inicia um pequeno servidor HTTP (porta auto-derivada, mcPort + 1 por padrão) expondo as rotas /bedrock.zip e /mappings.json, que leem o arquivo atualizado a cada requisição, e anuncia ao proxy a porta exata em que se vinculou.
  3. O plugin do proxy faz polling a cada 5 segundos, preferindo ETags fortes via If-None-Match e mantendo compatibilidade com If-Modified-Since para backends mais antigos. Ele baixa as saídas de cada backend quando elas mudam e aguarda a caixa de entrada estabilizar.
  4. O plugin do proxy une o pack Bedrock de cada backend em um único pack válido para toda a rede e o serve a clientes Bedrock por meio do Geyser do proxy.
  5. Se o proxy não conseguir alcançar diretamente a porta HTTP de um backend (comum em hospedagem compartilhada/gerenciada, onde portas adjacentes são bloqueadas pelo firewall), o backend faz push de seus arquivos para um endpoint de relay em magmaguy.com e o proxy os busca por lá.

Veja Redes com Proxy para a configuração. A mesclagem do lado do proxy é automática e não tem um interruptor para ativá-la. A config do proxy tem apenas duas configurações: network-http-offset-v2, o offset de porta de fallback usado antes de um anúncio de endpoint do backend estar disponível, e geyser-extension-auto-install, o equivalente do lado do proxy a geyserExtensionAutoInstall.

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  # only when item mappings exist

Se o auto-deploy estiver ativado e uma pasta de dados local do Geyser tiver sido detectada, o arquivo de mappings 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 em vez disso. Se uma versão antiga do RSPM deixou um ResourcePackManager_Bedrock.zip no diretório de packs do Geyser, o plugin atual não o apaga enquanto o Geyser está rodando: o Geyser já escaneou esse caminho e pode ainda tê-lo em memória. O RSPM pula o registro do provider ao vivo naquele boot e imprime o caminho legado exato. Pare o servidor completamente, apague apenas aquele arquivo legado e então inicie o servidor de novo. Um /reload não é suficiente.

Quando o conversor não encontra nada para publicar (nenhum mapping de item convertível e nenhum arquivo de bundle de entidade permitido), o RSPM deleta quaisquer saídas Bedrock obsoletas de uma execução anterior, em vez de entregar um pack vazio. A rota /bedrock.zip do backend então retorna 404 de forma limpa, que é o sinal correto para o proxy de que este backend não tem conteúdo Bedrock a contribuir. Packs contendo apenas entidades continuam sendo publicados.

Configurações em config.yml​

# Toggles Java-to-Bedrock conversion altogether.
bedrockConversionEnabled: true

# Copies the Geyser custom mappings file into the detected Geyser folder's
# custom_mappings/ directory on each mix.
bedrockAutoDeployToGeyser: true

# Manual override for the Geyser data folder. Empty = auto-detect.
# Relative values are tried from the server working directory first, then
# relative to plugins/. Absolute paths work directly.
bedrockGeyserFolder: ""

# Installs and updates the universal ResourcePackManager.jar in Geyser's
# extensions/ folder, which is what makes custom Bedrock ENTITIES render
# instead of armor stands. Separate from pack conversion above — items,
# textures and models convert and serve normally either way.
# Setting this false stops future installation and update staging; it does NOT
# remove an extension jar that is already installed. Delete that by hand while
# Geyser is stopped. See the Geyser extension page.
geyserExtensionAutoInstall: true

# Verbose per-item / per-bone progress logging from the Bedrock pipeline.
# Default false — a clean run emits a single "Bedrock conversion complete: N
# mappings" summary instead of dozens to hundreds of per-item lines. Flip on
# when debugging a specific conversion issue.
bedrockConverterDebug: false

A auto-detecção da pasta do Geyser observa, nesta ordem:

  1. bedrockGeyserFolder se estiver definido (usado exatamente como foi escrito primeiro, de modo que caminhos relativos resolvem a partir do diretório de trabalho do servidor; se esse não existir, é tentado relativo a plugins/). Caminhos absolutos também funcionam.
  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 e 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.

# ===== First-person (right hand, seen by the holder) =====
firstPersonBaseRotationX: -60.0   # pitch (tipping toward/away from camera)
firstPersonBaseRotationY: 123.0   # yaw (spinning around vertical line)
firstPersonBaseRotationZ: 170.0   # roll (around camera-forward axis)
firstPersonBasePositionX: -8.0    # vertical on screen (positive = up)
firstPersonBasePositionY: 7.5     # depth (positive = further into the scene)
firstPersonBasePositionZ: -5.0    # horizontal on screen (positive = right)

# ===== Third-person (right hand, seen by other players / F5) =====
thirdPersonBaseRotationX: 90.0    # pitch as observers see it
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # roll around the item's long axis
thirdPersonBasePositionX: 0.0     # horizontal across the holder's body (positive = outward)
thirdPersonBasePositionY: 6.0     # vertical (positive = raises the model)
thirdPersonBasePositionZ: -10.0   # depth relative to holder (positive = forward)

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

Altere o valor, execute /rspm reload e reconecte o cliente Bedrock de teste para que a próxima entrada dele receba o pack reconstruído. Itere até o item segurado ficar certo.

Log de Debug​

Há duas superfícies de debug disponíveis:

  • Backend: bedrockConverterDebug: true no config.yml ativa as linhas de log por item, por attachable e por mapping do conversor. Útil quando você precisa saber por que um item específico não entrou no pack Bedrock. Isso é separado de verboseLogging, que cobre a mesclagem de packs e a hospedagem em vez do pipeline Bedrock — para um problema de conversão você quer bedrockConverterDebug.
  • Proxy (Velocity e BungeeCord): /rspm debug bedrock on alterna o stream de log [RSPM-BedrockDebug] emitido pelo GeyserBinder do proxy. Útil quando jogadores Bedrock entram no proxy mas não veem o pack. A configuração volta a desligada no restart do proxy, então não pode ser deixada ligada por acidente.

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; atualize o Geyser se sua instalação não conseguir analisá-la.
  • Arquivos legados de override de modelo de item vanilla (qualquer coisa em assets/minecraft/models/item/, incluindo shield.json e crossbow.json) são mesclados entre packs em vez de deixar um pack vencer por completo: apenas os arrays overrides são combinados (deduplicados pela chave de override), enquanto campos que não são de override seguem o critério de maior-prioridade-vence. Nenhum arquivo recebe tratamento especial isolado.
  • Se o conversor não conseguir resolver um arquivo de textura ou modelo referenciado, essa folha é pulada e o restante do pipeline continua. Ative bedrockConverterDebug para traces detalhados de resolução. Um aviso normal é emitido quando um item acaba sem nenhuma textura personalizada válida ou quando um JSON de modelo referenciado não pode ser analisado.
  • Uma definição de item malformada é um caso diferente e agora é fatal para o ciclo: JSON impossível de analisar aborta a conversão inteira com Bedrock conversion failed: ... em vez de produzir silenciosamente um pack parcial. Um pack que antes convertia "quase todo" agora avisa que não converteu.
  • Itens base de banner e redstone são pulados. Itens personalizados cuja base seja um dos 16 banners tingidos ou minecraft:redstone não recebem um mapeamento de item personalizado do Geyser, porque o Geyser deriva desses bases um block-placer inválido. O Bedrock mostra o ícone vanilla para eles. O console nomeia os itens afetados quando isso acontece.
  • A conversão é cancelável de forma cooperativa: um /rspm reload ou um desligamento no meio do processo aborta de forma limpa em vez de deixar uma saída escrita pela metade. O arquivo de mappings do Geyser só é publicado depois que o zip do pack é concluído com sucesso, então você nunca fica com um pack novo pareado com mappings obsoletos.
  • Quando o pack unificado não contém nem mappings de item convertíveis nem arquivos de bundle de entidade permitidos, nenhum pack Bedrock é emitido e qualquer saída de execução anterior é deletada. Um pack contendo apenas entidades continua válido e é emitido mesmo quando há zero mappings de item.

Otimização de Tamanho do Pack​

Antes de publicar um pack Bedrock, o RSPM deduplica arquivos de textura byte a byte idênticos que usam a mesma extensão e reescreve as referências exatas de textura em JSON para o arquivo mantido. Ele deliberadamente mantém aliases quando uma referência é ambígua, está embutida em uma string maior ou aparece em JSON malformado/opaco, de modo que a otimização não quebre silenciosamente referências de recursos.