Pular para o conteúdo principal

FAQ do FreeMinecraftModels

Se você tiver uma pergunta que não está listada aqui, dê uma olhada na barra lateral para ver se há uma página dedicada a ela no wiki!

Primeiros Passos

Como instalar e usar o FreeMinecraftModels?​

Info

Instalação:

  1. Baixe o FreeMinecraftModels.jar e coloque-o em sua pasta de plugins
  2. Reinicie seu servidor para gerar as pastas do plugin
  3. Execute /fmm setup para o menu de configuração inicial / gerenciamento de conteúdo
  4. Se você usa packs de conteúdo oficiais, vincule o Nightbreak com /nightbreaklogin <token>
  5. Use /fmm setup ou /fmm downloadall para conteúdo oficial gerenciado pelo Nightbreak
  6. Para conteúdo manual, coloque arquivos .bbmodel em ~/plugins/FreeMinecraftModels/imports/ e execute /fmm reload
  7. Encontre o resource pack gerado em ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

Distribuindo o Resource Pack:

Escolha um destes métodos:

  • Opção A (Recomendada): Instale o Resource Pack Manager para distribuição automática
  • Opção B: Configure manualmente via server.properties ou um serviço de hospedagem

Spawnando Modelos:

  • /fmm spawn static <id> - Spawna um modelo decorativo temporário
  • /fmm spawn dynamic <id> - Spawna um modelo anexado a uma entidade
  • /fmm spawn prop <id> - Spawna um modelo persistente no mundo

Gerenciamento:

  • /fmm - Abre o menu de itens craftáveis (requer freeminecraftmodels.menu)
  • /fmm setup - Abre o menu de gerenciamento de conteúdo / configuração inicial
  • /fmm recommendedplugins - Navega plugins complementares que combinam bem com o FMM
  • /fmm downloadall - Baixa a atualização mais recente do plugin mais todo o conteúdo oficial acessível
  • /fmm downloadallcontent - Baixa todo o conteúdo oficial acessível (apenas conteúdo)
  • /fmm updatecontent - Atualiza conteúdo oficial desatualizado
  • /fmm downloadpluginupdate - Baixa apenas a atualização mais recente do jar do plugin
  • /fmm reload - Recarrega o plugin e converte novos modelos
  • /fmm version - Mostra a versão do plugin
  • /fmm stats - Exibe estatísticas de contagem de entidades

Recursos para Jogadores:

  • /fmm disguise <modelID> [player] - Transforma a sua aparência (ou a de um jogador alvo) em um modelo customizado
  • /fmm undisguise [player] - Remove o disfarce de um jogador
  • /fmm disguiselist - Lista todos os jogadores atualmente disfarçados
  • /fmm itemify <model> <material> - Cria um item colocável que spawna o modelo especificado
  • /fmm craftify <modelID> - Abre um construtor de receita interativo para criar uma receita de crafting para um prop
  • /fmm shop - Abre a loja de mobília opcional baseada em Vault (somente quando habilitada em shop_config.yml)
  • /fmm mount <modelID> - Spawna um cavalo montável disfarçado de modelo customizado (experimental)

Depuração:

  • /fmm hitbox visualize [duration] - Visualiza as hitboxes do modelo usando partículas (duração em ticks, padrão 100)
  • /fmm location - Reporta os provedores de proteção / dungeon registrados e os testa na sua localização atual
  • /fmm debug bedrock [on|off] - Alterna o stream de log verboso [FMM-BedrockDebug] para diagnosticar o pipeline de exibição Bedrock. Não é uma chave de config — volta para OFF a cada reinício

Administrativos:

  • /fmm deleteall [radius] - Remove todas as entidades modeladas carregadas e props (use com cuidado - sem prompt de confirmação). Um [radius] opcional (somente jogador) limita a remoção àquela quantidade de blocos

