Proxy-Netzwerke (BungeeCord / Waterfall / Velocity)

ResourcePackManager läuft auf Proxy-Netzwerken. Es gibt eine Jar — ResourcePackManager.jar — und du installierst dieselbe Jar auf jedem Backend und auf dem Proxy. Auf einem Backend läuft sie in der Backend-Rolle (zusammenführen, hosten, senden, konvertieren); auf einem Velocity- oder BungeeCord-/Waterfall-Proxy erkennt dieselbe Jar automatisch den Plattform-Loader und läuft in der Proxy-Rolle (netzwerkseitige Bedrock-Auslieferung). Die beiden Rollen verbinden sich selbst: Der Proxy besitzt den Netzwerkschlüssel und schiebt ihn an jedes Backend, sobald dort zum ersten Mal ein Spieler verbindet — keine separate plattformspezifische Proxy-Jar, kein einzufügender Schlüssel.

Auf dieser Seite steht „das Proxy-Plugin" als Kurzform für dieselbe ResourcePackManager.jar, die in der Proxy-Rolle läuft.

Was das Proxy-Plugin tut

Die Aufgabe des Proxy-Plugins ist das Zusammenführen und Ausliefern von Bedrock-Paketen. In einem Netzwerk mit mehreren Backends erzeugt jedes Backend sein eigenes Bedrock-Paket (die konvertierte Version seines zusammengeführten Java-Pakets). Das Proxy-Plugin:

1. Pollt den kleinen HTTP-Server jedes Backends alle 5 Sekunden auf /bedrock.zip und /mappings.json, bevorzugt starke ETags mit If-None-Match und behält die If-Modified-Since-Kompatibilität für ältere Backends bei. Unveränderte Dateien liefern 304 zurück und kosten damit nahezu null Bandbreite. Jedes Backend kündigt den genauen HTTP-Port an, an den es gebunden hat, sodass der Proxy normalerweise automatisch den richtigen Port trifft (siehe Auflösung des Backend-HTTP-Ports).
2. Wartet, bis der Zustand des Posteingangs stabil ist — es führt zusammen, sobald zwei aufeinanderfolgende Polls denselben Satz von Datei-Hashes beobachten.
3. Führt das Bedrock-Paket jedes Backends zu einem einzigen netzwerkweiten Paket zusammen.
4. Kopiert, sofern Item-Mappings existieren, die zusammengeführte Datei mit den benutzerdefinierten Geyser-Mappings nach plugins/Geyser-*/custom_mappings/ auf dem Proxy.
5. Liefert das zusammengeführte Paket bei der Verbindung über Geysers SessionLoadResourcePacksEvent an Bedrock-Clients aus.

Das Proxy-Plugin ist nur für Bedrock-Spieler nützlich. Die Java-Paketauslieferung in Netzwerken erfolgt weiterhin pro Backend über die reguläre setResourcePack-/addResourcePack-API — Java-Clients sehen das Paket, das das Backend, auf dem sie sich befinden, zu senden gewählt hat. Wenn dein Netzwerk reines Java ist, brauchst du das Proxy-Plugin nicht.

Einrichtung — Ein Schritt (plus Floodgate, wenn du Bedrock willst)

Floodgate

Floodgate ist erforderlich, damit Bedrock-Spieler sich am Proxy authentifizieren können. Es ist nicht erforderlich, damit RSPM den Proxy mit seinen Backends verbindet — ein reines Java-Netzwerk kann das Proxy-Plugin völlig ohne Floodgate betreiben.

Wenn Floodgate zu dem Zeitpunkt, an dem RSPM dort zum ersten Mal bootet, doch auf dem Proxy installiert ist, initialisiert RSPM seinen Netzwerkschlüssel einmalig aus plugins/floodgate/key.pem, sodass ein bestehendes, bereits funktionierendes Netzwerk seine Identität über das Upgrade hinweg behält. Nach diesem ersten Boot liegt der Schlüssel in RSPMs eigener Datei network-key und key.pem wird nie wieder gelesen.

ResourcePackManager.jar auf den Proxy kopieren

Es gibt nur eine Jar. Dieselbe ResourcePackManager.jar, die du auf Bukkit-/Paper-Backends installierst, ist auch das Proxy-Plugin — sie liefert die Velocity- und BungeeCord-/Waterfall-Implementierungen gemeinsam in einer geshadeten Jar und erkennt automatisch, auf welcher Plattform sie läuft. Es gibt keine separate, plattformspezifische Proxy-Jar zum Extrahieren.

