Dépannage Resource Pack Manager

Cette page ne couvre que les comportements actuellement confirmés dans le code de ResourcePackManager.

La toute première étape la plus utile pour n'importe quel problème RSPM est :

/rspm status

Elle affiche la version, le mode de déploiement (autonome vs network-backend), une courte empreinte non secrète de la clé réseau ainsi que la provenance de cette clé, l'état des packs Java + Bedrock, le chemin de distribution actif avec l'URL, l'hôte externe résolu + l'IP publique auto-détectée, tous les drapeaux de configuration pertinents, un rappel de déploiement proxy (le jar proxy réseau est le même ResourcePackManager.jar), et la détection de Floodgate / Geyser-Spigot. La même commande existe lorsque le jar s'exécute sur un proxy et affiche les équivalents côté proxy (liste des backends, résultats de récupération par backend, état du pack fusionné).

La console est silencieuse volontairement

RSPM affiche une seule ligne à chaque initialisation neuve d'un chemin de distribution — le résultat :

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

Tout le reste — chaque pack préparé, chaque cluster fusionné, chaque contrôle de stabilité, chaque sonde d'auto-hébergement et son résultat — est supprimé par défaut. Une condition dont RSPM se remet tout seul n'est pas signalée comme un avertissement. Si une sonde d'auto-hébergement échoue et que RSPM bascule silencieusement vers l'hébergement distant, c'est un succès, pas une panne, et la console n'en dit rien.

Donc : une absence d'avertissements n'est pas la preuve qu'il ne s'est rien passé, et la présence de la ligne de résultat signifie que les joueurs reçoivent bien un pack. Avant de signaler un bogue d'hébergement ou de fusion, activez la narration :

/rspm verbose on

puis /rspm reload. Cette commande écrit verboseLogging: true dans plugins/ResourcePackManager/config.yml à votre place et le réglage survit aux redémarrages : faites donc /rspm verbose off quand vous avez terminé. Éditer la clé à la main revient au même. Le convertisseur Bedrock possède un interrupteur distinct, bedrockConverterDebug, qui n'existe que dans la configuration.

Les avertissements que vous pouvez légitimement voir sont de véritables pannes : un échec répété de distribution du pack à un joueur précis, un client signalant INVALID_URL, un port HTTP qui n'a pas pu se lier, l'échec des deux chemins de distribution, ou un proxy ayant interrogé plusieurs cycles sans qu'aucun backend ne produise de contenu.

Les joueurs ne reçoivent pas le pack de ressources

Vérifiez d'abord ces points :

• autoHost doit être activé si vous voulez la distribution automatique normale (selfHostForce est la surcharge de test explicite)
• le pack fusionné doit exister et au moins un chemin de distribution (auto-hébergement ou distant) doit avoir réussi
• les joueurs ne reçoivent le pack qu'à la connexion, ou via la diffusion du premier téléversement qui se déclenche au moment où l'hébergement devient prêt
• les joueurs Floodgate sont volontairement ignorés par la distribution Java, car Geyser gère leur session de pack Bedrock

Si nécessaire :

1. Exécutez /rspm status et regardez la section « Hosting ». Active delivery indique si l'auto-hébergement, le distant, ou aucun des deux est actuellement utilisé.
2. Si « active delivery: not yet ready » — le mix ou le téléversement est encore en cours. Le plugin l'affiche bien en évidence dans la console quand un joueur se connecte trop tôt et enverra automatiquement le pack au moment où la distribution est prête.
3. Si « active delivery: none — hosting disabled or failed » — autoHost est désactivé, ou les sondes d'auto-hébergement et le téléversement distant ont tous deux échoué. Voir « Les contrôles de cohérence d'auto-hébergement ont échoué » et « L'auto-hébergement ne peut pas atteindre le serveur distant » ci-dessous.
4. Définissez verboseLogging: true, exécutez /rspm reload, surveillez la console pour les résultats de téléversement / de sonde d'auto-hébergement, puis reconnectez-vous avec un joueur de test. (Sans ce drapeau, les étapes de sonde ne sont pas affichées — seule la ligne de résultat finale « Resource pack is live via ... » l'est.)

