Disfarces de Jogadores

O FreeMinecraftModels pode disfarçar qualquer jogador online como um modelo carregado. Disfarces são controlados por comandos, uma DisguiseAPI pública e uma PlayerDisguiseEntity por jogador que cuida da invisibilidade e renderização do modelo para o jogador disfarçado.

Comandos

Comando	Permissão	Notas
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Disfarça o remetente. Somente jogador
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.others	Disfarça o jogador nomeado. Funciona pelo console
/fmm undisguise	freeminecraftmodels.disguise.self	Remove o disfarce do remetente. Somente jogador
/fmm undisguise <player>	freeminecraftmodels.disguise.others	Remove o disfarce do jogador nomeado. Funciona pelo console
/fmm disguiselist	freeminecraftmodels.disguise.others	Lista todos os jogadores disfarçados e o modelo de cada

O wildcard freeminecraftmodels.* concede admin, deleteall, disguise.self e disguise.others com padrão OP. Ele também concede a permissão freeminecraftmodels.bypassregionprotection, registrada separadamente.

Comportamento

• Disfarçar um jogador que já está disfarçado substitui o disfarce anterior de forma limpa — não é preciso retirar o disfarce primeiro.
• O jogador disfarçado fica invisível para outros jogadores, de forma que apenas o modelo seja visível. O jogador disfarçado continua se vendo normalmente.
• A invisibilidade persiste através de baldes de leite, /effect clear, limpezas de efeito por beacon, morte e respawn, e qualquer outra interação ou plugin que normalmente removeria o efeito (reaplicada no tick seguinte pelo DisguiseEffectListener).
• A hitbox do jogador não muda. Targeting de mobs, colisão e PvP funcionam normalmente.
• Disfarces não sobrevivem a uma reinicialização do servidor, a um /fmm reload ou ao jogador sair — eles são rastreados em memória e o handler DisguiseListeners.onQuit remove o disfarce no PlayerQuitEvent. Morte e mudanças de mundo não retiram o disfarce do jogador.
• Em /fmm reload, todos os disfarces ativos são derrubados como parte do desligamento do plugin. Jogadores precisam ser redisfarçados após um reload.

Animações de Disfarce

Disfarces não usam a máquina de estados normal de animação de entidades modeladas. Cada disfarce recebe seu próprio controlador, que lê o jogador disfarçado a cada tick e escolhe uma animação pelo nome.

Cinco nomes reservados de animação são reconhecidos, nesta ordem de prioridade (do maior para o menor):

Prioridade	Animação	Tipo	Acionada por
1	attack	disparo único	O jogador balança o braço
2	jump	disparo único	O jogador sai do chão movendo-se para cima
3	sneak	repetição	O jogador está agachado
4	walk	repetição	O jogador se moveu mais de ~0,01 bloco desde o último tick
5	idle	repetição	Nada mais se aplica

Comportamentos que vale conhecer:

• Apenas animações que o modelo realmente possui são consideradas. Um modelo sem animação sneak simplesmente cai para walk ou idle.

• Uma animação de disparo único interrompe a repetição atual e suprime animações de menor prioridade por 20 ticks (1 segundo) fixos. O sistema de animação não expõe nenhum callback de conclusão, então esse é um limite superior presumido, e não a duração real — mantenha as animações attack e jump em até um segundo se quiser um retorno limpo para a repetição.

• Repetições só são reemitidas quando a animação escolhida realmente muda, então uma caminhada contínua não é reiniciada a cada tick.

• jump está de fato implementado para disfarces, ao contrário do estado de jump (atualmente inerte) em entidades modeladas comuns. Veja Animações.

• Um modelo de disfarce sem animação idle registra um aviso a cada disfarce:

  Disguise model '<model>' has no 'idle' animation — disguised players using this model will freeze on the last animation frame whenever no other action is active.

  Inclua uma animação idle em qualquer modelo que você pretenda usar como disfarce.

Clientes Bedrock

Disfarces dependem do FMM renderizar o modelo customizado. O padrão sendCustomModelsToBedrockClientsV2: true em config.yml habilita o envio de modelos para Bedrock por padrão; se você definir como false (ou trouxe a chave antiga sendCustomModelsToBedrockClients: false), jogadores Bedrock não verão nem o modelo nem o jogador invisível subjacente — efetivamente, eles veem nada onde o jogador disfarçado está. Mesmo com o toggle ativado, você ainda precisa de um pipeline de resource pack compatível com Bedrock (Floodgate + Geyser + resource pack convertido) para o modelo ser renderizado.

DisguiseAPI

Plugins de terceiros podem controlar disfarces programaticamente via com.magmaguy.freeminecraftmodels.api.DisguiseAPI.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Disguise (returns false if the model ID is not loaded)
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Undisguise (returns true if a disguise was removed)
DisguiseAPI.undisguise(player);

// Queries
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null if not disguised

// Unmodifiable snapshot of all disguised players
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

A API é o ponto de entrada público e seguro para refatorações. Plugins devem chamar DisguiseAPI em vez do DisguiseManager interno.

Casos de Uso Comuns

• Servidores de roleplay e RPG: disfarce jogadores como modelos de chefes para cinemáticas ou scripts de quest.
• Hospedagem de eventos: disfarce um anunciante como um modelo customizado gigante.
• Montarias e veículos: combine /fmm mount com /fmm disguise para setups criativos de transporte.
• Integração com EliteMobs: scripts de chefe podem disfarçar o jogador que disparou um evento para um efeito de transformação temporária.

Solução de Problemas

Nada acontece quando rodo /fmm disguise dragon. O ID do modelo deve corresponder exatamente a um modelo carregado. Verifique /fmm admin ou o tab-complete do comando para conferir o nome do modelo. A forma com alvo verifica freeminecraftmodels.disguise.others antes de resolver o modelo ou o jogador e informa diretamente essa permissão ausente.

Meu disfarce sumiu após /fmm reload. Esperado. Todos os disfarces são derrubados em reload. Escute FmmReloadedEvent se você precisa reaplicar disfarces automaticamente.

Jogadores Bedrock não conseguem ver o disfarce. Veja Clientes Bedrock acima.

O jogador disfarçado ainda está visível para os outros. A invisibilidade é aplicada como efeito em nível de pacote. Se outro plugin está forçando a remoção da invisibilidade a cada tick (alguns plugins anticheat fazem isso), ele pode brigar com a reaplicação do FMM. Coloque o FMM em whitelist ou desabilite a verificação conflitante.