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.self + 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.self + 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 utilisé par chacun

La permission générique freeminecraftmodels.*, accordée par défaut aux opérateurs, donne accès à admin, deleteall, disguise.self et disguise.others. Elle accorde également freeminecraftmodels.bypassregionprotection, enregistrée séparément.

Comportement

• Déguiser un joueur déjà déguisé remplace son déguisement précédent sans avoir à le retirer d'abord.
• FMM cache le joueur aux autres spectateurs avec setVisibleByDefault(false) et ajoute un effet de potion d'invisibilité si le joueur n'en possède pas déjà un. Des substitutions d'équipement masquent l'armure et les objets tenus aux autres spectateurs sans modifier l'inventaire. Elles excluent la vue du joueur lui-même ; le rendu de son propre corps dépend toujours du comportement de visibilité du client.
• FMM réapplique l'invisibilité un tick après les événements concernés de suppression ou de modification d'effet, ou après la réapparition, uniquement si ce déguisement a initialement ajouté l'effet. Il ne conserve ni ne restaure un effet d'invisibilité déjà présent au début du déguisement. Retirer le déguisement rétablit la visibilité par défaut à true, supprime l'effet ajouté par FMM et renvoie l'équipement actuel du joueur.
• Le masquage de l'équipement est renvoyé aux spectateurs qui se connectent et lors des changements de monde. Il ne remplace pas l'armure ni les objets réellement tenus par le joueur.
• La hitbox du joueur est inchangée. Le déguisement décoratif ne crée aucune entité d'interaction par paquets et ses gestionnaires de clic ne font rien : il n'offre donc aucune cible distincte pour attaquer ou monter. L'invisibilité peut affecter des comportements extérieurs à FMM ; le ciblage des mobs n'est pas garanti identique.
• Les déguisements ne survivent ni au redémarrage du serveur, ni à /fmm reload, ni à la déconnexion du joueur. Ils sont conservés en mémoire et DisguiseListeners.onQuit les retire sur PlayerQuitEvent. La mort et les changements de monde ne retirent pas le déguisement.
• Un /fmm reload réussi supprime les déguisements actifs pendant l'arrêt du plugin ; il faut ensuite les réappliquer. Un rechargement rejeté pendant la préparation du contenu candidat conserve l'exécution active.

Animations de déguisement

Chaque déguisement possède un contrôleur qui sélectionne les animations selon l'état du joueur avant l'exécution du moteur de lecture partagé des entités modélisées. Il ne contourne pas ce moteur. Les noms réservés doivent être en minuscules, car les vérifications d'existence des animations sont sensibles à la casse.

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	lecture unique	Le joueur donne un coup de bras
2	jump	lecture unique	Le joueur quitte le sol en montant
3	sneak	boucle	Le joueur est accroupi
4	walk	boucle	La position du joueur a changé de plus de 0,01 bloc depuis le tick précédent, déplacement vertical compris
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 à lecture unique demande une lecture immédiate sans boucle et suspend toute nouvelle sélection pendant exactement 20 ticks (1 seconde à 20 TPS). Ce compte à rebours ne mesure pas la durée de l'animation. Une animation plus longue peut être interrompue par la sélection suivante ; une animation plus courte peut finir avant la reprise des sélections. Les coups de bras pendant la pause sont regroupés en une seule attaque en attente, tandis que les transitions de saut ne sont pas mises en file d'attente.

• 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 fonctionne pour les déguisements, contrairement à l'état de saut actuellement inactif des entités modélisées ordinaires. Consultez les 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 reposent sur le rendu du modèle personnalisé par FMM. Dans config.yml, sendCustomModelsToBedrockClientsV2: true active par défaut l'envoi des modèles aux clients Bedrock. Passer cette clé à false empêche les spectateurs Bedrock de recevoir le modèle, alors que le joueur déguisé reste invisible. L'ancienne clé sendCustomModelsToBedrockClients n'est plus lue. Même avec V2 activé, le client a besoin du resource pack converti et d'une intégration Geyser/Floodgate fonctionnelle.

DisguiseAPI

Les plugins tiers peuvent piloter les déguisements programmatiquement 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();

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.

L'API ne vérifie pas les permissions des commandes et ne normalise pas les ID de modèles. Fournissez un joueur en ligne et l'ID exact d'un modèle chargé. disguise retire le déguisement existant avant de tenter de créer son remplaçant : un ID inconnu renvoie donc false après avoir retiré l'ancien déguisement. La commande vérifie d'abord le modèle et conserve le déguisement précédent si l'ID est invalide. Un retour positif de l'API confirme la création, pas le rendu côté client ni l'acceptation du resource pack.

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.
• Organisation d'événements : déguisez un présentateur 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. C'est normal après un rechargement complet réussi. Écoutez FmmReloadedEvent, planifié sur le thread principal 40 ticks après l'initialisation, pour réappliquer automatiquement les déguisements si nécessaire. Une préparation rejetée ne supprime pas l'exécution active.

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

Le joueur déguisé est toujours visible aux autres. Vérifiez si le joueur possédait déjà l'invisibilité au début du déguisement : FMM ne prend pas en charge cet effet et ne le rétablit pas s'il disparaît. Vérifiez également les plugins qui modifient la visibilité, les effets ou les paquets d'équipement. FMM utilise à la fois la visibilité du joueur, un véritable effet de potion et des substitutions d'équipement ; confirmez le conflit avant de modifier les paramètres d'un autre plugin.