Notes de création de modèles FreeMinecraftModels

Cette page documente les détails de création actuels visibles dans le code source de FreeMinecraftModels. Elle est intentionnellement conservatrice : elle se concentre sur le contrat d'importation/exécution, pas sur chaque préférence de flux de travail Blockbench.

Formats sources

FreeMinecraftModels accepte actuellement :

• les fichiers .bbmodel pour les importations de sources éditables
• les fichiers .fmmodel pour les données de modèle prêtes à l'exécution et allégées

Le flux d'importation normal est :

1. placer le modèle dans plugins/FreeMinecraftModels/imports
2. exécuter /fmm reload
3. laisser FreeMinecraftModels importer le modèle dans l'ensemble de modèles actifs et reconstruire le resource pack généré

Rôles des dossiers

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports est le dossier de réception pour les importations manuelles de modèles et les téléchargements de packs officiels avant traitement
• models contient le contenu des modèles installés et actifs
• models_disabled contient le contenu des packs téléchargés ou installés qui sont actuellement désactivés

Les installations plus anciennes peuvent avoir un dossier Models en majuscule à la place. FreeMinecraftModels résout cela en préférant le dossier canonique models en minuscules lorsqu'il existe, et en ne retombant sur l'ancien Models que dans le cas contraire. Sur Windows et macOS, les deux noms désignent de toute façon le même répertoire ; sur un système de fichiers Linux sensible à la casse, une ancienne installation continue de fonctionner, mais si les deux répertoires existent malgré tout, seul models en minuscules est lu. Regroupez tout dans models si vous trouvez les deux.

Identifiants de modèles

• Les identifiants de modèles à l'exécution proviennent du nom de fichier, sans l'extension .bbmodel ou .fmmodel
• Utilisez des noms de fichiers stables et uniques car l'identifiant est ce que les commandes et les appels API résolvent
• Les références d'animation Blockbench sont basées sur les noms, donc un nommage dupliqué ou peu clair à l'intérieur du modèle est plus susceptible de causer des problèmes qu'un schéma de nommage propre et explicite
• La correspondance d'extension est insensible à la casse : .BBModel et .FMModel sont donc acceptés

Normalisation des identifiants et collisions

Le nom de fichier est normalisé avant de devenir l'identifiant de modèle à l'exécution et le nom de fichier dans le resource pack :

1. mis en minuscules
2. chaque caractère hors de a-z, 0-9, ., _ et - est remplacé par _

Ainsi, My Table.bbmodel, my table.bbmodel et my_table.bbmodel se normalisent tous en un même identifiant, my_table.

Avant toute conversion, FreeMinecraftModels balaie l'ensemble de l'arborescence des modèles et recherche les fichiers qui se normalisent vers le même identifiant. Lorsqu'il trouve une collision :

• tous les fichiers en collision sont rejetés — aucun n'est chargé, il n'y a donc pas de « le dernier l'emporte » silencieux
• l'identifiant de modèle est bloqué pour le reste de cette passe de chargement
• les modèles rejetés sont également exclus de l'export du bundle d'entités personnalisées Bedrock
• la console reçoit :

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

La correction consiste toujours à renommer les fichiers pour que les identifiants normalisés soient distincts. La meilleure habitude est de nommer les fichiers de modèles en minuscules avec des underscores dès le départ (stone_table.bbmodel), ce qui rend le nom de fichier et l'identifiant d'exécution identiques et supprime tout risque de collision surprise.

Compatibilité Blockbench

