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

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

Compatibilité Blockbench

• FreeMinecraftModels détecte la version du fichier Blockbench lors de l'importation
• L'importateur actuel contient encore des branches de compatibilité pour les versions antérieures à Blockbench v5
• 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
• tag_...
  • traité comme des os virtuels liés aux étiquettes de nom
• 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_... ou mount_...
  • 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 de montage 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.

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
• l'analyse des locators

Contrainte pratique importante :

• La recherche de contrôleurs IK 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

Séparation de la sortie 1.21.4+

Pour Minecraft 1.21.4+, FreeMinecraftModels génère des fichiers de définition de modèles d'objets sous :

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

Les versions plus anciennes utilisent toujours le chemin hérité de modèles d'objets. Si vous vérifiez la sortie générée pendant la création, assurez-vous de regarder la bonne structure de sortie pour votre version de serveur.

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      # optionnel — si défini, le modèle est aussi un objet personnalisé
name: '&b&lMy Custom Sword'  # optionnel — nom d'affichage
lore:                         # optionnel
  - '&7A custom weapon'
enchantments:                 # optionnel — 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 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_, mount_)
• 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                  <-- la config utilise le nom de base, pas _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.