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 contenu personnalisé compatible du pack 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. Le backend produit son pack Bedrock et l'expose sur un petit serveur HTTP afin que le plugin proxy puisse le récupérer.

La conversion doit aussi être activée avec bedrockConversionEnabled. Si elle est désactivée ou qu'aucune cible n'est présente, RSPM retire l'ancienne sortie Bedrock et ignore la conversion. /rspm status indique pourquoi le pack n'a pas été généré.

Ce qui est converti

Le convertisseur traite tous les espaces de noms. Il parcourt récursivement chaque fichier assets/<namespace>/items/**/*.json au format de définition d'objets 1.21.4+, y compris dans l'espace de noms minecraft.

Choix entre rendu plat et 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. Bedrock utilise cette couche comme sprite 2D dans l'inventaire et en main ; les autres couches ou branches du modèle Java ne sont pas nécessairement conservées.
• 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 × item definition × 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.

RSPM dérive un identifiant Bedrock pour chaque mapping (model × base item × item definition × predicate shape). Cela sépare les variantes d'objet de base et de prédicat d'un modèle d'épée, et attribue des identifiants distincts à deux définitions d'objet qui réutilisent un même modèle. Les noms de fichiers générés utilisent des hachages courts des identifiants source, et non du contenu des fichiers, pour éviter l'avertissement de Geyser concernant les chemins de 80 caractères ou plus.

Branches de modèles d'objets prises en charge

La conversion accepte les nœuds model, condition, range_dispatch et select, avec ou sans préfixe minecraft:. Les autres types, notamment composite et special, sont ignorés. Le bon rendu d'un pack Java ne garantit pas que toutes ses branches puissent être représentées sur Bedrock.

Nœud	Propriétés prises en charge et comportement de secours
condition	broken, damaged, fishing_rod_cast, has_component, custom_model_data. using_item ne conserve que on_false comme modèle au repos. Les autres conditions non prises en charge ignorent les deux branches.
range_dispatch	damage, count, bundle_fullness, custom_model_data. use_duration et les autres propriétés non prises en charge ne conservent que fallback, s'il existe.
select	charge_type, trim_material, context_dimension, custom_model_data. display_context conserve le cas gui, ou son fallback s'il n'existe aucun cas GUI. Les autres propriétés non prises en charge ne conservent que leur fallback.

Les étapes de tension d'un arc Java et les modèles distincts selon le contexte ne sont donc pas automatiquement conservés. Activez bedrockConverterDebug pour voir les messages des nœuds et propriétés ignorés, puis vérifiez le résultat sur un client Bedrock.

Packs hérités antérieurs à 1.21.4

Le lecteur du format hérité lit les fichiers JSON directement dans assets/minecraft/models/item/ et construit des définitions par plages à partir des surcharges ayant un predicate.custom_model_data numérique. Il ne parcourt pas les sous-dossiers hérités et ne conserve pas les autres prédicats de la surcharge. Une surcharge qui dépend aussi de la tension d'un arc perd donc cette condition. Le nombre d'objets hérités n'apparaît qu'avec bedrockConverterDebug activé. Utilisez le format de définition d'objets 1.21.4+ pour les packs maintenus et vérifiez ses branches dans le tableau de compatibilité ci-dessus.

Objets de base

Geyser associe chaque objet personnalisé à un ou plusieurs objets de base Java. RSPM les choisit ainsi :

