Spieler-Verkleidungen

FreeMinecraftModels kann jeden Online-Spieler als geladenes Modell verkleiden. Verkleidungen werden über Befehle, eine öffentliche DisguiseAPI und eine pro-Spieler-PlayerDisguiseEntity gesteuert, die die Unsichtbarkeit und das Modell-Rendering für den verkleideten Spieler übernimmt.

Befehle

Befehl	Berechtigung	Hinweise
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Verkleidet den Sender. Nur Spieler
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.others	Verkleidet den genannten Spieler. Funktioniert von der Konsole
/fmm undisguise	freeminecraftmodels.disguise.self	Entfernt die Verkleidung des Senders. Nur Spieler
/fmm undisguise <player>	freeminecraftmodels.disguise.others	Entfernt die Verkleidung des genannten Spielers. Funktioniert von der Konsole
/fmm disguiselist	freeminecraftmodels.disguise.others	Listet jeden verkleideten Spieler und das Modell auf, als das er verkleidet ist

Die Wildcard freeminecraftmodels.* gewährt standardmäßig (OP) admin, deleteall, disguise.self und disguise.others. Sie gewährt außerdem die separat registrierte Berechtigung freeminecraftmodels.bypassregionprotection.

Verhalten

• Das Verkleiden eines bereits verkleideten Spielers ersetzt die vorherige Verkleidung sauber — kein vorheriges Enthüllen nötig.
• Der verkleidete Spieler wird für andere Spieler unsichtbar gemacht, sodass nur das Modell sichtbar ist. Der verkleidete Spieler sieht sich selbst weiterhin normal.
• Die Unsichtbarkeit bleibt durch Milcheimer, /effect clear, Beacon-Effekt-Lösungen, Tod und Wiederbelebung sowie jede andere Interaktion oder jedes Plugin erhalten, die den Effekt normalerweise entfernen würden (im nächsten Tick von DisguiseEffectListener erneut angewendet).
• Die Hitbox des Spielers bleibt unverändert. Mob-Zielerfassung, Kollision und PvP funktionieren wie gewohnt.
• Verkleidungen überleben weder einen Server-Neustart noch ein /fmm reload noch das Abmelden des Spielers — sie werden nur im Speicher verfolgt, und der Handler DisguiseListeners.onQuit entfernt die Verkleidung beim PlayerQuitEvent. Tod und Weltwechsel enthüllen den Spieler nicht.
• Bei /fmm reload werden alle aktiven Verkleidungen als Teil des Plugin-Shutdowns abgebaut. Spieler müssen nach einem Reload erneut verkleidet werden.

Verkleidungs-Animationen

Verkleidungen verwenden nicht die normale Animations-Zustandsmaschine modellierter Entitäten. Jede Verkleidung erhält ihren eigenen Controller, der den verkleideten Spieler in jedem Tick ausliest und eine Animation nach Namen auswählt.

Fünf reservierte Animationsnamen werden erkannt, in dieser Prioritätsreihenfolge (höchste zuerst):

Priorität	Animation	Typ	Ausgelöst durch
1	attack	einmalig	Der Spieler schwingt seinen Arm
2	jump	einmalig	Der Spieler verlässt den Boden in Aufwärtsbewegung
3	sneak	Loop	Der Spieler schleicht
4	walk	Loop	Der Spieler hat sich seit dem letzten Tick um mehr als ~0,01 Blöcke bewegt
5	idle	Loop	Nichts anderes trifft zu

Wissenswertes zum Verhalten:

• Es werden nur Animationen berücksichtigt, die das Modell tatsächlich besitzt. Ein Modell ohne sneak-Animation fällt einfach auf walk oder idle zurück.

• Eine einmalige Animation unterbricht den aktuellen Loop und unterdrückt Animationen niedrigerer Priorität für feste 20 Ticks (1 Sekunde). Das Animationssystem bietet keinen Abschluss-Callback, das ist also eine angenommene Obergrenze und nicht die tatsächliche Länge — halte attack- und jump-Animationen bei höchstens einer Sekunde, wenn du eine saubere Übergabe zurück an den Loop möchtest.