Wenn du die Backends bereits gestartet hast, ohne RSPM auf den Proxy zu legen, musst du nicht nach dem Download suchen: Jedes proxied, noch schlüssellose Backend legt eine byteweise identische Kopie seiner eigenen Jar unter plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar ab und gibt genau diesen Pfad in der Konsole aus. Diese Datei zu kopieren garantiert, dass Proxy und Backend niemals auf unterschiedlichen Versionen laufen können.

Kopiere dieselbe ResourcePackManager.jar in den plugins/-Ordner deines Proxys:

Proxy-Software	Diese Jar verwenden
Velocity	ResourcePackManager.jar
BungeeCord	ResourcePackManager.jar
Waterfall (Bungee-Fork)	ResourcePackManager.jar

Du kannst dies jederzeit von einem Backend aus bestätigen, indem du /rspm status ausführst; der Abschnitt Proxy deployment gibt Network proxy jar: ResourcePackManager.jar und Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall. aus.

Starte den Proxy neu. Das war's.

Es gibt keine erforderliche Konfiguration zu bearbeiten und keinen Schlüssel einzufügen. Der Proxy legt den Netzwerkschlüssel beim Booten selbst fest und versorgt jedes Backend automatisch damit — siehe Wie sich Proxy und Backends verbinden weiter unten. Die generierte Proxy-config.yml enthält nur zwei optionale Einstellungen, beide weiter unten beschrieben.

Der erste Poll des Proxys feuert ~2 Sekunden nach dem Booten, danach alle 5 Sekunden. In Kombination mit dem Stabilitäts-Gate über einen einzigen Zyklus wird der erste Merge rund 7 Sekunden nachdem der Proxy mindestens ein Backend sehen kann, das bereits Inhalt produziert, veröffentlicht.

Wie sich Proxy und Backends verbinden

Alles, was jetzt folgt, geschieht ohne Konfiguration. Es ist hier dokumentiert, weil das Wissen um diese Abfolge die gesamte Diagnose ausmacht, wenn sich ein Netzwerk nicht verbindet.

1. Der Proxy legt den Schlüssel fest. Beim Booten löst er genau einen Wert auf, in dieser Reihenfolge:

1. seine gespeicherte Datei network-key im eigenen Datenordner des Proxy-Plugins — der Normalzustand bei jedem Boot nach dem ersten;
2. eine einmalige Initialisierung, abgeleitet aus plugins/floodgate/key.pem auf dem Proxy, falls diese Datei existiert;
3. ein frisch erzeugter Zufallsschlüssel.

Welcher Zweig auch greift, das Ergebnis wird in network-key geschrieben und danach für immer wiederverwendet. Die Proxy-Konsole sagt, was passiert ist (Network key loaded ✓, adopted from Floodgate key.pem oder New network key generated). Wenn die Datei nicht geschrieben werden kann, protokolliert der Proxy einen Fehler auf [ERROR]-Ebene — dieser Zustand ist für den aktuellen Boot nicht fatal, aber beim nächsten Neustart wird ein anderer Schlüssel erzeugt, der stillschweigend jedes Backend abkoppelt. Behebe also die Ordnerberechtigungen.

2. Der Proxy schiebt den Schlüssel an jedes Backend. Sobald ein Spieler zu einem Backend verbindet, sendet der Proxy ihm den Schlüssel über den Plugin-Kanal rspm:network. Die Richtung ist Absicht: Ein Backend kann physisch nicht danach fragen, weil ein Proxy keine Plugin-Nachricht auf einem Kanal weiterleitet, den der Client des Spielers selbst nie registriert hat.

3. Das Backend übernimmt und speichert ihn. Es sichert den Schlüssel in seiner data.yml und meldet Network key received from the proxy; this backend is now linked. Zuweisungen werden nur akzeptiert, solange das Backend noch keinen Schlüssel besitzt — ein bereits etabliertes Backend protokolliert eine Warnung und behält das, was es hat, statt sich von einer Nachricht auf ein anderes Netzwerk umlenken zu lassen.

Auf Velocity mit modernem Forwarding werden Zuweisungen mit einem HMAC über das forwarding.secret des Proxys signiert, und ein für modernes Forwarding konfiguriertes Backend verlangt diese Signatur. Auf BungeeCord, Waterfall und mit Legacy-Forwarding gibt es kein gemeinsames Geheimnis zum Signieren, daher sind Zuweisungen unsigniert und werden auch so akzeptiert.

