FreeMinecraftModels Hinweise zur Modellerstellung

Diese Hinweise beschreiben die Modelldateien, Begleitdateien und Namen, die FreeMinecraftModels beim Import und zur Laufzeit liest.

Quellformate

FreeMinecraftModels akzeptiert derzeit:

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

Für eine einzelne .bbmodel ohne Begleitdateien:

1. Lege sie direkt in plugins/FreeMinecraftModels/imports ab und verwende die kleingeschriebene Endung .bbmodel
2. Führe /fmm reload aus
3. Prüfe, ob die konvertierte .fmmodel im aktiven Modellordner erscheint und das Neuladen erfolgreich war

Der Einzeldatei-Importer lässt das Original in imports, sodass spätere Importe es erneut konvertieren. Er übernimmt keine losen .json- oder .yml-Begleitdateien und akzeptiert keine einzelne .fmmodel. Bewahre selbst erstellte Modellsätze mit ihren Begleitdateien gemeinsam im aktiven models-Ordner auf oder verwende ein korrekt aufgebautes Inhaltspaket. Beliebige Unterordner in imports ohne pack.meta werden übersprungen. Ein abgelehntes Neuladen kann den bisherigen Katalog aktiv lassen; prüfe die Konsole.

Die Einzeldatei-Konvertierung behält bei Texturen nur source, id und name und verwirft Metadaten zu Animationsabmessungen und Zeitablauf. Sie erwartet außerdem ein textures-Array. Wenn diese Metadaten wichtig sind, verwende den aktiven Modellordner oder ein Paket, das die Originaldatei erhält. Der Laufzeit-Modellleser selbst akzeptiert ein fehlendes Texturarray.

Aufgaben der Ordner

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 Ordner Models haben. Zur Laufzeit bevorzugt FreeMinecraftModels den kleingeschriebenen Ordner models, sofern er existiert, und verwendet andernfalls Models. Auf einem Dateisystem ohne Unterscheidung der Groß- und Kleinschreibung verweisen beide Namen auf dasselbe Verzeichnis. Auf einem Dateisystem mit dieser Unterscheidung können beide gleichzeitig existieren. Der gemeinsame Paketimporter bevorzugt derzeit ein vorhandenes großgeschriebenes Ziel Models, während die Laufzeit aus models liest. Erstelle eine Sicherung und führe beide bei gestopptem Server im kleingeschriebenen Ordner models zusammen, damit Importe im aktiven Verzeichnis landen.

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 im aktiven Modellordner ignoriert Groß- und Kleinschreibung, sodass dort .BBModel und .FMModel akzeptiert werden. Der Einzeldatei-Import aus imports erkennt nur das kleingeschriebene .bbmodel

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. Sind alle Dateien mit dieser ID Byte für Byte identisch, etwa weil zwei Inhaltspakete dasselbe Modell mitliefern, lädt FMM die Datei, deren absoluter Pfad in der Sortierung zuerst kommt, und überspringt die Kopien ohne Warnung. Unterscheiden sich die Dateien:

