Déguisements des joueurs

FreeMinecraftModels peut déguiser tout joueur en ligne en un modèle chargé. Les déguisements sont pilotés par des commandes, une DisguiseAPI publique et un PlayerDisguiseEntity par joueur qui gère l'invisibilité et le rendu du modèle pour le joueur déguisé.

Commandes

Commande	Permission	Notes
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Déguise l'expéditeur. Réservé aux joueurs
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.others	Déguise le joueur nommé. Fonctionne depuis la console
/fmm undisguise	freeminecraftmodels.disguise.self	Retire le déguisement de l'expéditeur. Réservé aux joueurs
/fmm undisguise <player>	freeminecraftmodels.disguise.others	Retire le déguisement du joueur nommé. Fonctionne depuis la console
/fmm disguiselist	freeminecraftmodels.disguise.others	Liste tous les joueurs déguisés et le modèle dont chacun est déguisé

Le wildcard freeminecraftmodels.* accorde admin, deleteall, disguise.self et disguise.others avec la valeur OP par défaut. Il accorde également la permission freeminecraftmodels.bypassregionprotection, enregistrée séparément.

Comportement

• Déguiser un joueur déjà déguisé remplace proprement le déguisement précédent — pas besoin de dé-déguiser d'abord.
• Le joueur déguisé est rendu invisible aux autres joueurs afin que seul le modèle soit visible. Le joueur déguisé continue de se voir normalement.
• L'invisibilité persiste à travers les seaux de lait, /effect clear, les suppressions d'effets de balise, la mort et la réapparition, ainsi que toute autre interaction ou plugin qui supprimerait normalement l'effet (elle est réappliquée au tick suivant par DisguiseEffectListener).
• La hitbox du joueur est inchangée. Le ciblage des mobs, la collision et le PvP fonctionnent tous comme d'habitude.
• Les déguisements ne survivent pas à un redémarrage de serveur, à un /fmm reload, ni à la déconnexion du joueur — ils sont suivis en mémoire et le gestionnaire DisguiseListeners.onQuit retire le déguisement sur PlayerQuitEvent. La mort et les changements de monde ne dé-déguisent pas le joueur.
• Lors de /fmm reload, tous les déguisements actifs sont démontés dans le cadre de l'arrêt du plugin. Les joueurs doivent être re-déguisés après un reload.

Animations de déguisement

Les déguisements n'utilisent pas la machine à états d'animation habituelle des entités modélisées. Chaque déguisement dispose de son propre contrôleur qui lit l'état du joueur déguisé à chaque tick et choisit une animation par son nom.

Cinq noms d'animation réservés sont reconnus, dans cet ordre de priorité (le plus élevé en premier) :

Priorité	Animation	Type	Déclenchée par
1	attack	coup unique	Le joueur donne un coup de bras
2	jump	coup unique	Le joueur quitte le sol en montant
3	sneak	boucle	Le joueur est accroupi
4	walk	boucle	Le joueur s'est déplacé de plus de ~0,01 bloc depuis le tick précédent
5	idle	boucle	Rien d'autre ne s'applique

Comportements à connaître :

• Seules les animations réellement présentes dans le modèle sont prises en compte. Un modèle sans animation sneak retombe simplement sur walk ou idle.

• Une animation à coup unique interrompt la boucle en cours et supprime les animations de priorité inférieure pendant une durée fixe de 20 ticks (1 seconde). Le système d'animation n'expose aucun callback de fin, il s'agit donc d'une borne supérieure supposée plutôt que de la durée réelle — gardez les animations attack et jump à une seconde ou moins si vous voulez un retour propre à la boucle.

• Les boucles ne sont réémises que lorsque l'animation choisie change réellement, donc une marche continue n'est pas redémarrée à chaque tick.

• jump est réellement câblé pour les déguisements, contrairement à l'état de saut (actuellement inerte) des entités modélisées classiques. Voir Animations.

• Un modèle de déguisement sans animation idle journalise un avertissement à chaque déguisement :

  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.

  Livrez une animation idle avec tout modèle que vous comptez utiliser comme déguisement.

Clients Bedrock

Les déguisements dépendent du rendu du modèle personnalisé par FMM. La valeur par défaut sendCustomModelsToBedrockClientsV2: true dans config.yml active l'envoi des modèles vers Bedrock d'emblée ; si vous la passez à false (ou si vous avez conservé l'ancien sendCustomModelsToBedrockClients: false), les joueurs Bedrock ne verront ni le modèle ni le joueur invisible sous-jacent — concrètement, ils ne verront rien là où le joueur déguisé se tient. Même avec l'option activée, il vous faut toujours une chaîne de resource pack compatible Bedrock (Floodgate + Geyser + resource pack converti) pour que le modèle s'affiche.

DisguiseAPI

Les plugins tiers peuvent piloter les déguisements programmatiquement via com.magmaguy.freeminecraftmodels.api.DisguiseAPI.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Déguiser (retourne false si l'ID de modèle n'est pas chargé)
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Dé-déguiser (retourne true si un déguisement a été retiré)
DisguiseAPI.undisguise(player);

// Requêtes
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null si non déguisé

// Snapshot non modifiable de tous les joueurs déguisés
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

L'API est le point d'entrée public, sûr face aux refactorisations. Les plugins devraient appeler DisguiseAPI plutôt que le DisguiseManager interne.

Cas d'utilisation courants

• Serveurs roleplay et RPG : déguisez les joueurs en modèles de boss pour les cinématiques ou scripts de quête.
• Hébergement d'événements : déguisez un annonceur en modèle personnalisé géant.
• Montures et véhicules : combinez /fmm mount avec /fmm disguise pour des configurations de transport créatives.
• Intégration EliteMobs : les scripts de boss peuvent déguiser le joueur qui a déclenché un événement pour un effet de transformation temporaire.

Dépannage

Rien ne se passe quand j'exécute /fmm disguise dragon. L'ID de modèle doit correspondre exactement à un modèle chargé. Vérifiez /fmm admin ou l'autocomplétion de la commande pour confirmer le nom du modèle. La forme ciblée vérifie freeminecraftmodels.disguise.others avant de résoudre le modèle ou le joueur et signale directement cette permission manquante.

Mon déguisement a disparu après /fmm reload. Attendu. Tous les déguisements sont démontés lors d'un reload. Écoutez FmmReloadedEvent si vous avez besoin de réappliquer les déguisements automatiquement.

Les joueurs Bedrock ne peuvent pas voir le déguisement. Voir Clients Bedrock ci-dessus.

Le joueur déguisé est toujours visible aux autres. L'invisibilité est appliquée comme un effet au niveau paquet. Si un autre plugin retire de force l'invisibilité à chaque tick (certains plugins anti-cheat le font), il peut entrer en conflit avec la réapplication de FMM. Whitelistez FMM ou désactivez la vérification conflictuelle.