• Un fichier de surcharge hérité et une définition racine assets/minecraft/items/<item>.json sont associés à cet objet vanilla.
• Les autres définitions sont associées d'après leur nom de fichier. Les mots désignant des armes et des outils renvoient aux objets vanilla correspondants : sword aux six épées, pickaxe aux six pioches, wand ou staff à minecraft:stick, spear à minecraft:trident, etc. Les noms d'armures utilisent le fichier d'équipement de l'espace de noms ou des mots d'emplacement tels que helmet et boots. Tout le reste utilise un ensemble de repli : papier, bâton, étiquette, boussole et les six épées.
• Les définitions de l'espace de noms freeminecraftmodels sont aussi associées à minecraft:leather_horse_armor, l'objet que FreeMinecraftModels utilise pour afficher les os des modèles.
• Un plugin producteur peut déclarer les véritables objets de base dans assets/<namespace>/rspm_item_bases/<path>.json, où <path> correspond à items/<path>.json. Le fichier contient {"base_items": ["minecraft:blaze_rod"]}. Seuls les identifiants minecraft: sont lus, et ils s'ajoutent au choix fondé sur le nom de fichier. FreeMinecraftModels en écrit un pour chaque objet personnalisé avec le matériau indiqué par sa configuration : une baguette basée sur BLAZE_ROD affiche donc son modèle sur Bedrock.

Objets réservés à Java

Un plugin producteur peut exclure des objets de la conversion en plaçant un fichier dans assets/<namespace>/rspm_item_java_only/<path>.json. Seule la présence du fichier compte. Il exclut items/<path>.json et toutes les définitions d'objets situées sous items/<path>/ : ces objets ne reçoivent ni mapping Geyser, ni icône, ni attachable. FreeMinecraftModels l'utilise pour les objets sprites de ses effets de particules, qui ne servent qu'aux affichages d'objets Java ; les joueurs Bedrock voient à la place la particule native. Un pack dont tous les objets sont réservés à Java ne déclenche pas l'avertissement de format hérité.

Ressources d'entités Bedrock créées manuellement

Un plugin peut fournir des ressources d'entités Bedrock natives sous assets/<namespace>/rspm_bedrock_pack/ dans son pack Java. RSPM les importe 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, particles, textures/entity), ce qui empêche de remplacer le manifeste ou l'atlas d'icônes. Les chemins pris en charge de 80 caractères ou plus sont raccourcis et les références JSON exactes à ces chemins, dans le même ensemble de ressources, sont mises à jour. Les autres fichiers sont copiés tels quels. Si deux espaces de noms produisent des octets différents à la même destination, l'import échoue.

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

La conversion des armures portées intervient sur la voie des objets plats, pour un objet de base d'armure ou des élytres. Elle obtient <material> en retirant un suffixe d'emplacement reconnu du nom de fichier de la définition d'objet, puis cherche assets/<namespace>/equipment/<material>.json dans l'espace de noms du modèle feuille. Elle utilise la première couche de texture de humanoid, de humanoid_leggings pour les jambières, ou de wings pour les élytres si cette couche existe. Le PNG correspondant doit être présent dans le pack fusionné. L'attachable généré utilise la géométrie d'armure vanilla de Bedrock. Un fichier d'équipement seul, des couches de texture supplémentaires ou un identifiant de ressource d'équipement sans rapport ne garantissent pas la conversion de l'armure.

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 sur serveur autonome

Avec la conversion activée et Geyser-Spigot sur le même backend autonome, RSPM enregistre un abonné à SessionLoadResourcePacksEvent. Il propose le dernier pack Bedrock autorisé depuis le disque à chaque joueur qui se connecte. Les modifications de texture ou de géométrie peuvent être reçues à la connexion suivante sans redémarrage si les mappings enregistrés restent inchangés. En mode réseau, les backends confient la distribution au proxy, même si Geyser-Spigot est aussi installé localement.

Les mappings d'objets personnalisés de Geyser, le JSON dans custom_mappings/, sont figés au démarrage. Ajouter ou supprimer des objets, changer une référence de modèle ou modifier des prédicats peut exiger de nouveaux mappings et donc un redémarrage. RSPM pré-déploie le précédent fichier de mappings autorisé au début du démarrage si le déploiement automatique est activé. Après la première conversion réussie, redémarrez Geyser pour charger les nouveaux mappings, puis reconnectez le client Bedrock.

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.

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

