Configuração do FreeMinecraftModels

registerCraftingRecipes em config.yml tem o valor padrão true. Defina false e reinicie para uma economia baseada apenas em compras: as receitas continuam visíveis nos menus e na loja, mas as receitas de crafting Bukkit são removidas. As instruções de crafting nesta página exigem true.

Esta página cobre as configurações atuais de config.yml e shop_config.yml que afetam materialmente setup, renderização, interação com jogadores e a loja de mobília opcional.

Localização dos Arquivos

plugins/FreeMinecraftModels/config.yml
plugins/FreeMinecraftModels/shop_config.yml

shop_config.yml é gerado na primeira execução; a loja em si permanece desabilitada até você optar por ativá-la.

Versão mínima do servidor

O plugin.yml declara api-version: 1.21.4, portanto o Minecraft 1.21.4 é a versão mínima de servidor suportada. O suporte a linhas mais antigas foi descontinuado; ramificações antigas de renderização/saída ainda existem no código, mas não são mais alcançáveis em um servidor capaz de carregar o plugin.

Configurações de config.yml

setupDone

• Padrão: false
• Controla se a orientação de configuração inicial é considerada completa
• Jogadores com permissões amplas do FreeMinecraftModels são lembrados a rodar /fmm setup enquanto isto permanecer false
• O fluxo de configuração alterna esse valor automaticamente; você não precisa editá-lo manualmente durante o onboarding normal

nightbreak.autoDownloadPluginUpdates

• Padrão: false
• Configuração compartilhada do MagmaCore (fica na seção nightbreak: do config.yml)
• Quando true, o FreeMinecraftModels baixa automaticamente as atualizações disponíveis do jar do plugin e os arquivos de atualização de conteúdo na inicialização
• Atualizações de plugin e de conteúdo baixadas só são aplicadas depois que o servidor reinicia
• Downloads automáticos de plugin exigem um token de conta Nightbreak válido e uma assinatura de apoiador ativa no Patreon. Sem os dois, deixe isto em false e use o botão de atualização no jogo
• Esta é a chave de config equivalente a rodar /fmm downloadpluginupdate / /fmm downloadall a cada boot; alterne-a pelo menu /fmm setup ou manualmente

useDisplayEntitiesWhenPossible

• Padrão: true
• Diz ao FreeMinecraftModels para preferir renderização com display-entity quando o servidor e o caminho do cliente suportarem
• O plugin ainda recorre a displays de armor-stand quando display entities não estão disponíveis (o comentário da config cita servidores anteriores ao 1.19.4 e clientes Bedrock; na prática o plugin atual declara api-version: 1.21.4, então o fallback que você realmente vai encontrar é o do Bedrock)
• Clientes Bedrock são um caso especial, então não assuma que isso força o mesmo caminho de renderização para todos os jogadores

maxModelViewDistance

• Padrão: 60
• Limita o quão longe entidades modeladas são enviadas aos espectadores
• Valores menores reduzem a carga de pacotes e renderização no cliente em áreas densas com muitos modelos
• Entidades individuais podem sobrescrever isto em runtime via ModeledEntity.setViewDistanceOverride(int) — veja o guia da API

maxInteractionAndAttackDistance

• Padrão: 3
• Aplica-se a entidades modeladas estáticas e dinâmicas
• Usado pelas verificações de interação e detecção de acerto em runtime

maxInteractionAndAttackDistanceForProps

• Padrão: 6
• Aplica-se a entidades prop
• Isto é separado da distância de interação de entidades estáticas/dinâmicas

sendCustomModelsToBedrockClientsV2

• Padrão: true
• Controla se o FreeMinecraftModels tenta enviar modelos customizados para clientes Bedrock
• Esta chave substitui a antiga sendCustomModelsToBedrockClients (cujo padrão era false). A renomeação para V2 inverte o padrão para que jogadores Bedrock vejam modelos por padrão; se você havia definido a chave antiga explicitamente, pode deletá-la e a nova chave V2 assume
• Se desabilitada, jogadores Bedrock recorrem à entidade vanilla subjacente onde ela existe (e disfarces não serão renderizados para eles)
• Se você ativá-la, certifique-se de que seu caminho de resource pack Bedrock/Geyser/Floodgate esteja realmente pronto para esses clientes
• O log de diagnóstico em runtime para o pipeline de exibição Bedrock não é uma chave de config — ele é alternado em runtime via /fmm debug bedrock on|off para que nunca fique acidentalmente ligado em produção. Veja Comandos

skipUnchangedBoneUpdates

