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.self + 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.self + 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.
• FMM verbirgt den Spieler vor anderen Betrachtern mit setVisibleByDefault(false) und fügt einen Unsichtbarkeitstrankeffekt hinzu, sofern noch keiner vorhanden ist. Ausrüstungsüberschreibungen verbergen Rüstung und gehaltene Gegenstände vor anderen Betrachtern, ohne das Inventar zu ändern. Die eigene Ansicht ist davon ausgenommen; wie der Client den eigenen Körper darstellt, hängt weiterhin von seinem Sichtbarkeitsverhalten ab.
• FMM wendet Unsichtbarkeit einen Tick nach entsprechenden Ereignissen zum Entfernen oder Ändern von Effekten oder nach dem Respawn erneut an, nur wenn diese Verkleidung den Effekt ursprünglich hinzugefügt hat. Ein bereits beim Verkleiden vorhandener Unsichtbarkeitseffekt wird weder erhalten noch wiederhergestellt. Das Entfernen der Verkleidung setzt die Standardsichtbarkeit auf true, entfernt einen von FMM hinzugefügten Effekt und sendet die aktuelle Ausrüstung erneut.
• Das Verbergen der Ausrüstung wird für neu beitretende Betrachter und bei Weltwechseln erneut gesendet. Die tatsächliche Rüstung und die gehaltenen Gegenstände bleiben unverändert.
• Die Hitbox des Spielers bleibt unverändert. Die dekorative Verkleidung erzeugt keine paketbasierte Interaktionsentität und ihre Klick-Handler tun nichts; sie bietet also kein separates Ziel zum Angreifen oder Aufsitzen. Unsichtbarkeit kann Verhalten außerhalb von FMM beeinflussen; unveränderte Mob-Zielerfassung ist nicht garantiert.
• 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.
• Ein erfolgreiches /fmm reload baut aktive Verkleidungen beim Herunterfahren ab; anschließend müssen Spieler erneut verkleidet werden. Ein während der Vorbereitung neuer Inhalte abgelehnter Reload erhält den aktiven Laufzeitzustand.

Verkleidungs-Animationen

Jede Verkleidung besitzt einen Controller, der Animationen anhand des Spielerzustands auswählt, bevor die gemeinsame Wiedergabe-Engine für modellierte Entitäten läuft. Sie umgeht diese Engine nicht. Reservierte Namen müssen kleingeschrieben werden, da die Prüfung auf vorhandene Animationen zwischen Groß- und Kleinschreibung unterscheidet.

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	Die Spielerposition hat sich seit dem letzten Tick um mehr als 0,01 Blöcke verändert, einschließlich vertikaler Bewegung
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 fordert sofortige Wiedergabe ohne Schleife an und pausiert jede neue Auswahl für feste 20 Ticks (1 Sekunde bei 20 TPS). Dieser Countdown misst nicht die Animationsdauer. Eine längere Animation kann durch die nächste Auswahl unterbrochen werden; eine kürzere kann vor Wiederaufnahme der Auswahl enden. Armschwünge während der Pause werden zu einem ausstehenden Angriff zusammengefasst, während Sprungübergänge nicht vorgemerkt werden.

• 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 setzen voraus, dass FMM das benutzerdefinierte Modell darstellt. Der Standardwert sendCustomModelsToBedrockClientsV2: true in config.yml aktiviert die Übertragung der Modelle an Bedrock-Clients. Bei false erreicht das Modell Bedrock-Betrachter nicht, während der verkleidete Spieler unsichtbar bleibt. Der eingestellte Schlüssel sendCustomModelsToBedrockClients wird nicht mehr gelesen. Auch bei aktiviertem V2 benötigt der Client das konvertierte Ressourcenpaket und eine funktionierende Geyser-/Floodgate-Integration.

DisguiseAPI

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

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();

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

Die API prüft keine Befehlsberechtigungen und normalisiert keine Modell-IDs. Übergib einen Online-Spieler und die exakte ID eines geladenen Modells. disguise entfernt die vorhandene Verkleidung, bevor es versucht, den Ersatz zu erstellen. Eine unbekannte ID liefert daher false, nachdem die alte Verkleidung entfernt wurde. Der Befehl prüft zuerst das Modell und erhält bei einer ungültigen ID die bisherige Verkleidung. Ein erfolgreicher API-Rückgabewert bestätigt die Erstellung, nicht die Darstellung beim Client oder die Annahme des Ressourcenpakets.

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. Das ist nach einem erfolgreichen vollständigen Reload zu erwarten. Höre auf FmmReloadedEvent, das 40 Ticks nach der Initialisierung auf dem Hauptthread eingeplant wird, um Verkleidungen bei Bedarf automatisch erneut anzuwenden. Eine abgelehnte Vorbereitung baut den aktiven Laufzeitzustand nicht ab.

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

Der verkleidete Spieler ist für andere weiterhin sichtbar. Prüfe, ob der Spieler bereits beim Verkleiden unsichtbar war: FMM übernimmt diesen Effekt nicht und stellt ihn nicht wieder her, wenn er verschwindet. Prüfe auch Plugins, die Spielersichtbarkeit, Effekte oder Ausrüstungspakete ändern. FMM verwendet sowohl Spielersichtbarkeit als auch einen echten Trankeffekt und Ausrüstungsüberschreibungen; bestätige den Konflikt, bevor du Einstellungen eines anderen Plugins änderst.