Zum Hauptinhalt springen

Geyser-Erweiterung & benutzerdefinierte Bedrock-Entities

Die Paketkonvertierung liefert unterstützte Item-Texturen und Modelle. Benutzerdefinierte Entities, etwa ein modellierter Boss mit eigener Darstellung und Animation, benötigen zusätzlich Code innerhalb von Geyser. Die RSPM-Geyser-Erweiterung bietet diese Integration für kompatible erzeugende Plugins und ihre Bedrock-Entity-Ressourcen.

Du lädst sie nicht separat herunter. Dieselbe ResourcePackManager.jar, die du als Plugin installierst, ist die Erweiterung.

Eine Jar, drei Rollen​

ResourcePackManager.jar ist gleichzeitig:

  • das Bukkit-/Paper-Backend-Plugin,
  • das Velocity- und BungeeCord-Proxy-Plugin,
  • und eine Geyser-Erweiterung.

Jeder Loader verwendet seinen passenden Einstiegspunkt. Ältere Releases lieferten eine separate ResourcePackManager-GeyserBridge.jar. Diese Datei ist ausgemustert. Findet der Installer sie, stellt er die universelle Jar über Geysers Update-Warteschlange zum Austausch beim Neustart bereit.

Wie sie installiert wird​

RSPM installiert die Erweiterung für dich, wo immer es kann. Was passiert, hängt davon ab, wo Geyser läuft:

Dein SetupWas RSPM tut
Geyser-Spigot auf demselben ServerKopiert bei der Erstinstallation die laufende Jar nach plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Unterscheiden sich die Bytes der vorhandenen Jar, wird unter Beachtung des Downgrade-Schutzes ein Ersatz in extensions/update/ bereitgestellt. Eine Neuinstallation oder ein vorbereiteter Ersatz meldet einen nötigen Neustart; eine identische aktuelle Jar muss nicht kopiert werden.
Geyser auf dem Proxy (Geyser-Velocity / Geyser-BungeeCord)Die Proxy-Rolle macht dasselbe im Ordner Geyser-*/extensions/ des Proxys.
Floodgate lokal, Geyser extern (Geyser läuft in einem separaten Prozess)Exportiert eine Kopie unter plugins/ResourcePackManager/geyser-extension/. Verwende den genauen Konsolenpfad; bei einem vorhandenen alten Export kann er auf den Unterordner update/ zeigen. Kopiere diese Jar in extensions/ des externen Geyser und starte Geyser neu. Der Export allein richtet weder externe Paketauslieferung noch das Laden der Definitionen beim Start ein.
Weder Geyser noch Floodgate vorhandenNichts zu tun — RSPM protokolliert eine Informationszeile und überspringt die Installation.

Der Installer bewahrt eine neuere gültige Version, die er in der installierten universellen Jar, der alten Bridge-Jar oder einem bereitgestellten Update findet. Er vergleicht auch Prüfsummen; geänderte Bytes bei gleicher Version können deshalb ebenfalls einen Austausch erfordern.

Die Installation erfordert immer einen Neustart. Geyser lädt Erweiterungen beim Start, daher bewirkt eine frisch kopierte oder bereitgestellte Jar nichts, bis der Server oder Proxy neu startet.

Die automatische Installation abschalten​

Jede Rolle hat ihren eigenen Schalter, und sie sind voneinander unabhängig:

WoEinstellungStandard
Backend plugins/ResourcePackManager/config.ymlgeyserExtensionAutoInstalltrue
Proxy config.ymlgeyser-extension-auto-installtrue

Einen der beiden auf false zu setzen hindert diese Rolle daran, die Erweiterung zu installieren oder ein Update dafür bereitzustellen, und sie protokolliert eine entsprechende Zeile. Lies die Semantik genau:

  • Es verhindert künftige Installationen und Update-Bereitstellungen.
  • Es entfernt keine installierte Jar und storniert kein bereits bereitgestelltes Update. Setze zum Deaktivieren der Bridge die betroffenen Einstellungen auf false und stoppe Geyser vollständig. Entferne ResourcePackManager.jar aus extensions/ und extensions/update/ sowie dort vorhandene alte ResourcePackManager-GeyserBridge.jar-Dateien. Starte Geyser danach erneut. Eine Kopie in der Warteschlange kann die Erweiterung beim Start wiederherstellen. Entferne nur diese RSPM-Dateien.
  • Das Abschalten der Einstellung wirkt sich weder auf die Paketkonvertierung und -auslieferung noch auf eine bereits installierte Erweiterung aus. Erst das Entfernen der Erweiterung deaktiviert die Integration benutzerdefinierter Bedrock-Entities; Item-Konvertierung und Paketauslieferung bleiben davon getrennt.

