Notas sobre criação de modelos do FreeMinecraftModels

Estas notas descrevem os ficheiros de modelo, os ficheiros complementares e os nomes que o FreeMinecraftModels lê durante a importação e a execução.

Formatos de origem

O FreeMinecraftModels aceita:

• Ficheiros .bbmodel, para importar modelos de origem editáveis.
• Ficheiros .fmmodel, com dados de modelo simplificados e preparados para execução.

Para um .bbmodel solto sem ficheiros complementares:

1. Coloque-o diretamente em plugins/FreeMinecraftModels/imports, com a extensão .bbmodel em minúsculas.
2. Execute /fmm reload.
3. Verifique se a conversão .fmmodel aparece na pasta de modelos ativa e se o recarregamento termina com sucesso.

O importador de ficheiros soltos deixa o original em imports, pelo que as importações seguintes voltam a convertê-lo. Não recolhe complementos .json ou .yml soltos nem aceita um .fmmodel solto. Para conjuntos de modelos criados por si, mantenha os modelos e os complementos juntos na pasta models ativa ou use um pacote de conteúdo com a estrutura correta. Uma subpasta qualquer de imports sem pack.meta é ignorada. Um recarregamento rejeitado pode deixar o catálogo anterior ativo; consulte a consola.

A conversão de ficheiros soltos conserva apenas source, id e name das texturas, descartando os metadados de dimensões e tempos de animação. Também exige um vetor textures. Quando esses metadados forem necessários, use a pasta de modelos ativa ou um pacote que preserve o ficheiro original; o leitor de modelos durante a execução aceita a ausência do vetor de texturas.

Funções das pastas

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports recebe as importações manuais e os pacotes oficiais descarregados antes do processamento.
• models contém os modelos instalados ativos.
• models_disabled contém conteúdo de pacotes descarregados ou instalados que está desativado.

As instalações antigas podem ter uma pasta Models, com maiúscula. Durante a execução, o FreeMinecraftModels prefere models quando existe e usa Models caso contrário. Num sistema de ficheiros que não distingue maiúsculas de minúsculas, os dois nomes identificam o mesmo diretório. Nos restantes, podem coexistir: o importador partilhado de pacotes prefere atualmente um destino Models existente, enquanto o plugin lê models. Com o servidor parado, faça uma cópia de segurança e reúna o conteúdo em models, para impedir que as importações fiquem fora da pasta ativa.

IDs dos modelos

• Os IDs usados durante a execução vêm do nome do ficheiro, sem a extensão .bbmodel ou .fmmodel.
• Use nomes estáveis e únicos: os comandos e chamadas da API procuram modelos pelo ID.
• As referências de animação do Blockbench usam nomes. Nomes duplicados ou ambíguos dentro do modelo podem causar problemas; prefira nomes claros e distintos.
• A verificação de extensões na pasta de modelos ativa ignora maiúsculas e minúsculas, aceitando .BBModel e .FMModel. A importação de ficheiros soltos de imports só reconhece .bbmodel em minúsculas.

Normalização de IDs e colisões

O nome do ficheiro é normalizado antes de se tornar o ID do modelo e o nome do ficheiro no pacote de recursos:

1. É convertido para minúsculas.
2. Os caracteres que não pertençam a a-z, 0-9, ., _ e - são substituídos por _.

Assim, My Table.bbmodel, my table.bbmodel e my_table.bbmodel produzem todos o ID my_table.

Antes de converter, o FreeMinecraftModels percorre toda a árvore de modelos à procura de ficheiros com o mesmo ID normalizado. Quando todos os ficheiros com esse ID são idênticos byte a byte, como acontece quando dois pacotes de conteúdo incluem o mesmo modelo, o FMM carrega aquele cujo caminho absoluto surge primeiro na ordenação e ignora as cópias sem aviso. Quando os ficheiros diferem:

• Rejeita todos os ficheiros envolvidos. Nenhum é carregado, evitando que um substitua outro silenciosamente.
• Bloqueia o ID durante o resto desse carregamento.
• Exclui esses modelos da exportação de entidades personalizadas Bedrock.
• Regista na consola:

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

Renomeie os ficheiros para que os IDs normalizados sejam distintos. Usar minúsculas e sublinhados desde o início, como em stone_table.bbmodel, torna o nome do ficheiro igual ao ID e evita colisões inesperadas de normalização.

Compatibilidade com Blockbench