• 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 ohne groups-Array wird ohne Zusammenführung weitergereicht. Ein bereits zusammengeführter Outliner kann funktionieren; unverarbeitete v5-Gruppenknoten ohne Namen können das Laden scheitern lassen, wenn der Skeleton-Leser einen Namen erwartet
  • 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, um Laufzeitkollisionen zu definieren. Eine verschachtelte hitbox wird wie ein gewöhnlicher Bone eingelesen, bleibt aber verborgen und definiert nicht die Hitbox des Modells
  • muss genau einen Cube enthalten, der Breite (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. Eine leere Gruppe protokolliert has a hitbox bone but no hitbox cube! und hinterlässt Abmessungen von null; sie verhält sich nicht wie eine fehlende Hitbox. Cube-Versatz und -Rotation werden nicht als Hitbox-Versatz übernommen: Der Parser verwendet absolute Seitenlängen und einen Modellversatz von null
  • 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_...
  • ein optionaler, im Modell definierter Anker für das Namensschild. Siehe Position des Namensschilds weiter unten
• h_...
  • wird als Kopf-Bones behandelt
• b_...
  • nicht dargestellte Bones in der Java-Laufzeit. Verwende für die Struktur Bones ohne Cubes: Der Bedrock-Geometrieexport filtert das Präfix b_ nicht, sodass Cubes auf solchen Bones dort sichtbar bleiben können
• m_...
  • Montagepunkt-Bones. Jeder Bone mit diesem Präfix erstellt einen Sitz für einen Spieler, verwaltet durch MountPointManager. Mehrere m_-Bones erstellen mehrere Sitze. Der Manager wählt den ersten freien Sitz und verwendet während der Belegung eine temporäre Interaction-Entität; seine öffentliche Mount-Methode akzeptiert Spieler, keine beliebigen Entitäten.

Die Präfixe unterscheiden Groß- und Kleinschreibung; der Name hitbox wird ohne diese Unterscheidung verglichen. Diese Namen beeinflussen Konvertierung und Laufzeitverhalten.

Position des Namensschilds

Ein tag_-Bone ist jetzt optional. FMM verwendet den alphabetisch ersten benannten tag_-Bone als Anker für das Namensschild des Modells. Ohne einen solchen Bone platziert es das Namensschild oberhalb der skalierten Hitbox. Auch ein Modell ohne Tag-Bone kann daher seinen Namen anzeigen.

Verwende einen tag_name-Bone ohne Cubes, wenn diese Standardposition ungeeignet ist. Mehrere Tag-Bones erzeugen keine mehrfachen Kopien desselben Namensschilds mehr.

Die API unterstützt mehrzeilige Namen, Skalierung, Zeilenabstand und Sichtbarkeit. Die Zeilen sind von oben nach unten angeordnet; die letzte Zeile liegt am Anker. Siehe die API-Anleitung.

Cube-Schattierung und Lichtemission

• Der Blockbench-Wert light_emission eines Cubes wird übernommen, wenn er eine ganze Zahl von 0 bis 15 ist. Jeder andere Wert wird mit einer Konsolenwarnung verworfen, die auf with invalid light_emission. Expected an integer from 0 to 15; ignoring this value. endet.
• Ein Cube mit ausgeschalteter Schattierung (shade: false) erhält in der erzeugten Geometrie zusätzlich shade_direction_override: "up", damit Clients mit Minecraft 26.3 ihn wie ältere Clients unschattiert darstellen. FMM wendet dieselbe Regel auf Cubes in einem begleitenden Anzeigemodell-.json an. Ein selbst gesetzter Wert bleibt erhalten

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. Locators können außerdem Blockbench-Partikeleffekte verankern; siehe Partikel

Ein Null-Objekt wird nur zum IK-Controller, wenn sein .bbmodel-Eintrag sowohl ik_source (Quell-Bone) als auch ik_target (Ziel-Bone oder Locator) enthält. Der Importer durchsucht die Hierarchie auch zwischen Geschwistern und nach unten. Geschwister auf Wurzelebene ergeben eine Kette nur aus der Quelle. lock_ik_target_rotation wird gelesen und gespeichert, vom aktuellen Solver aber nicht angewendet.

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 steuern IK. Ihr Versatz wird zur Ruheposition des Ziel-Bones oder Locators addiert, nicht zur gespeicherten Ruheposition des Controllers. Rotations- und Skalierungsspuren steuern IK nicht

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

Ausgabeaufteilung ab 1.21.4

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.

FMM liest das JSON neben der aktiven Modelldatei, kopiert es ins Ressourcenpaket und schreibt Werte ohne Namespace in dessen textures-Map um. Numerische Texturschlüssel entsprechen den Indizes der extrahierten Modelltexturen; bei einem nicht passenden Schlüssel dient eine verfügbare Textur als Ersatz, falls vorhanden. Werte mit Namespace bleiben unverändert. Ohne begleitendes JSON verwendet das Item das Aussehen seines Basismaterials: normalerweise Papier zum Platzieren eines Props oder das konfigurierte Material bei einem gehaltenen Item. Eine fehlerhafte Begleitdatei protokolliert Failed to process display model JSON for ... und registriert dieses Display-Modell nicht.

Benutzerdefinierte Item-Konfiguration in YML

Setze material in der begleitenden YAML-Datei des Modells, um ein gehaltenes Item zu registrieren:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

Verwende kleingeschriebene Verzauberungs-IDs mit Namensraum. Ledermaterialien akzeptieren ein RGB-Farbsuffix wie LEATHER_CHESTPLATE:ff8800; siehe Konfiguration. Ein Item mit einem nicht unterstützten Material, einer Verzauberung ohne Namensraum oder einer nicht leeren scripts:-Liste ist nicht verfügbar. Die Konsole nennt den Grund, und die Originaldatei bleibt erhalten. scripts: ist weiterhin ausschließlich für Props vorgesehen.

Andere ungültige Definitionen, etwa ein nicht boolesches isEnabled, fehlerhafte Verzauberungseinträge, doppelte Verzauberungen oder ein ungültiger Item-Dateiname, können den neuen Katalog und das Neuladen ablehnen lassen. Verwende kleingeschriebene Item-Dateinamen aus ausschließlich a-z, 0-9, ., _ und - mit höchstens 128 Zeichen. Die Suche nach selbst erstellten Items liest .yml, nicht .yaml. Registrierte Items erhältst du mit /fmm giveitem <item> oder im Admin-Browser; Prop-Rezepte und Shop-Käufe erzeugen Papier-Items zum Platzieren.

Item-Effekte gehören jetzt in Verzauberungsdefinitionen. Zauberstäbe und Magierstäbe verwenden die Konfiguration magischer Waffen. Beide verwenden die frühere Lua-Laufzeit für ausgerüstete Items nicht mehr.

Hinweise zu Bedrock und Rendering

• 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 Hinweise zur Modellerstellung

• 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_). Ergänze einen tag_-Anker nur, wenn die Standardposition des Namensschilds oberhalb der Hitbox ungeeignet ist
• Verwende die kleingeschriebenen Namen spawn, idle, walk, attack und death für die gemeinsamen Laufzeitzustände; Angriff und Tod benötigen weiterhin ihren Laufzeitauslöser, andere Namen einen expliziten Wiedergabeaufruf (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 erkennt Bogen- und Armbrust-Display-Zustände automatisch bei der Ressourcenpaket-Generierung. Jeder erforderliche Zustand braucht eine geladene Modelldatei und ein erfolgreich verarbeitetes begleitendes Display-.json; Dateinamen allein reichen nicht. Konfiguriere das gehaltene Item unter seinem Basisnamen mit dem passenden Material BOW oder CROSSBOW.

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 für die Dateianordnung

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

Ergänze für eine Armbrust auch cool_bow_charged.bbmodel und cool_bow_charged.json. Die Item-Konfiguration heißt cool_bow.yml und verwendet den Basisnamen ohne _idle.

Funktionsweise der Erkennung

• Die Erkennung erfolgt automatisch, wenn das Ressourcenpaket generiert wird (beim Start oder bei /fmm reload).
• Ein vollständiger Display-Zustandssatz bekommt eine öffentliche Item-Definition unter dem Basisnamen, beispielsweise cool_bow.json. Die einzelnen Item-Definitionen für _idle, Spann- und Ladezustände werden entfernt; ihre Geometrie bleibt in der Basisdefinition referenziert
• Die Display-Registrierung stellt die Basis-ID bereit und entfernt die Zustands-IDs. Ein vollständiger Satz mit _charged gilt als Armbrust, ohne diesen Zustand als Bogen. Fehlende Display-Zustände verhindern die Gruppierung
• Verwende den Basisnamen für die YML-Konfiguration, etwa cool_bow.yml. Der Item-Katalog überspringt YML-Dateien mit Zustandssuffix; die Prop-Konfigurationssuche entfernt das Suffix ebenfalls

JSON für das Anzeigemodell

Jeder erforderliche Zustand muss sein eigenes begleitendes Display-.json haben, etwa cool_bow_idle.json und cool_bow_draw_full.json. FMM verbindet sie über die generierte Basis-Item-Definition. Bedingungen und Ausgabepfad findest du unter Ressourcenpaket-Ausgabe.

Nicht behandelte Themen

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.