Ein Backend, das Schritt 2 erreicht, aber nie Schritt 3, behält als Schlüsselquelle not set. Genau dieser Zustand löst das Ablegen unter proxy-extension/ und das Bedrock-spezifische Warnbanner aus.

Verifizieren, dass es funktioniert

Proxy-Konsole

Innerhalb von ~10 Sekunden nach dem Neustart (vorausgesetzt, die Backends laufen) solltest du Folgendes sehen:

[ResourcePackManager] Network key loaded ✓
[ResourcePackManager] Network key provisioning ready on rspm:network; backends are keyed as players connect.
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/rspm status auf dem Proxy

Gibt eine Momentaufnahme aus: Fingerabdruck des Netzwerkschlüssels, Backend-Liste, Abrufergebnisse pro Backend und pro Pfad (200 / 304 / 404 / CONNECT_FAILED) für /bedrock.zip, /mappings.json und /rspm-update.jar, die empfangenen Endpunkt-Ankündigungen, die sichtbaren Relay-Einträge, den Zähler aufeinanderfolgender leerer Polls, ob das zusammengeführte Bedrock-Paket und die zusammengeführten Mappings auf der Festplatte liegen (mit ihren Größen) sowie das SHA-1-Präfix des aktuellen zusammengeführten Pakets, den network-http-offset-Fallback, den erkannten Geyser-Plugin-Ordner und die bereitgestellte Mappings-Datei sowie die Floodgate-/Geyser-Präsenz auf dem Proxy. Velocity akzeptiert resourcepackmanager.command.status oder resourcepackmanager.*; BungeeCord registriert exakt den Knoten resourcepackmanager.command.status, den Berechtigungs-Plugins über Wildcard-Erweiterung erfüllen können. Die Konsole kann den Befehl ausführen. Die Ausgabe enthält keine Geheimnisse (der Netzwerkschlüssel erscheint nur als kurzer Einweg-Hash-Fingerabdruck, und es werden keine Auth-Tokens ausgegeben), daher sind großzügige Vergaben unbedenklich.

/rspm status auf einem Backend

Die Zeile Deploy mode sollte network-backend anzeigen. Network key fingerprint sollte einen kurzen Hash zeigen — er muss mit dem Fingerabdruck übereinstimmen, den der Proxy ausgibt. Network key source sagt dir, wie dieses Backend an den Schlüssel gekommen ist:

Quellzeile	Bedeutung
provided by the proxy	Der normale verbundene Zustand. Der Proxy hat den Schlüssel bei einer Spielerverbindung zugewiesen.
saved on this server	Bereits bei einem früheren Boot verschlüsselt (oder ein Standalone-Server, der sich seinen eigenen erzeugt hat).
adopted from Floodgate's key	Einmalig aus der lokalen plugins/floodgate/key.pem dieses Backends initialisiert.
not set — the proxy sends one when a player next connects here	Nicht verbunden. Entweder hat seit dem Start des Proxys niemand verbunden, oder auf dem Proxy fehlt RSPM / es ist ein nicht unterstützter Proxy.

Bedrock-Client

Verbinde dich über Bedrock. Du solltest die Aufforderung zum Herunterladen des Ressourcenpakets sehen, bevor du die Welt erreichst. Custom-Items werden mit ihren beabsichtigten Modellen dargestellt statt mit schlichten Rüstungsständern.

Konfigurationsreferenz

Backend plugins/ResourcePackManager/config.yml

Der Netzwerkmodus wird automatisch erkannt — es gibt kein networkMode: true-Flag zu setzen. Erkennungssignale (eines genügt):

1. Floodgate vorhanden, Geyser-Spigot nicht vorhanden — stärkstes Signal für den Bedrock-über-Proxy-Fall.
2. spigot.yml: settings.bungeecord: true — der ältere BungeeCord-/Waterfall-IP-Forwarding-Schalter.
3. paper-global.yml: proxies.velocity.enabled: true — modernes Velocity-Forwarding.

