Conversão de Java para Bedrock

O ResourcePackManager pode converter o pacote de recursos Java combinado num pacote Bedrock, permitindo aos clientes GeyserMC ver o conteúdo personalizado suportado. A conversão está ativa por predefinição.

Quando é executada a conversão

A conversão exige a presença de um destino Bedrock. Basta uma destas condições:

1. Geyser-Spigot instalado neste backend, recebendo os jogadores Bedrock localmente.
2. Floodgate instalado neste backend, como numa configuração com Floodgate local e Geyser noutro processo.
3. Modo de rede ativo: o RSPM detetou um proxy Velocity ou BungeeCord. O backend produz o pacote Bedrock e disponibiliza-o por HTTP para o plugin do proxy o obter.

A conversão também deve estar ativa com bedrockConversionEnabled. Se estiver desativada ou não houver um destino, o RSPM retira qualquer resultado Bedrock anterior e ignora a conversão. /rspm status indica por que motivo o pacote não foi gerado.

Recursos convertidos

O conversor percorre recursivamente todos os ficheiros assets/<namespace>/items/**/*.json no formato de definição de objetos 1.21.4 ou posterior, incluindo o espaço de nomes minecraft.

Seleção da conversão plana ou 3D

Para cada modelo final, o conversor escolhe um de dois processos. Os modelos cuja origem é minecraft:item/generated ou minecraft:builtin/generated mantêm-se planos. Nas restantes cadeias de modelos ascendentes, só usa 3D se o modelo combinado tiver um array elements não vazio. Sem geometria, o modelo é uma imagem 2D.

• Plano: copia a textura layer0 para textures/items/<hash>.png e regista-a como ícone Geyser. O Bedrock usa essa camada como imagem 2D no inventário e na mão. Isto não preserva automaticamente outras camadas ou ramos do modelo Java.
• 3D: combina as texturas num atlas, converte os cuboides Java em geometria Bedrock, gera animações para a mão e cabeça, renderiza por software um ícone de inventário 64×64 e escreve um elemento equipável por combinação de modelo, objeto base, definição de objeto e forma do predicado.

Uma ferramenta plana com modelo ascendente minecraft:item/handheld, apenas layer0 e sem elementos continua a ser 2D. As versões anteriores enviavam estes objetos para o processo 3D, onde falhavam na geometria e desapareciam ou mostravam o ícone normal do objeto base. Isto afetava especialmente os muitos objetos planos do ItemsAdder. Como elements é lido da cadeia de modelos já combinada, um modelo que herde geometria de outro continua a usar 3D, desde que não tenha origem num modelo gerado.

O RSPM deriva um identificador Bedrock para cada combinação de modelo, objeto base, definição de objeto e forma do predicado. Isto separa as variantes de objeto base e predicado de um modelo de espada e mantém em identificadores separados duas definições de objeto que reutilizem o mesmo modelo. Os nomes dos ficheiros usam hashes curtos dos identificadores de origem, não do conteúdo dos ficheiros, para evitar o aviso do Geyser sobre caminhos com 80 ou mais caracteres.

Ramos de modelos de objetos suportados

A conversão suporta os nós model, condition, range_dispatch e select, com ou sem o prefixo minecraft:. Os restantes, incluindo composite e special, são ignorados. Um pacote que funciona em Java não garante que todos os ramos possam ser representados em Bedrock.

Nó	Propriedades suportadas e alternativas
condition	broken, damaged, fishing_rod_cast, has_component, custom_model_data. using_item conserva apenas on_false como modelo em repouso. As restantes condições não suportadas ignoram ambos os ramos.
range_dispatch	damage, count, bundle_fullness, custom_model_data. use_duration e outras propriedades não suportadas conservam apenas fallback, se existir.
select	charge_type, trim_material, context_dimension, custom_model_data. display_context conserva o caso gui, ou a alternativa se não existir esse caso. As restantes propriedades não suportadas conservam apenas a alternativa.

