FreeMinecraftModels Hinweise zur Modellerstellung

Diese Seite dokumentiert die aktuellen Erstellungsdetails, die in der FreeMinecraftModels-Codebasis sichtbar sind. Sie ist absichtlich konservativ: Sie konzentriert sich auf den Import-/Laufzeitvertrag, nicht auf jede Blockbench-Workflow-Präferenz.

Quellformate

FreeMinecraftModels akzeptiert derzeit:

• .bbmodel-Dateien für editierbare Quellimporte
• .fmmodel-Dateien für reduzierte, laufzeitfertige Modelldaten

Der normale Import-Ablauf ist:

1. Platziere das Modell in plugins/FreeMinecraftModels/imports
2. Führe /fmm reload aus
3. Lass FreeMinecraftModels das Modell in den aktiven Modellsatz importieren und das generierte Ressourcenpaket neu erstellen

Ordnerrollen

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports ist der Eingangsordner für manuelle Modellimporte und offizielle Paket-Downloads vor der Verarbeitung
• models enthält aktive installierte Modellinhalte
• models_disabled enthält heruntergeladene oder installierte Paketinhalte, die derzeit deaktiviert sind

Ältere Installationen können stattdessen einen großgeschriebenen Models-Ordner haben. FreeMinecraftModels löst das auf, indem es das kanonische kleingeschriebene models bevorzugt, wenn es existiert, und nur auf das alte Models zurückfällt, wenn nicht. Unter Windows und macOS sind die beiden Namen ohnehin dasselbe Verzeichnis; auf einem Linux-Dateisystem mit Groß-/Kleinschreibung funktioniert eine alte Installation weiterhin, aber wenn beide Verzeichnisse existieren sollten, wird nur das kleingeschriebene models gelesen. Führe sie in models zusammen, falls du beide vorfindest.

Modell-IDs

• Laufzeit-Modell-IDs stammen vom Dateinamen, ohne die .bbmodel- oder .fmmodel-Endung
• Verwende stabile, eindeutige Dateinamen, da die ID das ist, wogegen Befehle und API-Aufrufe auflösen
• Blockbench-Animationsreferenzen sind namensbasiert, daher verursachen doppelte oder unklare Benennungen innerhalb des Modells eher Probleme als ein sauberes, explizites Benennungsschema
• Der Endungsabgleich ist unabhängig von der Groß-/Kleinschreibung, sodass .BBModel und .FMModel akzeptiert werden

ID-Normalisierung und Kollisionen

Der Dateiname wird normalisiert, bevor er zur Laufzeit-Modell-ID und zum Ressourcenpaket-Dateinamen wird:

1. kleingeschrieben
2. jedes Zeichen außerhalb von a-z, 0-9, ., _ und - wird durch _ ersetzt

My Table.bbmodel, my table.bbmodel und my_table.bbmodel normalisieren also alle zur selben ID my_table.

Bevor irgendeine Konvertierung läuft, durchsucht FreeMinecraftModels den gesamten Modellbaum und prüft auf Dateien, die zur selben ID normalisieren. Wird eine Kollision gefunden:

• wird jede kollidierende Datei abgelehnt — keine davon wird geladen, es gibt also kein stilles „die letzte gewinnt"
• ist die Modell-ID für den Rest dieses Ladedurchlaufs gesperrt
• werden abgelehnte Modelle auch vom Export des Bedrock-Custom-Entity-Bundles ausgeschlossen
• gibt die Konsole aus:

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

Die Lösung besteht immer darin, die Dateien so umzubenennen, dass die normalisierten IDs eindeutig sind. Die sicherste Gewohnheit ist, Modelldateien von Anfang an kleingeschrieben mit Unterstrichen zu benennen (stone_table.bbmodel), wodurch Dateiname und Laufzeit-ID identisch sind und keine Überraschungskollision entstehen kann.

Blockbench-Kompatibilität

