Réseaux proxy (BungeeCord / Waterfall / Velocity)

ResourcePackManager fonctionne sur les réseaux proxy. Le plugin backend tourne sur chaque backend, et un plugin proxy distinct (Velocity OU BungeeCord, jamais les deux) tourne sur le proxy. Les deux composants se trouvent automatiquement grâce au fichier partagé plugins/floodgate/key.pem.

Rôle du plugin proxy

Le rôle du plugin proxy est la fusion et la livraison du pack Bedrock. Sur un réseau comportant plusieurs backends, chaque backend produit son propre pack Bedrock (la version convertie de son pack Java fusionné). Le plugin proxy :

1. Interroge toutes les 5 secondes le petit serveur HTTP de chaque backend pour récupérer /bedrock.zip et /mappings.json, en utilisant If-Modified-Since afin que les fichiers inchangés coûtent quasiment zéro bande passante.
2. Attend que l'état de la boîte de réception se stabilise sur deux interrogations consécutives.
3. Fusionne le pack Bedrock de chaque backend en un seul pack à l'échelle du réseau.
4. Copie le fichier de mappings personnalisés Geyser fusionné dans plugins/Geyser-*/custom_mappings/ sur le proxy.
5. Sert le pack fusionné aux clients Bedrock à la connexion via le SessionLoadResourcePacksEvent de Geyser.

Le plugin proxy n'est utile que pour les joueurs Bedrock. La livraison des packs Java sur les réseaux continue de se faire par backend via l'API classique setResourcePack / addResourcePack — les clients Java voient le pack que le backend sur lequel ils se trouvent a choisi d'envoyer. Si votre réseau est uniquement Java, vous n'avez pas besoin du plugin proxy.

Installation — Deux étapes

Étape 1 : Installer Floodgate sur le proxy et sur chaque backend

Floodgate est requis pour que les joueurs Bedrock s'authentifient sur le proxy. RSPM s'appuie sur le fichier plugins/floodgate/key.pem de Floodgate pour dériver l'identité réseau — ce fichier doit être identique octet par octet sur le proxy ET sur chaque backend. Floodgate l'exige déjà pour l'authentification Bedrock, donc si les joueurs Bedrock fonctionnent actuellement sur votre réseau, c'est déjà fait.

Si vous n'avez pas encore Floodgate, installez-le sur chaque composant, puis copiez un key.pem canonique unique sur chaque autre composant avant de continuer.

Étape 2 : Copier le jar proxy correspondant depuis n'importe quel backend

Après que le RSPM backend a démarré au moins une fois, regardez dans :

plugins/ResourcePackManager/proxy-extension/

Ce dossier contiendra :

ResourcePackManager-Velocity.jar
ResourcePackManager-BungeeCord.jar
README.md  (plus 9 fichiers README traduits)

Le backend extrait les deux jars à chaque démarrage, indépendamment de la topologie détectée, donc ils sont toujours disponibles. Copiez exactement un seul dans le dossier plugins/ de votre proxy :

Logiciel proxy	Utilisez ce jar
Velocity	ResourcePackManager-Velocity.jar
BungeeCord	ResourcePackManager-BungeeCord.jar
Waterfall (fork Bungee)	ResourcePackManager-BungeeCord.jar

N'installez pas les deux — seulement celui qui correspond. Installer les deux provoquera des erreurs de démarrage sur la plateforme qui tentera de charger le mauvais jar.

Redémarrez le proxy. C'est tout.

Il n'y a délibérément aucune configuration à éditer et aucune clé à coller. Le plugin proxy lit plugins/floodgate/key.pem sur le proxy au démarrage et en dérive l'identité réseau. Puisque Floodgate exige déjà que ce fichier soit identique sur chaque backend et sur le proxy, la clé dérivée correspond automatiquement à celle de chaque backend.

La première fusion s'effectue généralement dans les ~10 secondes après que tous les backends sont en ligne.

Vérification du bon fonctionnement

Console du proxy

Dans les ~10 secondes suivant le redémarrage (en supposant que les backends tournent), vous devriez voir :

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, ...)
[ResourcePackManager] Merged pack ready at .../merged/Bedrock.zip (sha1 ...)
[ResourcePackManager] Geyser mappings deployed to .../custom_mappings
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1ABCD1234)

/rspm status sur le proxy