Permissões:

  • freeminecraftmodels.* (padrão: OP) - Wildcard que concede freeminecraftmodels.admin, freeminecraftmodels.deleteall, freeminecraftmodels.disguise.self e freeminecraftmodels.disguise.others. Também a permissão literal exigida por /fmm reload, /fmm stats, /fmm spawn, /fmm itemify, /fmm craftify, /fmm mount, /fmm hitbox visualize, /fmm debug bedrock, /fmm location, /fmm setup, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent e /fmm downloadpluginupdate
  • freeminecraftmodels.admin (padrão: OP) - /fmm admin (o navegador de conteúdo para admins) e /fmm giveitem
  • freeminecraftmodels.disguise.self (padrão: OP) - Permite que um jogador disfarce/retire o disfarce apenas de si mesmo
  • freeminecraftmodels.disguise.others (padrão: OP) - Permite disfarce/retirada de disfarce com alvo e /fmm disguiselist
  • freeminecraftmodels.deleteall (padrão: OP) - Exigida para /fmm deleteall (filho do wildcard)
  • freeminecraftmodels.bypassregionprotection (padrão: OP) - Colocar/interagir com props dentro de regiões do WorldGuard ou claims do GriefPrevention mesmo quando preventPropPlacementInProtectedRegions está ligado
  • freeminecraftmodels.menu (padrão: true) - Permite que todos os jogadores abram o navegador de itens craftáveis via /fmm
  • freeminecraftmodels.shop (padrão: true) - Permite que todos os jogadores abram /fmm shop (ainda condicionado a a loja estar habilitada)

Comandos são exclusivos para OP por padrão, salvo indicação em contrário. Conceda essas permissões a jogadores não-OP se necessário.

Recursos e Limites de Modelos

Quais são os limites de tamanho e rotação dos modelos?​

Info

Limites de Tamanho:

  • Caixa delimitadora máxima por bone: 192x192x192 pixels de modelo (12x12x12 blocos no jogo) — medida entre todos os cubos dentro de um único bone
  • O FreeMinecraftModels usa escala interna de 4x e desloca a origem do modelo para caber na faixa -16..+32 de resource pack do Minecraft
  • Se um bone exceder o limite, o FMM registra um aviso no console; encolha os cubos, mova-os para mais perto ou divida-os em múltiplos bones
  • Modelos inteiros podem ser maiores que isso — apenas o limite por bone se aplica

Limites de Rotação de Cubos:

  • Ângulos permitidos: 0°, ±22,5°, ±45° e múltiplos de 22,5° (a partir da v2.3.0)
  • Apenas rotação em um único eixo
  • Exemplo: [22.5, 0, 0] funciona, mas [22.5, 0, 45] rotaciona apenas parcialmente
  • Outros ângulos não serão exibidos corretamente

Rotação de Bones:

  • Bones suportam qualquer ângulo de rotação
  • Evite posições de repouso padrão de 90°, -90°, 180°, -180° (podem causar comportamento inesperado)
  • Rotação em múltiplos eixos suportada
  • Cada bone cria uma entidade separada (consideração de desempenho)

Nota de Desempenho:

Mantenha a contagem de bones o mais baixa possível. Cada bone spawna uma entidade separada no Minecraft, o que pode impactar o desempenho do servidor em escala.

Quais animações são suportadas?​

Info

O FreeMinecraftModels suporta estas animações de estado padrão (declaradas no enum AnimationStateType):

Animações Padrão:

  • spawn
  • idle
  • walk
  • jump
  • attack
  • death
  • custom (curinga para animações de disparo único acionadas pela API ou Lua)

Como Funciona:

  • Crie animações no BlockBench usando os nomes em minúsculas acima para que o FMM as vincule automaticamente ao estado correspondente
  • O plugin lê os keyframes de animação dos arquivos .bbmodel
  • As animações disparam automaticamente com base no estado da entidade
  • Desenvolvedores podem disparar animações programaticamente usando playAnimation(animationName, blend, loop) em um ModeledEntity, ou context.prop:play_animation(name, blend, loop) a partir do Lua

Caso Especial:

Entidades Evoker detectam Evoker Fangs próximas para disparar animações de ataque automaticamente.

O que são bones virtuais e como funcionam?​

Info

Bones virtuais são bones especiais com nomes reservados que adicionam funcionalidade aos seus modelos:

Bones de Hitbox:

  • Nome: hitbox
  • Cria zonas de interação e caixas de colisão
  • Define os limites da entidade com valores x/z correspondentes

Bones de Name Tag:

  • Prefixo: tag_
  • Exibe texto acima dos modelos
  • Usado para nomear entidades

Bones de Rotação de Cabeça:

  • Prefixo: h_
  • Rotaciona com base na posição da cabeça do jogador/entidade
  • Acompanha o movimento da cabeça automaticamente

Uso:

Crie um bone no BlockBench com um desses nomes especiais, e o plugin aplica automaticamente a funcionalidade correspondente.

FAQ de Solução de Problemas

Em vez de modelos customizados, só vejo armadura de cavalo.​

Info

Se, em vez de modelos customizados aparecerem no seu jogo, você só vê armadura de cavalo, o problema provavelmente é que você não mesclou o resource pack do FMM corretamente com seu resource pack preexistente.

O MagmaGuy desenvolveu um plugin chamado Resource Pack Manager (RSPM) que pode mesclar resource packs automaticamente para você. Você pode baixá-lo do Spigot aqui.

Simplesmente solte o arquivo .jar do RSPM na sua pasta de plugins, e o RSPM cuidará de tudo. Ele mesclará todos os resource packs, os hospedará automaticamente e os distribuirá aos jogadores quando eles entrarem no seu servidor.

Por que não consigo ver meu modelo depois de adicionar o arquivo .bbmodel?​

Info

Se seu modelo não está aparecendo, verifique estes problemas comuns:

1. Esqueceu de recarregar

Execute /fmm reload depois de colocar arquivos .bbmodel na pasta imports. Isso converte os modelos e gera o resource pack.

2. Resource pack não aplicado

Os jogadores precisam ter o resource pack do FMM ativo para ver os modelos.

  • Verifique ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip pelo pack gerado
  • Instale o Resource Pack Manager para distribuição automática
  • OU distribua manualmente via server.properties ou um serviço de hospedagem

3. Local de arquivo errado

Arquivos .bbmodel para importações manuais devem ir em: ~/plugins/FreeMinecraftModels/imports/

Se você estiver usando packs de conteúdo oficiais, use /fmm setup ou /fmm downloadall em vez de soltar arquivos manualmente.

4. O modelo tem erros

Verifique os logs do console por mensagens de erro durante o /fmm reload. Problemas comuns incluem rotações não suportadas, modelos grandes demais ou problemas de textura.

5. Problema de mesclagem do resource pack

Se você vê armadura de cavalo em vez de modelos, os resource packs não foram mesclados corretamente. Use o Resource Pack Manager (RSPM) para lidar com a mesclagem automaticamente.

O ViaVersion pode fazer com que os Resource Packs não sejam exibidos corretamente.​

Info

O ViaVersion pode causar problemas com resource packs, particularmente ao rodar um servidor em uma versão inferior à 1.21.4. O Minecraft introduziu mudanças na forma como os resource packs são tratados a partir da 1.21.4. Se você estiver rodando um servidor em uma versão como 1.21.3 e usando o ViaVersion para permitir que clientes 1.21.4 se conectem, esses clientes podem ter problemas para exibir certos conteúdos do resource pack, como modelos customizados do FMM (FreeMinecraftModels).

Isso acontece porque o sistema de resource pack no Minecraft mudou com a atualização 1.21.4.

Nota: Esta é uma limitação do Minecraft e do ViaVersion, não específica do FreeMinecraftModels. A tradução de protocolo do ViaVersion pode não suportar totalmente as mudanças de resource pack ao rodar em versões de servidor abaixo da 1.21.4.

Para resolver isso, considere atualizar seu servidor para 1.21.4 ou superior, pois isso garantirá melhor compatibilidade com recursos modernos de resource pack, incluindo modelos customizados do FMM.

Por que meus modelos estão causando lag ou problemas de desempenho?​

Info

Cada bone no seu modelo do BlockBench cria uma entidade separada no Minecraft. Modelos com muitos bones podem impactar o desempenho do servidor.