• FreeMinecraftModels liest meta.format_version aus der .bbmodel und verzweigt anhand ihrer Major-Nummer
• Ein fehlender meta-Block, ein fehlendes format_version oder ein nicht parsbarer Wert fallen alle auf Version 4 zurück, mit einer Info-/Warnzeile, die das Modell benennt
• Ein fehlendes textures-Array wird akzeptiert und als leere Texturliste behandelt, statt den Importer abstürzen zu lassen. Der Bedrock-Custom-Entity-Exporter überspringt dieses Modell dann, weil der Bedrock-Export mindestens eine Textur benötigt
• Extrahierte Texturdateinamen werden auf eine einzige .png-Endung normalisiert. Ein Quellname wie body.jpg, body.PNG oder body wird als body.png geschrieben und referenziert
• format_version 4.x und älter: Bones werden direkt aus dem outliner-Baum gelesen, der die Bone-Namen inline mitführt
• format_version 5.x und neuer: Das Outliner-Schema hat sich geändert. outliner ist jetzt ein verschachtelter Baum aus reinen UUID-Strings und {uuid, isOpen, children}-Dicts ohne Namensschlüssel, während ein separates flaches groups-Array die eigentlichen Bone-Daten (einschließlich name) enthält. FMM verbindet beide über die UUID — jeder Outliner-Knoten wird durch seinen passenden groups-Eintrag ersetzt, dann werden die Kinder rekursiv zusammengeführt —, sodass Bone-Namen, Ursprünge und Rotationen normal aufgelöst werden
• Wissenswerte Konsequenzen beim Bearbeiten oder Erzeugen von .bbmodel-Dateien von Hand:
  • Eine v5-Datei, deren groups-Array fehlt, wird unverbunden durchgereicht, sodass ihre Bones ihre Namen verlieren und die reservierten Präfixe (tag_, h_, b_, m_, hitbox) nicht mehr erkannt werden
  • UUIDs müssen zwischen outliner und groups exakt übereinstimmen; ein Outliner-Knoten ohne passende Gruppe bleibt unverändert erhalten, statt entfernt zu werden
  • Mische nicht ein v5-format_version mit einem v4-förmigen Outliner oder umgekehrt — der Zweig wird anhand der deklarierten Version gewählt, nicht anhand der tatsächlichen Form
• Wenn Importprotokolle sagen, dass das Modellformat nicht mit FreeMinecraftModels kompatibel ist, behandle das zuerst als Modellformat-Problem, nicht als Wiki- oder Befehlsproblem

Laufzeitrelevante Bone-Konventionen

Die aktuelle Konverter- und Skeleton-Pipeline erkennt einige Namenskonventionen:

• hitbox
  • reserviert für Hitbox-Generierung
  • sollte die Modell-Hitbox sauber definieren, anstatt als visueller Bone verwendet zu werden
  • muss ein Bone auf oberster Ebene im Outliner sein. Der Importer prüft nur die Wurzelebene darauf; eine hitbox-Gruppe, die in einem anderen Bone verschachtelt ist, wird als gewöhnlicher Bone behandelt
  • muss genau einen Cube enthalten, der die Laufzeitbreite (x), -tiefe (z) und -höhe (y) definiert. Zusätzliche Cubes protokollieren has more than one value defining a hitbox! Only the first cube will be used; ein leerer Hitbox-Bone protokolliert has a hitbox bone but no hitbox cube! und es wird keine Hitbox erzeugt
  • wird nie animiert (Animationsspuren, die auf hitbox zielen, werden übersprungen), nie gerendert und ist vom Bedrock-Geometrieexport ausgeschlossen. Auf Bedrock fällt ein Modell ohne hitbox-Bone auf 1.0 x 2.0 zurück
• tag_...
  • die einzige Möglichkeit, dass ein Modell ein Namensschild bekommt. Siehe Namensschilder benötigen einen tag_-Bone weiter unten
• h_...
  • wird als Kopf-Bones behandelt
• b_...
  • Nicht-Anzeige-Bones (zur Laufzeit versteckt). Verwende diese für strukturelle oder organisatorische Bones, die im Spiel nicht gerendert werden sollen.
• m_...
  • Montagepunkt-Bones. Jeder Bone mit diesem Präfix erstellt eine reitbare Sitzposition auf dem Modell. Spieler oder Entities können zur Laufzeit auf diese Positionen montiert werden. Mehrere m_-Bones erstellen mehrere Sitze. Intern verwaltet durch MountPointManager.

Dies sind nicht nur Stilkonventionen; sie beeinflussen die Konvertierung und das Laufzeitverhalten.

Namensschilder benötigen einen tag_-Bone

Das ist die mit Abstand häufigste Ursache für ausgelieferte Inhalte mit namenlosen Mobs, daher unmissverständlich formuliert:

Ein Modell bekommt nur dann ein Namensschild, wenn es einen Bone enthält, dessen Name mit tag_ beginnt. Es gibt keinen Fallback.

So funktioniert es:

• Beim Import erhält jeder Bone namens tag_... einen parallelen, automatisch erzeugten „Meta"-Bone (fmm_nametag_bone_<name>), der als Namensschild-Bone markiert ist. Nichts sonst in der Pipeline setzt diese Markierung
• Zur Laufzeit sammelt das Skelett diese markierten Bones, und am Ursprung des tag_-Bones wird ein Text-Display gespawnt. Position und Text folgen diesem Bone
• ModeledEntity.setDisplayName(...) und setDisplayNameVisible(...) iterieren über diese Sammlung. Ohne tag_-Bone ist die Sammlung leer und beide Aufrufe tun still nichts — kein Fehler, keine Warnung, kein Name