En l'absence de mappings convertibles et de fichiers d'entités autorisés, RSPM retire la publication et tente de supprimer les anciennes sorties locales ainsi que son mapping déployé dans Geyser. Un fichier verrouillé restant sur disque n'est plus autorisé à être distribué. La route /bedrock.zip du backend renvoie 404 pour signaler qu'il ne fournit aucun contenu Bedrock. Les packs contenant uniquement des entités restent publiés. De simples remplacements de textures de blocs Java ou de textures vanilla ne produisent pas de pack converti ; il leur faut un pack Bedrock créé séparément.

La désactivation de bedrockAutoDeployToGeyser supprime le mapping précédemment déployé par RSPM lors de la réconciliation. Modifier bedrockGeyserFolder nettoie aussi l'ancienne destination dont RSPM était responsable. Ces actions ne changent pas les mappings déjà chargés dans Geyser ; redémarrez-le pour appliquer le nouvel ensemble.

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)

Poses des objets tenus en main

Chaque attachable 3D reçoit des animations à la première personne, à la troisième personne et sur la tête. Les poses en main proviennent des transformations display.firstperson_righthand et display.thirdperson_righthand du modèle Java. RSPM applique chaque transformation au squelette de joueur Bedrock vanilla : le modèle tenu se place donc là où Java le dessine, avec la même position, la même orientation et la même échelle sur chaque axe. Un emplacement que le modèle ne définit pas utilise la transformation identité de Java. L'animation de tête provient de display.head.

Il n'y a rien à régler. Pour changer la façon dont un objet se place dans la main, modifiez les transformations display du modèle Java ; Java et Bedrock suivent alors les mêmes valeurs. Le squelette utilise le bras large (Steve) : avec les skins à bras fins, Bedrock peut donc différer de Java d'un demi-pixel.

Les versions antérieures ajoutaient des décalages réglés à la main depuis plugins/ResourcePackManager/bedrock_display_offsets.yml. Ce fichier et ses paramètres firstPerson* et thirdPerson* ne sont plus lus, et RSPM régénère les packs Bedrock en cache après la mise à jour. Une ancienne copie du fichier peut être supprimée.

Particules des objets tenus

Un plugin producteur peut associer des particules à un objet 3D tenu en main avec un fichier annexe placé dans assets/<namespace>/rspm_item_particles/<model path>.json, où <model path> est le chemin du modèle Java tenu (display/wand pour freeminecraftmodels:display/wand). Ce fichier associe des noms d'effets aux identifiants de particules que le plugin fournit dans son ensemble d'entités, liste des locators en pixels du modèle Java et contient une timeline de particules en boucle. RSPM ajoute les locators à la géométrie de l'objet et joue la timeline comme une animation d'attachable supplémentaire : les clients Bedrock dessinent donc les particules au niveau de la main, à la première comme à la troisième personne. FreeMinecraftModels écrit ces fichiers annexes pour les objets dotés d'effets de particules. Un fichier annexe illisible est ignoré avec un avertissement.

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é.
• Un JSON de définition d'objet impossible à analyser interrompt la conversion avec Bedrock conversion failed: .... Un JSON valide sans modèle ou avec un nœud non pris en charge peut au contraire être ignoré avec un message de débogage. Examinez l'erreur et le nombre de mappings produit ; toute définition ignorée n'est pas une erreur d'analyse fatale.
• 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 accepte une annulation coopérative. RSPM prépare le ZIP et les mappings, puis remplace la publication comme un ensemble. En cas d'échec ou d'annulation pendant le remplacement, il tente de restaurer l'ensemble précédent ; un échec de conversion avant ce remplacement retire l'ancienne sortie. Les hachages publiés et les métadonnées de l'ensemble permettent de rejeter des générations périmées ou mélangées. La présence d'un ZIP sur disque ne prouve ni qu'il est autorisé ni qu'un client Bedrock l'a affiché.
• Quand le pack fusionné ne contient ni mappings convertibles ni fichiers d'entités autorisés, RSPM retire l'ancienne publication et tente d'en supprimer les sorties. Un pack contenant uniquement des entités est tout de même produit avec zéro mapping d'objet.

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.