Die einzige Stellschraube, die speziell für den Netzwerkmodus relevant ist, ist networkHttpOffset-v2, die den Fallback-HTTP-Port steuert, den der Proxy auf jedem Backend pollt (der Port, den der Proxy vermutet, bevor ein Backend den tatsächlich gebundenen Port angekündigt hat). Standard 1 funktioniert auf praktisch jedem Hosting. Siehe Selbst-Hosting für die vollständige Geschichte zur Port-Auflösung.

Im Normalbetrieb kündigt jedes Backend dem Proxy seinen echten HTTP-Port automatisch an (über die magmaguy.com-Endpunkt-Registry), sodass der Offset nur als Start-/Fehler-Fallback herangezogen wird. Siehe Auflösung des Backend-HTTP-Ports weiter unten.

Proxy config.yml

Das Proxy-Plugin schreibt beim ersten Booten eine minimale Standardkonfiguration. Der Ordner unterscheidet sich je nach Plattform, weil jeder Proxy ihn aus seiner eigenen Plugin-Kennung ableitet:

Proxy-Software	Konfigurationspfad
Velocity	plugins/resourcepackmanager/config.yml
BungeeCord / Waterfall	plugins/ResourcePackManager/config.yml

Sie enthält genau zwei Einstellungen, beide optional:

# FALLBACK offset added to each backend's Minecraft port to derive the HTTP
# port this proxy will hit for /bedrock.zip and /mappings.json BEFORE that
# backend has announced its real ResourcePackManager HTTP port. Default 1.
# In normal operation the backend announces the exact port it bound, so this
# value is only used at startup or if announcement fails — but if it IS used,
# it should match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

# Installs and updates this universal ResourcePackManager.jar in the proxy's
# Geyser extensions folder, which is what makes custom Bedrock ENTITIES render.
# Default true. Setting it to false stops future installation and update
# staging; it does not delete an extension jar that is already installed —
# remove that by hand while Geyser is stopped.
geyser-extension-auto-install: true

Die Backend-Entsprechungen sind networkHttpOffset-v2 und geyserExtensionAutoInstall in der Backend-config.yml. Die beiden Seiten sind getrennte Einstellungen — die Erweiterungsinstallation auf dem Proxy abzuschalten schaltet sie nicht auf den Backends ab und umgekehrt.

Neben der config.yml schreibt das Proxy-Plugin im selben Ordner auch eine Datei network-key. Das ist generierter Zustand, keine Konfiguration: Bearbeite sie nicht und kopiere sie nicht zwischen verschiedenen Netzwerken. Sie zu löschen führt dazu, dass der Proxy beim nächsten Boot einen brandneuen Schlüssel erzeugt, was jedes bereits versorgte Backend abkoppelt (jedes Backend behält den alten Schlüssel und übernimmt keinen Ersatz). Sie zu kopieren ist nur in einem einzigen Fall das richtige Vorgehen: zwei Proxys vor demselben Satz von Backends, die sich einen Schlüssel teilen müssen.

Es gibt keine proxy-seitige Einstellung force-resource-pack. Das Erzwingen der Paketannahme ist eine Backend-Entscheidung (forceResourcePack in der Backend-config.yml), weil das Proxy-Plugin nur die Bedrock-Paketauslieferung übernimmt — es sendet nie Java-Pakete. Trägt eine ältere Proxy-config.yml noch eine force-resource-pack-Zeile, wird sie schlicht ignoriert und kann gelöscht werden.

Es gibt absichtlich keinen Konfigurationseintrag network-key — ein einfügbarer Schlüssel wurde vor dem Release abgeschafft, weil Tippfehler die Proxy↔Backend-Verbindung stillschweigend zerstörten, ohne dass irgendwo ein Fehler auftauchte. Der Schlüssel wird vom Proxy festgelegt und automatisch an die Backends verteilt, wie unter Wie sich Proxy und Backends verbinden beschrieben.

Auflösung des Backend-HTTP-Ports

Der Proxy muss wissen, welchen HTTP-Port er auf jedem Backend für /bedrock.zip und /mappings.json pollen soll. Er löst diesen Port in dieser Reihenfolge auf:

1. Vom Backend angekündigter Endpunkt (bevorzugt). Jedes Backend lädt den genauen gebundenen HTTP-Port in die magmaguy.com-Endpunkt-Registry hoch, indiziert nach dem Netzwerkschlüssel. Bei jedem Poll aktualisiert der Proxy diese Liste und ordnet den angekündigten Port eines Backends dem Server-Listen-Eintrag über den Minecraft-Port zu (und den Host, wenn verfügbar). Das bedeutet, dass ein Admin, der auf einem Backend einen expliziten selfHostPort setzt oder dessen Backend automatisch auf mcPort + 1 landet, identisch behandelt wird — der Proxy verwendet, woran das Backend tatsächlich gebunden hat.
2. mcPort + network-http-offset-v2 (Fallback). Wird nur verwendet, wenn keine passende Ankündigung verfügbar ist (z. B. beim ersten Poll, bevor ein Backend etwas angekündigt hat, oder wenn die Endpunkt-Registry kurzzeitig nicht erreichbar ist). Deshalb sollten die beiden Offsets weiterhin übereinstimmen, wenn du dich auf den Fallback verlässt.

Der Proxy port-scannt ein Backend bewusst nicht als Fallback — das sieht für den Host nach missbräuchlichem Verhalten aus. Wenn ein direkter Abruf überhaupt nicht möglich ist, ist der Relay-Pfad (unten) die kategorische Antwort.

/rspm status auf dem Proxy zeigt pro Backend, welcher Port gewählt wurde und ob er aus einer Ankündigung oder dem Offset-Fallback stammt.

Stabilität und Merge-Takt

Der Proxy wartet, bis der Zustand des Posteingangs stabil ist, bevor er zusammenführt: Der erste Poll legt den Basissatz der Datei-Hashes fest, und der nächste Poll, der denselben Satz beobachtet, löst den Merge aus (ein Stabilitäts-Gate über einen Zyklus). Mit der ~2 s langen Anfangsverzögerung und dem 5 s langen Poll-Intervall liegt der erste Merge ~7 s nachdem der Proxy mindestens ein Backend sehen kann, das Inhalt produziert. Nachfolgende Merges zippen nur dann neu, wenn sich der SHA-1-Satz der Posteingangsdateien ändert, sodass eine lange ruhige Phase praktisch nichts kostet.

Backends schreiben ihre bedrock.zip in eine temporäre Datei und benennen sie atomar um, sodass die /bedrock.zip-Route immer eine vollständige ZIP ausliefert — der Proxy muss sich nie gegen halb geschriebene Lesevorgänge absichern, weshalb das Gate ein einzelner Zyklus statt zwei ist.

Direkter Abruf vs. Relay-Fallback

Der Standardpfad ist der direkte Abruf: Der Proxy macht für jedes Backend ein HTTP-GET an http://<backend-host>:<mcPort + offset><path>.

Wenn der Proxy den HTTP-Port eines Backends nicht direkt erreichen kann (typisch für Shared-/Managed-Minecraft-Hosting, wo MC-Ports freigegeben sind, benachbarte Ports aber durch eine Firewall blockiert werden), schiebt das Backend seine bedrock.zip und mappings.json an einen Relay-Endpunkt auf magmaguy.com unter dem Namespace des Netzwerks (abgeleitet vom Netzwerkschlüssel). Der Proxy listet und lädt vom Relay, wenn der direkte Abruf hart fehlschlägt.

Beide Pfade münden in denselben Merge-Schritt, sodass der Betreiber nie wählen muss — der direkte Abruf wird bevorzugt (keine Bandbreitenkosten für magmaguy.com), das Relay springt bei Bedarf transparent ein.

Das Relay hat serverseitig eine TTL von 30 Minuten. Backends schieben alle 25 Minuten, um den Eintrag am Leben zu halten; ein sauberes Herunterfahren entfernt den Eintrag sofort, statt auf die TTL zu warten.

Häufige Probleme beheben

Ein Backend bekommt nie einen Netzwerkschlüssel

Symptom: /rspm status auf dem Backend zeigt Network key source: not set — the proxy sends one when a player next connects here, und die Backend-Konsole wiederholt:

[ResourcePackManager] This backend is behind a proxy but has no network key yet, so it is not linked to the proxy.
[ResourcePackManager] The proxy sends one automatically the first time a player connects to this server.

Arbeite diese Punkte der Reihe nach ab:

1. Hat sich seit dem Start des Proxys überhaupt jemand mit diesem Backend verbunden? Die Zuweisung reitet auf einer Spielerverbindung mit. Eine Lobby, die noch niemand besucht hat, ist berechtigterweise ohne Schlüssel.
2. Liegt RSPM überhaupt auf dem Proxy? Das Backend legt für genau diesen Fall eine Kopie seiner eigenen Jar unter plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar ab. Kopiere sie in den plugins/-Ordner des Proxys und starte den Proxy neu.
3. Velocity mit modernem Forwarding: stimmt das Forwarding-Secret des Backends mit dem des Proxys überein? Ein für modernes Forwarding konfiguriertes Backend lehnt eine unsignierte oder falsch signierte Zuweisung absichtlich ab — diese Prüfung ist das Einzige, was verhindert, dass ein unbefugter Proxy deine Backends verschlüsselt. Das Backend-Log benennt, welcher der beiden Fälle eingetreten ist. Korrigiere das Secret auf beiden Seiten; die nächste Spielerverbindung versucht es automatisch erneut, ein Neustart auf keiner der beiden Seiten ist nötig.
4. Ist der Proxy ein nicht unterstützter Proxy? Nur Velocity und BungeeCord/Waterfall führen die Proxy-Rolle aus.

Beachte, dass Floodgates key.pem hierbei keine Rolle mehr spielt. Eine fehlende plugins/floodgate/key.pem auf dem Proxy ist ein vollständig unterstützter Zustand — der Proxy erzeugt stattdessen seinen eigenen Schlüssel. Floodgate wird weiterhin benötigt, damit Bedrock-Spieler den Proxy überhaupt erreichen.

Zwei Proxys stehen vor denselben Backends

Beide Proxys müssen denselben Netzwerkschlüssel vorweisen, sonst verbindet sich jedes Backend mit demjenigen, der es zuerst erreicht hat, und lehnt den anderen ab (mit dem Log-Eintrag A proxy offered a network key that differs from the one this backend already uses). Kopiere die Datei network-key aus dem RSPM-Datenordner des primären Proxys in den des anderen Proxys und starte diesen neu.

Warnung „No merged pack content" nach ~20 Sekunden

Nach 4 aufeinanderfolgenden leeren Poll-Zyklen protokolliert der Proxy eine einmalige mehrzeilige Warnung, die jedes gepollte Backend, die versuchte URL und das Ergebnis auflistet. Die Warnung erklärt die häufigsten Lösungen:

• CONNECT_FAILED bei jedem Backend — der Proxy kann den Backend-HTTP-Port überhaupt nicht erreichen. Prüfe, ob die Adresse in velocity.toml / config.yml eine ist, die der Proxy tatsächlich erreichen kann (kein Docker-interner Name, der aus dem Netzwerk des Proxys nicht aufgelöst wird), und dass der HTTP-Port des Backends zwischen Proxy und Backend offen ist. Die Warnung gibt für jedes Backend den genauen HTTP-host:port aus, den sie versucht hat, und ob dieser Port aus der Ankündigung des Backends oder dem mcPort + networkHttpOffset-v2-Fallback stammt. Wenn du keine Möglichkeit hast, diesen Port zu öffnen (Managed-Hosting), siehe den Abschnitt zum Relay-Fallback oben — das Backend sollte automatisch in das Relay hochladen.
• NOT_FOUND_404 bei jedem Backend — die Backends laufen, produzieren aber kein Bedrock-Paket. Führe /rspm status auf jedem Backend aus; der Diagnoseblock für das Bedrock-Paket sagt dir, warum (am häufigsten: keine konvertierbaren Item-Mappings oder Entity-Bundles im zusammengeführten Paket, oder der erste Mix-Zyklus ist noch nicht abgeschlossen).

Die Warnung feuert einmal pro Hänger-Phase. Eine Zeile NetworkSync: recovered wird protokolliert, sobald mindestens ein Backend wieder Inhalt zurückgibt.

Bedrock-Spieler sehen beim ersten Proxy-Boot keine Custom-Modelle

Geyser registriert seine Custom-Item-Tabelle nur beim Proxy-Start. Wenn der Proxy gestartet wurde, bevor ein Backend ein Bedrock-Paket produziert hat, läuft Geyser mit einer leeren Mappings-Tabelle und bleibt für den Rest der Session so.

Lösung: Starte den Proxy einmal neu, nachdem das Backend seine erste Merged Bedrock pack published-Zeile protokolliert hat. RSPM stellt bei jedem Proxy-Boot die Mappings des vorherigen Laufs vorab bereit, sodass dies nur bei einer brandneuen Installation zum Problem wird — bei nachfolgenden Boots ist etwas bereit, bevor Geyser scannt.

Warnungen „Duplicate bedrock_identifier" beim Booten des Proxys

