Disfarces de jogadores

O FreeMinecraftModels pode disfarçar qualquer jogador ligado ao servidor com um modelo carregado. Os disfarces são controlados por comandos, pela API pública DisguiseAPI e por uma PlayerDisguiseEntity por jogador, que trata da invisibilidade e da apresentação do modelo.

Comandos

Comando	Permissão	Notas
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Disfarça quem executa o comando. Apenas jogadores
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others	Disfarça o jogador indicado. Também funciona na consola
/fmm undisguise	freeminecraftmodels.disguise.self	Remove o disfarce de quem executa o comando. Apenas jogadores
/fmm undisguise <player>	freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others	Remove o disfarce do jogador indicado. Também funciona na consola
/fmm disguiselist	freeminecraftmodels.disguise.others	Lista todos os jogadores disfarçados e os respetivos modelos

A permissão global freeminecraftmodels.*, atribuída a operadores por predefinição, concede admin, deleteall, disguise.self e disguise.others. Também concede freeminecraftmodels.bypassregionprotection, que é registada separadamente.

Comportamento

• Aplicar um disfarce a um jogador já disfarçado substitui o anterior. Não é necessário removê-lo primeiro.
• O FMM oculta o jogador dos outros observadores com setVisibleByDefault(false) e adiciona um efeito de poção de invisibilidade se ainda não existir. As substituições de equipamento ocultam a armadura e os objetos nas mãos dos outros observadores, sem alterar o inventário. A vista do próprio jogador fica excluída dessas substituições; a apresentação do seu corpo continua a depender do comportamento de visibilidade do cliente.
• O FMM reaplica a invisibilidade um tick após os eventos relevantes de remoção ou alteração do efeito, ou após reaparecer, apenas se este disfarce tiver adicionado o efeito inicialmente. Não conserva nem restaura um efeito de invisibilidade que já existia ao aplicar o disfarce. Remover o disfarce repõe a visibilidade predefinida em true, remove o efeito adicionado pelo FMM e reenvia o equipamento atual do jogador.
• A ocultação do equipamento é reenviada para observadores que entram no servidor e nas mudanças de mundo. Não substitui a armadura nem os objetos realmente nas mãos do jogador.
• A hitbox do jogador não muda. O disfarce decorativo não cria uma entidade de interação por pacotes e os seus manipuladores de cliques não fazem nada, pelo que não oferece um alvo separado para atacar ou montar. A invisibilidade pode afetar comportamentos exteriores ao FMM; não há garantia de que a seleção de alvos dos mobs permaneça igual.
• Os disfarces são guardados em memória e não sobrevivem a um reinício, a /fmm reload ou à saída do jogador. DisguiseListeners.onQuit remove o disfarce em PlayerQuitEvent. A morte e as mudanças de mundo não o removem.
• Um /fmm reload bem-sucedido remove os disfarces ativos durante a desativação do plugin; é necessário voltar a aplicá-los. Um recarregamento rejeitado durante a preparação do conteúdo candidato mantém a execução ativa.

Animações dos disfarces

Cada disfarce tem um controlador que seleciona animações a partir do estado do jogador antes de executar o motor de reprodução partilhado pelas entidades com modelos. Não contorna esse motor. Os nomes reservados têm de estar em minúsculas, porque a verificação da existência das animações distingue maiúsculas de minúsculas.

São reconhecidos cinco nomes reservados, por ordem decrescente de prioridade:

Prioridade	Animação	Tipo	Ativação
1	attack	Execução única	O jogador balança o braço
2	jump	Execução única	O jogador sai do chão em movimento ascendente
3	sneak	Repetição	O jogador está agachado
4	walk	Repetição	A posição do jogador mudou mais de 0,01 blocos desde o último tick, incluindo deslocação vertical
5	idle	Repetição	Nenhuma das anteriores se aplica

Tenha em conta os seguintes comportamentos:

