Zum Hauptinhalt springen

Java-zu-Bedrock-Konvertierung

ResourcePackManager kann das zusammengeführte Java-Ressourcenpaket in ein Bedrock-Ressourcenpaket umwandeln, damit GeyserMC-Clients dieselben benutzerdefinierten Inhalte wie Java-Clients sehen. Diese Funktion ist standardmäßig aktiviert.

Was konvertiert wird​

Der Konverter ist nicht mehr ausschließlich für FreeMinecraftModels gedacht. Er durchläuft zwei Pipelines hintereinander über das zusammengeführte Java-Paket:

  1. FreeMinecraftModels-Bone-Scanner — erfasst FMM-Bone-Modelle unter assets/freeminecraftmodels/models/ und wandelt jeden Bone in ein Bedrock-Attachable um.
  2. Generische Items-Definitions-Pipeline — durchläuft jede assets/<namespace>/items/*.json-Datei im Format 1.21.4+ (überspringt dabei die Namespaces minecraft und freeminecraftmodels). Für jedes Blattmodell wird entweder:
    • ein flaches Bedrock-Inventarsymbol ausgegeben (für einfache minecraft:item/generated- und ähnliche flach-eingebaute Eltern) oder
    • Bedrock-Geometrie, ein Attachable, eine Animationsdatei und ein softwaregerendertes 2D-Inventarsymbol ausgegeben (für echte 3D-Modelle).

Pro (Modell × Basis-Item)-Paar wird ein eindeutiger Bedrock-Identifikator erzeugt, sodass z. B. ein einzelnes Schwertmodell, das mehreren Basis-Items zugeordnet ist, auf der Geyser-Seite nicht kollidiert.

Benutzerdefinierte Rüstungssets werden erkannt, wenn eine benachbarte Datei assets/<namespace>/equipment/<material>.json existiert. Der Konverter verdrahtet ein Rüstungs-Attachable, das die Vanilla-Rüstungsgeometrie mit der Java-Textur als sichtbarer Schicht kombiniert, sodass Bedrock-Spieler beim Tragen des Items die richtige Rüstungstextur sehen.

Die Manifest-UUID des Bedrock-Pakets wird deterministisch aus dem Paketnamen abgeleitet und bleibt damit über alle Rebuilds stabil; nur das Versions-Tripel wird pro Build hochgezählt (Cache-Bust-Token aus der Build-Zeit abgeleitet).

Live-Auslieferung pro Session​

Wenn Geyser-Spigot erkannt wird, registriert ResourcePackManager einen SessionLoadResourcePacksEvent-Subscriber. Jeder Bedrock-Spieler, der nach einem frischen Mix beitritt, erhält das neueste Bedrock-Paket direkt von der Festplatte ausgeliefert; für Textur- oder Modellbearbeitungen ist kein Serverneustart erforderlich.

Geysers Mappings für benutzerdefinierte Items (das JSON in custom_mappings/) sind weiterhin beim Booten eingefroren, daher erfordert das Hinzufügen neuer oder das Entfernen bestehender Custom-Items einen Serverneustart, bevor Bedrock-Clients diese Änderungen sehen. RSPM stellt die Mapping-Datei des vorherigen Laufs früh beim Startup bereit, damit Geysers Custom-Item-Registrierung sie beim Booten automatisch aufgreift.

Aktuell verbundene Bedrock-Spieler behalten das Paket, das sie beim Beitritt erhalten haben — das ist eine Einschränkung des Bedrock-Protokolls, nichts, was das Plugin mitten in der Session überschreiben kann.

Ausgabedateien​

Nach einem erfolgreichen Mix liegen die Bedrock-Dateien in:

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json

Wenn Auto-Deploy aktiviert ist und Geyser erkannt wurde, wird die Mapping-Datei zusätzlich kopiert nach:

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Die Bedrock-Paket-ZIP wird nicht in <geyser-folder>/packs/ kopiert — sie wird stattdessen live pro Session ausgeliefert. RSPM entfernt außerdem jede Altkopie, die ältere Plugin-Versionen in diesem Ordner hinterlassen haben, damit Geyser das Paket nicht doppelt ausliefert (doppelte UUIDs würden den Bedrock-Client verwirren).

Einstellungen in config.yml​

# Schaltet die Java-zu-Bedrock-Konvertierung insgesamt ein/aus.
bedrockConversionEnabled: true

# Kopiert die Datei mit den benutzerdefinierten Geyser-Mappings bei jedem Mix
# in das Verzeichnis custom_mappings/ des erkannten Geyser-Ordners.
bedrockAutoDeployToGeyser: true

# Manuelle Überschreibung für den Geyser-Datenordner. Leer = automatische Erkennung.
# Kann absolut oder relativ zum Verzeichnis plugins/ sein.
bedrockGeyserFolder: ""

Die automatische Erkennung prüft in dieser Reihenfolge:

  1. bedrockGeyserFolder, falls gesetzt (wird zuerst als absoluter Pfad behandelt, dann als Pfad relativ zu plugins/).
  2. plugins/Geyser-Spigot/
  3. plugins/Geyser-*/ (jede Variante)
  4. config/Geyser-*/ (für Fabric-/NeoForge-Setups)