Warum das Vanilla-Namensschild nicht einspringt:

• Ein dynamisches Modell verbirgt seine zugrunde liegende lebende Entität vor Clients (setVisibleByDefault(false) plus das Unsichtbarkeits-Flag), sodass auch das eigene Namensschild des Vanilla-Mobs nicht gerendert wird
• Unterm Strich ergibt das einen völlig namenlosen Mob, obwohl das aufrufende Plugin einen Anzeigenamen erfolgreich gesetzt hat

Praktische Regeln:

• Wenn ein Modell eine benannte Entität darstellt (einen EliteMobs-Boss, einen Quest-NPC, alles, worauf ein Plugin setDisplayName aufruft), füge einen tag_-Bone hinzu
• Platziere ihn dort, wo das Namensschild schweben soll — üblicherweise knapp über dem Kopf
• Der Bone benötigt keine Cubes; er ist ein Positionsanker. Insbesondere tag_name wird beim Erzeugen der Item-Modell-Definitionen übersprungen, sodass er nie als Geometrie gerendert wird
• Mehrere tag_-Bones sind erlaubt; jeder einzelne erhält sein eigenes Text-Display, das denselben Namen zeigt
• Wenn du nametag bone did not spawn name tag in der Konsole siehst, wurde der Bone erkannt, aber sein Text-Display konnte nicht gespawnt werden — das ist ein anderes Problem, als überhaupt keinen tag_-Bone zu haben

Freischwebende Cubes

Cubes, die oben im Outliner ohne umschließende Gruppe deklariert sind, kommen als reine UUID-Strings statt als Bone-Einträge an. FreeMinecraftModels hängt sie an den automatisch erzeugten Wurzel-Bone (freeminecraftmodels_autogenerated_root), damit sie trotzdem gerendert werden. Sie sind für Animationen nicht adressierbar, packe also alles, was du animieren willst, in eine echte Gruppe.

IK, Null-Objekte und Locators

Der aktuelle Code bestätigt Unterstützung für:

• Blockbench-Null-Objekte als IK-Controller
• IK-Ketten-Blueprints und Laufzeit-IK-Lösung (FABRIK)
• Locator-Parsing

Ein Null-Objekt wird nur dann zum IK-Controller, wenn sein .bbmodel-Eintrag beides trägt: ik_source (der Bone, an dem die Kette beginnt) und ik_target (der Bone oder Locator, nach dem die Kette greift). lock_ik_target_rotation wird ebenfalls gelesen. Die Kette wird ermittelt, indem die Bone-Hierarchie vom Target zur Source hinaufgelaufen wird, die beiden müssen also tatsächlich verbunden sein.

Wichtige praktische Einschränkungen:

• Die Verknüpfung von Source und Target erfolgt über die UUID, sie übersteht also Umbenennungen — aber wenn eine der beiden UUIDs im Modell fehlt, protokolliert die Konsole IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ... und diese Kette wird übersprungen
• Findet der Durchlauf keinen Pfad von Source zu Target, erhältst du Could not find path from source to target und die Kette wird übersprungen
• Die Animationssuche für einen Controller ist namensbasiert, daher muss die Controller-Benennung zwischen der Modellstruktur und den Animationsdaten stabil bleiben
• Nur Positions-Keyframes an einem Null-Objekt sind relevant — sie werden zum IK-Ziel-Offset. Rotations- und Skalierungsspuren an einem Null-Objekt werden ignoriert

Siehe Animationen dafür, wie IK pro Frame angesteuert wird.

1.21.4+ Ausgabeaufteilung

FreeMinecraftModels deklariert api-version: 1.21.4, 1.21.4 ist also die minimale Serverversion und das moderne Layout der Item-Modell-Definitionen ist das, welches du immer bekommst:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

Die Legacy-Zweige (vor 1.21.4) mit Leder-Pferderüstungs-Overrides existieren im Code weiterhin, aber kein Server, der das aktuelle Plugin laden kann, erreicht sie. Wenn du alte Notizen oder einen alten Ausgabeordner liest, ist das der Unterschied, den du siehst.

Display Model JSON (1.21.4+)

Administratoren können eine begleitende .json-Datei neben einer .bbmodel- oder .fmmodel-Datei mit dem gleichen Basisnamen platzieren (zum Beispiel table.bbmodel + table.json). Dieses JSON sollte aus Blockbench als "Java Block/Item"-Modell exportiert werden und definiert, wie das Item aussieht, wenn es in der Hand gehalten oder im Inventar angezeigt wird.

Beim Import kopiert FMM das JSON in die Ressourcenpaket-Ausgabe und schreibt automatisch alle einfachen Texturreferenzen darin um, damit sie auf die extrahierten Texturen des Modells zeigen. Wenn kein begleitendes JSON existiert, wird das Item im Spiel als einfaches Papier angezeigt.