• Só são consideradas animações existentes no modelo. Sem sneak, por exemplo, o controlador passa a walk ou idle.

• Uma animação de execução única pede reprodução imediata sem repetição e suspende todas as novas seleções durante exatamente 20 ticks (1 segundo a 20 TPS). Esta contagem não mede a duração da animação. Uma animação mais longa pode ser interrompida pela seleção seguinte; uma mais curta pode terminar antes de as seleções retomarem. Os movimentos do braço durante a pausa ficam resumidos a um único ataque pendente, enquanto as transições de salto não ficam em espera.

• Uma animação em repetição só é novamente iniciada quando muda a animação escolhida. Uma caminhada contínua não recomeça a cada tick.

• jump funciona nos disfarces, ao contrário do estado de salto atualmente inativo nas entidades com modelos normais. Consulte Animações.

• Um modelo de disfarce sem idle gera o seguinte aviso sempre que é aplicado:

  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 todos os modelos que pretende usar como disfarce.

Clientes Bedrock

Os disfarces dependem da apresentação do modelo personalizado pelo FMM. A predefinição sendCustomModelsToBedrockClientsV2: true em config.yml permite enviar modelos para clientes Bedrock. Com false, esses clientes não recebem o modelo, mas o jogador disfarçado continua invisível. A antiga chave sendCustomModelsToBedrockClients deixou de ser lida. Mesmo com V2 ativa, o cliente precisa do pacote de recursos convertido e de uma integração Geyser/Floodgate funcional.

DisguiseAPI

Outros plugins podem controlar os disfarces através de 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();

Esta API é o ponto de entrada público, protegido das alterações de organização interna. Os plugins devem chamar DisguiseAPI em vez do DisguiseManager interno.

A API não verifica as permissões dos comandos nem normaliza os ID dos modelos. Passe um jogador ligado e o ID exato de um modelo carregado. disguise remove o disfarce existente antes de tentar criar o substituto, pelo que um ID desconhecido devolve false depois de remover o disfarce anterior. O comando verifica primeiro o modelo e conserva o disfarce anterior se o ID for inválido. Um resultado positivo da API confirma a criação, não a apresentação no cliente nem a aceitação do pacote de recursos.

Utilizações comuns

• Servidores de interpretação de personagens e RPG: disfarçar jogadores com modelos de bosses em sequências cinematográficas ou scripts de missões.
• Eventos: apresentar o anfitrião como um modelo personalizado gigante.
• Montadas e veículos: combinar /fmm mount com /fmm disguise para criar formas de transporte.
• Integração com EliteMobs: um script de boss pode disfarçar temporariamente o jogador que ativou um evento, produzindo um efeito de transformação.

Resolução de problemas

Nada acontece ao executar /fmm disguise dragon. O ID tem de corresponder exatamente a um modelo carregado. Confirme o nome em /fmm admin ou na conclusão do comando com Tab. A forma que indica um jogador verifica freeminecraftmodels.disguise.others antes de procurar o modelo ou jogador e identifica diretamente a falta dessa permissão.

O disfarce desapareceu após /fmm reload. É o comportamento esperado após um recarregamento completo bem-sucedido. Use FmmReloadedEvent, agendado na thread principal 40 ticks após a inicialização, para reaplicar automaticamente os disfarces quando necessário. Uma preparação rejeitada não encerra a execução ativa.

Os jogadores Bedrock não veem o disfarce. Consulte Clientes Bedrock.

Os outros jogadores continuam a ver o jogador disfarçado. Verifique se o jogador já tinha invisibilidade ao aplicar o disfarce: o FMM não assume esse efeito e não o restaura se desaparecer. Verifique também os plugins que alteram a visibilidade, os efeitos ou os pacotes de equipamento. O FMM usa a visibilidade do jogador, um efeito real de poção e substituições de equipamento; confirme o conflito antes de alterar as definições de outro plugin.