Feinjustierung der Anzeige gehaltener Items: bedrock_display_offsets.yml​

Bedrock rendert das gehaltene Item über einen Eltern-Bone, dessen Ruhepose von den Java-Transformationen für Ego- und Drittperson abweicht, sodass die algorithmische Konvertierung einen Basis-Offset zusätzlich zu dem anwenden muss, was die display-Transformation des Java-Modells vorgibt. Die Standard-Offsets funktionieren für typische rechtshändige Java-Modelle, aber Sonderfälle können Anpassungen erfordern.

Ego- und Drittpersonperspektive sind zwei vollständig getrennte Bedrock-Render-Durchläufe (unterschiedliche Eltern-Bones, unterschiedliche Ruheposen), daher hat jede ihren eigenen unabhängigen Satz von sechs Stellschrauben. Die eine zu tunen wirkt sich nicht auf die andere aus.

# ===== Egoperspektive (rechte Hand, vom Träger gesehen) =====
firstPersonBaseRotationX: -90.0   # pitch (Kippen zur Kamera hin/weg). Standardwert hebt die Eltern-Rotation auf.
firstPersonBaseRotationY: 0.0     # yaw (Drehung um die vertikale Achse)
firstPersonBaseRotationZ: 0.0     # roll (um die Achse Richtung Kamera)
firstPersonBasePositionX: 0.0     # vertikal auf dem Bildschirm (positiv = oben)
firstPersonBasePositionY: 12.5    # Tiefe (positiv = weiter in die Szene hinein)
firstPersonBasePositionZ: 0.0     # horizontal auf dem Bildschirm (positiv = rechts)

# ===== Drittpersonperspektive (rechte Hand, von anderen Spielern / F5 gesehen) =====
thirdPersonBaseRotationX: 90.0    # pitch wie Beobachter es sehen
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # roll um die Längsachse des Items
thirdPersonBasePositionX: 0.0     # horizontal quer zum Körper des Trägers (positiv = nach außen)
thirdPersonBasePositionY: 12.5    # vertikal (positiv = hebt das Modell an)
thirdPersonBasePositionZ: 0.0     # Tiefe relativ zum Träger (positiv = nach vorne)

Positionswerte sind in Pixeln angegeben, wobei 1 Pixel = 1/16 Block. Rotationen sind in Grad angegeben.

Der Bedrock-Client lädt Attachable-JSON live nach, ohne neu zu starten. Wenn ein Bedrock-Testclient eingeloggt ist, ändere den Wert, führe /rspm reload aus, und der nächste Bedrock-Beitritt (oder in manchen Fällen derselbe verbundene Spieler nach einer kleinen In-World-Aktion, die das Attachable neu bindet) zeigt den neuen Offset. Iteriere, bis es passt.

Einschränkungen und bekanntes Verhalten​

  • 3D-Inventarsymbole werden softwareseitig aus der display.gui-Transformation des Java-Modells gerendert. Das Ergebnis ist passabel, aber nicht pixelgenau; wenn das Symbol falsch aussieht, ist die häufigste Ursache eine fehlende/falsch benannte Texturdatei, auf die das Modell verweist.
  • Flipbook-Texturen, die als Item-Symbole verwendet werden, werden auf Frame 0 zugeschnitten — Bedrocks item_texture.json unterstützt keine animierten Symbole, sondern nur animierte Block-/Terrain-Texturen über flipbook_textures.json.
  • Die Geometrie-Formatversion von Attachables ist fest auf 1.21.0 festgelegt (war 1.16.0 in älteren Plugin-Versionen); aktualisiere Geyser, falls deine Installation sie nicht parsen kann.
  • Vanilla-Item-Modelle (shield.json, crossbow.json) werden nicht paketübergreifend rekursiv zusammengeführt, um eine paketübergreifende Beschädigung des Prädikatsbaums zu vermeiden; für diese beiden gewinnt speziell die Kopie des Pakets mit der höchsten Priorität.
  • Wenn der Konverter eine referenzierte Textur- oder Modelldatei nicht auflösen kann, wird dieses Blatt übersprungen und eine [BedrockConverter]-Warnung protokolliert; die restliche Pipeline läuft weiter.