Zwei Backends haben denselben Bedrock-Identifikator für dasselbe Basis-Item ausgegeben. „Letzter Schreiber gewinnt"; harmlos, wenn nur ein Backend dieses Item bereitstellen muss. Wenn beide Backends unter demselben Basis-Item unterschiedliche Custom-Items hosten sollen, benenne eines der Quell-Java-Modelle um, damit sich die automatisch generierten Hashes unterscheiden.

Bedrock-Spieler ist verbunden, sieht aber das Paket nicht

Der Proxy feuert ein Chat-Banner an alle online befindlichen Java-Spieler, wenn eine Bedrock-Session ohne ein nutzbares RSPM-Paket lädt:

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

Der Bedrock-Spieler selbst erhält außerdem ein modales Popup, und die Proxy-Konsole erhält ein Banner. Wenn du tiefer graben musst, aktiviere den Debug-Stream (verfügbar sowohl auf Velocity als auch auf BungeeCord):

/rspm debug bedrock on

Das aktiviert ausführliche [RSPM-BedrockDebug]-Protokollzeilen des GeyserBinder. Reproduziere das Problem und schalte es dann wieder aus:

/rspm debug bedrock off

Die Einstellung wird bei einem Proxy-Neustart auf „aus" zurückgesetzt, damit sie nicht versehentlich aktiviert bleiben kann.

RSPM in einem Netzwerk aktualisieren

Es ist dieselbe Jar auf jedem Backend und auf dem Proxy, halte also alle Komponenten auf derselben Version.

Der manuelle Weg lautet: Backend-Jar aktualisieren, dieselbe ResourcePackManager.jar erneut in den plugins/-Ordner des Proxys kopieren, Proxy neu starten.

RSPM kann die Proxy-Hälfte auch selbst erledigen. Jedes Backend bietet dem Proxy seine universelle Plugin-Jar über eine authentifizierte Route an (/rspm-update.jar, geschützt durch ein Token, das aus dem gemeinsamen Netzwerkschlüssel abgeleitet wird — der Schlüssel selbst wird nie übertragen). Der Proxy prüft, dass die angebotene Datei eine vollständige universelle RSPM-Jar mit passenden Plattform-Deskriptor-Versionen und den erwarteten Einstiegspunkten ist, lehnt Downgrades ab und verifiziert die bereitgestellten Bytes gegen die angekündigte Größe und den SHA-256, bevor er irgendetwas ersetzt. Er stellt dieselbe Jar für das Proxy-Plugin bereit und, wenn ein proxy-gehostetes Geyser erkannt wird, auch dessen mitgelieferte Geyser-Erweiterung; diese Dateien werden beim Herunterfahren des Proxys angewendet, wobei die vorherigen Dateien als Rollback-Kopien erhalten bleiben.

Das ist eine authentifizierte Netzwerk-Vertrauensgrenze, keine unabhängige Herkunftsprüfung gegen Nightbreak: Jedes Backend, das mit dem gemeinsamen Netzwerkschlüssel versorgt wurde, gilt als vertrauenswürdig genug, um eine strukturell gültige, gleich neue oder neuere RSPM-Jar anzubieten. Schütze diesen Schlüssel und behandle jedes Backend, das ihn teilt, als vertrauenswürdige Infrastruktur.

In der Praxis genügt es daher meist, die Backends zu aktualisieren und anschließend den Proxy neu zu starten — der Proxy wird sich die passende Jar bereits selbst bereitgestellt haben. Ein abgelehntes Update protokolliert Rejected backend-offered ResourcePackManager update: ... mitsamt Grund.

Was noch nicht unterstützt wird

• Java-Pakete in Netzwerken über das Proxy-Plugin. Java-Clients erhalten Pakete direkt von jedem Backend über die reguläre API. Es gibt keinen proxy-seitigen Java-Paket-Mixer.
• Backend-übergreifendes Zusammenführen von Java-Paketen. Das Java-Paket jedes Backends ist unabhängig. Wechselt ein Spieler das Backend, erhält er das Paket des neuen Backends.
• Live-Rotation des Netzwerkschlüssels. Ein Backend übernimmt einen Schlüssel genau einmal und akzeptiert keinen Ersatz aus einer Nachricht. Rotieren bedeutet: die Datei network-key des Proxys löschen und networkKey aus der data.yml jedes Backends entfernen, dann alles neu starten.