Conversion Java vers Bedrock

ResourcePackManager peut convertir le pack de ressources Java fusionné en pack de ressources Bedrock afin que les clients GeyserMC voient le même contenu personnalisé que les clients Java. Cette conversion est activée par défaut.

Quand la conversion s'exécute

La conversion est conditionnée par la présence d'une cible Bedrock. RSPM considère qu'une cible est présente si l'une de ces conditions est vraie :

1. Geyser-Spigot est installé sur ce backend (les joueurs Bedrock arrivent sur Geyser localement).
2. Floodgate est installé sur ce backend (configuration proxy-backend typique — Floodgate s'exécute localement, Geyser se trouve ailleurs).
3. Le mode réseau est actif — RSPM a détecté qu'il se trouve derrière un proxy Velocity / BungeeCord / Waterfall. Le backend produit son pack Bedrock et l'expose sur un petit serveur HTTP afin que le plugin proxy puisse le récupérer.

Si aucune de ces conditions n'est remplie, le convertisseur ne représente qu'un surcoût et est ignoré silencieusement. /rspm status explique précisément pourquoi lorsque le pack n'a pas été généré.

Ce qui est converti

Le convertisseur est agnostique vis-à-vis des espaces de noms. Il parcourt chaque fichier assets/<namespace>/items/*.json au format de définition d'items 1.21.4+. Pour chaque modèle feuille, il fait soit :

• émettre une icône d'inventaire Bedrock plate (pour les parents intégrés plats du type minecraft:item/generated et similaires), soit
• émettre une géométrie Bedrock, un attachable, un fichier d'animation et une icône d'inventaire 2D rendue par logiciel (pour les vrais modèles 3D).

Un identifiant Bedrock unique est généré par paire (modèle × item de base), de sorte qu'un même modèle d'épée enregistré contre plusieurs items de base n'entre pas en collision côté Geyser.

Les sets d'armures personnalisées sont détectés lorsqu'un fichier voisin assets/<namespace>/equipment/<material>.json existe. Le convertisseur câble un attachable d'armure qui combine la géométrie d'armure vanilla avec la texture Java comme couche visible, afin que les joueurs Bedrock voient la bonne texture d'armure en portant l'item.

Les UUID de l'en-tête et du module du manifeste du pack Bedrock sont dérivés de manière déterministe de la chaîne de version du plugin (graines rspm_bedrock_header:<pluginVersion> et rspm_bedrock_module:<pluginVersion>), de sorte qu'ils restent stables entre les reconstructions d'une même version du plugin et ne changent que lorsque la version du plugin change. Le nom du pack lui-même n'est utilisé que pour header.name, pas pour l'UUID. Le triplet de version est incrémenté à chaque build à partir d'un jeton de cache-bust dérivé d'un condensé de contenu SHA-256 du pack Bedrock préparé — un contenu identique produit la même version (ainsi les reconstructions sans effet ne perturbent pas le cache de Geyser), tandis que de vrais changements de contenu invalident le cache de pack de Bedrock indexé par (uuid, version). Le temps de build (System.currentTimeMillis()) n'est utilisé qu'en repli lorsque le condensé de contenu ne peut pas être calculé.

Distribution en direct par session (autonome)

Lorsque Geyser-Spigot est détecté sur le même backend, RSPM enregistre un abonné SessionLoadResourcePacksEvent. Chaque joueur Bedrock qui se connecte après une nouvelle fusion reçoit le dernier pack Bedrock servi directement depuis le disque — aucun redémarrage du serveur n'est requis pour que les modifications de textures ou de modèles d'items existants prennent effet.

Les mappings d'items personnalisés de Geyser (les JSON dans custom_mappings/) sont toujours figés au démarrage, donc ajouter de nouveaux items personnalisés ou en supprimer nécessite un redémarrage du serveur avant que les clients Bedrock voient ces changements. RSPM pré-déploie le fichier de mappings du précédent run tôt dans le démarrage afin que l'enregistrement des items personnalisés effectué par Geyser au démarrage le récupère automatiquement.

Les joueurs Bedrock actuellement connectés conservent le pack qu'ils ont reçu au moment de leur connexion — c'est une contrainte du protocole Bedrock, pas quelque chose que le plugin puisse outrepasser en pleine session.

Comment cela fonctionne en mode proxy

Dans un réseau proxy, le backend lui-même n'enregistre pas d'abonné SessionLoadResourcePacks (il n'y a pas de Geyser local auquel s'abonner). À la place :

1. Le backend produit output/ResourcePackManager_Bedrock.zip + output/rspm_geyser_mappings.json comme d'habitude.
2. Le backend démarre un petit serveur HTTP (port auto-dérivé, mcPort + 1 par défaut) exposant les routes /bedrock.zip et /mappings.json qui lisent le fichier à neuf à chaque requête, et annonce au proxy le port exact auquel il s'est lié.
3. Le plugin proxy interroge toutes les 5 secondes via If-Modified-Since, télécharge les sorties de chaque backend lorsqu'elles changent et attend que la boîte de réception se stabilise.
4. Le plugin proxy fusionne le pack Bedrock de chaque backend en un seul pack à l'échelle du réseau et le sert aux clients Bedrock via le Geyser du proxy.
5. Si le proxy ne peut pas atteindre directement le port HTTP d'un backend (fréquent sur l'hébergement partagé/managé où les ports adjacents sont bloqués par le pare-feu), le backend pousse ses fichiers vers un point de relais magmaguy.com et le proxy les récupère par ce biais.

Voir Réseaux proxy pour la configuration. Côté proxy, la conversion (en fait la fusion) est entièrement automatique ; il n'y a aucune configuration côté proxy pour le pipeline Bedrock.

Fichiers de sortie

Après une fusion réussie, les fichiers Bedrock se trouvent dans :

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json

Si l'auto-déploiement est activé et que Geyser a été détecté sur la même JVM, le fichier de mappings est également copié vers :

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Le zip du pack Bedrock n'est pas copié dans <geyser-folder>/packs/ — il est servi en direct par session à la place. RSPM supprime également toute copie héritée que d'anciennes versions du plugin auraient laissée dans ce dossier, afin que Geyser ne finisse pas par servir le pack deux fois (des UUID en double sèmeraient la confusion chez le client Bedrock).

Lorsque le convertisseur ne trouve rien à convertir (aucune définition d'items dans le pack fusionné), RSPM supprime toute sortie Bedrock périmée d'un run précédent plutôt que d'expédier un pack vide. La route /bedrock.zip du backend renvoie alors proprement un 404, ce qui est le bon signal pour le proxy indiquant que ce backend n'a aucun contenu Bedrock à apporter.

Paramètres de config.yml

# Active/désactive entièrement la conversion Java vers Bedrock.
bedrockConversionEnabled: true

# Copie le fichier de mappings personnalisés Geyser dans le dossier
# custom_mappings/ du dossier Geyser détecté à chaque fusion.
bedrockAutoDeployToGeyser: true

# Surcharge manuelle pour le dossier de données Geyser. Vide = détection automatique.
# Peut être absolu ou relatif au répertoire plugins/.
bedrockGeyserFolder: ""

# Journalisation détaillée de la progression par item / par os du pipeline Bedrock.
# Défaut false — un run propre émet un unique résumé « Bedrock conversion complete: N
# mappings » au lieu de dizaines à centaines de lignes par item. Activez-le
# lors du débogage d'un problème de conversion spécifique.
bedrockConverterDebug: false

La détection automatique du dossier Geyser examine, dans cet ordre :

1. bedrockGeyserFolder s'il est défini (traité d'abord comme chemin absolu, puis comme chemin relatif à plugins/).
2. plugins/Geyser-Spigot/
3. plugins/Geyser-*/ (toute variante)
4. config/Geyser-*/ (pour les configurations Fabric/NeoForge)

Réglage de l'affichage des items tenus en main : bedrock_display_offsets.yml

Bedrock rend l'item tenu en main via un os parent dont la pose de repos diffère des transformations première et troisième personne de Java, donc la conversion algorithmique doit appliquer un décalage de base par-dessus tout ce que la transformation display du modèle Java spécifie. Les décalages par défaut fonctionnent pour les modèles Java typiques droitiers, mais certains cas particuliers peuvent nécessiter un réglage.

La première personne et la troisième personne sont deux passes de rendu Bedrock totalement séparées (os parents différents, poses de repos différentes), donc chacune dispose de son propre ensemble indépendant de six paramètres. Régler l'une n'affecte pas l'autre.

# ===== Première personne (main droite, vue par le porteur) =====
firstPersonBaseRotationX: -90.0   # tangage (basculement vers/loin de la caméra). Par défaut annule la rotation parente.
firstPersonBaseRotationY: 0.0     # lacet (rotation autour de la ligne verticale)
firstPersonBaseRotationZ: 0.0     # roulis (autour de l'axe caméra-avant)
firstPersonBasePositionX: 0.0     # vertical à l'écran (positif = vers le haut)
firstPersonBasePositionY: 12.5    # profondeur (positif = plus loin dans la scène)
firstPersonBasePositionZ: 0.0     # horizontal à l'écran (positif = vers la droite)

# ===== Troisième personne (main droite, vue par les autres joueurs / F5) =====
thirdPersonBaseRotationX: 90.0    # tangage tel que les observateurs le voient
thirdPersonBaseRotationY: 0.0     # lacet
thirdPersonBaseRotationZ: 0.0     # roulis autour de l'axe long de l'item
thirdPersonBasePositionX: 0.0     # horizontal en travers du corps du porteur (positif = vers l'extérieur)
thirdPersonBasePositionY: 12.5    # vertical (positif = monte le modèle)
thirdPersonBasePositionZ: 0.0     # profondeur par rapport au porteur (positif = vers l'avant)

Les valeurs de position sont en pixels, où 1 pixel = 1/16 de bloc. Les rotations sont en degrés.

Le client Bedrock recharge à chaud le JSON des attachables sans relancement. Si un client de test Bedrock est connecté, modifiez la valeur, exécutez /rspm reload, et la prochaine connexion Bedrock (ou dans certains cas le même joueur connecté après une petite action en jeu qui relie l'attachable) affichera le nouveau décalage. Itérez jusqu'à obtenir le bon rendu.

Journalisation de débogage

Deux surfaces de débogage sont disponibles :

• Backend : bedrockConverterDebug: true dans config.yml active les lignes de journal par item, par attachable et par mapping émises par le convertisseur. Utile lorsque vous avez besoin de savoir pourquoi un item spécifique n'a pas été inclus dans le pack Bedrock.
• Proxy (Velocity et BungeeCord) : /rspm debug bedrock on active le flux de journal [RSPM-BedrockDebug] émis par le GeyserBinder du proxy. Utile lorsque les joueurs Bedrock rejoignent le proxy mais ne voient pas le pack. Le paramètre est remis à off au redémarrage du proxy afin qu'il ne puisse pas rester activé par accident.

Limites et comportements connus

• Les icônes d'inventaire 3D sont rendues par logiciel à partir de la transformation display.gui du modèle Java. Le rendu est raisonnable mais pas parfait au pixel près ; si l'icône paraît incorrecte, la cause la plus fréquente est un fichier de texture référencé par le modèle qui est manquant ou mal nommé.
• Les textures « flipbook » utilisées comme icônes d'item sont rognées à la frame 0 — le item_texture.json de Bedrock ne prend pas en charge les icônes animées, seulement les textures animées de blocs/terrain via flipbook_textures.json.
• La version du format de géométrie des attachables est fixée à 1.21.0 ; mettez Geyser à jour si votre installation ne peut pas l'analyser.
• Les fichiers de surcharge de modèles d'items vanilla hérités (tout ce qui se trouve sous assets/minecraft/models/item/, y compris shield.json et crossbow.json) sont fusionnés entre packs plutôt que de laisser un seul pack l'emporter entièrement : seuls les tableaux overrides sont combinés (dédupliqués par clé de surcharge), tandis que les champs hors surcharge restent en mode priorité-la-plus-haute-l'emporte. Aucun fichier n'est traité de façon particulière.
• Si le convertisseur ne peut pas résoudre un fichier de texture ou de modèle référencé, cette feuille est ignorée et un avertissement [BedrockConverter] est enregistré (ou une ligne de débogage si bedrockConverterDebug est désactivé) ; le reste du pipeline continue.
• Lorsque le pack fusionné ne contient aucun item convertible, aucun pack Bedrock n'est émis du tout et toute sortie d'un run précédent est supprimée. RSPM n'expédie pas un pack vide inutile d'environ 22 Ko accompagné d'une invite.