Aller au contenu principal

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), la clé réseau masquée, 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é).

Les joueurs ne reçoivent pas le pack de ressources​

Vérifiez d'abord ces points :

  • autoHost doit être activé si vous voulez que ResourcePackManager envoie automatiquement une URL
  • 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

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. 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.

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.

Le plugin ignore les packs qu'il ne peut pas extraire proprement et émet des avertissements dans la console quand cela se produit.

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é.

Les contrôles de cohérence d'auto-hébergement ont échoué ; repli sur l'hébergement distant​

Ce message 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é :

  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 la raison sont enregistrées.

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 et garder preferSelfHost: true afin que RSPM utilise l'auto-hébergement sans avoir besoin de magmaguy.com du tout (dans ce scénario, définissez aussi selfHostExternalHost sur votre nom d'hôte public afin que la sonde externe de couche 3 soit inutile — RSPM conserve l'auto-hébergement en cas d'IOException de la sonde)

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

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 le scanner a trouvé zéro définition d'items dans le pack fusionné, 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. Le chemin peut être absolu ou relatif 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.

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 et ajustez l'axe concerné. La première personne et la troisième personne sont indépendantes — régler l'une n'affecte pas l'autre. Le client Bedrock recharge à chaud le JSON des attachables sans relancement, donc l'itération est rapide. 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 : « Floodgate key.pem missing » au démarrage du proxy​

Le plugin proxy n'a pas pu trouver plugins/floodgate/key.pem sur l'hôte proxy et est resté inactif. RSPM dérive l'identité réseau de ce fichier, donc sans lui le proxy ne peut se lier à aucun backend. Correctif :

  1. Installez Floodgate sur le proxy. Il est de toute façon requis pour que les joueurs Bedrock atteignent le proxy, c'est donc quelque chose dont vous avez besoin indépendamment de RSPM.
  2. Assurez-vous que plugins/floodgate/key.pem sur le proxy est identique octet par octet au même fichier sur chaque backend. Copiez un key.pem canonique vers chaque composant (autres backends + le proxy) et redémarrez tout. 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.

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 après que le backend a enregistré Wrote merged Geyser mappings: N entries. 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.