• FreeMinecraftModels lit meta.format_version dans le .bbmodel et se branche sur son numéro majeur
• Un bloc meta absent, un format_version absent, ou une valeur qu'il ne peut pas analyser retombent tous sur la version 4, avec une ligne d'information ou d'avertissement nommant le modèle
• Un tableau textures absent est accepté et traité comme une liste de textures vide au lieu de faire planter l'importateur. L'exportateur d'entités personnalisées Bedrock ignore ensuite ce modèle, car l'export Bedrock exige au moins une texture
• Les noms de fichiers de textures extraites sont normalisés vers une seule extension .png. Un nom source tel que body.jpg, body.PNG ou body est écrit et référencé sous la forme body.png
• format_version 4.x et antérieur : les os sont lus directement dans l'arbre outliner, qui porte les noms d'os en ligne
• format_version 5.x et ultérieur : le schéma de l'outliner a changé. outliner est désormais un arbre imbriqué de simples chaînes UUID et de dictionnaires {uuid, isOpen, children} sans clé de nom, tandis qu'un tableau plat groups distinct contient les véritables données d'os (dont name). FMM joint les deux par UUID — chaque nœud de l'outliner est remplacé par son entrée groups correspondante, puis les enfants sont fusionnés récursivement — de sorte que les noms d'os, origines et rotations se résolvent normalement
• Conséquences à connaître lorsque vous éditez ou générez des fichiers .bbmodel à la main :
  • Un fichier v5 dont le tableau groups est absent est transmis sans fusion, ses os perdent donc leurs noms et les préfixes réservés (tag_, h_, b_, m_, hitbox) cessent d'être reconnus
  • Les UUID doivent correspondre exactement entre outliner et groups ; un nœud d'outliner sans groupe correspondant est conservé tel quel plutôt que supprimé
  • Ne mélangez pas un format_version v5 avec un outliner de forme v4, ni l'inverse — la branche est choisie d'après la version déclarée, pas d'après la forme réelle
• Si les journaux d'importation indiquent que le format du modèle n'est pas compatible avec FreeMinecraftModels, traitez cela comme un problème de format de modèle d'abord, pas comme un problème de wiki ou de commande

Conventions de nommage des os significatifs à l'exécution

Le convertisseur actuel et le pipeline de squelette reconnaissent quelques conventions de nommage :

