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+, de manière récursive et y compris l'espace de noms minecraft.

Routage plat vs 3D

Pour chaque modèle feuille, le convertisseur décide lequel des deux pipelines utiliser. Les modèles enracinés dans minecraft:item/generated ou minecraft:builtin/generated restent sur la voie plate. Pour toute autre chaîne de parents, un modèle emprunte le pipeline 3D uniquement lorsque le modèle fusionné porte un tableau elements non vide ; un modèle sans géométrie est un sprite 2D.

• Plat — la texture layer0 du modèle est copiée directement vers textures/items/<hash>.png et enregistrée comme icône Geyser. Sur Bedrock, l'item affiche le bon sprite 2D dans l'inventaire et en main, exactement comme Java le rend.
• 3D — le convertisseur assemble un atlas de textures, convertit les cuboïdes Java en géométrie Bedrock, génère les animations de tenue/tête, rend par logiciel une icône d'inventaire 64×64 et écrit un attachable par mapping (model × base item × predicate shape).

Pourquoi la vérification de la géométrie importe : un outil plat tenu en main (parent minecraft:item/handheld avec seulement une texture layer0 et aucun élément) reste un sprite 2D. Les versions antérieures poussaient les items plats tenus en main dans le pipeline 3D, où ils échouaient à l'étape de la géométrie et disparaissaient sur Bedrock ou retombaient sur l'icône de l'item de base vanilla. Cela affectait particulièrement les packs ItemsAdder, qui livrent beaucoup d'items plats tenus en main. Comme elements est lu depuis la chaîne de parents fusionnée, un modèle non généré qui hérite sa géométrie d'un parent est tout de même routé vers la 3D.

Un identifiant Bedrock unique est généré par mapping (model × base item × predicate shape), de sorte qu'un même modèle d'épée enregistré contre plusieurs items de base ou plusieurs branches de prédicat n'entre pas en collision côté Geyser. Les noms de fichiers générés sont de courts hachages de contenu plutôt que des noms lisibles, car les noms complets espace-de-noms+chemin dépassaient régulièrement la limite de 80 caractères de chemin de pack de Geyser.

Packs hérités antérieurs à 1.21.4

Les packs qui utilisent encore l'ancien format assets/minecraft/models/item/*.json + overrides[].predicate.custom_model_data sont également pris en compte et synthétisés vers la forme moderne de dispatch par plage. C'est du « meilleur effort » : la console indique combien d'items utilisaient le format hérité, car ils ne s'affichent souvent pas correctement sur Bedrock. Migrer le pack source vers le format de définition d'items 1.21.4+ est la vraie solution.

Bundles d'entités Bedrock écrits à la main

Un plugin peut livrer directement des ressources d'entités Bedrock natives en les plaçant sous assets/<namespace>/rspm_bedrock_pack/ dans son pack Java. RSPM copie ces fichiers tels quels dans le pack Bedrock généré. Seuls les répertoires liés aux entités sont acceptés (entity, models/entity, animations, animation_controllers, render_controllers, materials, textures/entity) afin qu'un plugin contributeur ne puisse pas masquer le manifeste du pack ou l'atlas d'icônes. Les chemins trop longs sont raccourcis automatiquement, avec réécriture des références croisées JSON correspondantes, de sorte que les références de géométrie et de texture continuent de se résoudre. Deux espaces de noms écrivant des octets différents vers la même destination constituent une erreur fatale plutôt qu'un écrasement silencieux.

C'est le mécanisme derrière les véritables entités Bedrock personnalisées — voir Extension Geyser et entités personnalisées. Un pack ne contenant que des bundles d'entités et aucun mapping d'item est tout de même livré.

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 d'en-tête visible est le texte fixe ResourcePackManager Bedrock Pack ; il ne fait pas partie de 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 et, lorsque des mappings d'items existent, output/rspm_geyser_mappings.json.
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, en privilégiant les ETags forts via If-None-Match tout en conservant la compatibilité If-Modified-Since pour les backends plus anciens. Il 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. La fusion côté proxy est automatique et n'a aucun interrupteur d'activation. La configuration du proxy ne comporte que deux réglages : network-http-offset-v2, le décalage de port de repli utilisé avant qu'une annonce de point d'accès du backend soit disponible, et geyser-extension-auto-install, l'équivalent côté proxy de geyserExtensionAutoInstall.

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  # only when item mappings exist

Si l'auto-déploiement est activé et qu'un dossier de données Geyser local a été détecté, 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. Si une version antérieure de RSPM a laissé un ResourcePackManager_Bedrock.zip dans le dossier de packs de Geyser, le plugin actuel ne le supprime pas tant que Geyser tourne : Geyser a déjà scanné ce chemin et peut encore le garder en mémoire. RSPM saute l'enregistrement du fournisseur en direct pour ce démarrage et affiche le chemin hérité exact. Arrêtez complètement le serveur, supprimez uniquement ce fichier hérité, puis redémarrez le serveur. Un /reload ne suffit pas.