L'offre de connexion est retardée d'environ une seconde. Si un client Java signale FAILED_DOWNLOAD ou DISCARDED, RSPM réessaie automatiquement jusqu'à trois tentatives pour cette session de joueur. Il ne réessaie pas après un refus du joueur ni après un INVALID_URL ; l'épuisement répété des tentatives et les URL invalides sont journalisés comme de véritables pannes.

Si vous auto-hébergez via votre propre pipeline externe (autoHost: false), RSPM ne pousse pas votre URL personnalisée à votre place. Dans cette configuration, vous avez toujours besoin de votre propre flux de distribution de pack côté serveur.

ItemsAdder est installé, mais son contenu est absent du pack final

Cela signifie généralement qu'ItemsAdder est encore configuré d'une manière qui empêche ResourcePackManager de lire ou d'héberger sa sortie.

Utilisez :

/rspm itemsadder configure

Cette commande, actuellement :

• active resource-pack.hosting.no-host.enabled
• désactive protection_1, protection_2 et protection_3
• définit resource-pack.zip.compress-json-files: false
• exécute /iareload, puis /iazip
• recharge ResourcePackManager environ 15 secondes plus tard

Si la commande vous indique qu'ItemsAdder héberge déjà son propre pack, désactivez d'abord manuellement l'hébergement ItemsAdder, puis relancez la commande.

Le pack fusionné est invalide ou échoue au téléversement

L'intégration d'auto-hébergement de ResourcePackManager gère explicitement ces types d'erreurs côté serveur :

• fichiers requis manquants
• fichier trop volumineux
• format de fichier invalide
• session manquante
• serveur distant indisponible

Si vous rencontrez l'un de ces cas :

1. Exécutez /rspm reload pour reconstruire le pack.
2. Vérifiez si l'un des packs source est malformé, chiffré ou autrement illisible.
3. Vérifiez si le pack fusionné final contient toujours un pack.mcmeta et un pack.png valides à la racine.

Si un pack activé ne peut pas être extrait ou préparé, le mix en cours s'interrompt et la console nomme le pack fautif. Réparez ce pack, retirez un ZIP ajouté manuellement, ou définissez isEnabled: false dans sa configuration d'intégration automatique avant de recharger.

Un pack cassé ne bloque plus tout indéfiniment

Un pack qui ne peut pas être préparé échoue de la même façon à chaque tentative : laissé tel quel, il coincerait donc la distribution pour toujours — la fusion n'aboutit jamais et la même erreur se répète indéfiniment. Après trois échecs consécutifs du même fichier, RSPM retire ce pack de la fusion afin que les packs restants puissent être livrés, et le dit une fois, haut et fort :

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

Lisez cela comme prévu : les joueurs reçoivent désormais un pack auquel il manque le contenu de ce plugin. La cause habituelle est un zip corrompu ou partiellement écrit.

L'exclusion se lève d'elle-même. L'enregistrement de l'échec est indexé sur la taille et la date de modification du fichier, donc réparer ou remplacer le fichier retire automatiquement la quarantaine et le pack rejoint la fusion suivante — aucune commande, aucun redémarrage. /rspm reload réinitialise également tous les enregistrements de quarantaine depuis zéro. Les compteurs d'échec qui n'ont jamais atteint trois sont effacés après tout mix réussi, de sorte que des ratés transitoires sans rapport, étalés sur une longue durée de fonctionnement, ne peuvent pas s'accumuler jusqu'à une exclusion.

En cas d'erreur SESSION_NOT_FOUND de l'auto-hébergement distant, RSPM efface son UUID de session et se réinitialise au prochain tick de keep-alive — aucune intervention manuelle requise.

Les assets d'un plugin écrasent ceux d'un autre plugin

Cela est contrôlé par priorityOrder dans :

plugins/ResourcePackManager/config.yml