As etapas de puxar um arco e os modelos diferentes por contexto não são, portanto, preservados automaticamente. Ative bedrockConverterDebug para consultar os nós e propriedades ignorados e verifique o resultado num cliente Bedrock.

Pacotes antigos, anteriores à versão 1.21.4

O leitor do formato antigo lê os ficheiros JSON diretamente em assets/minecraft/models/item/ e cria definições por intervalos a partir de substituições com um predicate.custom_model_data numérico. Não percorre as subpastas antigas nem preserva os restantes predicados da substituição. Por exemplo, uma substituição que também dependa do estado de tensão de um arco perde essa condição. A contagem de objetos antigos só aparece com bedrockConverterDebug ativo. Use o formato de definição de objetos 1.21.4 ou posterior nos pacotes que mantém e compare os seus ramos com a tabela de suporte acima.

Objetos base

O Geyser mapeia cada objeto personalizado sob um ou mais objetos base Java. O RSPM escolhe-os da seguinte forma:

• Um ficheiro de substituição antigo e uma definição na raiz assets/minecraft/items/<item>.json são mapeados para esse objeto normal.
• As restantes definições são associadas pelo nome do ficheiro. As palavras de armas e ferramentas correspondem a objetos normais relacionados: sword às seis espadas, pickaxe às seis picaretas, wand ou staff a minecraft:stick, spear a minecraft:trident, e assim por diante. Os nomes de armaduras usam o ficheiro de equipamento do espaço de nomes ou palavras de ranhura como helmet e boots. Tudo o resto usa um conjunto alternativo: papel, pau, etiqueta de nome, bússola e as seis espadas.
• As definições no espaço de nomes freeminecraftmodels também são mapeadas sob minecraft:leather_horse_armor, o objeto que o FreeMinecraftModels usa para apresentar os ossos dos modelos.
• Um plugin produtor pode declarar os verdadeiros objetos base em assets/<namespace>/rspm_item_bases/<path>.json, em que <path> corresponde a items/<path>.json. O ficheiro contém {"base_items": ["minecraft:blaze_rod"]}. Só são lidos IDs minecraft:, que são acrescentados à escolha feita pelo nome do ficheiro. O FreeMinecraftModels escreve um destes ficheiros para cada objeto personalizado com o material indicado na sua configuração, pelo que uma varinha sobre BLAZE_ROD apresenta o seu modelo no Bedrock.

Objetos apenas Java

Um plugin produtor pode excluir objetos da conversão colocando um ficheiro em assets/<namespace>/rspm_item_java_only/<path>.json. Só importa a presença do ficheiro. Exclui items/<path>.json e todas as definições de objetos em items/<path>/, pelo que esses objetos não recebem mapeamento Geyser, ícone nem elemento equipável. O FreeMinecraftModels usa-o para os objetos de sprite por trás dos seus efeitos de partículas, que apenas as entidades de apresentação de objetos do Java usam; os jogadores Bedrock veem a partícula nativa. Um pacote cujos objetos sejam todos apenas Java não desencadeia o aviso de formato antigo.

Conjuntos de entidades Bedrock criados manualmente

Um plugin pode incluir recursos nativos de entidades Bedrock em assets/<namespace>/rspm_bedrock_pack/ dentro do pacote Java. O RSPM importa-os para o pacote Bedrock gerado. Só aceita pastas relacionadas com entidades: entity, models/entity, animations, animation_controllers, render_controllers, materials, particles e textures/entity. Isto impede substituir o manifesto ou o atlas de ícones. Os caminhos suportados com 80 ou mais caracteres são abreviados e as referências JSON exatas a esses caminhos, dentro do mesmo conjunto, são atualizadas. Os restantes ficheiros são copiados tal como fornecidos. Se dois espaços de nomes produzirem bytes diferentes no mesmo destino, a importação falha.

Este é o mecanismo das entidades Bedrock personalizadas, descrito em Extensão do Geyser e entidades personalizadas. Um pacote que contenha apenas entidades, sem mapeamentos de objetos, continua a ser disponibilizado.

