Cosmetic

Installation rapide en 3 etapes

1. Concevez le modele dans Blockbench

Utilisez le preset Blockbench « Item / Modded Block » (ou « Modded Entity » si vous voulez du multi-bones). La taille standard recommandee pour un casque : un cube centre sur (8, 28, 8) en pixels Blockbench. Sauvegardez le modele JSON dans :

assets/votremod/models/item/barry_mask.json

Et les textures associees dans :

assets/votremod/textures/blocks/barry_mask/<nomTexture>.png

2. Creez l'item avec le builder

import fr.eri.eriapi.cosmetic.EriCosmetics;
import net.minecraft.inventory.EntityEquipmentSlot;

Item barryMask = EriCosmetics.armor()
    .modId("eriniumfaction").registryName("barry_mask")
    .slot(EntityEquipmentSlot.HEAD)
    .displayName("Masque de Barry")
    .creativeTab(MyCreativeTab.INSTANCE)
    .model("eriniumfaction:item/barry_mask")
    .build();

3. Enregistrez l'item dans le registry Forge

Le builder ne s'enregistre pas automatiquement dans le registry Forge (meme convention que EriItem). C'est a vous de le faire dans votre handler de registry :

@SubscribeEvent
public static void registerItems(RegistryEvent.Register<Item> event) {
    event.getRegistry().register(barryMask);
}

Cote client, ne faites rien de plus — le layer renderer est attache automatiquement par EriAPI sur le RenderPlayer de chaque variante de skin (default + slim) pendant init.

@SideOnly(Side.CLIENT)
public class ClientProxy extends CommonProxy {
    @Override
    public void preInit(FMLPreInitializationEvent e) {
        super.preInit(e);
        EriCosmetics.preInit();
    }
}

API du builder

Entry point : EriCosmetics.armor() retourne un ArmorCosmeticBuilder.

Methodes fluent

Validation a build()

build() leve IllegalStateException si :

• modId est null ou vide
• registryName est null ou vide
• slot est null ou pas un des 4 slots autorises
• model est null ou vide

Mapping des bones par slot

Chaque slot d'armure pointe vers un bone principal. Si votre modele Blockbench n'a qu'un seul groupe (ou plusieurs groupes sans nom particulier), tout est rendu a ce bone.

Modeles multi-bones

Pour un cosmetic qui couvre plusieurs parties du corps (par exemple un plastron + des manches), nommez vos groupes Blockbench avec les conventions suivantes (insensible a la casse, les espaces et tirets bas sont accepted) :

Chaque groupe racine dont le nom matche est rendu a son bone. Les groupes au nom non-matche tombent dans le bone principal du slot.

Exemple : un plastron avec manches qui suivent les bras

"groups": [
  { "name": "body",      "children": [...] },
  { "name": "right_arm", "children": [...] },
  { "name": "left_arm",  "children": [...] }
]

Resultat : le body est rendu sur le torse, les right_arm / left_arm suivent les bras du joueur (et donc l'animation d'arm-swing pendant la marche, le mouvement lors d'une attaque, etc.).

Desactiver le dispatch multi-bones

Si vous voulez que TOUT votre modele reste sur le bone principal (par exemple un casque conique avec un groupe interne nomme « body » pour le maillage de support), utilisez .followBones(false) :

EriCosmetics.armor()
    .modId("mymod").registryName("conical_hat")
    .slot(EntityEquipmentSlot.HEAD)
    .model("mymod:item/conical_hat")
    .followBones(false)        // tout va sur bipedHead
    .build();

Offset par defaut & reperage Blockbench

Quand le module dessine votre modele, il appelle d'abord bone.postRender(0.0625f) sur le bone cible (place la matrice OpenGL au pivot du bone, avec sa rotation appliquee — meme pipeline que l'armure vanilla), puis applique un offset par defaut qui ramene l'origine Blockbench (0, 0, 0) a l'emplacement attendu dans le repere du bone.

Verifier visuellement

Concevez votre modele dans Blockbench en partant des reperes suivants :

• Casque : centre la tete sur (8, 28, 8) en pixels — le centre du cube tomb pile sur la tete vanilla.
• Torse : meme reperage que le casque (centre sur (8, 18, 8)) car le bone du body partage le meme pivot Y que la tete.
• Jambes : modelez chaque jambe centree sur (8, 6, 8), hauteur 12px (de y=0 a y=12).

Le .offset() du builder s'ajoute AU dessus de l'offset par defaut — utilisez-le pour ajuster finement (par exemple si votre casque doit etre legerement en avant : .offset(0, 0, -0.05f)).

