Items

Items

Butterfly API includes item helpers for three common Minecraft 1.21.11 tasks:

• displayed attack speed modifiers
• separate GUI and held item models
• custom progress bars beneath item stacks

Displayed Attack Speed

Vanilla attack speed attributes use a modifier based on displayed speed - 4.0.

ItemUtils lets you work with the attack speed value you actually want players to see.

import moth.butterflyapi.item.ItemUtils;
import net.minecraft.item.Item;

public static final Item QUICK_BLADE = MOD.item(
        "quick_blade",
        settings -> new Item(ItemUtils.combatAttributes(
                settings,
                MOD.id("quick_blade"),
                5.0D,
                1.8D))
);

In this example:

• 5.0D is the attack damage
• 1.8D is the displayed attack speed

Attack Speed Only

ItemUtils.displayedAttackSpeed(
        settings,
        MOD.id("fast_tool"),
        2.4D
);

Convert Displayed Speed Manually

double vanillaModifier =
        ItemUtils.attackSpeedModifier(1.6D);

Separate GUI And Held Models

Minecraft 1.21.11 uses item model definitions under:

assets/<modid>/items/<id>.json

Butterfly API can generate the JSON needed for an item that uses one model in the GUI and another while held.

import moth.butterflyapi.item.ItemModelDefinitions;

var models = ItemModelDefinitions.separateGuiAndHeld(
        MOD.id("twisted_spade")
);

String itemDefinitionPath = models.itemDefinitionPath();
String itemDefinitionJson = models.itemDefinitionJson();

String guiModelJson = models.guiModelJson(
        MOD.id("item/twisted_spade_gui")
);

String heldModelJson = models.heldModelJson(
        MOD.id("item/twisted_spade")
);

The default output paths are:

assets/<modid>/items/<id>.json
assets/<modid>/models/item/<id>.json
assets/<modid>/models/item/<id>_held.json

The held model is used for:

• firstperson_lefthand
• firstperson_righthand
• thirdperson_lefthand
• thirdperson_righthand

The GUI model is used as the fallback for inventory, ground, fixed, and other contexts.

Custom Item Progress Bars

Butterfly API can render custom progress bars beneath item stacks.

Single Progress Bar

import moth.butterflyapi.item.bar.ItemProgressBars;

ItemProgressBars.register(
        TWISTED_SPADE,
        0xE63F51,
        stack -> charge(stack)
);

The progress function should normally return a value from:

0.0

to:

1.0

where 0.0 is empty and 1.0 is full.

Multiple Progress Bars

import moth.butterflyapi.item.bar.ItemProgressBar;

ItemProgressBars.register(
        TWISTED_CORE,
        stack -> List.of(
                ItemProgressBar.of(
                        primaryProgress(stack),
                        0x66CCFF
                ),
                ItemProgressBar.of(
                        secondaryProgress(stack),
                        0xFFD166,
                        false
                )
        )
);

This allows an item to display multiple separate rows.

Layered Progress

Use registerLayered(...) when one value can progress through multiple full layers.

ItemProgressBars.registerLayered(
        TWISTED_SPADE,
        true,
        stack -> storedCycles(stack),
        0xE63F51,
        0x8A4DFF,
        0xFFD166
);

Layered progress can be greater than 1.0.

For example:

2.35

means:

• two completed layers
• 35% progress through the next layer

Butterfly renders layered bars in constant time, so large progress values do not require every completed layer to be drawn individually.

Pixel Snapping

pixelSnap controls how the visible bar width is rounded.

true

Rounds to pixel steps for a crisp vanilla-style bar.

false

Uses ceiling behavior so very small non-zero progress becomes visible sooner.

Related Pages

• Registration
• Quick Start
• Resource Conventions
• Troubleshooting