A conversão da armadura vestida ocorre no processo de objetos planos quando o objeto base é uma armadura ou élitros. Obtém <material> do nome do ficheiro de definição do objeto, removendo um sufixo de ranhura reconhecido, e procura assets/<namespace>/equipment/<material>.json no espaço de nomes do modelo final. Usa a primeira camada de textura de humanoid, de humanoid_leggings para calças ou de wings para élitros, se existir. O PNG correspondente deve estar no pacote combinado. O elemento equipável gerado usa a geometria normal de armadura do Bedrock. Um ficheiro de equipamento isolado, camadas de textura adicionais ou um ID de recurso de equipamento sem relação não garantem a conversão da armadura.

Os UUIDs do cabeçalho e módulo do manifesto Bedrock são calculados deterministicamente a partir da versão do plugin, usando as sementes rspm_bedrock_header:<pluginVersion> e rspm_bedrock_module:<pluginVersion>. Mantêm-se entre reconstruções da mesma versão e só mudam quando muda a versão do plugin. O nome visível é sempre ResourcePackManager Bedrock Pack e não participa no UUID. A versão de três números é calculada por construção a partir de um identificador de invalidação de cache derivado do resumo SHA-256 do conteúdo preparado. Conteúdos idênticos produzem a mesma versão; alterações reais invalidam a cache Bedrock indexada por (uuid, version). A hora da construção, System.currentTimeMillis(), só é usada se não for possível calcular o resumo do conteúdo.

Entrega por sessão num servidor independente

Com a conversão ativa e Geyser-Spigot no mesmo backend independente, o RSPM subscreve SessionLoadResourcePacksEvent. Oferece o último pacote Bedrock autorizado a cada jogador que entra, diretamente do disco. Alterações de textura ou geometria podem chegar na ligação seguinte sem reiniciar o servidor, desde que os mapeamentos registados não mudem. Os backends em modo de rede deixam a entrega ao proxy, mesmo que Geyser-Spigot também esteja instalado localmente.

Os mapeamentos de objetos personalizados do Geyser, o JSON em custom_mappings/, ficam fixados no arranque. Acrescentar ou remover objetos, mudar uma referência de modelo ou alterar predicados pode exigir novos mapeamentos e, portanto, um reinício. Com a instalação automática ativa, o RSPM coloca o último ficheiro de mapeamentos autorizado no início do arranque. Depois da primeira conversão bem-sucedida, reinicie o Geyser para carregar os novos mapeamentos e volte a ligar o cliente Bedrock.

Os jogadores Bedrock já ligados mantêm o pacote recebido à entrada. É uma restrição do protocolo Bedrock que o plugin não pode alterar a meio da sessão.

Funcionamento em modo de proxy

Numa rede, o backend não subscreve SessionLoadResourcePacks, pois não tem Geyser local. O processo é:

1. O backend produz output/ResourcePackManager_Bedrock.zip e, se houver mapeamentos de objetos, output/rspm_geyser_mappings.json.
2. Inicia um servidor HTTP numa porta calculada, mcPort + 1 por predefinição. As rotas /bedrock.zip e /mappings.json leem os ficheiros em cada pedido. O backend anuncia ao proxy a porta real em uso.
3. O proxy consulta a cada 5 segundos, preferindo ETags fortes com If-None-Match e mantendo If-Modified-Since para backends antigos. Transfere os resultados alterados e espera que a pasta de entrada estabilize.
4. Combina os pacotes Bedrock de todos os backends num pacote de rede, entregue através do Geyser do proxy.
5. Se não conseguir alcançar diretamente a porta HTTP, como pode acontecer em alojamentos que bloqueiam portas adjacentes, o backend envia os ficheiros para um serviço de retransmissão em magmaguy.com, de onde o proxy os obtém.

Consulte Redes com proxy. A combinação no proxy é automática e não tem opção de ativação. A configuração tem apenas network-http-offset-v2, o desvio usado antes de receber o anúncio do backend, e geyser-extension-auto-install, equivalente a geyserExtensionAutoInstall no proxy.