• Padrão: true
• Quando true, um osso de modelo só envia seus pacotes de movimento/metadados por tick aos espectadores se sua posição, rotação ou escala de fato mudou desde o último tick
• Ossos perfeitamente parados (props estáticos, partes ociosas de um modelo) não enviam nada, o que reduz muito a carga de pacotes por cliente em áreas densas, como hubs de NPC e cidades
• A ressincronização completa periódica continua rodando, então qualquer desvio raro do cliente se autocorrige
• Defina como false apenas para restaurar o antigo comportamento de "reenviar todo osso a cada tick" para depuração

useDeltaMetadataPackets

• Padrão: true
• Quando true, o pacote de metadados por tick dos ossos de modelo baseados em display entity envia apenas os valores que mudaram (a transformação do osso), em vez de reserializar todo o blob de item-display (modelo do item + custom model data) a cada tick
• O estado completo ainda é enviado quando um jogador vê um modelo pela primeira vez e na ressincronização periódica
• Defina como false para restaurar o antigo comportamento de snapshot completo a cada tick, para depuração ou comparação

maxModelsForProximityOverride

• Padrão: 25
• Pseudo balanceador de carga para a substituição de visibilidade a curta distância
• Normalmente, um modelo a até 10 blocos de um jogador é sempre exibido, pulando o raytrace de linha de visão para que modelos ao seu lado não apareçam de repente
• Em uma área densa (por exemplo, um hub de NPC de vários andares), essa substituição transforma dezenas de modelos que o jogador não consegue ver de fato -- em outros andares, atrás de paredes -- em espectadores que enviam pacotes a cada tick
• Quando um mundo contém pelo menos essa quantidade de modelos carregados, a substituição de curta distância é desabilitada naquele mundo, então o raytrace de oclusão roda mesmo de perto e descarta modelos aos quais o jogador não tem linha de visão. Mundos esparsos mantêm a substituição e, portanto, o comportamento sem pop-in
• A decisão é por mundo, não global, então um mundo de hub lotado não penaliza os tranquilos
• Aumente muito o valor para efetivamente restaurar o comportamento de sempre substituir; defina como 0 para sempre exigir linha de visão
• /fmm packetdebug é a ferramenta indicada para medir o efeito -- veja Comandos

preventPropPlacementInProtectedRegions

• Padrão: true
• Quando true, o FreeMinecraftModels pergunta aos provedores de proteção registrados no MagmaCore se este jogador específico pode construir na célula que o prop ocuparia, e recusa a colocação se a resposta for não
• Jogadores com a permissão freeminecraftmodels.bypassregionprotection (padrão: op) pulam a verificação por completo e nunca são bloqueados
• Os provedores integrados cientes do jogador cobrem atualmente WorldGuard e GriefPrevention. Qualquer outro plugin pode registrar um provedor de proteção do MagmaCore e será respeitado da mesma forma. Sem nenhum provedor registrado, a verificação não tem efeito
• A mensagem de recusa é You don't have permission to place a model here!

A verificação é ciente do jogador, não da região. Versões anteriores perguntavam "esta localização está dentro de alguma região protegida?" e bloqueavam todo mundo. A verificação atual pergunta "este jogador pode construir aqui?", então um jogador que legitimamente possui o claim, ou é membro confiável dele, ou está dentro da própria região do WorldGuard, consegue colocar props ali normalmente. Só são recusados jogadores que não poderiam colocar um bloco vanilla naquela célula.

Toda colocação recebe uma verificação de célula única; props voxelizados recebem uma segunda, de volume inteiro:

Tipo de prop	Células verificadas
Prop normal (forma livre)	A única célula adjacente à face do bloco clicado -- a célula que o prop vai ocupar
Prop com voxelize: true	Essa mesma célula adjacente primeiro, depois cada célula na área ocupada e rotacionada do prop (largura x altura x profundidade) ao redor do ponto de colocação alinhado à grade. Se qualquer célula desse volume estiver fora dos limites, a colocação inteira é recusada

A verificação de volume existe porque um prop voxelizado pode ter vários blocos de largura, então testar apenas a célula clicada permitiria que um jogador ficasse sobre a divisa de um claim e soltasse um prop grande dentro da construção de outra pessoa. Ela roda depois da verificação de espaço livre, então Not enough space to place this model! ainda tem prioridade quando a área ocupada está fisicamente obstruída.

nota

A permissão de bypass é verificada antes da consulta ao provedor, então conceder freeminecraftmodels.bypassregionprotection é a forma suportada de deixar a equipe colocar props em qualquer lugar sem desabilitar esta chave em todo o servidor.