Les entrées plus hautes l'emportent sur les entrées plus basses.

Pour les fichiers non fusionnables, ResourcePackManager remplace le fichier de priorité inférieure. Pour les fichiers JSON fusionnables, il fusionne le contenu à la place. Les catégories JSON actuellement fusionnables sont :

• sounds.json
• les fichiers de langue
• le JSON des modèles d'items vanilla dans minecraft/models/item (fusion non récursive : seul le tableau overrides est combiné entre packs, le reste du fichier suit la règle priorité-la-plus-haute-l'emporte)
• les fichiers atlas
• les fichiers de police
• les définitions de modèles d'items 1.21.4+ dans items/ (fusion adaptée au format qui respecte la structure de l'arbre de prédicats)

pack.mcmeta est également fusionné de manière spéciale : le pack_format le plus élevé l'emporte, les plages supported_formats sont élargies (les formats entier, tableau de deux entiers et objet {min_inclusive, max_inclusive} sont tous pris en charge), les entrées d'overlay sont combinées et les clés de premier niveau non standard sont préservées. Les entrées d'overlay sont normalisées pour la compatibilité 1.21.9+ en ajoutant les champs min_format/max_format lorsqu'ils sont absents. Les sources d'atlas de base sont également fusionnées dans les fichiers d'atlas d'overlay afin d'empêcher les overlays de masquer les entrées de base.

Si vous avez besoin d'inspecter ce qui s'est passé pendant la dernière fusion, consultez :

plugins/ResourcePackManager/collision_log.txt

Le texte de l'interface ou les éléments à base de polices semblent incorrects

Les fichiers de police font partie des catégories JSON que ResourcePackManager fusionne, mais cela ne garantit pas que deux systèmes de polices différents se comporteront bien ensemble dans Minecraft.

Si un menu ou un HUD piloté par les polices semble incorrect :

1. Modifiez priorityOrder pour que le pack que vous voulez voir l'emporter soit plus haut.
2. Exécutez /rspm reload.
3. Vérifiez collision_log.txt pour confirmer que les collisions se sont produites là où vous l'attendiez.

Les modifications du pack de ressources n'apparaissent pas immédiatement

ResourcePackManager possède un chien de garde pour les sources de packs prises en charge.

Il attend qu'un pack modifié reste inchangé pendant 3 secondes, puis, une fois que tous les packs surveillés sont stables, la refusion s'exécute immédiatement.

Si vous êtes en train de régénérer activement le pack d'un autre plugin, laissez quelques secondes après l'arrêt des écritures de fichiers. En cas de doute, exécutez /rspm reload une fois que le plugin amont a terminé.

/rspm status indique l'hébergement distant, mais j'attendais l'auto-hébergement

C'est un comportement normal lorsque preferSelfHost: true (par défaut) et que l'un des trois contrôles de cohérence d'auto-hébergement a échoué. RSPM n'avertit pas à ce sujet — se replier sur l'hébergement distant est un résultat réussi, le contrôle échoué est donc journalisé au niveau détail avec un « This is OK. » explicite et reste masqué à moins que verboseLogging: true ne soit défini. La seule ligne obtenue par défaut est Resource pack is live via automatic hosting — ....

Exécutez /rspm verbose on (ou définissez verboseLogging: true) puis /rspm reload pour voir laquelle des trois couches a échoué :

