Cosmetic

Quick start in 3 steps

1. Design the model in Blockbench

Use the Blockbench « Item / Modded Block » preset (or « Modded Entity » if you want multi-bone). Recommended standard size for a helmet: a cube centered on (8, 28, 8) in Blockbench pixels. Save the JSON model to:

assets/yourmod/models/item/barry_mask.json

And the associated textures in:

assets/yourmod/textures/blocks/barry_mask/<textureName>.png

2. Create the item with the 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("Barry Mask")
    .creativeTab(MyCreativeTab.INSTANCE)
    .model("eriniumfaction:item/barry_mask")
    .build();

3. Register the item with the Forge registry

The builder does NOT auto-register with the Forge registry (same convention as EriItem). You must do it in your registry handler:

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

On the client side, do nothing more — the layer renderer is attached automatically by EriAPI on each skin variant's RenderPlayer (default + slim) during init.

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

Builder API

Entry point: EriCosmetics.armor() returns an ArmorCosmeticBuilder.

Fluent methods

Validation at build()

build() throws IllegalStateException if:

• modId is null or empty
• registryName is null or empty
• slot is null or not one of the 4 allowed slots
• model is null or empty

Bone mapping per slot

Each armor slot points to a primary bone. If your Blockbench model has only one group (or several groups without specific names), everything is rendered to that bone.

Multi-bone models

For a cosmetic that covers multiple body parts (e.g. chestplate + sleeves), name your Blockbench groups with the following conventions (case-insensitive, spaces and underscores accepted):

Each root group whose name matches is rendered at its bone. Groups with non-matching names fall back to the slot's primary bone.

Example: a chestplate with sleeves that follow the arms

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

Result: body is rendered on the torso, right_arm / left_arm follow the player's arms (and so the arm-swing animation during walk, attack motion, etc.).

Disabling multi-bone dispatch

If you want EVERYTHING on the primary bone (e.g. a conical hat with an inner group named « body » for the support mesh), use .followBones(false):

EriCosmetics.armor()
    .modId("mymod").registryName("conical_hat")
    .slot(EntityEquipmentSlot.HEAD)
    .model("mymod:item/conical_hat")
    .followBones(false)        // everything goes to bipedHead
    .build();

Default offsets & Blockbench coordinates

When the module draws your model, it first calls bone.postRender(0.0625f) on the target bone (places the OpenGL matrix at the bone pivot with its rotation applied — same pipeline as vanilla armor), then applies a default offset that brings the Blockbench origin (0, 0, 0) to the expected location in the bone's coordinate frame.

Visual checkpoints

Design your model in Blockbench starting from these reference points:

• Helmet: center the head on (8, 28, 8) in pixels — the cube center lands right on the vanilla head.
• Chestplate: same reference as the helmet (centered on (8, 18, 8)) since the body bone shares the same Y pivot as the head.
• Legs: model each leg centered on (8, 6, 8), height 12px (from y=0 to y=12).

The builder's .offset() adds on top of the default offset — use it for fine adjustments (e.g. if your helmet should be slightly forward: .offset(0, 0, -0.05f)).

Calculation example

For a mask whose front face is drawn in Blockbench from [4,23,3.9] to [12,32,3.9] — center (8, 27.5, 3.9):

• Conversion to blocks: (0.5, 1.71875, 0.24375)
• After the offset (-0.5, -1.5, -0.5): (0, 0.21875, -0.25625) in the bipedHead bone frame
• The vanilla head extends from y=-0.5 (neck) to y=0 (top) in bone local. y=0.21875 is slightly above the top — correctable with .offset(0, -0.22f, 0) if needed.
• The vanilla head's front face is at z=-0.25. The mask lands at z=-0.256 — right in front of the head.

BlockbenchRenderer (public helper)

Internally, the Cosmetic module uses BlockbenchRenderer, a helper that renders an already-parsed AnimatedBlockModel with or without an AnimationPose. This helper was extracted from AnimatedBlockTESR and is public — you can use it for your own custom render systems (TileEntity, in-hand items, 3D GUI, etc.).

API

// Full model render in static pose, auto-bind textures
BlockbenchRenderer.renderModel(AnimatedBlockModel model);

// Render with an interpolated AnimationPose
BlockbenchRenderer.renderModel(AnimatedBlockModel model, AnimationPose pose);

// Full control (caller binds textures manually)
BlockbenchRenderer.renderModel(AnimatedBlockModel model, AnimationPose pose, boolean bindTextures);

// Render a single group at the current position
BlockbenchRenderer.renderGroup(ModelGroup group);
BlockbenchRenderer.renderGroup(ModelGroup group, AnimationPose pose);
BlockbenchRenderer.renderGroup(ModelGroup group, AnimationPose pose,
                               Map<String, ResourceLocation> textures, boolean bindTextures);

// Variant with texture overrides (used by AnimatedBlockTESR)
BlockbenchRenderer.renderModelWithOverrides(AnimatedBlockModel model, AnimationPose pose,
                                            Map<String, String> textureOverrides);

Troubleshooting

The model doesn't appear at all

• Verify you registered the item with the Forge registry (the builder does not do it).
• Check the model path: .model("mod:item/name") must point to assets/mod/models/item/name.json.
• Look at the logs on startup: EriAPI - ArmorCosmeticManager: attached cosmetic layer to N player renderers must appear. If N=0, your ClientProxy runs before the render manager is ready — open an issue.

The vanilla helmet is still visible

The transparent texture is embedded in EriAPI under assets/eriapi/textures/models/armor/transparent_layer_1.png. If you see a white / pink helmet (missing texture), check that the EriAPI jar is in your mods/ folder (in dev: add it as compile files() in build.gradle).

The model is offset / in the wrong position

• Verify your Blockbench model is designed in the right coordinate frame — see Default offsets.
• Tune with .offset(x, y, z) (in GL blocks = Blockbench pixels / 16).
• For a model imported from other software, try .rotation(0, 180, 0) — some exporters flip the Z axis.

The sleeves don't follow the arms

Check that your Blockbench groups are named exactly right_arm / left_arm (case-insensitive, underscore tolerated). The mapping looks for the exact name — a group named « ArmRight » will not be recognized.

The model flickers / disappears at certain angles

Classic cause: your model has transparent faces poorly sorted for OpenGL blend. The module enables disableCull() and enableBlend() by default, but the draw order remains that of the Blockbench JSON elements. For a clean effect, avoid overlapping multiple transparent faces — prefer a single cube with an alpha texture.

Performance

The layer is called every frame for every visible player. The cost is minimal because:

• The Item -> ArmorCosmeticDefinition lookup is an O(1) HashMap.get().
• The Blockbench model is cached in memory (first load only).
• No per-frame allocations — loops use for(int i) over existing lists.
• If the player is invisible (isInvisible()), the layer is short-circuited.