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_...
  • 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.

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 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_)
• 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.