Das Abschalten auf dem Backend verhindert auch die Bereitstellung eines heruntergeladenen RSPM-Updates in der Warteschlange des lokalen Geyser-Spigot. Erweiterung und Plugin können dadurch auseinanderdriften. Halte ihre Artefakte manuell synchron; der folgende Kompatibilitätsschutz prüft benötigte Geyser-Klassen und binäre Kompatibilität, nicht die Versionsgleichheit von Plugin und Erweiterung.

Was die Erweiterung tatsächlich tut​

  • Registriert RSPMs benutzerdefinierte Bedrock-Entity-Definitionen bei Geyser beim Start, indem sie die Entity-Identifikatoren aus dem erzeugten Bedrock-Paket ausliest. Die Properties jeder Entity werden aus den Animations- und Render-Controllern gesammelt, auf die ihre Client-Entity-Datei verweist, zugeordnet über den Controller-Identifikator. So registrieren auch Bundles, deren lange Dateipfade gekürzt wurden, weiterhin ihre Properties und Animationen.
  • Tauscht die Bedrock-Definition spawnender Entities aus, sodass eine modellierte Entity als ihre benutzerdefinierte Bedrock-Entity spawnt statt als Vanilla-Fallback.
  • Wendet Live-Entity-Daten und Property-Overrides an, solange die Entity existiert.
  • Initialisiert Geysers Rezept-Netzwerk-IDs frühzeitig, was eine Klasse von Problemen mit kollidierenden Rezept-IDs auf Geyser 2.11 vermeidet.

Die Ressourcen stammen aus den unter Bedrock-Konvertierung beschriebenen Entity-Bundles. Ein Plugin liefert native Bedrock-Entity-Dateien unter assets/<namespace>/rspm_bedrock_pack/, und RSPM importiert sie in das erzeugte Paket. Das erzeugende Plugin muss die entsprechenden Java-Entities auch über die Bridge markieren. Ein Ressourcenpaket allein verwandelt keine beliebigen Entities in benutzerdefinierte Modelle.