shop_config.yml

A loja de mobília opcional baseada em Vault fica em sua própria config para que possa ser habilitada ou ajustada independentemente do comportamento principal do plugin. A loja se recusa a registrar se o Vault ou um provedor de economia estiver faltando.

Chaves de nível superior

Chave	Padrão	Descrição
enabled	false	Toggle mestre para /fmm shop. O comando só registra quando isto é true e o Vault + um provedor de economia estão ambos presentes
defaultPrice	100.0	Preço escrito nos arquivos de receita que não definem seu próprio shopPrice no próximo carregamento
menuTitle	&8FMM - Furniture Shop	Título mostrado no topo do inventário da loja (suporta códigos de cor &)
priceLoreFormat	&7Price: &e{price}	Linha de lore adicionada a cada item da loja mostrando seu preço. Placeholder: {price}
clickToBuyLoreFormat	&aClick to purchase	Linha de lore adicionada a cada item da loja incentivando a compra

Chaves de mensagem (messages.*)

Todas as strings de mensagem suportam códigos de cor &.

Chave	Padrão	Placeholders
messages.purchaseSuccess	&aPurchased &f{item} &afor &e{price}&a. Balance: &e{balance}&a.	{item}, {price}, {balance}
messages.insufficientFunds	&cYou need &e{price} &cto buy &f{item}&c. Balance: &e{balance}&c.	{item}, {price}, {balance}
messages.shopDisabled	&cThe furniture shop is currently unavailable.	nenhum
messages.itemNotForSale	&cThat item is not currently for sale.	{item}
messages.inventoryFull	&eYour inventory was full; &f{item} &ehas been dropped at your feet.	{item}

Campos de loja por receita

Cada arquivo de receita em plugins/FreeMinecraftModels/recipes/<model_id>.yml ganha dois campos adicionais:

Campo	Padrão	Descrição
shopEnabled	true	Se esta receita é visível em /fmm shop. Receitas com shopEnabled: false ainda são craftáveis mas nunca listadas para compra
shopPrice	defaultPrice de shop_config.yml	Custo em moeda do Vault para este item específico

O construtor de receitas (/fmm craftify) escreve ambos os campos ao salvar, então ajustar preço fica a uma edição de texto de distância.

Permissões

Registradas em plugin.yml

Permissão	Padrão	Descrição
freeminecraftmodels.*	op	Wildcard que concede admin, deleteall, disfarce próprio/de outros e as permissões de bypass da proteção de região
freeminecraftmodels.admin	op	Acesso a /fmm admin (o navegador de conteúdo para admins) e /fmm giveitem. Outros comandos de admin/debug (/fmm location, /fmm spawn, /fmm mount, /fmm itemify, /fmm craftify, /fmm reload, /fmm stats, /fmm hitbox visualize, /fmm debug, /fmm packetdebug, /fmm setup, /fmm initialize, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent, /fmm downloadpluginupdate, /fmm forcereinstallcontent) verificam o wildcard freeminecraftmodels.* em vez disso
freeminecraftmodels.deleteall	op	Filho do wildcard; acesso a /fmm deleteall
freeminecraftmodels.disguise.self	op	Permite /fmm disguise / /fmm undisguise no remetente
freeminecraftmodels.disguise.others	op	Permite disfarce/retirada de disfarce com alvo, mais /fmm disguiselist
freeminecraftmodels.bypassregionprotection	op	Colocar e interagir com props em qualquer lugar onde outro plugin bloquearia a colocação normal de blocos, mesmo quando preventPropPlacementInProtectedRegions está ligado
freeminecraftmodels.menu	true	Acesso ao menu de itens craftáveis /fmm
freeminecraftmodels.shop	true	Acesso a /fmm shop
nightbreak.login	op	Registrada pelo MagmaCore, não pelo plugin.yml. Exigida pelos comandos compartilhados /nightbreaklogin e /nightbreaklogout

Configuração YML do Modelo

Cada arquivo .bbmodel pode ter um arquivo .yml companheiro (mesmo nome, mesmo diretório) que controla configurações específicas do modelo. O formato YML unificado suporta os seguintes campos:

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
  - "&7Deals frost damage"
enchantments:
  - SHARPNESS,3
  - UNBREAKING,2