• O FreeMinecraftModels lê meta.format_version do .bbmodel e escolhe o processamento pelo número principal da versão.
• Se faltar meta, faltar format_version ou o valor não puder ser interpretado, assume a versão 4 e regista uma mensagem informativa ou aviso com o nome do modelo.
• A ausência do vetor textures é aceite como uma lista vazia, sem falhar a importação. O exportador de entidades personalizadas Bedrock ignora depois esse modelo, pois exige pelo menos uma textura.
• Os nomes das texturas extraídas são normalizados para uma única extensão .png. body.jpg, body.PNG e body são escritos e referenciados como body.png.
• Com format_version 4.x ou anterior, os ossos são lidos diretamente da árvore outliner, que contém os respetivos nomes.
• Com format_version 5.x ou posterior, outliner é uma árvore de cadeias UUID e dicionários {uuid, isOpen, children}, sem chave de nome. Um vetor separado groups contém os dados dos ossos, incluindo name. O FMM cruza ambos por UUID, substitui cada nó pela entrada correspondente de groups e reúne os filhos recursivamente. Desta forma, recupera os nomes, origens e rotações.
• Ao editar ou gerar ficheiros .bbmodel, tenha em conta estas consequências:
  • Um ficheiro v5 sem groups é passado adiante sem junção. Um outliner já unido pode funcionar; nós de grupos v5 sem nome podem fazer falhar o carregamento quando o leitor do esqueleto espera um nome.
  • Os UUID devem corresponder exatamente entre outliner e groups. Um nó sem grupo correspondente é mantido tal como está.
  • Não combine uma declaração v5 com um outliner v4, nem o contrário. O processamento depende da versão declarada, não da forma dos dados.
• Se o registo de importação indicar um formato incompatível com FreeMinecraftModels, investigue primeiro o formato do modelo.

Convenções de ossos com efeito na execução

O conversor e o sistema de esqueletos reconhecem estas convenções:

• hitbox
  • Reservado à geração da hitbox.
  • Deve definir a colisão do modelo, sem ser usado como osso visual.
  • Tem de ser um osso no nível raiz do outliner para definir a colisão durante a execução. Um hitbox aninhado passa pela leitura normal dos ossos, mas permanece oculto e não define a hitbox do modelo.
  • Deve conter exatamente um cubo, que define largura X, profundidade Z e altura Y. Cubos adicionais geram has more than one value defining a hitbox! Only the first cube will be used. Um grupo vazio gera has a hitbox bone but no hitbox cube! e deixa dimensões zero; não equivale à ausência de hitbox. Os deslocamentos e rotações do cubo não se tornam um deslocamento da hitbox: o leitor usa os comprimentos absolutos dos lados e um deslocamento de modelo zero.
  • Nunca é animado nem apresentado e é excluído da geometria Bedrock. As pistas dirigidas a hitbox são ignoradas. Em Bedrock, a ausência deste osso usa as dimensões 1.0 x 2.0.
• tag_...
  • Âncora opcional criada pelo autor para a etiqueta de nome. Consulte Posição da etiqueta de nome.
• h_...
  • Identifica ossos da cabeça.
• b_...
  • Ossos sem apresentação no componente Java. Use ossos sem cubos para a estrutura: a exportação de geometria Bedrock não filtra o prefixo b_, pelo que os cubos nesses ossos podem continuar visíveis aí.
• m_...
  • Pontos de montada. Cada osso com este prefixo cria um assento para um jogador, gerido por MountPointManager. Vários ossos m_ criam vários assentos. O gestor escolhe o primeiro assento livre e usa uma entidade Interaction temporária enquanto está ocupado; o seu método público de montagem aceita jogadores, não entidades arbitrárias.

Os prefixos distinguem maiúsculas e minúsculas; o nome hitbox é comparado sem essa distinção. Estes nomes afetam a conversão e o comportamento durante a execução.

Posição da etiqueta de nome

O osso tag_ é agora opcional. O FMM usa o primeiro osso tag_ por ordem alfabética como âncora da etiqueta. Se não existir, coloca-a acima da hitbox com a escala aplicada. Um modelo sem esse osso continua, portanto, a poder apresentar um nome.

Use um osso tag_name sem cubos quando essa posição automática não for adequada. Vários ossos tag_ já não produzem várias cópias da mesma etiqueta.

A API suporta nomes com várias linhas, escala, espaçamento entre linhas e visibilidade. As linhas são ordenadas de cima para baixo, com a última na âncora. Consulte o guia da API.

Sombreamento e emissão de luz dos cubos

