Notes de création de modèles FreeMinecraftModels

Ces notes décrivent les fichiers de modèles, leurs fichiers associés et les noms que FreeMinecraftModels lit à l'importation et à l'exécution.

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

Pour un .bbmodel isolé sans fichiers associés :

1. placez-le directement dans plugins/FreeMinecraftModels/imports, avec l'extension .bbmodel en minuscules
2. exécutez /fmm reload
3. vérifiez que sa conversion .fmmodel apparaît dans le dossier de modèles actif et que le rechargement réussit

L'importateur de fichiers isolés laisse l'original dans imports, donc les importations suivantes le convertissent à nouveau. Il ne récupère pas les fichiers .json ou .yml associés et n'accepte pas de .fmmodel isolé. Pour vos ensembles de modèles, conservez modèles et fichiers associés ensemble dans le dossier models actif, ou utilisez un paquet de contenu correctement structuré. Un sous-dossier quelconque d'imports sans pack.meta est ignoré. Un rechargement rejeté peut laisser l'ancien catalogue actif ; vérifiez la console.

La conversion des fichiers isolés ne conserve que source, id et name pour les textures, en supprimant les métadonnées de dimensions et de durée d'animation. Elle exige aussi un tableau textures. Lorsque ces métadonnées comptent, utilisez le dossier de modèles actif ou un paquet qui préserve le fichier d'origine ; le lecteur de modèles à l'exécution accepte, lui, l'absence du tableau de textures.

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 anciennes installations peuvent posséder un dossier Models avec une majuscule. À l'exécution, FreeMinecraftModels préfère models en minuscules s'il existe et utilise Models sinon. Sur un système de fichiers insensible à la casse, les deux noms désignent le même dossier. Sur un système sensible à la casse, ils peuvent coexister : l'importateur partagé de paquets préfère alors une destination Models existante, tandis que le moteur lit models. Sauvegardez leur contenu et regroupez-le dans models en minuscules pendant que le serveur est arrêté, pour éviter d'importer des fichiers hors de l'arborescence active.

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
• Dans le dossier de modèles actif, la comparaison des extensions ignore la casse : .BBModel et .FMModel sont acceptés. L'importation de fichiers isolés depuis imports ne reconnaît que .bbmodel en minuscules

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. Lorsque tous les fichiers portant cet identifiant sont identiques octet par octet, comme lorsque deux packs de contenu fournissent le même modèle, FMM charge celui dont le chemin absolu arrive en premier dans l'ordre de tri et ignore les copies sans avertissement. Lorsque les fichiers diffèrent :

• 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 sans tableau groups est transmis sans fusion. Un outliner déjà fusionné peut fonctionner ; des nœuds de groupe v5 bruts sans nom peuvent faire échouer le chargement lorsque le lecteur du squelette attend un nom
  • 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 ayant un effet à 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 pour définir les collisions à l'exécution. Un hitbox imbriqué suit l'analyse ordinaire des os, mais reste masqué et ne définit pas la hitbox du modèle
  • doit contenir exactement un cube, qui définit la largeur (x), la profondeur (z) et la hauteur (y). Les cubes supplémentaires journalisent has more than one value defining a hitbox! Only the first cube will be used. Un groupe vide journalise has a hitbox bone but no hitbox cube! et laisse des dimensions nulles ; ce n'est pas équivalent à une hitbox absente. Les décalages et rotations du cube ne deviennent pas un décalage de hitbox : le lecteur utilise les longueurs absolues des côtés et un décalage de modèle nul
  • 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_...
  • ancrage facultatif de plaque de nom créé par l'auteur. Consultez la position des plaques de nom ci-dessous
• h_...
  • traité comme des os de tête
• b_...
  • os sans affichage dans le moteur Java. Utilisez des os sans cubes pour la structure : l'export de géométrie Bedrock ne filtre pas le préfixe b_, donc leurs cubes peuvent y rester visibles
• m_...
  • os de point de montage. Chaque os avec ce préfixe crée un siège pour un joueur, géré par MountPointManager. Plusieurs os m_ créent plusieurs sièges. Le gestionnaire choisit le premier siège libre et utilise une entité Interaction temporaire pendant son occupation ; sa méthode publique de montage accepte des joueurs, pas des entités quelconques.

Les préfixes sont sensibles à la casse ; le nom hitbox est comparé sans tenir compte de la casse. Ces noms influencent la conversion et le comportement à l'exécution.

Position des plaques de nom

Un os tag_ est désormais facultatif. FMM choisit comme ancrage le premier os tag_ par ordre alphabétique. S'il n'y en a aucun, la plaque de nom est placée au-dessus de la hitbox mise à l'échelle : un modèle sans cet os peut donc afficher son nom.

Utilisez un os tag_name sans cube si cette position de repli ne convient pas. Plusieurs os de nom ne produisent plus plusieurs copies de la même plaque.

L'API prend en charge les noms sur plusieurs lignes, l'échelle, l'espacement des lignes et la visibilité. Les lignes sont ordonnées du haut vers le bas, la dernière se trouvant à l'ancrage. Consultez le guide de l'API.

Ombrage des cubes et émission de lumière

