Notas de Criação de Modelos do FreeMinecraftModels

Esta página documenta os detalhes de criação atuais que são visíveis na base de código do FreeMinecraftModels. É intencionalmente conservadora: foca no contrato de importação/runtime, não em cada preferência de fluxo de trabalho do Blockbench.

Formatos de Origem

FreeMinecraftModels atualmente aceita:

• arquivos .bbmodel para importações de origem editáveis
• arquivos .fmmodel para dados de modelo prontos para runtime

O fluxo normal de importação é:

1. coloque o modelo em plugins/FreeMinecraftModels/imports
2. execute /fmm reload
3. deixe o FreeMinecraftModels importar o modelo para o conjunto de modelos ativos e reconstruir o resource pack gerado

Funções das Pastas

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

• imports é a pasta de entrada para importações manuais de modelos e downloads de pacotes oficiais antes do processamento
• models contém o conteúdo de modelos ativos instalados
• models_disabled contém conteúdo de pacotes baixados ou instalados que estão atualmente desabilitados

Instalações antigas podem ter, em vez disso, uma pasta Models com maiúscula. O FreeMinecraftModels resolve isso preferindo a models canônica em minúsculas quando ela existe, e só recorrendo à Models legada quando ela não existe. No Windows e no macOS os dois nomes são o mesmo diretório de qualquer forma; em um sistema de arquivos Linux sensível a maiúsculas, uma instalação antiga continua funcionando, mas, se ambos os diretórios existirem, apenas a models em minúsculas é lida. Consolide tudo em models se encontrar as duas.

IDs de Modelos

• IDs de modelos em runtime vêm do nome do arquivo, sem a extensão .bbmodel ou .fmmodel
• Use nomes de arquivo estáveis e únicos porque o ID é o que comandos e chamadas de API resolvem
• Referências de animação do Blockbench são baseadas em nome, então nomenclatura duplicada ou confusa dentro do modelo é mais provável de causar problemas do que um esquema de nomenclatura limpo e explícito
• A correspondência de extensão não distingue maiúsculas, então .BBModel e .FMModel são aceitos

Normalização de ID e colisões

O nome do arquivo é normalizado antes de virar o ID de modelo em runtime e o nome de arquivo no resource pack:

1. convertido para minúsculas
2. todo caractere fora de a-z, 0-9, ., _ e - é substituído por _

Então My Table.bbmodel, my table.bbmodel e my_table.bbmodel normalizam todos para o mesmo ID, my_table.

Antes de qualquer conversão rodar, o FreeMinecraftModels varre toda a árvore de modelos e verifica arquivos que normalizam para o mesmo ID. Quando encontra uma colisão:

• todo arquivo em colisão é rejeitado — nenhum deles é carregado, então não há um silencioso "vence o último"
• o ID do modelo fica bloqueado pelo restante daquela passagem de carregamento
• modelos rejeitados também são excluídos da exportação do bundle de entidade personalizada Bedrock
• o console recebe:

[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.

A correção é sempre renomear os arquivos para que os IDs normalizados sejam distintos. O hábito mais seguro é nomear arquivos de modelo em minúsculas com underscores desde o começo (stone_table.bbmodel), o que torna o nome do arquivo e o ID em runtime idênticos e remove qualquer chance de uma colisão surpresa.

Compatibilidade com Blockbench

• O FreeMinecraftModels lê meta.format_version do .bbmodel e ramifica com base no número maior
• Um bloco meta ausente, um format_version ausente ou um valor que ele não consegue analisar caem todos na versão 4, com uma linha de info/aviso nomeando o modelo
• Um array textures ausente é aceito e tratado como uma lista de texturas vazia, em vez de quebrar o importador. O exportador de entidade personalizada Bedrock então pula esse modelo, porque a exportação Bedrock exige pelo menos uma textura
• Os nomes de arquivo das texturas extraídas são normalizados para uma única extensão .png. Um nome de origem como body.jpg, body.PNG ou body é gravado e referenciado como body.png
• format_version 4.x e anteriores: os bones são lidos diretamente da árvore outliner, que carrega os nomes dos bones inline
• format_version 5.x e mais recentes: o esquema do outliner mudou. outliner agora é uma árvore aninhada de strings de UUID puras e dicionários {uuid, isOpen, children} sem chave de nome, enquanto um array plano separado groups guarda os dados reais dos bones (incluindo name). O FMM junta os dois por UUID — cada nó do outliner é substituído pela entrada correspondente em groups, e então os filhos são mesclados recursivamente — de modo que nomes, origens e rotações dos bones resolvem normalmente
• Consequências que vale conhecer ao editar à mão ou gerar arquivos .bbmodel:
  • Um arquivo v5 cujo array groups esteja ausente é repassado sem a mesclagem, então seus bones perdem os nomes e os prefixos reservados (tag_, h_, b_, m_, hitbox) deixam de ser reconhecidos
  • Os UUIDs devem corresponder exatamente entre outliner e groups; um nó de outliner sem um group correspondente é mantido como está, em vez de ser descartado
  • Não misture um format_version v5 com um outliner no formato v4, nem o contrário — a ramificação é escolhida pela versão declarada, não pelo formato real
• Se os logs de importação dizem que o formato do modelo não é compatível com FreeMinecraftModels, trate isso como um problema de formato de modelo primeiro, não um problema de wiki ou comando

Convenções de Bones Significativos para Runtime

O conversor atual e o pipeline de esqueleto reconhecem algumas convenções de nomenclatura:

• hitbox
  • reservado para geração de hitbox
  • deve definir a hitbox do modelo de forma limpa em vez de ser usado como um bone visual
  • precisa ser um bone de nível superior no outliner. O importador só o procura no nível raiz; um grupo hitbox aninhado dentro de outro bone é tratado como um bone comum
  • precisa conter exatamente um cubo, que define a largura (x), profundidade (z) e altura (y) em runtime. Cubos extras registram has more than one value defining a hitbox! Only the first cube will be used; um bone de hitbox vazio registra has a hitbox bone but no hitbox cube! e nenhuma hitbox é gerada
  • nunca é animado (trilhas de animação que apontam para hitbox são puladas), nunca é renderizado e é excluído da exportação de geometria Bedrock. No Bedrock, um modelo sem bone hitbox cai para 1.0 x 2.0
• tag_...
  • a única forma de um modelo receber um nametag. Veja Nametags exigem um bone tag_ abaixo
• h_...
  • tratado como bones de cabeça
• b_...
  • bones sem exibição (ocultos em runtime). Use para bones estruturais ou organizacionais que não devem ser renderizados no jogo.
• m_...
  • bones de ponto de montagem. Cada bone com este prefixo cria uma posição de assento montável no modelo. Jogadores ou entidades podem ser montados nessas posições em runtime. Múltiplos bones m_ criam múltiplos assentos. Gerenciado internamente pelo MountPointManager.

Estas não são apenas convenções de estilo; elas afetam a conversão e o comportamento em runtime.

Nametags exigem um bone tag_

Esta é de longe a causa mais comum de conteúdo publicado com mobs sem nome, então vale dizer sem rodeios:

Um modelo só recebe um nametag se contiver um bone cujo nome comece com tag_. Não há fallback.

Como funciona:

• Durante a importação, qualquer bone chamado tag_... ganha um bone "meta" autogerado paralelo (fmm_nametag_bone_<name>) que é marcado como bone de nametag. Nada mais no pipeline define essa marca
• Em runtime, o esqueleto reúne esses bones marcados e um text display é spawnado na origem do bone tag_. Sua posição e texto seguem aquele bone
• ModeledEntity.setDisplayName(...) e setDisplayNameVisible(...) percorrem essa coleção. Sem um bone tag_, a coleção fica vazia e ambas as chamadas silenciosamente não fazem nada — sem erro, sem aviso, sem nome

Por que o nametag vanilla não cobre por você:

• Um modelo dinâmico esconde dos clientes a entidade viva subjacente (setVisibleByDefault(false), mais a flag de invisibilidade), então o próprio nametag vanilla do mob também não é renderizado
• O efeito líquido é um mob completamente sem nome, mesmo que o plugin chamador tenha definido um nome de exibição com sucesso

Regras práticas:

• Se um modelo representa uma entidade nomeada (um boss do EliteMobs, um NPC de quest, qualquer coisa em que um plugin chame setDisplayName), adicione um bone tag_
• Coloque-o onde o nametag deve flutuar — normalmente logo acima da cabeça
• O bone não precisa de cubos; ele é uma âncora posicional. tag_name em particular é pulado quando as definições de item-model são geradas, então nunca renderiza como geometria
• Múltiplos bones tag_ são permitidos; cada um deles ganha seu próprio text display exibindo o mesmo nome
• Se você vir nametag bone did not spawn name tag no console, o bone foi reconhecido mas o text display dele falhou ao spawnar — isso é um problema diferente de não ter nenhum bone tag_

Cubos Flutuantes

Cubos declarados no topo do outliner sem um grupo contendor chegam como strings de UUID puras, e não como entradas de bone. O FreeMinecraftModels os anexa ao bone raiz autogerado (freeminecraftmodels_autogenerated_root) para que ainda sejam renderizados. Eles não são endereçáveis por animações, então coloque dentro de um grupo real qualquer coisa que você pretenda animar.

IK, Objetos Nulos e Locators

O código atual confirma suporte para:

• Objetos nulos do Blockbench como controladores de IK
• Blueprints de cadeia IK e resolução de IK em runtime (FABRIK)
• Parsing de locators

Um objeto nulo só se torna um controlador de IK quando sua entrada no .bbmodel carrega ambos ik_source (o bone onde a cadeia começa) e ik_target (o bone ou locator que a cadeia tenta alcançar). lock_ik_target_rotation também é lido. A cadeia é descoberta subindo pela hierarquia de bones do alvo até a origem, então os dois precisam estar de fato conectados.

Restrições práticas importantes:

• O vínculo origem/alvo é por UUID, então ele sobrevive a renomeações — mas se qualquer um dos UUIDs estiver ausente do modelo, o console registra IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ... e aquela cadeia é pulada
• Se a busca não encontrar um caminho da origem até o alvo, você recebe Could not find path from source to target e a cadeia é pulada
• A busca de animações de um controlador é baseada em nome, então a nomenclatura dos controladores precisa permanecer estável entre a estrutura do modelo e os dados de animação
• Apenas os keyframes de posição em um objeto nulo importam — eles viram o deslocamento de meta da IK. Trilhas de rotação e escala em um objeto nulo são ignoradas

Veja Animações para saber como a IK é controlada quadro a quadro.

Divisão de Saída 1.21.4+

O FreeMinecraftModels declara api-version: 1.21.4, então 1.21.4 é a versão mínima de servidor e o layout moderno de definição de item-model é o único que você vai obter:

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

Ramificações legadas (anteriores ao 1.21.4) com override de leather horse armor ainda existem no código, mas nenhum servidor capaz de carregar o plugin atual chega até elas. Se você está lendo notas antigas ou uma pasta de saída antiga, essa é a diferença que está vendo.

Display Model JSON (1.21.4+)

Administradores podem colocar um arquivo .json irmão ao lado de um arquivo .bbmodel ou .fmmodel com o mesmo nome base (por exemplo, table.bbmodel + table.json). Este JSON deve ser exportado do Blockbench como um modelo "Java Block/Item" e define como o item aparece quando segurado na mão ou mostrado no inventário.

Durante a importação, FMM copia o JSON para a saída do resource pack e automaticamente reescreve quaisquer referências de textura simples dentro dele para apontar para as texturas extraídas do modelo. Se nenhum JSON irmão existir, o item é exibido como papel simples no jogo.

Configuração Personalizada de Item em YML

O arquivo de configuração .yml irmão (mesmo nome base do modelo) agora suporta campos opcionais de item. Se material: estiver definido, o modelo também está disponível como um item personalizado que pode ser segurado. O formato YML completo é:

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

Quando material: está presente, o modelo aparece no navegador de conteúdo do administrador ao lado dos props e pode ser dado a jogadores como um item funcional.

Notas sobre Bedrock e Caminho de Renderização

• O suporte ao Bedrock depende de sendCustomModelsToBedrockClientsV2 (padrão true; substitui a chave antiga sendCustomModelsToBedrockClients) e do caminho Floodgate/Geyser/resource pack ao redor
• Clientes Java em versões suportadas podem usar renderização por display entity quando useDisplayEntitiesWhenPossible está habilitado
• Não assuma que um modelo que parece correto em um cliente Java é automaticamente seguro para seu caminho Bedrock

Conselhos Práticos de Criação

• mantenha nomes de arquivo estáveis porque eles se tornam IDs de runtime
• mantenha a nomenclatura de controladores e animações explícita porque a busca de animação do Blockbench é orientada por nome
• use os nomes reservados de bones virtuais intencionalmente (hitbox, tag_, h_, b_, m_) — e lembre-se de que qualquer modelo que deva exibir um nome precisa de um bone tag_, ou ficará silenciosamente sem nome
• nomeie as animações de estado como spawn, idle, walk, attack e death se quiser que elas disparem automaticamente; todo o resto é uma animação personalizada que você mesmo aciona (veja Animações)
• um modelo destinado a /fmm disguise deve trazer no mínimo um idle, e pode adicionar sneak e jump, que só o controlador de disfarce reconhece (veja Disfarces de Jogadores)
• valide a saída importada após /fmm reload, não apenas dentro do Blockbench
• verifique o conteúdo do pack gerado para sua linha alvo de Minecraft, especialmente em 1.21.4+

Modelos de Estado de Arco e Besta

FMM suporta estados de animação de puxar automáticos para itens personalizados de arco e besta. Nenhuma configuração é necessária -- apenas nomeie seus arquivos de modelo com os sufixos corretos e o FMM detecta o conjunto de estados automaticamente durante a geração do resource pack.

Convenção de Nomes

Sufixo	Propósito	Arco	Besta
_idle	Item na mão, sem puxar ou carregado	obrigatório	obrigatório
_draw_start	Acabou de começar a puxar	obrigatório	obrigatório
_draw_half	Puxado pela metade	obrigatório	obrigatório
_draw_full	Totalmente puxado	obrigatório	obrigatório
_charged	Besta carregada (flecha ou foguete)	--	obrigatório

Um arco precisa de quatro modelos (todos exceto _charged). Uma besta precisa de todos os cinco.

Exemplo de Layout de Arquivos

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

Para uma besta você adicionaria um quinto arquivo, cool_bow_charged.bbmodel.

Como a Detecção Funciona

• A detecção acontece automaticamente quando o resource pack é gerado (na inicialização ou ao executar /fmm reload).
• Apenas o modelo _idle recebe um JSON de definição de item no pack de saída. Os estados de puxar e carregado são referenciados como entradas condicionais dentro dessa definição.
• Apenas o nome base recebe um arquivo de configuração YML. Para o exemplo acima, a configuração é cool_bow.yml, não cool_bow_idle.yml.

Display Model JSON

Cada modelo de estado pode ter seu próprio arquivo .json de display model irmão (ex: cool_bow_idle.json, cool_bow_draw_full.json). FMM os conecta automaticamente na definição de item gerada. Veja Saída do Resource Pack para a estrutura JSON exata que é gerada.

Fora do Escopo

Esta página não tenta garantir:

• passos exatos na UI do Blockbench
• preferências artísticas de fluxo de trabalho
• cada peculiaridade legada de .bbmodel descrita em material README local mais antigo

Esses detalhes mudam mais rápido que o contrato de runtime verificado acima.