• hitbox
  • réservé à la génération de hitbox
  • doit définir proprement la hitbox du modèle au lieu d'être utilisé comme un os visuel
  • doit être un os de premier niveau dans l'outliner. L'importateur ne le cherche qu'à la racine ; un groupe hitbox imbriqué dans un autre os est traité comme un os ordinaire
  • doit contenir exactement un cube, qui définit la largeur (x), la profondeur (z) et la hauteur (y) à l'exécution. Des cubes supplémentaires journalisent has more than one value defining a hitbox! Only the first cube will be used ; un os hitbox vide journalise has a hitbox bone but no hitbox cube! et aucune hitbox n'est générée
  • jamais animé (les pistes d'animation ciblant hitbox sont ignorées), jamais rendu, et exclu de l'export de géométrie Bedrock. Sur Bedrock, un modèle sans os hitbox retombe sur 1.0 x 2.0
• tag_...
  • le seul moyen pour un modèle d'obtenir une plaque de nom. Voir Les plaques de nom nécessitent un os tag_ ci-dessous
• h_...
  • traité comme des os de tête
• b_...
  • os sans affichage (masqués à l'exécution). Utilisez-les pour les os structurels ou organisationnels qui ne doivent pas s'afficher en jeu.
• m_...
  • os de point de montage. Chaque os avec ce préfixe crée une position de siège montable sur le modèle. Les joueurs ou entités peuvent être montés sur ces positions à l'exécution. Plusieurs os m_ créent plusieurs sièges. Géré en interne par MountPointManager.

Ce ne sont pas de simples conventions de style ; elles affectent la conversion et le comportement à l'exécution.

Les plaques de nom nécessitent un os tag_

C'est de loin la cause la plus fréquente de contenu livré avec des mobs sans nom, cela mérite donc d'être dit sans détour :

Un modèle n'obtient une plaque de nom que s'il contient un os dont le nom commence par tag_. Il n'y a aucun repli.

Comment cela fonctionne :

• Lors de l'importation, tout os nommé tag_... reçoit un os « méta » auto-généré en parallèle (fmm_nametag_bone_<name>) marqué comme os de plaque de nom. Rien d'autre dans le pipeline ne pose ce marqueur
• À l'exécution, le squelette collecte ces os marqués, et un affichage de texte apparaît à l'origine de l'os tag_. Sa position et son texte suivent cet os
• ModeledEntity.setDisplayName(...) et setDisplayNameVisible(...) parcourent cette collection. Sans os tag_, la collection est vide et les deux appels ne font silencieusement rien — aucune erreur, aucun avertissement, aucun nom

Pourquoi la plaque de nom vanilla ne compense pas :

• Un modèle dynamique masque son entité vivante sous-jacente aux clients (setVisibleByDefault(false), plus le drapeau d'invisibilité), la plaque de nom propre au mob vanilla n'est donc pas rendue non plus
• Le résultat net est un mob totalement anonyme, alors même que le plugin appelant a défini un nom d'affichage avec succès

Règles pratiques :

• Si un modèle représente une entité nommée (un boss EliteMobs, un PNJ de quête, tout ce sur quoi un plugin appelle setDisplayName), ajoutez un os tag_
• Placez-le là où la plaque de nom doit flotter — généralement juste au-dessus de la tête
• L'os n'a pas besoin de cubes ; c'est un ancrage de position. tag_name en particulier est ignoré lors de la génération des définitions d'item model, il n'est donc jamais rendu sous forme de géométrie
• Plusieurs os tag_ sont autorisés ; chacun d'eux obtient son propre affichage de texte montrant le même nom
• Si vous voyez nametag bone did not spawn name tag dans la console, l'os a été reconnu mais son affichage de texte n'a pas pu apparaître — c'est un problème différent de l'absence totale d'os tag_

Cubes flottants libres

Les cubes déclarés en haut de l'outliner sans groupe conteneur arrivent sous forme de simples chaînes UUID plutôt que d'entrées d'os. FreeMinecraftModels les rattache à l'os racine auto-généré (freeminecraftmodels_autogenerated_root) afin qu'ils s'affichent quand même. Ils ne sont pas adressables par les animations : placez donc tout ce que vous comptez animer à l'intérieur d'un vrai groupe.

IK, objets nuls et locators

Le code actuel confirme le support de :

• les objets nuls de Blockbench en tant que contrôleurs IK
• les plans de chaînes IK et la résolution IK à l'exécution (FABRIK)
• l'analyse des locators

Un objet nul ne devient un contrôleur IK que si son entrée .bbmodel porte à la fois ik_source (l'os où commence la chaîne) et ik_target (l'os ou le locator que la chaîne cherche à atteindre). lock_ik_target_rotation est également lu. La chaîne est découverte en remontant la hiérarchie des os depuis la cible jusqu'à la source, les deux doivent donc réellement être reliés.

Contraintes pratiques importantes :

• Le lien source/cible se fait par UUID, il survit donc aux renommages — mais si l'un des UUID est absent du modèle, la console journalise IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ... et cette chaîne est ignorée
• Si le parcours ne trouve aucun chemin de la source vers la cible, vous obtenez Could not find path from source to target et la chaîne est ignorée
• La recherche d'animation pour un contrôleur est basée sur les noms, donc le nommage des contrôleurs doit rester stable entre la structure du modèle et les données d'animation
• Seules les keyframes de position d'un objet nul comptent — elles deviennent le décalage d'objectif de l'IK. Les pistes de rotation et d'échelle d'un objet nul sont ignorées

Voir Animations pour savoir comment l'IK est pilotée image par image.

Séparation de la sortie 1.21.4+

FreeMinecraftModels déclare api-version: 1.21.4, donc 1.21.4 est la version minimale du serveur et la disposition moderne des définitions de modèles d'objets est celle que vous obtiendrez toujours :

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

Les branches héritées (antérieures à 1.21.4) basées sur les overrides d'armure de cheval en cuir existent toujours dans le code, mais aucun serveur capable de charger le plugin actuel ne les atteint. Si vous lisez d'anciennes notes ou consultez un ancien dossier de sortie, c'est la différence que vous constatez.

Display Model JSON (1.21.4+)

Les administrateurs peuvent placer un fichier .json adjacent à un fichier .bbmodel ou .fmmodel avec le même nom de base (par exemple, table.bbmodel + table.json). Ce JSON doit être exporté depuis Blockbench en tant que modèle "Java Block/Item" et définit l'apparence de l'objet lorsqu'il est tenu en main ou affiché dans l'inventaire.

Lors de l'importation, FMM copie le JSON dans la sortie du resource pack et réécrit automatiquement toutes les références de texture simples qu'il contient pour pointer vers les textures extraites du modèle. Si aucun JSON adjacent n'existe, l'objet s'affiche comme du papier simple en jeu.

Configuration d'objet personnalisé en YML

Le fichier de configuration .yml adjacent (même nom de base que le modèle) prend désormais en charge des champs d'objet optionnels. Si material: est défini, le modèle est également disponible comme objet personnalisé pouvant être tenu. Le format YML complet est :

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

Lorsque material: est présent, le modèle apparaît dans le navigateur de contenu administrateur aux côtés des props et peut être donné aux joueurs comme objet fonctionnel.

Notes sur Bedrock et le chemin de rendu

• Le support de Bedrock dépend de sendCustomModelsToBedrockClientsV2 (valeur par défaut true ; remplace l'ancienne clé sendCustomModelsToBedrockClients) et du chemin Floodgate/Geyser/resource pack environnant
• Les clients Java sur les versions supportées peuvent utiliser le rendu par display entities lorsque useDisplayEntitiesWhenPossible est activé
• Ne supposez pas qu'un modèle qui apparaît correctement sur un client Java est automatiquement sûr pour votre chemin Bedrock

Conseils pratiques de création

• gardez les noms de fichiers stables car ils deviennent des identifiants d'exécution
• gardez le nommage des contrôleurs et des animations explicite car la recherche d'animations Blockbench est pilotée par les noms
• utilisez les noms d'os virtuels réservés intentionnellement (hitbox, tag_, h_, b_, m_) — et rappelez-vous que tout modèle censé afficher un nom a besoin d'un os tag_, faute de quoi il restera silencieusement anonyme
• nommez les animations d'état spawn, idle, walk, attack et death si vous voulez qu'elles se déclenchent automatiquement ; tout le reste est une animation personnalisée que vous déclenchez vous-même (voir Animations)
• un modèle destiné à /fmm disguise devrait au minimum fournir aussi idle, et peut ajouter sneak et jump, que seul le contrôleur de déguisement reconnaît (voir Déguisements des joueurs)
• validez la sortie importée après /fmm reload, pas seulement dans Blockbench
• vérifiez le contenu du pack généré pour votre ligne Minecraft cible, surtout sur 1.21.4+

Modèles d'état d'arc et d'arbalète

FMM prend en charge les états d'animation de tir automatiques pour les objets personnalisés arc et arbalète. Aucune configuration n'est nécessaire -- nommez simplement vos fichiers de modèle avec les suffixes corrects et FMM détecte automatiquement l'ensemble d'états lors de la génération du resource pack.

Convention de nommage

Suffixe	Objectif	Arc	Arbalète
_idle	Objet en main, pas en train de tirer ou chargé	requis	requis
_draw_start	Vient de commencer à tirer	requis	requis
_draw_half	À moitié tiré	requis	requis
_draw_full	Complètement tiré	requis	requis
_charged	Arbalète chargée (flèche ou fusée)	--	requis

Un arc nécessite quatre modèles (tous sauf _charged). Une arbalète nécessite les cinq.

Exemple de disposition de fichiers

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

Pour une arbalète, vous ajouteriez un cinquième fichier, cool_bow_charged.bbmodel.

Fonctionnement de la détection

• La détection se fait automatiquement lorsque le resource pack est généré (au démarrage ou lors de /fmm reload).
• Seul le modèle _idle obtient un JSON de définition d'objet dans le pack de sortie. Les états de tir et de charge sont référencés comme entrées conditionnelles dans cette définition.
• Seul le nom de base obtient un fichier de configuration YML. Pour l'exemple ci-dessus, la configuration est cool_bow.yml, pas cool_bow_idle.yml.

Display Model JSON

Chaque modèle d'état peut avoir son propre fichier .json de display model adjacent (ex : cool_bow_idle.json, cool_bow_draw_full.json). FMM les intègre automatiquement dans la définition d'objet générée. Voir Sortie du resource pack pour la structure JSON exacte qui est générée.

Hors du périmètre

Cette page n'essaie pas de garantir :

• les étapes exactes de l'interface Blockbench
• les préférences de flux de travail artistique
• chaque particularité héritée des fichiers .bbmodel décrites dans l'ancien matériel README local

Ces détails changent plus rapidement que le contrat d'exécution vérifié ci-dessus.

Les noms de texture sont normalisés en minuscules et doivent finir par .png : body.PNG et body.jpg se résolvent par exemple en textures/body.png. Évitez les noms qui ne diffèrent que par la casse.