Items

Declaring an item

mod.content().item("ruby", ItemDefinition.builder()
        .rarity(ItemRarity.RARE)
        .creativeTab(CreativeTab.INGREDIENTS)
        .build());

Builder method	Meaning
maxStackSize(int)	Maximum count in one slot
durability(int)	Durability
fireResistant()	Does not burn
rarity(ItemRarity)	COMMON, UNCOMMON, RARE, EPIC
food(FoodDefinition)	Food
creativeTab(CreativeTab)	One of the game's creative tabs (added at the end of the tab). A mod's own tab is declared with mod.content().creativeTab(path, …); see Tags and creative tabs
behavior(ItemBehavior)	Use callback

Food

mod.content().item("star_fruit", ItemDefinition.builder()
        .food(new FoodDefinition(4, 0.3f, true))   // hunger, saturation, can be eaten even when full
        .creativeTab(CreativeTab.FOOD_AND_DRINKS)
        .build());

Use callback

mod.content().item("spark", ItemDefinition.builder()
        .behavior(new ItemBehavior() {
            @Override
            public InteractionResult onUse(ItemUse use) {
                if (!use.world().isClientSide()) {
                    use.player().sendMessage("Spark at " + use.player().blockPos());
                }
                return InteractionResult.SUCCESS;
            }
        })
        .build());

ItemUse has world(), player(), and stack(), the real stack that was used. If you return PASS, the game's default behavior applies.

Item data components

Declare a data component to store a value on each stack.

ItemComponentKey<Integer> CHARGE = mod.content().itemComponent("charge", ComponentType.INTEGER);

mod.content().item("wand", ItemDefinition.builder().maxStackSize(1).behavior(new ItemBehavior() {
    @Override
    public InteractionResult onUse(ItemUse use) {
        if (!use.world().isClientSide()) {
            use.stack().set(CHARGE, use.stack().get(CHARGE).orElse(0) + 1);
        }
        return InteractionResult.SUCCESS;
    }
}).build());

• The value types are ComponentType.INTEGER, BOOLEAN, STRING, and TREE (DataTree).
• The value is saved, copied, and synced with the stack. You can also use it in the /give <id>[<mod>:<name>=<value>] syntax.
• Stacks with different values do not merge.

Real stack references

ItemStackRef changes the real stack directly. ItemUse.stack(), PlayerView.mainHandStack(), and InventoryView.stackAt(slot) return it. Change it on the server.

Method	Meaning
item(), count(), setCount(n), isEmpty()	Item and count
get(key), set(key, value), remove(key)	Data components
customName(), setCustomName(name)	Name
damage(), maxDamage(), setDamage(n)	Durability
isIn(tag)	Whether the item is in an item tag (Tags)
snapshot()	An unchanging copy (ItemStackView)

Player inventory

player.give(ResourceId.of("my_mod", "ruby"), 2);
int count = player.countItem(ResourceId.of("my_mod", "ruby"));
ResourceId inHand = player.mainHandItem();
InventoryView inventory = player.inventory();

Tooltips

mod.events().register(ClientEvents.ITEM_TOOLTIP, (stack, lines, advanced) -> {   // client entrypoint
    if (stack.isIn(SPARKLY)) {
        lines.add(1, "§bSparkly");                                                  // right below the name
    }
});

• ClientEvents.ITEM_TOOLTIP fires on the client thread whenever the game builds an item's tooltip, after the game's own lines. That is every frame the tooltip is shown, and also for the creative search, so keep the listener light.
• It does not fire for items whose tooltip the game hides.
• advanced is whether advanced tooltips are on (F3+H). stack is the client's copy, so read it and do not change it.

TooltipLines holds the lines of one tooltip. The first line is the item's name. It is valid only during the listener call.

Method	Meaning
size()	Number of lines, the name included
get(index)	The text of a line, without formatting
add(line), add(index, line)	Add a line at the end, or insert it before line index (size() appends)
remove(index)	Remove a line

• Lines are plain text. Section-sign formatting codes (for example §7 for grey) are drawn as colors.
• Lines the game or other mods added keep their formatting unless you remove them.
• An index out of range throws IndexOutOfBoundsException.
• The rule and the line editing are covered by unit tests. The drawn tooltip on screen has not been checked by a person, because no window-opening test was run.

Resources

The item's appearance comes from assets/<mod>/items/<item>.json, models/item/…, and textures/item/…. Its name is item.<mod>.<id> in the lang file.

assets/my_mod/items/ruby.json

{"model": {"type": "minecraft:model", "model": "my_mod:item/ruby"}}

assets/my_mod/models/item/ruby.json

{"parent": "minecraft:item/generated", "textures": {"layer0": "my_mod:item/ruby"}}