Exemple de calcul

Pour un masque dont le devant est dessine en Blockbench from [4,23,3.9] to [12,32,3.9] — centre (8, 27.5, 3.9) :

• Conversion en blocs : (0.5, 1.71875, 0.24375)
• Apres l'offset (-0.5, -1.5, -0.5) : (0, 0.21875, -0.25625) dans le repere du bone bipedHead
• La tete vanilla s'etend de y=-0.5 (cou) a y=0 (sommet) en bone local. y=0.21875 est legerement au-dessus du sommet — corrigeable avec .offset(0, -0.22f, 0) si besoin.
• La face avant de la tete vanilla est a z=-0.25. Le masque tombe a z=-0.256 — pile devant la tete.

BlockbenchRenderer (helper public)

Le module Cosmetic utilise en interne BlockbenchRenderer, un helper qui rend un AnimatedBlockModel deja parse avec ou sans AnimationPose. Ce helper a ete extrait de AnimatedBlockTESR et est public — vous pouvez l'utiliser pour vos propres systemes de rendu custom (TileEntity, items en main, GUI 3D, etc.).

API

// Rendu complet du modele en pose statique, textures auto-bind
BlockbenchRenderer.renderModel(AnimatedBlockModel model);

// Rendu avec une AnimationPose interpolee
BlockbenchRenderer.renderModel(AnimatedBlockModel model, AnimationPose pose);

// Controle total (bind manuel des textures par le caller)
BlockbenchRenderer.renderModel(AnimatedBlockModel model, AnimationPose pose, boolean bindTextures);

// Rendre un seul groupe a la position actuelle
BlockbenchRenderer.renderGroup(ModelGroup group);
BlockbenchRenderer.renderGroup(ModelGroup group, AnimationPose pose);
BlockbenchRenderer.renderGroup(ModelGroup group, AnimationPose pose,
                               Map<String, ResourceLocation> textures, boolean bindTextures);

// Variante avec texture overrides (utilisee par AnimatedBlockTESR)
BlockbenchRenderer.renderModelWithOverrides(AnimatedBlockModel model, AnimationPose pose,
                                            Map<String, String> textureOverrides);

Troubleshooting

Le modele n'apparait pas du tout

• Verifiez que vous avez bien enregistre l'item dans le registry Forge (le builder ne le fait pas).
• Verifiez le chemin du modele : .model("mod:item/nom") doit pointer sur assets/mod/models/item/nom.json.
• Regardez les logs au demarrage : EriAPI - ArmorCosmeticManager: attached cosmetic layer to N player renderers doit apparaitre. Si N=0, votre ClientProxy tourne avant que le render manager soit pret — ouvrez une issue.

Le casque vanilla est encore visible

La texture transparente est embarquee dans EriAPI sous assets/eriapi/textures/models/armor/transparent_layer_1.png. Si vous voyez un casque blanc / rose (texture manquante), verifiez que le jar EriAPI est bien dans votre dossier mods/ (en dev : ajoutez-le en compile files() dans le build.gradle).

Le modele est decalle / dans la mauvaise position

• Verifiez que votre modele Blockbench est concu dans le bon repere — voir Offsets par defaut.
• Ajustez avec .offset(x, y, z) (en blocs GL = pixels Blockbench / 16).
• Pour un modele importe depuis un autre logiciel, essayez .rotation(0, 180, 0) — certains exporters inversent le sens du Z.

Les manches ne suivent pas les bras

Verifiez que vos groupes Blockbench s'appellent bien right_arm / left_arm (insensible a la casse, le tiret bas est tolere). Le mapping cherche le nom exact — un groupe nomme « ArmRight » ne sera pas reconnu.

Le modele clignote / disparait selon l'angle

Cause classique : votre modele a des faces transparentes mal triees pour le blend OpenGL. Le module active disableCull() et enableBlend() par defaut, mais l'ordre de dessin reste celui des elements du JSON Blockbench. Pour un effet propre, evitez de superposer plusieurs faces transparentes — preferez un seul cube avec une texture alpha.

Performance

Le layer est appele chaque frame pour chaque joueur visible. Le cout est minimal car :

• Le lookup Item -> ArmorCosmeticDefinition est un HashMap.get() O(1).
• Le modele Blockbench est cache en memoire (premier load uniquement).
• Aucune allocation par frame — les boucles utilisent des for(int i) sur les listes existantes.
• Si le joueur est invisible (isInvisible()), le layer est court-circuite.