• O valor light_emission de um cubo no Blockbench é mantido quando é um número inteiro de 0 a 15. Qualquer outro valor é descartado com um aviso na consola que termina em with invalid light_emission. Expected an integer from 0 to 15; ignoring this value.
• Um cubo com o sombreamento desativado (shade: false) recebe também shade_direction_override: "up" na geometria gerada, para que os clientes Minecraft 26.3 o apresentem sem sombreamento, como fazem os clientes mais antigos. O FMM aplica a mesma regra aos cubos de um .json de apresentação complementar. Um valor definido por si é mantido.

Cubos sem grupo

Os cubos no topo do outliner, sem um grupo, chegam como cadeias UUID em vez de entradas de ossos. O FreeMinecraftModels associa-os ao osso raiz automático freeminecraftmodels_autogenerated_root, permitindo apresentá-los. Não podem ser selecionados por animações; coloque num grupo real tudo o que pretende animar.

IK, objetos nulos e localizadores

O código atual suporta:

• Objetos nulos do Blockbench como controladores de IK.
• Definições de cadeias IK e resolução durante a execução com FABRIK.
• Leitura de localizadores. Os localizadores também podem servir de âncora a efeitos de partículas do Blockbench; consulte Partículas.

Um objeto nulo só se torna controlador IK quando a sua entrada .bbmodel contém ambos ik_source, o osso de origem, e ik_target, o osso ou localizador de destino. O importador procura na hierarquia, incluindo percursos entre irmãos e descendentes. Irmãos no nível raiz produzem uma cadeia apenas com a origem. lock_ik_target_rotation é lido e guardado, mas o solucionador atual não o aplica.

Restrições práticas:

• A ligação entre origem e alvo usa UUID, sobrevivendo a renomeações. Se faltar um UUID, surge IK chain in model <model>: Could not find source bone with UUID ... ou Could not find target with UUID ..., e a cadeia é ignorada.
• Se não existir um caminho entre origem e alvo, surge Could not find path from source to target e a cadeia é ignorada.
• A procura das animações do controlador usa o nome. Mantenha os nomes coerentes entre a estrutura do modelo e os dados de animação.
• Só os fotogramas-chave de posição controlam a IK. O deslocamento é somado à posição de repouso do osso ou localizador de destino, não à posição de repouso guardada do controlador. As pistas de rotação e escala não controlam a IK.

Consulte Animações para o funcionamento da IK em cada fotograma.

Organização da saída em 1.21.4+

O FreeMinecraftModels declara api-version: 1.21.4, pelo que 1.21.4 é a versão mínima do servidor. A saída usa sempre a organização moderna das definições de modelos de itens:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

O código ainda contém os ramos antigos de substituição de armaduras de couro para cavalo, anteriores a 1.21.4. Nenhum servidor capaz de carregar o plugin atual os executa. Isto explica as diferenças em notas ou pastas de saída antigas.

JSON de apresentação do modelo (1.21.4+)

Pode colocar um .json junto do .bbmodel ou .fmmodel com o mesmo nome base, como table.bbmodel e table.json. Exporte esse JSON do Blockbench como modelo «Java Block/Item». Define o aspeto do item na mão e no inventário.

O FMM lê o JSON junto ao ficheiro de modelo ativo, copia-o para o pacote e reescreve os valores sem espaço de nomes no mapa textures. As chaves numéricas correspondem aos índices das texturas extraídas; uma chave sem correspondência usa uma textura disponível, se existir. Os valores com espaço de nomes não mudam. Sem JSON complementar, o item usa o aspeto do material base: normalmente papel para colocar um elemento decorativo, ou o material configurado num item para segurar. Um complemento malformado regista Failed to process display model JSON for ... e não regista esse modelo de apresentação.

Configuração de itens personalizados em YML

Defina material no YAML correspondente ao modelo para registar um item para segurar na mão:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

Use IDs de encantamentos em minúsculas, com espaço de nomes. Os materiais de couro aceitam um sufixo de tinta RGB, como LEATHER_CHESTPLATE:ff8800; consulte Configuração. Um item com material não suportado, encantamento sem espaço de nomes ou lista scripts: não vazia fica indisponível. A consola explica o motivo e o ficheiro original é preservado. scripts: continua reservado a elementos decorativos.