Ficheiros de saída

Após uma combinação bem-sucedida:

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json  # only when item mappings exist

Se a instalação automática dos mapeamentos estiver ativa e for detetada uma pasta Geyser local, o ficheiro também é copiado para:

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

O ZIP Bedrock não é copiado para <geyser-folder>/packs/: é entregue por sessão. Se uma versão antiga deixou ResourcePackManager_Bedrock.zip nessa pasta, o plugin atual não o apaga enquanto o Geyser estiver em execução, pois este já pode tê-lo carregado em memória. Nesse arranque, o RSPM não regista o fornecedor por sessão e apresenta o caminho antigo exato. Pare completamente o servidor, apague apenas esse ficheiro antigo e volte a iniciar. /reload não basta.

Sem mapeamentos convertíveis nem ficheiros de entidades permitidos, o RSPM retira a publicação e tenta apagar os resultados locais anteriores e o seu mapeamento instalado no Geyser. Um ficheiro bloqueado que permaneça no disco não continua autorizado para entrega. A rota /bedrock.zip devolve 404 para indicar que o backend não contribui conteúdo Bedrock. Os pacotes apenas de entidades continuam a ser publicados. Simples substituições de texturas de blocos Java ou de texturas normais não produzem um pacote convertido; precisam de um pacote Bedrock criado separadamente.

Desativar bedrockAutoDeployToGeyser remove o mapeamento anteriormente instalado pelo RSPM durante a reconciliação. Alterar bedrockGeyserFolder também limpa o destino anterior gerido pelo RSPM. Nenhuma destas ações muda os mapeamentos já carregados numa instância Geyser em execução. Reinicie o Geyser para aplicar o novo conjunto.

Definições de 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 deteção da pasta Geyser segue esta ordem:

1. bedrockGeyserFolder, se definido. Primeiro usa o valor tal como escrito, resolvendo caminhos relativos a partir da pasta de trabalho do servidor. Se não existir, tenta relativamente a plugins/. Os caminhos absolutos também funcionam.
2. plugins/Geyser-Spigot/.
3. plugins/Geyser-*/, qualquer variante.
4. config/Geyser-*/, para instalações Fabric/NeoForge.

Poses dos objetos na mão

Cada elemento equipável 3D recebe animações de primeira pessoa, terceira pessoa e cabeça. As poses na mão vêm das transformações display.firstperson_righthand e display.thirdperson_righthand do modelo Java. O RSPM converte cada transformação através do esqueleto normal do jogador Bedrock, pelo que o modelo na mão fica onde o Java o desenha, com a mesma posição, orientação e escala por eixo. Uma posição que o modelo não define usa a transformação identidade do Java. A animação da cabeça vem de display.head.

Não há nada a ajustar. Para mudar a forma como um objeto fica na mão, altere as transformações display do modelo Java; o Java e o Bedrock seguem então os mesmos valores. O esqueleto usa o braço largo (Steve), pelo que, com skins de braços finos, o Bedrock pode diferir do Java em meio píxel.

As versões anteriores acrescentavam desvios ajustados manualmente a partir de plugins/ResourcePackManager/bedrock_display_offsets.yml. Esse ficheiro e as suas definições firstPerson* e thirdPerson* já não são lidos, e o RSPM regenera os pacotes Bedrock em cache após a atualização. Pode eliminar uma cópia antiga do ficheiro.

Partículas de objetos na mão

Um plugin produtor pode associar partículas a um objeto 3D na mão com um ficheiro auxiliar em assets/<namespace>/rspm_item_particles/<model path>.json, em que <model path> é o caminho do modelo Java na mão (display/wand para freeminecraftmodels:display/wand). O ficheiro auxiliar associa nomes de efeitos a identificadores de partículas que o plugin inclui no seu conjunto de entidades, lista localizadores em píxeis do modelo Java e contém uma linha temporal de partículas em ciclo. O RSPM acrescenta os localizadores à geometria do objeto e reproduz a linha temporal como animação adicional do elemento equipável, para que os clientes Bedrock desenhem as partículas na mão em primeira e terceira pessoa. O FreeMinecraftModels escreve estes ficheiros auxiliares para objetos com efeitos de partículas. Um ficheiro auxiliar ilegível é ignorado com um aviso.