Lorsque le convertisseur ne trouve rien à publier (aucun mapping d'item convertible et aucun fichier de bundle d'entité autorisé), 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. Les packs contenant uniquement des entités sont tout de même publiés.

Paramètres de config.yml

# Toggles Java-to-Bedrock conversion altogether.
bedrockConversionEnabled: true

# Copies the Geyser custom mappings file into the detected Geyser folder's
# custom_mappings/ directory on each mix.
bedrockAutoDeployToGeyser: true

# Manual override for the Geyser data folder. Empty = auto-detect.
# Relative values are tried from the server working directory first, then
# relative to plugins/. Absolute paths work directly.
bedrockGeyserFolder: ""

# Installs and updates the universal ResourcePackManager.jar in Geyser's
# extensions/ folder, which is what makes custom Bedrock ENTITIES render
# instead of armor stands. Separate from pack conversion above — items,
# textures and models convert and serve normally either way.
# Setting this false stops future installation and update staging; it does NOT
# remove an extension jar that is already installed. Delete that by hand while
# Geyser is stopped. See the Geyser extension page.
geyserExtensionAutoInstall: true

# Verbose per-item / per-bone progress logging from the Bedrock pipeline.
# Default false — a clean run emits a single "Bedrock conversion complete: N
# mappings" summary instead of dozens to hundreds of per-item lines. Flip on
# when debugging a specific conversion issue.
bedrockConverterDebug: false

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

1. bedrockGeyserFolder s'il est défini (utilisé tel quel en premier, donc les chemins relatifs se résolvent depuis le répertoire de travail du serveur ; si cela n'existe pas, il est essayé relativement à plugins/). Les chemins absolus fonctionnent également.
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.

# ===== First-person (right hand, seen by the holder) =====
firstPersonBaseRotationX: -60.0   # pitch (tipping toward/away from camera)
firstPersonBaseRotationY: 123.0   # yaw (spinning around vertical line)
firstPersonBaseRotationZ: 170.0   # roll (around camera-forward axis)
firstPersonBasePositionX: -8.0    # vertical on screen (positive = up)
firstPersonBasePositionY: 7.5     # depth (positive = further into the scene)
firstPersonBasePositionZ: -5.0    # horizontal on screen (positive = right)

# ===== Third-person (right hand, seen by other players / F5) =====
thirdPersonBaseRotationX: 90.0    # pitch as observers see it
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # roll around the item's long axis
thirdPersonBasePositionX: 0.0     # horizontal across the holder's body (positive = outward)
thirdPersonBasePositionY: 6.0     # vertical (positive = raises the model)
thirdPersonBasePositionZ: -10.0   # depth relative to holder (positive = forward)

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

Modifiez la valeur, exécutez /rspm reload, puis reconnectez le client de test Bedrock afin que sa prochaine connexion reçoive le pack reconstruit. Itérez jusqu'à ce que l'item tenu en main ait 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. C'est distinct de verboseLogging, qui couvre la fusion des packs et l'hébergement plutôt que le pipeline Bedrock — pour un problème de conversion, c'est bedrockConverterDebug qu'il vous faut.
• 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 le reste du pipeline continue. Activez bedrockConverterDebug pour obtenir des traces de résolution détaillées. Un avertissement normal est émis lorsqu'un item se retrouve sans aucune texture personnalisée valide ou qu'un JSON de modèle référencé ne peut pas être analysé.
• Une définition d'item malformée est un cas différent et est désormais fatale pour le cycle : un JSON non analysable interrompt toute la conversion avec Bedrock conversion failed: ... plutôt que de produire silencieusement un pack partiel. Un pack qui se convertissait « à peu près » vous dit maintenant qu'il ne s'est pas converti.
• Les items de base bannière et redstone sont ignorés. Les items personnalisés dont la base est l'une des 16 bannières teintes ou minecraft:redstone ne reçoivent pas de mapping d'item personnalisé Geyser, car Geyser en dérive un placeur de bloc invalide. Bedrock affiche l'icône vanilla pour ceux-ci. La console nomme les items concernés lorsque cela se produit.
• La conversion est annulable de façon coopérative : un /rspm reload ou un arrêt en cours de route s'interrompt proprement au lieu de laisser une sortie à moitié écrite. Le fichier de mappings Geyser n'est publié qu'après la réussite du zip du pack, vous n'obtenez donc jamais un nouveau pack associé à des mappings obsolètes.
• Lorsque le pack fusionné ne contient ni mapping d'item convertible ni fichier de bundle d'entité autorisé, aucun pack Bedrock n'est émis et toute sortie d'un run précédent est supprimée. Un pack contenant uniquement des entités reste valide et est émis même s'il n'y a aucun mapping d'item.

Optimisation de la taille du pack

Avant de publier un pack Bedrock, RSPM déduplique les fichiers de texture identiques octet par octet qui utilisent la même extension et réécrit les références de texture JSON exactes vers le fichier conservé. Il conserve délibérément les alias lorsqu'une référence est ambiguë, intégrée dans une chaîne plus grande, ou trouvée dans un JSON malformé/opaque, afin que l'optimisation ne casse pas silencieusement des références de ressources.