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

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

Compatibilidade com Blockbench

• FreeMinecraftModels detecta a versão do arquivo Blockbench durante a importação
• O importador atual ainda contém ramificações de compatibilidade para versões anteriores ao Blockbench v5
• 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
• tag_...
  • tratado como bones virtuais relacionados a nametag
• 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_... ou mount_...
  • 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 de montagem 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.

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
• Parsing de locators

Restrição prática importante:

• A busca de controladores IK é baseada em nome, então a nomenclatura dos controladores precisa permanecer estável entre a estrutura do modelo e os dados de animação

Divisão de Saída 1.21.4+

Para Minecraft 1.21.4+, FreeMinecraftModels gera arquivos de definição de item-model em:

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

Versões mais antigas ainda usam o caminho legado de item-model. Se você está verificando a saída gerada durante a criação, certifique-se de que está olhando para a forma de saída correta para a versão do seu servidor.

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      # opcional — se definido, modelo também é um item personalizado
name: '&b&lMy Custom Sword'  # opcional — nome de exibição
lore:                         # opcional
  - '&7A custom weapon'
enchantments:                 # opcional — formato: 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 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_, mount_)
• 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                  <-- a config usa o nome base, não _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.