Player Disguises

FreeMinecraftModels can disguise any online player as a loaded model. Disguises are driven by commands, a public DisguiseAPI, and a per-player PlayerDisguiseEntity that handles invisibility and model rendering for the disguised player.

Commands

Command	Permission	Notes
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Disguises the sender. Player-only
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.others	Disguises the named player. Works from console
/fmm undisguise	freeminecraftmodels.disguise.self	Removes the sender's disguise. Player-only
/fmm undisguise <player>	freeminecraftmodels.disguise.others	Removes the named player's disguise. Works from console
/fmm disguiselist	freeminecraftmodels.disguise.others	Lists every disguised player and the model each is disguised as

The freeminecraftmodels.* wildcard grants all three permissions (admin, disguise.self, disguise.others) at OP default.

Behavior

• Disguising a player who is already disguised cleanly replaces the previous disguise — no need to undisguise first.
• The disguised player is made invisible to other players so only the model is visible. The disguised player still sees themselves normally.
• The invisibility persists through milk buckets, beacon effect clears, and other interactions that would normally strip the effect.
• The player's hitbox is unchanged. Mob targeting, collision, and PvP all work as usual.
• Disguises do not survive a server restart. They are tracked in memory only.
• On /fmm reload, all active disguises are torn down as part of plugin shutdown. Players need to be re-disguised after a reload.

Bedrock Clients

Disguises rely on FMM rendering the custom model. To make disguises visible to Bedrock players you must set sendCustomModelsToBedrockClients: true in config.yml and have a Bedrock-compatible resource pack pipeline (Floodgate + Geyser + converted resource pack). If that is not configured, Bedrock players will see neither the model nor the underlying invisible player — effectively, they see nothing where the disguised player is standing.

DisguiseAPI

Third-party plugins can drive disguises programmatically 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();

The API is the public, refactor-safe entry point. Plugins should call DisguiseAPI rather than the internal DisguiseManager.

Common Use Cases

• Roleplay and RPG servers: disguise players as boss models for cinematics or quest scripts.
• Event hosting: disguise an announcer as a giant custom model.
• Mounts and vehicles: combine /fmm mount with /fmm disguise for creative transport setups.
• EliteMobs integration: boss scripts can disguise the player who triggered an event for a temporary transformation effect.

Troubleshooting

Nothing happens when I run /fmm disguise dragon. The model ID must match a loaded model exactly. Check /fmm admin or /fmm stats to verify the model name. If the sender lacks freeminecraftmodels.disguise.others, FMM intentionally returns a generic "invalid entity ID" message even when the model exists — that is to avoid leaking the list of loaded model IDs to unauthorized players.

My disguise vanished after /fmm reload. Expected. All disguises are torn down on reload. Listen for FmmReloadedEvent if you need to re-apply disguises automatically.

Bedrock players cannot see the disguise. See Bedrock Clients above.

The disguised player is still visible to others. The invisibility is applied as a packet-level effect. If another plugin is force-removing invisibility every tick (some anti-cheat plugins do this), it can fight FMM's reapplication. Whitelist FMM or disable the conflicting check.