1. Couche 1 (heuristique) — l'hôte externe résolu est RFC1918 / loopback / link-local. Définissez soit selfHostExternalHost sur votre vrai nom d'hôte public, soit assurez-vous que le plugin peut atteindre api.ipify.org / checkip.amazonaws.com.
2. Couche 2 (auto-sonde localhost) — une requête HEAD vers http://127.0.0.1:<port>/rspm.zip n'a pas renvoyé 200 avec un corps non vide. Attrape les collisions de liaison de port ou les fichiers de pack manquants.
3. Couche 3 (sonde d'accessibilité externe) — magmaguy.com a essayé de récupérer votre URL annoncée et n'a pas pu l'atteindre. Le plus souvent : le port HTTP n'est pas redirigé au niveau du routeur / pare-feu. L'URL de la sonde et un code de raison (PRIVATE_HOST_REJECTED, CONNECT_TIMEOUT, ECONNREFUSED, RATE_LIMITED, ...) sont affichés sous verboseLogging.

Correctifs (par ordre de préférence) : ouvrez le port HTTP au niveau de votre pare-feu + routeur, définissez selfHostExternalHost sur un nom d'hôte routable, ou définissez preferSelfHost: false pour sauter entièrement l'auto-hébergement.

Lorsque la sonde magmaguy.com est elle-même inaccessible (RSPM ne peut pas lui parler pour l'interroger), l'auto-hébergement est conservé plutôt qu'échoué — le raisonnement étant que le chemin de repli a aussi besoin de magmaguy.com, donc refuser de s'engager en raison de l'incapacité à sonder serait paradoxal.

Voir Auto-hébergement pour l'arbre de décision complet.

L'auto-hébergement ne peut pas atteindre le serveur distant

L'hôte distant intégré de ResourcePackManager communique avec :

https://magmaguy.com/rsp/

Si cette connexion échoue, le plugin émet des avertissements de communication et ne peut pas utiliser le repli distant tant qu'il ne s'est pas reconnecté avec succès.

Vos options sont :

1. corriger la connectivité HTTPS sortante du serveur
2. attendre que le service distant redevienne joignable
3. désactiver autoHost et héberger vous-même le zip généré
4. ouvrir votre port HTTP, définir selfHostExternalHost sur votre nom d'hôte public et garder preferSelfHost: true. Le nom d'hôte explicite contourne l'auto-détection de l'IP publique, mais RSPM tente quand même la sonde de couche 3. Si le service de sonde est lui-même inaccessible, RSPM conserve l'auto-hébergement au lieu de traiter cet échec de communication comme la preuve que votre URL est inaccessible.

Je veux auto-héberger le pack fusionné via mon propre serveur web

La configuration prise en charge par le code est :

1. Définissez autoHost: false.
2. Définissez resourcePackRerouting si vous voulez que ResourcePackManager écrive une copie supplémentaire dans un dossier existant.
3. Hébergez vous-même ResourcePackManager_RSP.zip.

resourcePackRerouting est résolu relativement au répertoire plugins, et le dossier cible doit déjà exister.

Si vous voulez plutôt utiliser le serveur HTTP d'auto-hébergement intégré de RSPM (chose différente — même JVM que le plugin), voir Auto-hébergement.

J'ai besoin d'inspecter les données distantes stockées pour ce serveur

Utilisez :

/rspm data_compliance_request

S'il y a une session d'hébergement distant active, ResourcePackManager télécharge la réponse dans :

plugins/ResourcePackManager/data_compliance/data.zip

RSPM écrit également un ReadMe.md dans ce même dossier data_compliance.

S'il n'y a pas de session distante (par ex. si vous utilisez l'auto-hébergement), la commande signale qu'il n'y a aucune donnée distante à demander.

Le pack Bedrock n'est pas généré

bedrockConversionEnabled vaut true par défaut, donc cela devrait s'exécuter automatiquement. Exécutez d'abord /rspm status — la section Bedrock Pack vous dira pourquoi le pack n'est pas sur le disque :

• « No Bedrock target detected » — pas de Geyser-Spigot local, pas de Floodgate local, et pas en mode réseau. La conversion est intentionnellement sautée. Installez Floodgate (pour les configurations proxy) ou Geyser-Spigot (pour les configurations autonomes) et /rspm reload.
• « Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing » — généralement le premier cycle de fusion n'est pas encore terminé (attendez ~30 s après le démarrage), ou la conversion n'a trouvé ni mapping d'item convertible ni bundle d'entité autorisé, ou la conversion a levé une exception. Cherchez dans la console les avertissements [BedrockConverter] ou Generic scanner: discovered 0 items definition files.

Si la détection automatique de Geyser échoue :

1. Définissez bedrockGeyserFolder dans config.yml sur le chemin de votre dossier de données Geyser (par ex. Geyser-Spigot).
2. Les chemins absolus fonctionnent. Un chemin relatif est essayé d'abord depuis le répertoire de travail du serveur, puis relativement au répertoire plugins.

Le convertisseur détecte automatiquement Geyser dans plugins/Geyser-Spigot/, toute variante plugins/Geyser-*/, ou config/Geyser-*/ pour les configurations Fabric/NeoForge.

Pour une sortie de journal par item / par os, définissez bedrockConverterDebug: true et rechargez.

Bedrock : le fournisseur en direct est ignoré car un pack hérité existe

Si la console signale Legacy RSPM Bedrock pack detected, c'est que Geyser a déjà scanné au démarrage un ancien ResourcePackManager_Bedrock.zip présent dans son répertoire de packs. Supprimer ce fichier pendant que le processus tourne laisserait Geyser avec un codec en mémoire pointant vers un chemin qui n'existe plus ; RSPM saute donc délibérément son fournisseur de pack en direct pour ce démarrage.

Arrêtez complètement le serveur, supprimez uniquement le chemin exact du fichier hérité affiché par RSPM, puis redémarrez le serveur. N'utilisez pas /reload pour cette migration. Le pack actuel reste dans plugins/ResourcePackManager/output/ et est servi par session ; il n'a pas sa place dans le répertoire packs/ de Geyser.

Les joueurs Bedrock voient les items tenus en main à la mauvaise position

Il s'agit d'un problème de réglage, pas d'un bug de conversion. Ouvrez plugins/ResourcePackManager/bedrock_display_offsets.yml, ajustez l'axe concerné, exécutez /rspm reload, puis reconnectez le client de test Bedrock afin que la prochaine connexion reçoive le pack reconstruit. La première personne et la troisième personne sont indépendantes — régler l'une n'affecte pas l'autre. Consultez la page Conversion Bedrock pour la liste complète des paramètres et ce que chacun contrôle.

Les textures d'armure personnalisée sont absentes sur les joueurs Bedrock

L'armure personnalisée est rendue sur Bedrock en combinant la géométrie d'armure vanilla avec la texture Java comme couche visible. Pour que cela fonctionne, le pack du plugin source doit définir un fichier d'équipement sous assets/<namespace>/equipment/<material>.json aux côtés de la définition d'items. Si le journal de conversion affiche l'item mais qu'aucune texture d'armure n'apparaît en jeu, vérifiez que ce fichier existe bien dans le pack fusionné.

Proxy : un backend dit qu'il n'a pas de clé réseau

Sur le backend, /rspm status affiche Network key source: not set — the proxy sends one when a player next connects here, et la console répète « This backend is behind a proxy but has no network key yet ».

Un plugins/floodgate/key.pem manquant n'est pas la cause — ce fichier est désormais optionnel. C'est le proxy qui possède la clé : il charge son propre fichier network-key, ou l'initialise une seule fois depuis le key.pem de Floodgate s'il est présent, ou génère une clé neuve, puis la transmet à chaque backend lorsqu'un joueur s'y connecte.

Vérifiez, dans l'ordre :

1. Un joueur s'est-il connecté à ce backend depuis le démarrage du proxy ? L'attribution voyage avec une connexion de joueur.
2. ResourcePackManager.jar est-il réellement sur le proxy ? Le backend prépare pour vous une copie de son propre jar dans plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar et affiche ce chemin — copiez-la dans le plugins/ du proxy et redémarrez le proxy.
3. Sur Velocity avec le transfert moderne, le secret de transfert du backend correspond-il à celui du proxy ? Un backend en transfert moderne rejette délibérément une attribution non signée ou mal signée ; son journal précise laquelle des deux. Corrigez le secret des deux côtés et la prochaine connexion de joueur réessaie d'elle-même.
4. Comparez les lignes Network key fingerprint de /rspm status des deux côtés. Des empreintes identiques signifient que le lien est bon ; la clé elle-même n'est jamais affichée.

Voir Réseaux proxy pour la séquence complète.

Proxy : « Could not save the network key »

Le proxy a résolu une clé mais n'a pas pu l'écrire dans son fichier network-key. Ce démarrage-ci fonctionne quand même. Le redémarrage suivant génère une clé différente, et chaque backend déjà approvisionné conserve l'ancienne et refuse la nouvelle — tout le réseau se délie silencieusement.

Corrigez les permissions du système de fichiers sur le dossier de données du plugin proxy avant de redémarrer.

Proxy : « no merged pack » après plusieurs cycles d'interrogation

Après ~20 secondes de cycles d'interrogation vides (4 cycles × 5 s d'intervalle par défaut) sur le proxy, RSPM enregistre une bannière de diagnostic unique listant chaque backend qu'il a interrogé, l'URL HTTP qu'il a essayée et le résultat (200 / 304 / 404 / CONNECT_FAILED / etc.). La bannière explique les correctifs les plus courants :

• CONNECT_FAILED sur chaque backend → le proxy ne peut pas atteindre le port HTTP du backend. Vérifiez que l'adresse dans velocity.toml / config.yml en est une que le proxy peut réellement atteindre (pas, par ex., un nom interne Docker qui ne se résout pas depuis le réseau du proxy), et que le port HTTP annoncé du backend est ouvert entre le proxy et le backend. La bannière affiche l'URL exacte qu'il a essayée ; avant qu'un backend ait annoncé son port, le proxy se replie sur mcPort + network-http-offset-v2, donc un CONNECT_FAILED précoce peut aussi signifier que ce port de repli n'est pas encore joignable.
• NOT_FOUND_404 sur chaque backend → les backends sont en marche mais ne produisent pas de pack Bedrock. Exécutez /rspm status sur chaque backend ; le bloc de diagnostic Bedrock Pack vous dira pourquoi.

La bannière se déclenche une fois par période de blocage et une ligne « NetworkSync: recovered » est enregistrée lorsqu'au moins un backend recommence à renvoyer du contenu. Voir Réseaux proxy pour plus de détails.

Proxy : les joueurs Bedrock ne voient aucun modèle 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.

Le correctif est de redémarrer le proxy une fois que le proxy a enregistré Merged Bedrock pack published at .... RSPM pré-déploie les mappings du run précédent au 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.

Backend : « Backend HTTP server failed to bind on port X »

En mode réseau, le backend expose ses sorties Bedrock via un petit serveur HTTP. Si le port est utilisé ou indisponible, vous verrez un bloc [ERROR] multi-ligne dans la console. Correctifs :

• Définissez selfHostPort sur une autre valeur positive dans config.yml.
• Ou changez networkHttpOffset-v2 pour éloigner le port auto-dérivé de la collision (par ex. RCON sur mcPort + 1 ? réglez-le sur 2 ou 3). Vous n'avez pas besoin de mettre à jour le proxy pour correspondre : une fois que le backend se lie avec succès, il annonce automatiquement son port HTTP réel au proxy, donc le propre network-http-offset-v2 du proxy ne compte que comme estimation avant l'annonce.

Tant que le serveur HTTP du backend est hors service, le pack Bedrock de ce backend n'atteindra pas le proxy via la récupération directe. Le repli par relais magmaguy.com fonctionne toujours (le backend pousse ses fichiers vers le relais et le proxy les récupère par ce biais).

Nettoyer une configuration v1 obsolète

Les opérateurs effectuant une mise à niveau depuis RSPM v1 peuvent avoir une clé morte networkHttpOffset (sans -v2) dans leur config.yml. RSPM v2 ne lit délibérément pas l'ancienne clé — vous obtenez la valeur par défaut v2 (1) écrite dans la configuration au prochain démarrage automatiquement. La clé v1 morte reste dans votre configuration comme un artefact inoffensif jusqu'à ce que vous la nettoyiez à la main.