Dicas de Otimização:

  • Minimize a contagem de bones nos seus modelos
  • Limite o número de modelos spawnados
  • Considere usar modelos Estáticos em vez de Dinâmicos quando animações não forem necessárias
  • Evite spawnar muitos modelos com alta contagem de bones perto uns dos outros

Explicação Técnica:

O FreeMinecraftModels renderiza cada bone como uma entidade Minecraft separada. Um modelo com 50 bones spawna 50 entidades. Em escala, isso impacta o desempenho.

Boas Práticas:

  • Projete modelos com menos bones
  • Teste o desempenho com contagens de spawn realistas
  • Monitore o TPS do servidor ao adicionar novos modelos

Recursos Avançados

Eu preciso do Resource Pack Manager (RSPM)?​

Info

O Resource Pack Manager (RSPM) é opcional mas altamente recomendado.

O que o RSPM Faz:

  • Mescla automaticamente resource packs de múltiplos plugins
  • Hospeda resource packs (sem hospedagem externa necessária)
  • Distribui packs aos jogadores automaticamente no login
  • Elimina a configuração manual de resource pack

Sem o RSPM:

Você precisa, manualmente:

  • Mesclar o resource pack do FMM com quaisquer resource packs preexistentes do servidor
  • Hospedar o pack mesclado em um serviço externo ou via server.properties
  • Configurar o servidor para enviar o pack aos jogadores
  • Atualizar o pack toda vez que adicionar novos modelos

Por que Usar o RSPM:

A maioria dos problemas de "armadura de cavalo em vez de modelos" são causados por mesclagem inadequada do resource pack. O RSPM lida com isso automaticamente.

Baixe o RSPM: https://www.spigotmc.org/resources/resource-pack-manager.118574/

Desenvolvido pelo MagmaGuy, o mesmo autor do FreeMinecraftModels.

Posso usar o FreeMinecraftModels no meu próprio plugin?​

Info

Sim, o FreeMinecraftModels fornece uma API para desenvolvedores.

Integração Maven/Gradle:

Repositório: https://repo.magmaguy.com/releases

Artefato:

  • GroupId: com.magmaguy
  • ArtifactId: FreeMinecraftModels
  • Scope: provided (deve estar instalado no servidor, não faça shade)

Classes Principais da API:

  • ModeledEntity (classe base)
  • StaticEntity
  • DynamicEntity
  • PropEntity

Exemplo de Uso:

StaticEntity staticEntity = StaticEntity.create(id, location);
if (staticEntity == null) {
    Bukkit.getLogger().warning("Failed to create model");
    return;
}
staticEntity.setRightClickCallback(...);
staticEntity.remove();

Importante:

Não faça shade do FreeMinecraftModels no seu plugin. Ele deve ser instalado separadamente no servidor.

Para documentação detalhada da API, veja o README oficial.

Como disfarço um jogador como um modelo customizado?​

Info

O comando /fmm disguise transforma a aparência de um jogador em qualquer modelo customizado.

Comandos:

/fmm disguise <modelID> [player]
/fmm undisguise [player]
/fmm disguiselist

Como funciona:

  • Torna o jogador invisível para outros jogadores
  • Sobrepõe o modelo customizado na posição do jogador
  • O modelo segue os movimentos do jogador
  • Perfeito para servidores de roleplay ou eventos especiais

Exemplos:

/fmm disguise dragon              # Disfarça você mesmo
/fmm disguise dragon Steve         # Disfarça outro jogador
/fmm undisguise Steve              # Retira o disfarce do Steve
/fmm disguiselist                  # Lista todos os atualmente disfarçados

Requisitos:

  • Mirando em si mesmo: freeminecraftmodels.disguise.self (padrão: OP)
  • Mirando em outros e /fmm disguiselist: freeminecraftmodels.disguise.others (padrão: OP)
  • O console pode executar a forma com alvo desde que um nome de jogador seja fornecido
  • modelID deve ser um modelo convertido válido na sua pasta de modelos
  • Plugins de terceiros podem controlar disfarces via a DisguiseAPI pública