Beim Start liest die Erweiterung Identifikatoren aus den Einträgen entity/*.entity.json im lokal erzeugten RSPM-Paket. Sie prüft zuerst die üblichen Proxy-Ausgaben plugins/resourcepackmanager/work/merged/Bedrock.zip und plugins/ResourcePackManager/work/merged/Bedrock.zip, dann die Backend-Ausgabe plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip, jeweils relativ zu Geysers Arbeitsverzeichnis. Ein externer Geyser-Prozess kann die Ausgabe eines anderen Rechners nicht automatisch lesen. Prüfe im Log, welches Paket vorgeladen wurde, statt aus dem Kopieren der Erweiterung auf vorhandene Definitionen zu schließen.

Geyser-Versionsanforderungen​

Die Erweiterung zielt auf Geyser 2.11+.

Ihr Deskriptor nennt Geyser-API-Level 2.9.0. Dieses niedrigere Level belegt keine Kompatibilität mit älterem Geyser. Zur Laufzeit prüft die Erweiterung die benötigten Klassen und deaktiviert die Bridge, wenn sie fehlen.

Bei Klassen- oder Linkage-Inkompatibilität soll sich die Erweiterung abschalten, ohne Geyser zum Absturz zu bringen. Ihr äußerer Teil referenziert nur langjährig stabile Geyser-API-Typen; versionsabhängige Klassen werden geprüft, bevor der Kern startet. Liefert dein Geyser-Build eine Klasse nicht mit, die die Bridge benötigt, deaktiviert sich die Bridge selbst und meldet das:

Disabled the RSPM custom Bedrock entity bridge: this Geyser build does not ship <class>. Geyser itself is unaffected, but custom Bedrock entities will not appear until a ResourcePackManager update matches this Geyser version.

Das Deaktivieren der Bridge schaltet weder den separaten Item-Konverter noch den Paketanbieter ab. Beide benötigen weiterhin ihre eigenen kompatiblen Geyser-APIs und eine erfolgreiche Paketauslieferung. Verwende ein kompatibles RSPM/Geyser-Paar, um benutzerdefinierte Entities wiederherzustellen.

Frühere RSPM-Versionen erreichten dasselbe Ergebnis, indem sie eine mitgelieferte Kopie eines von Geysers internen Paket-Übersetzern in Geysers Registry einschleusten. Dieser Übersetzer-Austausch ist Geschichte: Die Erweiterung nutzt jetzt die öffentlichen Entity-Lebenszyklus-/Events von Geyser 2.11 für Registrierung und den Austausch der Spawn-Definition. Der Kern prüft weiterhin eine begrenzte Menge an Geyser-Internas, die zum Erzeugen von Definitionsinstanzen und zum Empfang nachgelagerter Plugin-Nachrichten verwendet werden — deshalb sind der Kompatibilitätsschutz und die exakte Übereinstimmung der RSPM-/Geyser-Versionen weiterhin wichtig.

Reihenfolge: Warum manchmal ein Neustart nötig ist​

Geyser registriert Entity-Definitionen während seines Startfensters. Erzeugt RSPM das erste Bedrock-Paket erst danach, kommen die Definitionen für die laufenden Registries zu spät. RSPM fordert einen Neustart an, damit das erzeugte Paket beim nächsten Start vorgeladen werden kann:

RSPM custom Bedrock entity definitions became available after Geyser closed its startup registration windows ... restart the proxy once to activate the newly generated custom models.

Die Warnung erscheint, wenn nach dem Schließen der Registrierung ein neuer Entity-Identifikator oder ein neuer beziehungsweise geänderter Property-Typ hinzukommt. Ein erneuter Export derselben Definitionen und Property-Typen erfordert keinen Neustart.

Starte nach der ersten erfolgreichen Paketerzeugung den Server- oder Proxy-Prozess mit Geyser neu. Neuverbinden allein aktiviert keine Definitionen, die das Startfenster verpasst haben. Beim nächsten Start muss das erzeugte Paket am lokalen Lesepfad der Erweiterung liegen, und beide Registrierungsfenster müssen empfangen werden. Die Statuszeile beim Start zeigt, ob das geschehen ist.

Überprüfen, ob es funktioniert​

  1. Prüfe, ob der Ziel-Ordner extensions/ tatsächlich ResourcePackManager.jar enthält.
  2. Prüfe beim Start die Zeile RSPM Geyser bridge health. Sie enthält Erweiterungsversion, artifactSha256, activationRoute, loadedDefinitions, packUuid und definitionWindows. Bei einem Paket mit benutzerdefinierten Entities sollten Definitionen registriert sein, die vorgesehene Paket-UUID erscheinen und definitionWindows=observed gelten. MISSED oder RSPM GEYSER BRIDGE UNHEALTHY bedeutet ein verpasstes Registrierungsfenster. Eine als geladen angezeigte Erweiterung reicht nicht aus.
  3. Verbinde dich über Bedrock und prüfe Darstellung und Animation einer modellierten Entity. Bleibt sie ein Vanilla-Träger wie ein Rüstungsständer, prüfe Bridge-Aktivierung, Paketauslieferung an den Client, registrierte Definitionen und die Integration des erzeugenden Plugins. Ein erfolgreiches Startlog beweist allein keine Darstellung auf dem Client.

Fehlerbehebung​

„Erweiterung geladen, aber Entities sind immer noch Armor Stands." Das Paket und die Erweiterung sind zwei getrennte Hälften. Vergewissere dich zuerst, dass das Bedrock-Paket selbst den Client erreicht hat (siehe Bedrock-Konvertierung); ohne die Entity-Assets des Pakets gibt es für die Definitionen nichts zu rendern.

„Es hat funktioniert, dann habe ich Geyser aktualisiert und die Entities waren kaputt." Halte nach der oben genannten Selbstdeaktivierungs-Meldung Ausschau. Ein Geyser-Update kann die API-Oberfläche verschieben, nach der die Bridge sucht.

„Es wurde nie etwas in extensions/ installiert." Sieh in der Konsole nach Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall (Backend) oder ... by geyser-extension-auto-install (Proxy). Jemand hat den Schalter abgeschaltet. Sind Geyser und Floodgate beide lokal nicht vorhanden, siehst du stattdessen Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation — das ist RSPM, das korrekt entscheidet, dass es nichts gibt, worin installiert werden könnte.

„Ich habe RSPM aktualisiert, aber die Erweiterung ist immer noch die alte Version." Die Erweiterung wird nur beim Neustart ersetzt, und wenn RSPM sie über Geysers Update-Warteschlange bereitgestellt hat, braucht es einen Neustart, damit sie eingewechselt wird. Halte die Plugin-Jar und die Erweiterungs-Jar auf derselben Version — es ist dieselbe Datei, also genügt es, das Plugin erneut zu kopieren.

Die Erweiterung richtet neben ihren annotierten Handlern frühzeitige programmgesteuerte Lebenszyklus-Abonnements ein. Auf Velocity leitet das Proxy-Plugin zusätzlich Lebenszyklus- und Sitzungsereignisse weiter, um Startpfade mit verpassten automatischen Abonnements abzudecken. Dafür ist keine Konfiguration nötig. Nutze die Statuszeile beim Start sowie Registrierungs- oder Weiterleitungswarnungen, um Aktivierungsfehler einzugrenzen.

Nächste Schritte​