• La valeur light_emission d'un cube définie dans Blockbench est conservée lorsqu'il s'agit d'un nombre entier de 0 à 15. Toute autre valeur est ignorée avec un avertissement console se terminant par with invalid light_emission. Expected an integer from 0 to 15; ignoring this value.
• Un cube dont l'ombrage est désactivé (shade: false) reçoit aussi shade_direction_override: "up" dans la géométrie générée, afin que les clients Minecraft 26.3 l'affichent sans ombrage comme les clients plus anciens. FMM applique la même règle aux cubes d'un modèle d'affichage .json voisin. Une valeur que vous avez définie vous-même est conservée

Cubes sans groupe

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. Les locators peuvent aussi servir d'ancrage aux effets de particules Blockbench ; voir Particules

Un objet nul ne devient un contrôleur IK que si son entrée .bbmodel porte à la fois ik_source (os source) et ik_target (os ou locator cible). L'importateur recherche dans la hiérarchie, y compris entre éléments frères et vers les descendants. Des éléments frères à la racine produisent une chaîne limitée à la source. lock_ik_target_rotation est lu et conservé, mais le solveur actuel ne l'applique pas.

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 images clés de position pilotent l'IK. Leur décalage s'ajoute à la position de repos de l'os ou du locator cible, et non à celle du contrôleur conservée en mémoire. Les pistes de rotation et d'échelle ne pilotent pas l'IK

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

Organisation de la sortie en 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.

JSON de modèle d'affichage (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.

FMM lit le JSON voisin du modèle actif, le copie dans le resource pack et réécrit les valeurs sans espace de noms de sa table textures. Les clés numériques correspondent aux indices des textures extraites ; une clé sans correspondance utilise une texture disponible, s'il y en a une. Les valeurs avec espace de noms restent inchangées. Sans JSON voisin, l'objet utilise l'apparence de son matériau de base : généralement du papier pour placer un prop, ou le matériau configuré pour un objet tenu. Un fichier associé mal formé journalise Failed to process display model JSON for ... et ce modèle d'affichage n'est pas enregistré.

Configuration d'un objet personnalisé en YML

Définissez material dans le YAML voisin du modèle pour enregistrer un objet tenu :

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

Utilisez des identifiants d'enchantements en minuscules avec espace de noms. Les matériaux en cuir acceptent un suffixe de teinture RVB tel que LEATHER_CHESTPLATE:ff8800 ; voir Configuration. Un objet dont le matériau n'est pas pris en charge, qui contient un enchantement sans espace de noms ou une liste scripts: non vide est indisponible. La console explique pourquoi et le fichier d'origine est conservé. scripts: reste réservé aux props.

D'autres définitions invalides, comme un isEnabled non booléen, des entrées d'enchantement mal formées, des enchantements en double ou un nom de fichier d'objet invalide, peuvent faire rejeter le catalogue candidat et le rechargement. Utilisez des noms de fichiers d'objets en minuscules, composés uniquement de a-z, 0-9, ., _ et -, sur 128 caractères au maximum. La recherche d'objets personnalisés lit .yml, pas .yaml. Obtenez un objet enregistré avec /fmm giveitem <item> ou le navigateur d'administration ; les recettes de props et les achats en boutique produisent des objets en papier pour le placement.

Les effets des objets appartiennent désormais aux définitions d'enchantements. Les baguettes et les bâtons utilisent la configuration des armes magiques. Aucun de ces systèmes n'utilise l'ancien moteur Lua d'objets équipés.

Notes sur Bedrock et le 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 à bon escient (hitbox, tag_, h_, b_, m_). Ajoutez un ancrage tag_ seulement si la position de repli au-dessus de la hitbox ne convient pas
• utilisez spawn, idle, walk, attack et death en minuscules pour les états partagés ; attaque et mort nécessitent toujours leur déclencheur à l'exécution, et les autres noms exigent une lecture explicite (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 détecte automatiquement les états d'affichage des arcs et arbalètes pendant la génération du resource pack. Chaque état requis nécessite un modèle chargé et un .json d'affichage voisin traité avec succès ; les noms de fichiers seuls ne suffisent pas. Configurez l'objet tenu sous son nom de base avec le matériau BOW ou CROSSBOW approprié.

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 d'organisation des fichiers

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

Pour une arbalète, ajoutez aussi cool_bow_charged.bbmodel et cool_bow_charged.json. La configuration de l'objet est cool_bow.yml, avec le nom de base sans _idle.

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).
• Un ensemble complet d'états d'affichage reçoit une définition d'objet publique sous le nom de base, comme cool_bow.json. Les définitions individuelles de _idle, d'armement et de charge sont supprimées ; leur géométrie reste référencée dans la définition de base
• Le registre d'affichage expose l'ID de base et retire les ID des états. Un ensemble complet avec _charged est traité comme une arbalète ; sans cet état, comme un arc. Des états d'affichage manquants empêchent le regroupement
• Utilisez le nom de base pour la configuration YML, comme cool_bow.yml. Le catalogue d'objets ignore les fichiers YML portant un suffixe d'état ; la recherche de configuration des props retire également le suffixe

JSON de modèle d'affichage

Chaque état requis doit avoir son propre .json d'affichage voisin, comme cool_bow_idle.json et cool_bow_draw_full.json. FMM les relie par la définition d'objet de base générée. Consultez la sortie du resource pack pour ses conditions et son chemin de sortie.

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.