Notas:

  • A hitbox do jogador permanece inalterada (mesma caixa de colisão)
  • Outros jogadores veem o modelo customizado em vez da skin do seu jogador
  • Disfarçar novamente enquanto já disfarçado substitui o disfarce anterior de forma limpa
  • A invisibilidade persiste através de baldes de leite e outras interações que limpam efeitos até que o disfarce do jogador seja removido

Como crio itens de modelo colocáveis?​

Info

O comando /fmm itemify cria itens especiais que jogadores podem usar para colocar modelos no mundo.

Comando:

/fmm itemify <model> <material>

Parâmetros:

  • model - Qualquer ID de modelo válido da sua pasta de modelos
  • material - Qualquer material do Minecraft (STICK, PAPER, DIAMOND, etc.)

Exemplo:

/fmm itemify lamp_post STICK

O que ele cria:

  • Um item customizado com um nome de exibição formatado e decorado em dourado (ex.: "✦ Wolf ✦")
  • Lore descritiva explicando o item
  • O item é adicionado diretamente ao seu inventário
  • Clique com botão direito para colocar o modelo como prop

Casos de uso:

  • Dar aos jogadores itens para decorar suas construções
  • Criar "ovos de spawn" customizados para mobília
  • Distribuir modelos sem conceder permissões de construção
  • Configurar kits para construção criativa

Requisitos:

  • Permissão: freeminecraftmodels.*
  • O jogador deve estar no jogo (não console)

Como depuro as hitboxes de modelos?​

Info

O comando /fmm hitbox visualize visualiza as hitboxes de modelos usando partículas.

Comando:

/fmm hitbox visualize [duration]

Parâmetros:

  • duration (opcional) - Por quanto tempo mostrar as hitboxes em ticks (padrão: 100, máx: 1200)
  • 20 ticks = 1 segundo

Exemplos:

/fmm hitbox visualize          # Mostra por 5 segundos
/fmm hitbox visualize 200      # Mostra por 10 segundos

Como funciona:

  • Procura por modelos dentro de 10 blocos de você
  • Exibe os limites da caixa delimitadora orientada (OBB) com partículas
  • Mostra tanto o modelo quanto seus limites de colisão
  • Útil para verificar o tamanho e a rotação da hitbox

Quando usar:

  • Testar se as hitboxes correspondem aos modelos visuais
  • Depurar problemas de interação
  • Verificar rotações de hitbox
  • Solucionar problemas de detecção de clique

Requisitos:

  • Permissão: freeminecraftmodels.*

Nota: Hitboxes no FMM rotacionam com o modelo, ao contrário das AABBs padrão do Minecraft.

Posso criar modelos customizados montáveis?​

Info

Sim, use o comando /fmm mount para criar modelos customizados montáveis (recurso experimental).

Comando:

/fmm mount <modelID>

O que ele faz:

  • Spawna um cavalo na sua localização
  • Disfarça o cavalo como seu modelo customizado
  • Doma o cavalo automaticamente e adiciona uma sela
  • Faz você montar o cavalo imediatamente

Exemplo:

/fmm mount dragon

Requisitos:

  • Permissão: freeminecraftmodels.*
  • ID de modelo válido

Notas importantes:

  • Este recurso é marcado como experimental
  • A velocidade de movimento e o comportamento correspondem a um cavalo padrão
  • A hitbox do cavalo permanece inalterada
  • Funciona melhor com modelos projetados para montarias

Casos de uso:

  • Montarias customizadas para servidores de roleplay
  • Transporte especial para jogadores VIP
  • Criaturas montáveis únicas para mapas de aventura

O que são bones de ponto de montagem?​

Info

Pontos de montagem permitem definir posições montáveis diretamente no seu modelo usando bones com nomes especiais.

Como criar pontos de montagem:

No Blockbench, nomeie qualquer bone com o prefixo m_ (ex.: m_seat, m_back). Cada bone m_ se torna uma posição de assento no modelo onde um jogador ou entidade pode ser montado.