Campo	Tipo	Descrição
isEnabled	boolean	Se o modelo é carregado (padrão: true)
scripts	lista de strings	Nomes de arquivos de script Lua a anexar de plugins/FreeMinecraftModels/scripts/. Inclua .lua para clareza; entradas de config sem .lua são aceitas e resolvidas para arquivos .lua.
voxelize	boolean	Quando true, o prop se ajusta a incrementos de rotação de 90 graus e se alinha à grade de blocos ao ser colocado. A área ocupada é calculada a partir das dimensões da hitbox do modelo (arredondadas para blocos inteiros). A colocação verifica que todos os blocos da área ocupada são não sólidos.
solidify	boolean	Quando true (requer voxelize: true), blocos de barreira apenas em pacotes são colocados em cada bloco da área ocupada do prop, dando a ele colisão no lado do cliente. Essas barreiras são invisíveis e existem apenas em pacotes — não são colocadas no mundo. As barreiras são removidas automaticamente quando o prop é recolhido ou destruído.
material	string	Um nome de material do Bukkit (ex.: DIAMOND_SWORD, PAPER). Quando definido, o modelo se torna um item customizado que jogadores podem segurar e equipar
name	string	Nome de exibição do item customizado (suporta códigos de cor &)
lore	lista de strings	Linhas de lore do item customizado (suporta códigos de cor &)
enchantments	lista de strings	Encantamentos no formato ENCHANTMENT_NAME,LEVEL (ex.: SHARPNESS,3)

Quando material é definido, o modelo é registrado como um item customizado. Jogadores podem recebê-lo via /fmm giveitem, craftá-lo se uma receita estiver configurada, e ele ganha acesso a todos os 22 hooks Lua de item.

Props executam cada script listado em scripts: como instâncias independentes. Itens customizados atualmente usam apenas o primeiro script válido da lista; entradas adicionais após a primeira são ignoradas para o binding de runtime do item.

Notas Operacionais

• /fmm reload reimporta conteúdo e regenera o pack de saída, então mudanças de configuração que afetam o comportamento de renderização são mais fáceis de validar após um reload. Um FmmReloadedEvent é disparado a cada reload para que plugins dependentes possam re-vincular seus anexos de modelo.
• O pack gerado é byte-estável, então regenerá-lo a partir de um conjunto de modelos inalterado produz um zip e um SHA1 idênticos. É isso que permite ao ResourcePackManager pular um re-upload redundante. Veja Saída do Resource Pack.
• O FreeMinecraftModels apenas gera o resource pack; ele não o hospeda sozinho.
• O ResourcePackManager continua sendo o caminho de entrega recomendado para clientes Java e o caminho documentado mais seguro para configurações mistas.
• WorldGuard, WorldEdit, GriefPrevention, Vault, floodgate e Geyser-Spigot são declarados como softdepend em plugin.yml — nenhum deles é necessário para iniciar o plugin, mas eles desbloqueiam recursos específicos quando presentes: WorldGuard/WorldEdit/GriefPrevention alimentam tanto os predicados Lua cientes de proteção quanto a verificação de colocação de props ciente do jogador, o Vault habilita a loja de mobília, e floodgate/Geyser-Spigot habilitam o backend de renderização Bedrock.

Quando Alterar Esses Valores

Use esta config para ajuste de comportamento em runtime, não para gerenciamento de pacotes de conteúdo.

• Use /fmm setup, /fmm downloadall e /fmm updatecontent para o trabalho de ciclo de vida de pacotes oficiais
• Use a pasta imports para trabalho de importação manual de .bbmodel ou outro conteúdo local
• Use config.yml quando precisar ajustar o modo de renderização, distância de visibilidade, distância de interação, comportamento Bedrock, aplicação da proteção de região ou downloads automáticos de atualização
• Use skipUnchangedBoneUpdates, useDeltaMetadataPackets e maxModelsForProximityOverride para ajuste de pacotes/banda em mundos densos em modelos. Os três já vêm com o comportamento otimizado; as configurações false / valores muito altos existem para depuração e comparação A/B, não como valores recomendados de produção
• Use shop_config.yml (e os campos por receita shopEnabled/shopPrice) para ajustar a loja de mobília sem tocar em código

Ressalvas Conhecidas

• O comportamento Bedrock depende tanto de sendCustomModelsToBedrockClientsV2 quanto da sua configuração mais ampla de Floodgate/Geyser/resource pack, então mantenha afirmações conservadoras a menos que tenha testado sua stack exata.
• A loja se desabilita silenciosamente se o Vault ou um provedor de economia estiver faltando. Use /fmm version e verifique o console na inicialização se /fmm shop estiver inesperadamente ausente.