Pacote de recursos gerado pelo FreeMinecraftModels

O FreeMinecraftModels escreve o pacote gerado na pasta output.

Caminhos de saída predefinidos

O plugin reconstrói esta pasta no arranque e ao executar /fmm reload:

plugins/FreeMinecraftModels/output/FreeMinecraftModels

Depois comprime-a para:

plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

Este é o caminho ZIP que o ResourcePackManager espera ao integrar-se com o FreeMinecraftModels.

A geração elimina tudo o que existe em output, exceto o último FreeMinecraftModels.zip publicado, e depois reconstrói o conteúdo. Guarde os modelos originais e outros ficheiros fora dele. Se o FMM não conseguir limpar a pasta, a geração falha com Failed to prepare output folder e o FMM não conclui a inicialização.

Ficheiros gerados

A geração copia os metadados, o ícone e o atlas incluídos no plugin e acrescenta os modelos e texturas carregados:

• pack.mcmeta
• pack.png
• assets/minecraft/atlases/blocks.json
• Modelos e texturas em assets/freeminecraftmodels/...

Um recurso incluído em falta, ou uma pasta que o FMM não consiga criar, faz falhar a geração. Uma falha ao escrever os ficheiros de um modelo é registada e a geração continua, por isso consulte a consola além da saída. Antes de criar o ZIP, o FMM acrescenta entradas explícitas no atlas para as suas texturas de entidades, incluindo as texturas de partículas, e substitui a sua fonte de atlas baseada no diretório de entidades. As outras fontes são preservadas. Um erro de leitura ou escrita do atlas faz falhar a geração.

O FreeMinecraftModels gera definições de modelos de itens em:

assets/freeminecraftmodels/items

O código ainda contém a substituição antiga baseada em armadura de couro para cavalo, destinada a servidores anteriores à versão 1.21.4. Contudo, o plugin declara api-version: 1.21.4, pelo que nenhum servidor capaz de o carregar executa esse ramo.

Modelos de apresentação (1.21.4+)

Quando um modelo tem um ficheiro .json de apresentação válido na mesma pasta, o FMM processa o seu mapa textures e escreve-o no destino abaixo. Consulte Notas sobre criação de modelos.

assets/freeminecraftmodels/models/display/{modelId}.json

Também é gerada uma definição de item correspondente em:

assets/freeminecraftmodels/items/display/{modelId}.json

Os valores de textura com espaço de nomes permanecem iguais. Os restantes são resolvidos pelo índice numérico da textura, usando uma textura extraída disponível como alternativa. Um JSON de apresentação malformado produz um aviso e não é registado. O registo permite ao FMM atribuir o modelo processado ao aspeto de um item na mão e no inventário.

Sprites de partículas

Para cada efeito de partículas usado por um modelo, o FMM escreve a textura do efeito e um modelo de item plano por sprite:

assets/freeminecraftmodels/textures/entity/fmm_particles/{modelId}/{effect}.png
assets/freeminecraftmodels/models/particle/{modelId}/{effect}/{index}.json
assets/freeminecraftmodels/items/particle/{modelId}/{effect}/{index}.json

Só os jogadores Java veem estes sprites. Os jogadores Bedrock recebem o efeito como uma partícula nativa, a partir do conjunto Bedrock descrito abaixo.

Ficheiros auxiliares do ResourcePackManager

O FMM escreve pequenos ficheiros JSON que o ResourcePackManager lê enquanto converte o pacote para Bedrock. Não têm qualquer efeito nos clientes Java.

Ficheiro	Escrito quando	Finalidade
assets/freeminecraftmodels/rspm_item_bases/display/{modelId}.json	O modelo tem um modelo de apresentação e o seu .yml complementar define um material que o servidor conhece. Um sufixo de tinta de couro, como LEATHER_CHESTPLATE:ff8800, faz com que o ficheiro não seja escrito	Indica o item normal em que o item personalizado se baseia, como minecraft:blaze_rod, para que o Bedrock apresente o modelo sobre o item base correto, em vez de um deduzido a partir do nome do ficheiro
assets/freeminecraftmodels/rspm_item_particles/display/{modelId}.json	O modelo tem um modelo de apresentação e uma animação com fotogramas-chave de partículas	Lista os efeitos, os localizadores e a linha temporal de partículas em ciclo que o ResourcePackManager acrescenta ao attachable Bedrock do item
assets/freeminecraftmodels/rspm_item_java_only/particle/{modelId}/{effect}.json	O modelo usa um efeito de partículas	Indica ao ResourcePackManager que não deve transformar os itens de sprite desse efeito em itens personalizados Bedrock