Como funciona:

  • A posição de montagem segue a localização do bone, incluindo animações
  • Múltiplos bones m_ criam múltiplos assentos
  • Jogadores/entidades podem ser montados nessas posições via a API ou scripts Lua

Testando:

Use /fmm mount <modelID> para testar rapidamente pontos de montagem em um modelo.

Casos de uso:

  • Veículos de múltiplos assentos (barcos, carruagens)
  • Criaturas montáveis com posições de assento específicas
  • Pets ou companheiros montados no ombro

Itens Customizados

O que são itens customizados?​

Info

Itens customizados são modelos que têm um campo material: definido em seu arquivo de config YML irmão, transformando-os em itens seguráveis e equipáveis com suporte a scripting Lua.

Principais diferenças dos itens de colocação de prop:

  • Itens customizados usam a chave PDC (PersistentDataContainer) fmm_item_id
  • Itens de colocação de prop (de /fmm itemify) usam a chave PDC model_id
  • Itens customizados suportam 22 hooks de script Lua específicos de item (equip, attack, consume, etc.)
  • Itens customizados podem ter encantamentos, nomes customizados e lore definidos em sua config YML

Como criar um item customizado:

  1. Crie um modelo .bbmodel no Blockbench
  2. Crie um arquivo YML irmão com o mesmo nome base (ex.: magic_sword.yml ao lado de magic_sword.bbmodel)
  3. Defina o campo material: no YML para qualquer material válido do Minecraft (ex.: material: DIAMOND_SWORD)
  4. Opcionalmente defina os campos name:, lore: e enchantments:
  5. Opcionalmente crie um script Lua em plugins/FreeMinecraftModels/scripts/ e referencie-o via o campo scripts:

Exemplo de YML:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A legendary weapon"
  - "&cBurns enemies on hit"
enchantments:
  - "FIRE_ASPECT,2"
scripts:
  - flame_blade.lua

Como obter um item customizado:

  • /fmm giveitem <id> (requer a permissão freeminecraftmodels.admin)
  • Através do menu de admin (/fmm admin)

Menus

Quais menus o FMM fornece?​

Info

O FreeMinecraftModels fornece dois menus no jogo para navegar e gerenciar conteúdo.

Menu do Jogador — /fmm

  • Permissão: freeminecraftmodels.menu (padrão: true, todos os jogadores podem usar)
  • Mostra apenas itens que têm receitas de crafting definidas
  • Clique em um item para ver uma visão detalhada com um preview da grade de crafting espacial 3x3
  • Permite que jogadores descubram e aprendam como craftar itens customizados

Menu de Admin — /fmm admin

  • Permissão: freeminecraftmodels.admin (padrão: OP)
  • Navegador de conteúdo completo mostrando:
    • Pacotes instalados
    • Pastas de modelos não empacotados
    • Modelos no nível raiz
    • Itens customizados (modelos com material: definido)
  • Permite que admins deem itens, visualizem modelos e gerenciem conteúdo

Modelos de Exibição

O que são modelos de exibição?​

Info

Modelos de exibição permitem que itens customizados mostrem um modelo 3D no inventário e na mão do jogador, em vez da aparência padrão do material.

Como configurar um modelo de exibição:

  1. No Blockbench, use File > Export > Java Block/Item para exportar um arquivo de modelo .json
  2. Coloque o arquivo .json ao lado do arquivo .bbmodel com o mesmo nome base (ex.: magic_sword.json ao lado de magic_sword.bbmodel)
  3. Execute /fmm reload

Como funciona:

  • No Minecraft 1.21.4+, o item será exibido com o modelo 3D customizado quando segurado ou visualizado no inventário
  • Referências de textura simples no JSON são reescritas automaticamente para caminhos do namespace do FMM
  • Se nenhum arquivo .json existir, o item recorre à aparência simples do material
  • Versões de servidor mais antigas ignoram os modelos de exibição silenciosamente

Requisitos:

  • Servidor rodando Minecraft 1.21.4 ou mais novo
  • Uma exportação "Java Block/Item" do Blockbench válida (.json) colocada ao lado do arquivo do modelo