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.

Wann die Konvertierung läuft​

Die Konvertierung ist daran gebunden, dass ein Bedrock-Ziel vorhanden ist. RSPM betrachtet ein Ziel als vorhanden, wenn eines der folgenden zutrifft:

  1. Geyser-Spigot ist auf diesem Backend installiert (Bedrock-Spieler treffen lokal auf Geyser).
  2. Floodgate ist auf diesem Backend installiert (typisches Proxy-Backend-Setup — Floodgate läuft lokal, Geyser ist anderswo).
  3. Der Netzwerkmodus ist aktiv — RSPM hat erkannt, dass es hinter einem Velocity-/BungeeCord-/Waterfall-Proxy läuft. Das Backend erzeugt sein Bedrock-Paket und stellt es über einen kleinen HTTP-Server bereit, damit das Proxy-Plugin es abholen kann.

Trifft keine dieser Bedingungen zu, ist der Konverter reiner Overhead und wird stillschweigend übersprungen. /rspm status erklärt genau, warum das Paket nicht erzeugt wurde.

Was konvertiert wird​

Der Konverter ist namespace-agnostisch. Er durchläuft jede assets/<namespace>/items/*.json-Datei im Items-Definitionsformat 1.21.4+. 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 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 Header-/Modul-UUIDs im Manifest des Bedrock-Pakets werden deterministisch aus dem Versionsstring des Plugins abgeleitet (Seeds rspm_bedrock_header:<pluginVersion> und rspm_bedrock_module:<pluginVersion>), sodass sie über Rebuilds derselben Plugin-Version stabil bleiben und sich nur ändern, wenn sich die Plugin-Version ändert. Der Paketname selbst wird nur für header.name verwendet, nicht für die UUID. Das Versions-Tripel wird pro Build aus einem Cache-Bust-Token hochgezählt, das aus einem SHA-256-Inhalts-Digest des bereitgestellten Bedrock-Pakets abgeleitet wird — identische Inhalte ergeben dieselbe Version (sodass No-Op-Rebuilds Geysers Cache nicht aufwirbeln), während echte Inhaltsänderungen Bedrocks über (uuid, version) indizierten Paket-Cache invalidieren. Die Build-Zeit (System.currentTimeMillis()) wird nur als Fallback verwendet, wenn der Inhalts-Digest nicht berechnet werden kann.

Live-Auslieferung pro Session (eigenständig)​

Wenn Geyser-Spigot auf demselben Backend erkannt wird, registriert RSPM 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 an bestehenden Items 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 zum Zeitpunkt ihres Beitritts erhalten haben — das ist eine Einschränkung des Bedrock-Protokolls, nichts, was das Plugin mitten in der Session überschreiben kann.

Wie es im Proxy-Modus funktioniert​

In einem Proxy-Netzwerk registriert das Backend selbst keinen SessionLoadResourcePacks-Subscriber (es gibt kein lokales Geyser, bei dem man sich registrieren könnte). Stattdessen:

  1. Das Backend erzeugt wie üblich output/ResourcePackManager_Bedrock.zip + output/rspm_geyser_mappings.json.
  2. Das Backend startet einen kleinen HTTP-Server (automatisch abgeleiteter Port, standardmäßig mcPort + 1), der die Routen /bedrock.zip und /mappings.json bereitstellt, die bei jeder Anfrage die Datei frisch einlesen, und kündigt dem Proxy den genauen Port an, an den es gebunden hat.
  3. Das Proxy-Plugin pollt alle 5 Sekunden per If-Modified-Since, lädt die Ausgaben jedes Backends herunter, wenn sie sich ändern, und wartet, bis der Posteingang stabil ist.
  4. Das Proxy-Plugin führt das Bedrock-Paket jedes Backends zu einem einzigen netzwerkweiten Paket zusammen und liefert es über das Geyser des Proxys an Bedrock-Clients aus.
  5. Wenn der Proxy den HTTP-Port eines Backends nicht direkt erreichen kann (häufig bei Shared-/Managed-Hosting, wo benachbarte Ports durch eine Firewall blockiert sind), schiebt das Backend seine Dateien an einen magmaguy.com-Relay-Endpunkt, und der Proxy holt sie dort ab.

Siehe Proxy-Netzwerke für die Einrichtung. Auf der Proxy-Seite läuft die Konvertierung (genauer: das Zusammenführen) vollautomatisch; es gibt keine proxy-seitige Konfiguration für die Bedrock-Pipeline.

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 auf derselben JVM erkannt wurde, wird die Mapping-Datei zusätzlich kopiert nach:

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Die Bedrock-Paket-ZIP wird nicht nach <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).

Wenn der Konverter nichts zu konvertieren findet (keine Items-Definitionen im zusammengeführten Paket), löscht RSPM jede veraltete Bedrock-Ausgabe eines vorherigen Laufs, anstatt ein leeres Paket auszuliefern. Die /bedrock.zip-Route des Backends gibt dann sauber 404 zurück, was für den Proxy das richtige Signal ist, dass dieses Backend keinen Bedrock-Inhalt beizusteuern hat.

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: ""

# Ausführliche Fortschrittsprotokollierung der Bedrock-Pipeline pro Item / pro Bone.
# Standard false — ein sauberer Lauf gibt eine einzige Zusammenfassung
# "Bedrock conversion complete: N mappings" aus statt dutzender bis hunderter
# Zeilen pro Item. Aktivieren, wenn ein konkretes Konvertierungsproblem
# untersucht werden soll.
bedrockConverterDebug: false

Die automatische Erkennung des Geyser-Ordners 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.

Debug-Protokollierung​

Es stehen zwei Debug-Oberflächen zur Verfügung:

  • Backend: bedrockConverterDebug: true in der config.yml aktiviert Protokollzeilen des Konverters pro Item, pro Attachable und pro Mapping. Nützlich, wenn du wissen musst, warum ein bestimmtes Item nicht ins Bedrock-Paket gelangt ist.
  • Proxy (Velocity und BungeeCord): /rspm debug bedrock on schaltet den [RSPM-BedrockDebug]-Log-Stream um, der vom GeyserBinder des Proxys ausgegeben wird. Nützlich, wenn Bedrock-Spieler den Proxy betreten, aber das Paket nicht sehen. Die Einstellung wird bei einem Proxy-Neustart auf „aus" zurückgesetzt, damit sie nicht versehentlich aktiviert bleiben kann.

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; aktualisiere Geyser, falls deine Installation sie nicht parsen kann.
  • Veraltete Vanilla-Item-Model-Override-Dateien (alles unter assets/minecraft/models/item/, einschließlich shield.json und crossbow.json) werden paketübergreifend zusammengeführt, statt ein Paket vollständig gewinnen zu lassen: Es werden nur die overrides-Arrays kombiniert (dedupliziert nach Override-Schlüssel), während Nicht-Override-Felder weiterhin „höchste Priorität gewinnt" folgen. Keine Datei wird für eine Sonderbehandlung herausgegriffen.
  • Wenn der Konverter eine referenzierte Textur- oder Modelldatei nicht auflösen kann, wird dieses Blatt übersprungen und eine [BedrockConverter]-Warnung protokolliert (oder eine Debug-Zeile, falls bedrockConverterDebug aus ist); die restliche Pipeline läuft weiter.
  • Wenn das zusammengeführte Paket null konvertierbare Items enthält, wird überhaupt kein Bedrock-Paket erzeugt und jede Ausgabe eines vorherigen Laufs wird gelöscht. RSPM liefert kein nutzloses ~22 KB großes leeres Paket mit Prompt aus.