Benutzerdefinierte Item-Konfiguration in YML

Die begleitende .yml-Konfigurationsdatei (gleicher Basisname wie das Modell) unterstützt jetzt optionale Item-Felder. Wenn material: gesetzt ist, ist das Modell auch als benutzerdefiniertes, haltbares Item verfügbar. Das vollständige YML-Format ist:

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

Wenn material: vorhanden ist, erscheint das Modell im Admin-Inhaltsbrowser neben Props und kann Spielern als funktionales Item gegeben werden.

Bedrock- und Rendering-Pfad-Hinweise

• Bedrock-Unterstützung hängt von sendCustomModelsToBedrockClientsV2 (Standard true; ersetzt den älteren Schlüssel sendCustomModelsToBedrockClients) und dem umgebenden Floodgate/Geyser/Ressourcenpaket-Pfad ab
• Java-Clients auf unterstützten Versionen können Display-Entity-Rendering verwenden, wenn useDisplayEntitiesWhenPossible aktiviert ist
• Gehe nicht davon aus, dass ein Modell, das auf einem Java-Client korrekt aussieht, automatisch für deinen Bedrock-Pfad sicher ist

Praktische Erstellungsratschläge

• Halte Dateinamen stabil, da sie zu Laufzeit-IDs werden
• Halte Controller- und Animationsbenennung explizit, da die Blockbench-Animationssuche namensgesteuert ist
• Verwende die reservierten virtuellen Bone-Namen bewusst (hitbox, tag_, h_, b_, m_) — und denke daran, dass jedes Modell, das einen Namen zeigen soll, einen tag_-Bone braucht, sonst bleibt es still namenlos
• Benenne Zustandsanimationen spawn, idle, walk, attack und death, wenn sie automatisch starten sollen; alles andere ist eine benutzerdefinierte Animation, die du selbst auslöst (siehe Animationen)
• Ein Modell, das für /fmm disguise gedacht ist, sollte mindestens idle mitbringen und kann sneak und jump ergänzen, die nur der Verkleidungs-Controller erkennt (siehe Spieler-Verkleidungen)
• Validiere importierte Ausgabe nach /fmm reload, nicht nur innerhalb von Blockbench
• Überprüfe die generierten Paketinhalte für deine Ziel-Minecraft-Version, insbesondere bei 1.21.4+

Bogen- und Armbrust-Zustandsmodelle

FMM unterstützt automatische Spannanimations-Zustände für benutzerdefinierte Bogen- und Armbrust-Items. Keine Konfiguration nötig -- benenne einfach deine Modelldateien mit den richtigen Suffixen und FMM erkennt den Zustandssatz automatisch während der Ressourcenpaket-Generierung.

Namenskonvention

Suffix	Zweck	Bogen	Armbrust
_idle	Item in der Hand, nicht gespannt oder geladen	erforderlich	erforderlich
_draw_start	Gerade angefangen zu spannen	erforderlich	erforderlich
_draw_half	Halb gespannt	erforderlich	erforderlich
_draw_full	Voll gespannt	erforderlich	erforderlich
_charged	Geladene Armbrust (Pfeil oder Rakete)	--	erforderlich

Ein Bogen benötigt vier Modelle (alle außer _charged). Eine Armbrust benötigt alle fünf.

Beispiel-Dateilayout

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

Für eine Armbrust würdest du eine fünfte Datei hinzufügen, cool_bow_charged.bbmodel.

Wie die Erkennung funktioniert

• Die Erkennung erfolgt automatisch, wenn das Ressourcenpaket generiert wird (beim Start oder bei /fmm reload).
• Nur das _idle-Modell bekommt eine Item-Definitions-JSON in der Ausgabe. Die Spann- und Ladezustände werden als bedingte Einträge innerhalb dieser Definition referenziert.
• Nur der Basisname bekommt eine YML-Konfigurationsdatei. Für das obige Beispiel ist die Konfiguration cool_bow.yml, nicht cool_bow_idle.yml.

Display Model JSON

Jedes Zustandsmodell kann sein eigenes begleitendes .json-Display-Modell haben (z.B. cool_bow_idle.json, cool_bow_draw_full.json). FMM integriert sie automatisch in die generierte Item-Definition. Siehe Ressourcenpaket-Ausgabe für die exakte JSON-Struktur, die generiert wird.

Außerhalb des Rahmens

Diese Seite versucht nicht zu garantieren:

• exakte Blockbench-UI-Schritte
• künstlerische Workflow-Präferenzen
• jede Legacy-.bbmodel-Eigenheit, die in älterem lokalem README-Material beschrieben wird

Diese Details ändern sich schneller als der oben verifizierte Laufzeitvertrag.