• Loops werden nur dann neu ausgelöst, wenn sich die gewählte Animation tatsächlich ändert, ein gleichmäßiges Gehen wird also nicht in jedem Tick neu gestartet.

• jump ist bei Verkleidungen wirklich angebunden, anders als der (derzeit wirkungslose) Jump-Zustand bei normalen modellierten Entitäten. Siehe Animationen.

• Ein Verkleidungsmodell ohne idle-Animation protokolliert bei jeder Verkleidung eine Warnung:

  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.

  Liefere eine idle-Animation mit jedem Modell aus, das du als Verkleidung einsetzen willst.

Bedrock-Clients

Verkleidungen verlassen sich darauf, dass FMM das benutzerdefinierte Modell rendert. Der Standardwert sendCustomModelsToBedrockClientsV2: true in config.yml aktiviert das Senden von Bedrock-Modellen von Haus aus; wenn du ihn auf false setzt (oder das ältere sendCustomModelsToBedrockClients: false übernommen hast), sehen Bedrock-Spieler weder das Modell noch den darunterliegenden unsichtbaren Spieler — sie sehen praktisch nichts an der Stelle, an der der verkleidete Spieler steht. Selbst bei aktiviertem Schalter brauchst du weiterhin eine Bedrock-kompatible Ressourcenpaket-Pipeline (Floodgate + Geyser + konvertiertes Ressourcenpaket), damit das Modell gerendert wird.

DisguiseAPI

Drittanbieter-Plugins können Verkleidungen programmatisch über com.magmaguy.freeminecraftmodels.api.DisguiseAPI steuern.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Verkleiden (gibt false zurück, wenn die Modell-ID nicht geladen ist)
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Enthüllen (gibt true zurück, wenn eine Verkleidung entfernt wurde)
DisguiseAPI.undisguise(player);

// Abfragen
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null, wenn nicht verkleidet

// Unveränderliche Momentaufnahme aller verkleideten Spieler
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

Die API ist der öffentliche, refactor-sichere Einstiegspunkt. Plugins sollten DisguiseAPI aufrufen statt des internen DisguiseManager.

Häufige Anwendungsfälle

• Rollenspiel- und RPG-Server: verkleide Spieler als Boss-Modelle für Filmsequenzen oder Quest-Skripte.
• Event-Hosting: verkleide einen Ansager als riesiges benutzerdefiniertes Modell.
• Reittiere und Fahrzeuge: kombiniere /fmm mount mit /fmm disguise für kreative Transport-Setups.
• EliteMobs-Integration: Boss-Skripte können den Spieler verkleiden, der ein Event ausgelöst hat, für einen vorübergehenden Verwandlungseffekt.

Fehlerbehebung

Es passiert nichts, wenn ich /fmm disguise dragon ausführe. Die Modell-ID muss exakt einem geladenen Modell entsprechen. Prüfe /fmm admin oder die Tab-Vervollständigung des Befehls, um den Modellnamen zu verifizieren. Die Variante mit Ziel prüft freeminecraftmodels.disguise.others, bevor Modell oder Spieler aufgelöst werden, und meldet die fehlende Berechtigung direkt.

Meine Verkleidung ist nach /fmm reload verschwunden. Erwartet. Alle Verkleidungen werden beim Reload abgebaut. Höre auf FmmReloadedEvent, falls du Verkleidungen automatisch erneut anwenden möchtest.

Bedrock-Spieler können die Verkleidung nicht sehen. Siehe Bedrock-Clients oben.

Der verkleidete Spieler ist für andere weiterhin sichtbar. Die Unsichtbarkeit wird als paket-basierter Effekt angewendet. Wenn ein anderes Plugin in jedem Tick die Unsichtbarkeit zwangsweise entfernt (einige Anti-Cheat-Plugins tun das), kann es FMMs Wiederanwenden behindern. Setze FMM auf die Whitelist oder deaktiviere die widersprüchliche Prüfung.