Enquanto particleEffectsEnabled estiver a false, o FMM não escreve os ficheiros rspm_item_particles nem os ficheiros de partículas Bedrock. Os sprites de partículas Java e os respetivos ficheiros rspm_item_java_only continuam a ser escritos.

Conjunto de entidades personalizadas Bedrock

Além dos recursos Java, o FreeMinecraftModels tenta exportar um conjunto de entidades personalizadas Bedrock para cada modelo carregado com texturas para:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/rspm_bedrock_pack

Cada modelo fornece texturas, geometria, controlador de renderização, animações, controladores de animação e definição de entidade. Todos usam o espaço de nomes freeminecraftmodels:, no formato freeminecraftmodels:<model_id>. Um modelo com efeitos de partículas fornece também particles/<model_id>_<effect>.json (identificador fmm:<model_id>_<effect>) e, quando o FMM encontrou a textura do efeito, textures/entity/fmm_particles/<model_id>/<effect>.png. Consulte Partículas.

Ao criar modelos, tenha em conta que:

• Um modelo sem texturas é ignorado, com a mensagem Skipping Bedrock custom entity export for <id>: model has no textures. na consola.
• O importador Java continua a aceitar essa definição sem texturas. A exclusão aplica-se apenas à entrada no conjunto de entidades personalizadas Bedrock.
• A geometria Bedrock exclui ossos de pontos de montada (m_), ossos de etiquetas de nome gerados (fmm_nametag_bone_*) e hitbox. As âncoras tag_ criadas pelo autor permanecem na geometria, muitas vezes sem cubos.
• Um modelo sem animações continua a exportar uma única entrada de animação idle.
• A geometria de um modelo pende de um osso freeminecraftmodels_lean gerado, a menos que o modelo tenha mais de 672 animações. O osso mostra aos jogadores Bedrock a orientação de deslocação e o centramento. Os canais de animação com fotogramas-chave MoLang são escritos tal como foram criados, pelo que os clientes Bedrock os avaliam.
• A largura e altura da hitbox da entidade Bedrock vêm do osso hitbox do modelo. Sem esse osso, são usados 1.0 x 2.0.

Um grupo hitbox vazio tem dimensões zero; não usa esses valores alternativos. O prefixo b_ oculta a renderização Java, mas não é filtrado da geometria Bedrock. A exportação de animações Bedrock não incorpora a solução de IK calculada pelo FMM durante a execução; consulte Animações. Os erros de exportação são registados e podem deixar ficheiros incompletos.

O componente de execução Bedrock exige um plugin ativo chamado floodgate, Geyser-Spigot ou Geyser. Esta verificação ignora maiúsculas e minúsculas. A deteção individual de jogadores verifica separadamente o Floodgate ou Geyser-Spigot; ativar o componente não comprova a deteção de jogadores nem a entrega do pacote. Num servidor apenas Java, o FMM exporta os ficheiros sem criar nem executar esse componente.

Definições condicionais de arcos e bestas

Quando o FMM deteta um conjunto completo de modelos de estado de arco ou besta carregados com os respetivos JSON de apresentação registados, gera uma definição de item com o ID base do modelo. Esta alterna entre estados no cliente. O item configurado deve usar o material BOW ou CROSSBOW correspondente. Consulte Notas sobre criação de modelos.

Arcos

Para arcos, a definição usa minecraft:condition sobre using_item e minecraft:range_dispatch sobre use_duration, com escala 0.05:

Condição	Modelo usado
Item sem estar em uso	_idle
Em uso, estado inicial	_draw_start
Em uso, limiar 0.65	_draw_half
Em uso, limiar 0.9	_draw_full

Bestas

Para bestas, a definição usa minecraft:select sobre charge_type. Quando carregada com uma flecha ou foguete, apresenta _charged. O estado descarregado usa minecraft:range_dispatch sobre crossbow/pull:

Condição	Modelo usado
Sem estar em uso e descarregada	_idle
Em uso, estado inicial	_draw_start
Em uso, limiar 0.58	_draw_half
Em uso, limiar 1.0	_draw_full
Carregada com flecha ou foguete	_charged

Localização dos ficheiros

A definição condicional é escrita junto das restantes definições de itens em:

assets/freeminecraftmodels/items/display/{baseModelId}.json

O ID base passa a ser o item de apresentação público. As definições de item dos estados individuais são removidas da saída e do registo; a geometria de apresentação mantém-se porque a definição condicional a referencia.

Correções de compatibilidade com Minecraft 26.1+

O gerador aplica estas correções em todas as versões suportadas, incluindo Minecraft 26.1 e posteriores:

• Limitação de coordenadas UV: as UV das faces são limitadas aos limites UV da textura (0–textureWidth / 0–textureHeight), antes da conversão para o espaço UV 16x16 do Minecraft. Estes limites usam os metadados UV da textura quando existem; caso contrário, usam as dimensões da imagem ou a resolução alternativa do modelo. Limitar coordenadas negativas ou excessivas pode reduzir o detalhe da textura na face afetada.
• Exclusão de ossos vazios ou usados apenas como âncoras: um osso sem cubos não gera JSON de geometria. Gerar uma definição de modelo de item para ele deixaria uma referência sem destino. A versão 1.21.x tolerava isso sem aviso; a 26.1+ regista cada caso como Missing block model: freeminecraftmodels:.... O gerador omite agora tanto a geometria como a definição de item desses ossos. Isto abrange ossos hitbox, usados apenas para colisão, âncoras posicionais tag_name, variantes automáticas fmm_nametag_bone_* e ossos usados apenas para agrupar ou ancorar.

As correções são automáticas e não exigem configuração.

nota

Uma âncora tag_ de etiqueta de nome não precisa de cubos. Âncoras sem cubos não geram geometria; o prefixo, por si só, não oculta todos os ossos criados com cubos. O osso com o nome exato tag_name recebe tratamento especial. Consulte Âncoras de etiquetas de nome.

Saída determinística

O FMM reduz alterações desnecessárias usando mapas que preservam a ordem de inserção nas definições de itens por osso e nos blocos display dos modelos. O código de escrita ZIP também fixa as datas das entradas.

Não são garantidos bytes ZIP idênticos: o código percorre os diretórios pela ordem do sistema de ficheiros, sem ordenar as entradas. Alterações a modelos, texturas, JSON de apresentação, configuração ou versões do gerador e servidor também podem alterar legitimamente o pacote.

Se o hash mudar inesperadamente, compare o conteúdo e a ordem das entradas do arquivo, além dos dados usados na geração. Uma descarga repetida, por si só, não identifica a causa.

Comportamento do recarregamento

Com /fmm reload, o FMM começa por importar conteúdo e preparar os catálogos candidatos de itens, encantamentos e receitas enquanto a execução atual permanece ativa. Se essa preparação falhar, rejeita o recarregamento e mantém o catálogo atual. Após uma preparação bem-sucedida:

• Remove os modelos ativos, elementos decorativos, disfarces, ambientes de scripts, estado dos listeners e registos de tempos de recarga dos scripts, antes de os reconstruir.
• Recarrega a configuração e as receitas.
• Reconstrói a pasta output/FreeMinecraftModels.
• Regenera output/FreeMinecraftModels.zip.
• Executa resourcepackmanager reload se o ResourcePackManager estiver ativo.
• Agenda FmmReloadedEvent na thread principal para 40 ticks depois, permitindo que os plugins dependentes recriem as ligações aos modelos.

O FMM escreve primeiro o arquivo em output/FreeMinecraftModels.zip.pending e depois move-o para o lugar de FreeMinecraftModels.zip. Se a escrita ou a mudança falharem, a geração falha e o ZIP anterior mantém-se. Um ZIP completo não prova a entrega, por isso confirme também a entrega pelo ResourcePackManager e a aceitação no cliente. Consulte Configuração para distinguir um recarregamento completo de uma atualização do conteúdo importado.