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

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

Blockbench-Kompatibilität

• FreeMinecraftModels erkennt die Blockbench-Dateiversion während des Imports
• Der aktuelle Importer enthält noch Kompatibilitätszweige für Versionen älter als Blockbench v5
• 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
• tag_...
  • wird als nametag-bezogene virtuelle Bones behandelt
• 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_... oder mount_...
  • 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 Montage-Bones erstellen mehrere Sitze. Intern verwaltet durch MountPointManager.

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

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
• Locator-Parsing

Wichtige praktische Einschränkung:

• Die IK-Controller-Suche ist namensbasiert, daher muss die Controller-Benennung zwischen der Modellstruktur und den Animationsdaten stabil bleiben

1.21.4+ Ausgabeaufteilung

Für Minecraft 1.21.4+ generiert FreeMinecraftModels Item-Modell-Definitionsdateien unter:

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

Ältere Versionen verwenden weiterhin den Legacy-Item-Modellpfad. Wenn du die generierte Ausgabe beim Erstellen überprüfst, stelle sicher, dass du die richtige Ausgabeform für deine Serverversion betrachtest.

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 — wenn gesetzt, ist das Modell auch ein benutzerdefiniertes Item
name: '&b&lMy Custom Sword'  # optional — Anzeigename
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 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_, mount_)
• 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                  <-- Konfiguration verwendet den Basisnamen, nicht _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.