Aller au contenu principal

Extension Geyser et entités Bedrock personnalisées

La conversion du pack fournit les textures et modèles d'objets pris en charge. Les entités personnalisées, comme un boss modélisé avec sa propre apparence et ses animations, nécessitent aussi du code dans Geyser. L'extension Geyser de RSPM assure cette intégration pour les plugins producteurs compatibles et leurs ressources d'entités Bedrock.

Vous ne la téléchargez pas séparément. Le même ResourcePackManager.jar que vous installez comme plugin est l'extension.

Un seul jar, trois rôles​

ResourcePackManager.jar est simultanément :

  • le plugin backend Bukkit/Paper,
  • le plugin proxy Velocity et BungeeCord,
  • et une extension Geyser.

Chaque chargeur utilise son point d'entrée. Les anciennes versions fournissaient un ResourcePackManager-GeyserBridge.jar séparé. Ce fichier est retiré. Si l'installateur le trouve, il place le jar universel dans la file de mise à jour de Geyser pour le remplacer au redémarrage.

Installation de l'extension​

RSPM installe l'extension à votre place dans les cas où il le peut. Ce qui se passe dépend de l'endroit où se trouve Geyser :

Votre configurationCe que fait RSPM
Geyser-Spigot sur le même serveurÀ la première installation, copie le jar en cours d'exécution vers plugins/Geyser-Spigot/extensions/ResourcePackManager.jar. Si le jar existant contient des octets différents, prépare son remplacement dans extensions/update/, sous réserve de la protection contre les versions antérieures. Une nouvelle installation ou un remplacement préparé demande un redémarrage ; un jar actuel identique ne nécessite aucune copie.
Geyser sur le proxy (Geyser-Velocity / Geyser-BungeeCord)Le rôle proxy fait la même chose dans le dossier Geyser-*/extensions/ du proxy.
Floodgate local, Geyser externe (Geyser s'exécute dans un processus séparé)Exporte une copie sous plugins/ResourcePackManager/geyser-extension/. Suivez le chemin exact indiqué dans la console : il peut pointer vers le sous-dossier update/ si un ancien export existe. Copiez ce jar dans extensions/ du Geyser externe et redémarrez Geyser. Exporter l'extension seul ne configure ni la distribution externe du pack ni le chargement des définitions au démarrage.
Ni Geyser ni Floodgate présentsRien à faire — RSPM enregistre une ligne d'information et ignore l'installation.

L'installateur conserve toute version valide plus récente trouvée dans le jar universel installé, l'ancien pont ou une mise à jour en attente. Il compare aussi les sommes de contrôle : des octets différents avec la même version peuvent nécessiter un remplacement.

L'installation nécessite toujours un redémarrage. Geyser charge les extensions au démarrage, donc un jar fraîchement copié ou mis en file d'attente ne fait rien tant que le serveur ou le proxy n'a pas redémarré.

Désactiver l'installation automatique​

Chaque rôle possède son propre interrupteur, et ils sont indépendants :

OùRéglageDéfaut
Backend plugins/ResourcePackManager/config.ymlgeyserExtensionAutoInstalltrue
config.yml du proxygeyser-extension-auto-installtrue

Mettre l'un ou l'autre à false empêche ce rôle d'installer l'extension ou de préparer sa mise à jour, et une ligne de journal le signale. Ce réglage a les effets suivants :

  • Cela empêche les futures installations et mises en file de mises à jour.
  • Cela ne supprime pas un jar installé et n'annule pas une mise à jour déjà en attente. Pour désactiver le pont, mettez les réglages concernés à false et arrêtez complètement Geyser. Supprimez ResourcePackManager.jar dans extensions/ et extensions/update/, ainsi que tout ancien ResourcePackManager-GeyserBridge.jar dans ces dossiers, puis relancez Geyser. Une copie laissée dans la file peut réinstaller l'extension au démarrage. Supprimez uniquement ces fichiers RSPM.
  • Désactiver ce réglage n'affecte ni la conversion du pack, ni sa distribution, ni une extension déjà installée. Supprimer l'extension désactive l'intégration des entités Bedrock personnalisées ; la conversion des objets et la distribution du pack restent indépendantes.

Le désactiver sur le backend empêche aussi de placer une mise à jour RSPM téléchargée dans la file du Geyser-Spigot local. L'extension et le plugin peuvent alors diverger. Maintenez leurs fichiers alignés manuellement ; la protection ci-dessous vérifie les classes Geyser nécessaires et la compatibilité binaire, pas l'égalité des versions du plugin et de l'extension.

Rôle de l'extension​

  • Enregistre auprès de Geyser les définitions d'entités Bedrock personnalisées de RSPM au démarrage, en lisant les identifiants d'entités dans le pack Bedrock généré. Les propriétés de chaque entité sont collectées à partir des contrôleurs d'animation et de rendu référencés par son fichier d'entité client, associés par identifiant de contrôleur : les ensembles dont les longs chemins de fichiers ont été raccourcis enregistrent donc quand même leurs propriétés et leurs animations.
  • Remplace la définition Bedrock des entités qui apparaissent, afin qu'une entité modélisée apparaisse comme son entité Bedrock personnalisée plutôt que comme le repli vanilla.
  • Applique en direct les données d'entité et les surcharges de propriétés pendant l'existence de l'entité.
  • Amorce tôt les identifiants réseau de recettes de Geyser, ce qui évite une catégorie de problèmes de collision d'ID de recettes sur Geyser 2.11.

Les ressources proviennent des ensembles d'entités décrits dans Conversion Bedrock. Un plugin fournit les fichiers d'entités Bedrock natifs sous assets/<namespace>/rspm_bedrock_pack/, et RSPM les importe dans le pack généré. Le producteur doit aussi marquer les entités Java correspondantes via le pont ; les ressources seules ne transforment pas des entités arbitraires en modèles personnalisés.

Au démarrage, l'extension recherche les identifiants dans les entrées entity/*.entity.json du pack local généré par RSPM. Elle vérifie les chemins de sortie habituels du proxy plugins/resourcepackmanager/work/merged/Bedrock.zip et plugins/ResourcePackManager/work/merged/Bedrock.zip, puis la sortie backend plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip, relativement au répertoire de travail de Geyser. Un processus Geyser externe ne peut pas lire automatiquement la sortie d'une autre machine. Vérifiez dans le journal quel pack a été préchargé ; copier l'extension ne fournit pas automatiquement les définitions.

Versions de Geyser requises​

L'extension cible Geyser 2.11+.

Son descripteur déclare le niveau d'API Geyser 2.9.0. Ce niveau inférieur ne prouve pas la compatibilité avec un ancien Geyser. À l'exécution, l'extension vérifie les classes requises et désactive le pont si elles sont absentes.

En cas d'incompatibilité de classes ou de liaison, l'extension est conçue pour se désactiver sans faire tomber Geyser. Sa couche d'entrée ne référence que des types de l'API Geyser présents depuis longtemps ; les classes sensibles à la version sont vérifiées avant le démarrage du cœur. Si votre version de Geyser ne fournit pas une classe nécessaire au pont, celui-ci se désactive et le signale :

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.

La désactivation du pont ne désactive ni le convertisseur d'objets ni le fournisseur de packs, qui sont indépendants. Ceux-ci nécessitent toujours leurs propres API Geyser compatibles et une distribution réussie du pack. Utilisez une combinaison RSPM/Geyser compatible pour rétablir les entités personnalisées.

Les versions antérieures de RSPM obtenaient le même résultat en injectant dans le registre de Geyser une copie embarquée de l'un de ses traducteurs de paquets internes. Ce remplacement de traducteur a disparu : l'extension utilise désormais le cycle de vie et les événements publics d'entités de Geyser 2.11 pour l'enregistrement et le remplacement des définitions d'apparition. Le cœur sonde toujours un ensemble limité d'internes de Geyser utilisés pour construire les instances de définitions et recevoir les messages de plugin en aval, ce qui explique pourquoi la garde de compatibilité et la correspondance exacte des versions RSPM/Geyser restent importantes.

Ordre de démarrage : pourquoi un redémarrage est parfois nécessaire​

Geyser enregistre les définitions d'entités pendant sa fenêtre de démarrage. Si RSPM génère le premier pack Bedrock après sa fermeture, les définitions arrivent trop tard pour les registres en cours d'exécution. RSPM demande un redémarrage afin de précharger le pack généré au prochain lancement :

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.

Cet avertissement apparaît lorsqu'un nouvel identifiant d'entité ou un type de propriété nouveau ou modifié arrive après la fermeture de l'enregistrement. Réexporter les mêmes définitions et types de propriétés ne nécessite pas de redémarrage.

Redémarrez le processus serveur ou proxy qui héberge Geyser après la première génération réussie du pack. Une reconnexion seule n'active pas les définitions arrivées trop tard. Au prochain démarrage, le pack doit être disponible au chemin local lu par l'extension et les deux fenêtres d'enregistrement doivent être reçues. La ligne d'état du démarrage indique si cela a eu lieu.

Vérifier le fonctionnement​

  1. Vérifiez que le dossier extensions/ cible contient bien ResourcePackManager.jar.
  2. Au démarrage, vérifiez la ligne RSPM Geyser bridge health. Elle contient la version de l'extension, artifactSha256, activationRoute, loadedDefinitions, packUuid et definitionWindows. Pour un pack contenant des entités personnalisées, attendez-vous à des définitions enregistrées, à l'UUID du pack prévu et à definitionWindows=observed. MISSED ou RSPM GEYSER BRIDGE UNHEALTHY indique qu'une fenêtre d'enregistrement a été manquée ; une extension indiquée comme chargée ne suffit pas.
  3. Connectez-vous sur Bedrock et vérifiez l'apparence et l'animation d'une entité modélisée. Si elle reste une entité vanilla, comme un porte-armure, vérifiez l'activation du pont, la distribution au client, les définitions enregistrées et l'intégration du producteur. Un journal de démarrage réussi ne prouve pas à lui seul que le client a affiché l'entité.

Dépannage​

« L'extension est chargée, mais les entités sont toujours des porte-armures. » Le pack et l'extension sont deux moitiés distinctes. Confirmez d'abord que le pack Bedrock lui-même a atteint le client (voir Conversion Bedrock) ; sans les ressources d'entités du pack, les définitions n'ont rien à afficher.

« Ça marchait, puis j'ai mis Geyser à jour et les entités ont cassé. » Cherchez le message d'auto-désactivation ci-dessus. Une mise à jour de Geyser peut déplacer la surface d'API que le pont recherche.

« Rien n'a jamais été installé dans extensions/. » Cherchez dans la console Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall (backend) ou ... by geyser-extension-auto-install (proxy). Quelqu'un a désactivé l'interrupteur. Si Geyser et Floodgate sont tous deux absents localement, vous verrez plutôt Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation — c'est RSPM qui décide correctement qu'il n'y a nulle part où installer.

« J'ai mis RSPM à jour mais l'extension est toujours en ancienne version. » L'extension n'est remplacée qu'au redémarrage, et si RSPM l'a placée dans la file de mise à jour de Geyser, un redémarrage est nécessaire pour qu'elle soit substituée. Gardez le jar du plugin et le jar de l'extension sur la même version — c'est le même fichier, donc recopier le plugin suffit.

L'extension installe des abonnements précoces au cycle de vie par code, en plus de ses gestionnaires annotés. Sur Velocity, le plugin proxy relaie également les événements de cycle de vie et de session pour couvrir les démarrages où les abonnements automatiques ont été manqués. Aucune configuration n'est nécessaire. Utilisez la ligne d'état du démarrage et les avertissements d'enregistrement ou de relais pour diagnostiquer les échecs d'activation.

Pour continuer​