Affiche un instantané : liste des backends, résultats de récupération par backend et par chemin (200 / 304 / 404 / CONNECT_FAILED), compteur d'interrogations vides consécutives, chemin et taille actuels du pack fusionné, network-http-offset, et présence de Floodgate / Geyser sur le proxy. Nécessite resourcepackmanager.command.status ou resourcepackmanager.*. La console possède toujours les deux ; accordez l'une aux joueurs via votre plugin de permissions si vous souhaitez qu'ils puissent l'exécuter. La sortie ne révèle aucun secret (la clé réseau est masquée, aucun jeton d'authentification), donc des autorisations larges sont sans danger.

/rspm status sur un backend

La ligne Deploy mode devrait afficher network-backend. La ligne Network key devrait afficher une clé masquée (les 4 derniers caractères visibles) — comparez-la à la clé masquée du proxy pour confirmer que les deux côtés sont d'accord.

Client Bedrock

Connectez-vous en Bedrock. Vous devriez voir la fenêtre de téléchargement du pack de ressources avant d'arriver dans le monde. Les items personnalisés s'affichent avec leurs modèles prévus au lieu de simples armor stands.

Référence de configuration

Backend plugins/ResourcePackManager/config.yml

Le mode réseau est auto-détecté — il n'y a pas de drapeau networkMode: true à activer. Signaux de détection (un seul suffit) :

1. Floodgate présent, Geyser-Spigot absent — signal le plus fort pour le cas Bedrock-via-proxy.
2. spigot.yml: settings.bungeecord: true — ancien commutateur de transfert d'IP BungeeCord / Waterfall.
3. paper-global.yml: proxies.velocity.enabled: true — transfert moderne Velocity.

Le seul réglage qui compte spécifiquement pour le mode réseau est networkHttpOffset-v2, qui contrôle le port HTTP que le proxy interrogera sur chaque backend. La valeur par défaut 1 fonctionne sur pratiquement tous les hébergeurs. Voir Auto-hébergement pour l'explication complète de la résolution des ports.

Proxy plugins/ResourcePackManager/config.yml

Le plugin proxy écrit une configuration par défaut minimale au premier démarrage :

# Force clients to accept the pack (kick on decline). Default: false.
force-resource-pack: false

# Offset added to each backend's Minecraft port to derive the HTTP port
# this proxy will hit for /bedrock.zip and /mappings.json. Default 1.
# Must match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

Il n'y a délibérément aucune entrée network-key — elle a été retirée avant la sortie publique car le collage manuel était une source majeure de mauvaise configuration (les fautes de frappe cassaient silencieusement le lien proxy↔backend). La clé est auto-dérivée de plugins/floodgate/key.pem.

Stabilité et cadence de fusion

Le proxy attend que l'état de la boîte de réception se stabilise sur deux interrogations consécutives avant de fusionner. Avec l'intervalle d'interrogation par défaut de 5 s, cela signifie que la première fusion a lieu ~10 s après que le proxy peut voir au moins un backend produisant du contenu. Les fusions suivantes ne re-zippent que lorsque l'ensemble SHA-1 des fichiers de la boîte de réception change, donc une longue période calme ne coûte quasiment rien.

Récupération directe vs repli relais

Le chemin par défaut est la récupération directe : le proxy effectue un GET HTTP vers http://<backend-host>:<mcPort + offset><path> pour chaque backend.

Si le proxy ne peut pas atteindre directement le port HTTP d'un backend (typique des hébergements Minecraft mutualisés / managés où les ports MC sont exposés mais les ports adjacents sont bloqués par le pare-feu), le backend envoie son bedrock.zip et son mappings.json vers un point de relais sur magmaguy.com, sous l'espace de noms du réseau (dérivé de la clé Floodgate). Le proxy liste et télécharge depuis le relais lorsque la récupération directe échoue durement.

Les deux chemins alimentent la même étape de fusion, donc l'opérateur n'a jamais à choisir — la récupération directe est préférée (zéro coût de bande passante vers magmaguy.com), le relais prend le relais de manière transparente quand c'est nécessaire.

Le relais a un TTL de 30 minutes côté serveur. Les backends envoient toutes les 25 minutes pour maintenir l'entrée en vie ; un arrêt propre supprime l'entrée immédiatement plutôt que d'attendre le TTL.

Dépannage des problèmes courants

« Floodgate key.pem missing » au démarrage du proxy

Le plugin proxy n'a pas trouvé plugins/floodgate/key.pem et est resté inactif. RSPM ne peut se lier à aucun backend sans ce fichier.

Solution : installez Floodgate sur le proxy, puis assurez-vous que plugins/floodgate/key.pem sur le proxy est identique octet par octet au même fichier sur chaque backend. Floodgate génère automatiquement des clés différentes par installation par défaut — copiez un key.pem canonique depuis n'importe quel backend vers chaque autre composant, puis redémarrez tout.

Avertissement « No merged pack content » après ~20 secondes

Après 4 cycles d'interrogation vides consécutifs, le proxy enregistre un avertissement unique sur plusieurs lignes listant chaque backend interrogé, l'URL essayée et le résultat. L'avertissement explique les correctifs les plus courants :

• CONNECT_FAILED sur chaque backend — le proxy ne peut pas du tout atteindre le port HTTP du backend. Vérifiez que l'adresse dans velocity.toml / config.yml est bien une adresse que le proxy peut réellement atteindre (et non un nom interne Docker qui ne se résout pas depuis le réseau du proxy), et que mcPort + networkHttpOffset-v2 est ouvert entre le proxy et le backend. Si vous n'avez aucun moyen d'ouvrir ce port (hébergement managé), voir la section repli relais ci-dessus — le backend devrait téléverser automatiquement vers le relais.
• NOT_FOUND_404 sur chaque backend — les backends sont en ligne mais ne produisent pas de pack Bedrock. Exécutez /rspm status sur chaque backend ; le bloc de diagnostic Bedrock Pack vous indiquera pourquoi (le plus souvent : aucune définition d'item dans le pack fusionné, ou le premier cycle de mix n'est pas encore terminé).

L'avertissement se déclenche une seule fois par période bloquée. Une ligne NetworkSync: recovered est enregistrée quand au moins un backend recommence à renvoyer du contenu.

Les joueurs Bedrock ne voient aucun modèle personnalisé au premier démarrage du proxy

Geyser enregistre sa table d'items personnalisés uniquement au démarrage du proxy. Si le proxy a démarré avant qu'un backend produise un pack Bedrock, Geyser tourne avec une table de mappings vide et le reste pour le reste de la session.

Solution : redémarrez le proxy une fois après que le backend a enregistré sa première ligne Merged Bedrock pack published. RSPM pré-déploie les mappings du run précédent à chaque démarrage du proxy, donc cela ne se produit que sur une toute nouvelle installation — les démarrages suivants ont déjà quelque chose de prêt avant que Geyser scanne.

Avertissements « Duplicate bedrock_identifier » au démarrage du proxy

Deux backends ont émis le même identifiant Bedrock pour le même item de base. Le dernier qui écrit l'emporte ; sans conséquence si vous n'avez besoin que d'un seul backend pour fournir cet item. Si les deux backends doivent héberger des items personnalisés distincts sous le même item de base, renommez l'un des modèles Java source pour que les hachages auto-générés diffèrent.

Un joueur Bedrock est connecté mais ne voit pas le pack

Le proxy déclenche une bannière de chat pour tous les joueurs Java en ligne lorsqu'une session Bedrock se charge sans pack RSPM utilisable :

⚠ [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: ...)

Le joueur Bedrock lui-même reçoit également une fenêtre modale, et la console du proxy reçoit une bannière. Si vous avez besoin de creuser davantage, activez le flux de débogage (disponible sur Velocity comme sur BungeeCord) :

/rspm debug bedrock on

Cela active des lignes de log verbeuses [RSPM-BedrockDebug] depuis GeyserBinder. Reproduisez le problème, puis désactivez-le :

/rspm debug bedrock off

Le paramètre revient à off au redémarrage du proxy afin qu'il ne puisse pas être accidentellement laissé activé.

Mise à jour de RSPM sur un réseau

Après avoir mis à jour le jar RSPM backend, recopiez également le jar proxy correspondant depuis plugins/ResourcePackManager/proxy-extension/ d'un backend vers le proxy, puis redémarrez le proxy. Le backend régénère ces jars à chaque démarrage afin qu'ils soient toujours synchronisés avec la version du backend.

Ce qui n'est pas encore pris en charge

• Packs Java sur les réseaux via le plugin proxy. Les clients Java reçoivent les packs directement depuis chaque backend via l'API classique. Il n'y a pas de mixeur de pack Java côté proxy.
• Fusion de packs Java entre backends. Le pack Java de chaque backend est indépendant. Si un joueur change de backend, il reçoit le pack du nouveau backend.
• Reconfiguration à chaud de la clé réseau. La clé est liée au key.pem de Floodgate. La changer nécessite de redémarrer le proxy ET chaque backend (ce qui est de toute façon ce que vous feriez en faisant tourner la clé Floodgate).