Registo de depuração

Existem duas opções:

• Backend: bedrockConverterDebug: true em config.yml ativa registos por objeto, elemento equipável e mapeamento. Ajuda a perceber por que motivo um objeto não foi incluído. É independente de verboseLogging, que cobre a combinação e o alojamento. Para problemas de conversão, use bedrockConverterDebug.
• Proxy Velocity ou BungeeCord: /rspm debug bedrock on ativa o registo [RSPM-BedrockDebug] do GeyserBinder. Ajuda quando o jogador entra no proxy mas não recebe o pacote. A opção é desativada ao reiniciar o proxy.

Limitações e comportamentos conhecidos

• Os ícones 3D são renderizados por software a partir de display.gui. O resultado é aproximado, não uma reprodução exata de cada píxel. Uma textura ausente ou com nome incorreto é uma causa comum de ícones errados.
• As texturas animadas usadas como ícones são reduzidas ao fotograma 0. item_texture.json não suporta ícones animados; as animações de blocos e terreno usam flipbook_textures.json.
• A versão do formato de geometria dos elementos equipáveis é 1.21.0. Atualize o Geyser se não conseguir lê-la.
• Os ficheiros antigos de substituição de modelos em assets/minecraft/models/item/, incluindo shield.json e crossbow.json, são combinados entre pacotes. Só os arrays overrides são combinados e deduplicados por chave; os restantes campos usam o valor do pacote de maior prioridade. Nenhum ficheiro tem tratamento especial.
• Se uma textura ou modelo referido não puder ser encontrado, esse modelo final é ignorado e o processo continua. Ative bedrockConverterDebug para acompanhar a resolução. É emitido um aviso normal quando um objeto fica sem texturas personalizadas válidas ou um JSON de modelo referido não pode ser analisado.
• Um JSON de definição de objeto impossível de analisar termina a conversão com Bedrock conversion failed: .... Um JSON válido sem modelo ou com um nó não suportado pode, em vez disso, ser ignorado com uma mensagem de depuração. Consulte o erro e a contagem de mapeamentos resultante; nem todas as definições ignoradas correspondem a um erro fatal de análise.
• As bases de estandartes e redstone são ignoradas. Objetos personalizados baseados nos dezasseis estandartes coloridos ou em minecraft:redstone não recebem mapeamento personalizado, porque o Geyser deriva dessas bases um colocador de blocos inválido. Em Bedrock aparece o ícone normal. A consola identifica os objetos afetados.
• A conversão admite cancelamento cooperativo. O RSPM prepara o ZIP e os mapeamentos e substitui a publicação como um conjunto. Uma falha ou cancelamento durante a substituição tenta restaurar o conjunto anterior; uma falha de conversão anterior à substituição retira os resultados antigos. Os hashes publicados e os metadados do conjunto permitem rejeitar gerações antigas ou misturadas. A existência de um ZIP no disco não prova que esteja autorizado nem que um cliente Bedrock o tenha apresentado.
• Sem mapeamentos convertíveis nem ficheiros de entidades permitidos, o RSPM retira a publicação anterior e tenta apagar os resultados. Um pacote apenas de entidades é emitido mesmo com zero mapeamentos de objetos.

Otimização do tamanho do pacote

Antes de publicar, o RSPM elimina texturas duplicadas byte a byte que tenham a mesma extensão e atualiza as referências JSON exatas para o ficheiro mantido. Preserva os nomes alternativos quando uma referência é ambígua, faz parte de um texto maior ou aparece em JSON mal formado ou opaco, evitando quebrar silenciosamente as referências dos recursos.