Outras definições inválidas, como um isEnabled não booleano, entradas de encantamento malformadas, encantamentos duplicados ou um nome de ficheiro de item inválido, podem rejeitar o catálogo candidato e o recarregamento. Use nomes de ficheiros de itens em minúsculas, apenas com a-z, 0-9, ., _ e -, até 128 caracteres. A pesquisa de itens criados lê .yml, não .yaml. Obtenha um item registado com /fmm giveitem <item> ou o navegador de administração; as receitas de elementos decorativos e as compras na loja produzem itens de papel para colocação.

Os efeitos de itens usam agora definições de encantamentos. As varinhas e cajados usam configuração de armas mágicas. Nenhum usa o antigo ambiente Lua de itens equipados.

Bedrock e métodos de apresentação

• O suporte Bedrock depende de sendCustomModelsToBedrockClientsV2, com predefinição true, que substitui sendCustomModelsToBedrockClients, e da integração com Floodgate, Geyser e o pacote de recursos.
• Os clientes Java em versões suportadas podem usar entidades de apresentação quando useDisplayEntitiesWhenPossible está ativo.
• Confirme o resultado em Bedrock, mesmo que o modelo pareça correto num cliente Java.

Recomendações práticas de criação

• Mantenha os nomes dos ficheiros estáveis: tornam-se IDs durante a execução.
• Use nomes claros para controladores e animações, pois a procura no Blockbench depende deles.
• Use intencionalmente os nomes reservados hitbox, tag_, h_, b_ e m_. Adicione uma âncora tag_ apenas quando a posição automática do nome acima da hitbox não for adequada.
• Use spawn, idle, walk, attack e death em minúsculas para os estados partilhados; ataque e morte continuam a precisar do respetivo evento durante a execução, e outros nomes exigem reprodução explícita. Consulte Animações.
• Um modelo para /fmm disguise deve incluir pelo menos idle. Pode também incluir sneak e jump, reconhecidos pelo controlador de disfarces. Consulte Disfarces de jogadores.
• Valide o resultado importado após /fmm reload, além da visualização no Blockbench.
• Verifique o conteúdo do pacote gerado para a versão Minecraft pretendida, especialmente em 1.21.4+.

Modelos de estados de arcos e bestas

O FMM deteta automaticamente os estados de apresentação de arcos e bestas ao gerar o pacote. Cada estado obrigatório precisa de um modelo carregado e de um .json de apresentação complementar processado com sucesso; os nomes dos ficheiros não bastam. Configure o item para segurar com o nome base e o material BOW ou CROSSBOW correspondente.

Convenção de nomes

Sufixo	Finalidade	Arco	Besta
_idle	Item na mão, sem puxar nem estar carregado	Obrigatório	Obrigatório
_draw_start	Início da preparação do disparo	Obrigatório	Obrigatório
_draw_half	Preparação a meio	Obrigatório	Obrigatório
_draw_full	Preparação completa	Obrigatório	Obrigatório
_charged	Besta carregada com flecha ou foguete	--	Obrigatório

Um arco precisa de quatro modelos, todos exceto _charged. Uma besta precisa dos cinco.

Exemplo de organização dos ficheiros

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

Para uma besta, adicione também cool_bow_charged.bbmodel e cool_bow_charged.json. A configuração do item é cool_bow.yml, usando o nome base sem _idle.

Funcionamento da deteção

• A deteção é automática ao gerar o pacote, no arranque ou em /fmm reload.
• Um conjunto completo de estados de apresentação recebe uma definição de item pública com o nome base, como cool_bow.json. As definições individuais de item de _idle, preparação e carregado são removidas; a geometria continua referenciada na definição base.
• O registo de apresentação disponibiliza o ID base e remove os IDs de estado. Um conjunto completo com _charged é tratado como besta; sem esse estado, como arco. Estados de apresentação em falta impedem o agrupamento.
• Use o nome base na configuração YML, como cool_bow.yml. O catálogo de itens ignora ficheiros YML com sufixos de estado; a procura da configuração de elementos decorativos também remove o sufixo.

JSON de apresentação

Cada estado obrigatório deve ter o seu próprio .json de apresentação complementar, como cool_bow_idle.json e cool_bow_draw_full.json. O FMM liga-os através da definição base de item gerada. Consulte Pacote de recursos gerado para as condições e o caminho de saída.

Limites desta página

Esta página não procura garantir:

• Os passos exatos na interface do Blockbench.
• Preferências de trabalho artístico.
• Todas as particularidades antigas de .bbmodel descritas em ficheiros README locais anteriores.

Esses detalhes mudam mais depressa do que os requisitos verificados de execução aqui descritos.