Skip to content

How to store a value on an item with a data component (Minecraft mod)

An item stack keeps extra data. On 1.20.5 and newer that is data components: a registered DataComponentType with a Codec for saving and a stream codec for sending it to the client. Read it with stack.get or getOrDefault and change it with stack.set or stack.update. Before 1.20.5 it is an NBT tag on the stack (getOrCreateTag to write, getTag to read, which can be null). Only change stacks on the server. Stacks with the same data are the ones that can merge.

Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.

  1. On 1.20.5 and newer, register a DataComponentType with persistent(codec) and networkSynchronized(streamCodec); before that, pick a key for the NBT tag.
  2. Read the value and write it on the server (getOrDefault and update; getTag and getOrCreateTag before 1.20.5).
  3. Show it in appendHoverText.
  4. Right-click the item a few times and hover over it.

The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.

Uses:

  • ItemStack.getOrCreateTag
  • ItemStack.getTag
  • CompoundTag.putInt
  • Item.appendHoverText

Data components came with 1.20.5. Before that an item stack keeps extra data in an NBT tag: getOrCreateTag to write on the server, getTag to read (it can be null).

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import java.util.List;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
import org.jetbrains.annotations.Nullable;
// Tally Stick: counts how often it was used. The number lives on the stack as an NBT tag and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
CompoundTag tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable Level level, List<Component> tooltip, TooltipFlag flag) {
CompoundTag tag = stack.getTag();
tooltip.add(Component.literal("Used " + (tag == null ? 0 : tag.getInt(USES)) + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.List;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES, 0, uses -> uses + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, List<Component> tooltip, TooltipFlag flag) {
tooltip.add(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES, 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import net.minecraft.core.Registry;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.network.codec.ByteBufCodecs;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
public static final DataComponentType<Integer> USES = Registry.register(BuiltInRegistries.DATA_COMPONENT_TYPE, ExampleMod.id("tally_stick_uses"),
DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's onInitialize; loading this class registers the component above.
public static void register() {
}
}

In your main mod class, inside onInitialize:

TallyStickComponents.register();

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.List;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES.get(), 0, uses -> uses + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, List<Component> tooltip, TooltipFlag flag) {
tooltip.add(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES.get(), 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import java.util.function.Supplier;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.Registries;
import net.minecraft.network.codec.ByteBufCodecs;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.neoforge.registries.DeferredRegister;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
private static final DeferredRegister<DataComponentType<?>> COMPONENTS = DeferredRegister.create(Registries.DATA_COMPONENT_TYPE, ExampleMod.MOD_ID);
public static final Supplier<DataComponentType<Integer>> USES = COMPONENTS.register("tally_stick_uses",
() -> DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's constructor.
public static void register(IEventBus modBus) {
COMPONENTS.register(modBus);
}
}

In your main mod class, inside <init>:

TallyStickComponents.register(modEventBus);

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • CompoundTag.putInt
  • CompoundTag.getInt
  • Item.appendHoverText

Data components came with 1.20.5. Before that an item stack keeps its extra data in an NBT tag (stack.getTag()). Only change stacks on the server. Stacks with the same tag merge.

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import java.util.List;
import javax.annotation.Nullable;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives in the stack's NBT tag, is saved with the item and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
CompoundTag tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable Level level, List<Component> tooltip, TooltipFlag flag) {
int uses = stack.hasTag() ? stack.getTag().getInt(USES) : 0;
tooltip.add(Component.literal("Used " + uses + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.List;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResult;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResult use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES, 0, uses -> uses + 1);
}
return InteractionResult.SUCCESS;
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, List<Component> tooltip, TooltipFlag flag) {
tooltip.add(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES, 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import net.minecraft.core.Registry;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.network.codec.ByteBufCodecs;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
public static final DataComponentType<Integer> USES = Registry.register(BuiltInRegistries.DATA_COMPONENT_TYPE, ExampleMod.id("tally_stick_uses"),
DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's onInitialize; loading this class registers the component above.
public static void register() {
}
}

In your main mod class, inside onInitialize:

TallyStickComponents.register();

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.List;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResult;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResult use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES.get(), 0, uses -> uses + 1);
}
return InteractionResult.SUCCESS;
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, List<Component> tooltip, TooltipFlag flag) {
tooltip.add(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES.get(), 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import java.util.function.Supplier;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.Registries;
import net.minecraft.network.codec.ByteBufCodecs;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.neoforge.registries.DeferredRegister;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
private static final DeferredRegister<DataComponentType<?>> COMPONENTS = DeferredRegister.create(Registries.DATA_COMPONENT_TYPE, ExampleMod.MOD_ID);
public static final Supplier<DataComponentType<Integer>> USES = COMPONENTS.register("tally_stick_uses",
() -> DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's constructor.
public static void register(IEventBus modBus) {
COMPONENTS.register(modBus);
}
}

In your main mod class, inside <init>:

TallyStickComponents.register(modEventBus);

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.function.Consumer;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResult;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.item.component.TooltipDisplay;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResult use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES.get(), 0, uses -> uses + 1);
}
return InteractionResult.SUCCESS;
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, TooltipDisplay display, Consumer<Component> tooltip, TooltipFlag flag) {
tooltip.accept(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES.get(), 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import java.util.function.Supplier;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.Registries;
import net.minecraft.network.codec.ByteBufCodecs;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.neoforge.registries.DeferredRegister;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
private static final DeferredRegister<DataComponentType<?>> COMPONENTS = DeferredRegister.create(Registries.DATA_COMPONENT_TYPE, ExampleMod.MOD_ID);
public static final Supplier<DataComponentType<Integer>> USES = COMPONENTS.register("tally_stick_uses",
() -> DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's constructor.
public static void register(IEventBus modBus) {
COMPONENTS.register(modBus);
}
}

In your main mod class, inside <init>:

TallyStickComponents.register(modEventBus);

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • DataComponentType.builder
  • ItemStack.update
  • ItemStack.getOrDefault
  • Item.appendHoverText

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import com.example.examplemod.registry.TallyStickComponents;
import java.util.function.Consumer;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResult;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.item.component.TooltipDisplay;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives on the stack as a data component and shows in the tooltip.
public class TallyStickItem extends Item {
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResult use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
stack.update(TallyStickComponents.USES, 0, uses -> uses + 1);
}
return InteractionResult.SUCCESS;
}
@Override
public void appendHoverText(ItemStack stack, Item.TooltipContext context, TooltipDisplay display, Consumer<Component> tooltip, TooltipFlag flag) {
tooltip.accept(Component.literal("Used " + stack.getOrDefault(TallyStickComponents.USES, 0) + " times"));
}
}

src/main/java/com/example/examplemod/registry/TallyStickComponents.java

package com.example.examplemod.registry;
import com.example.examplemod.ExampleMod;
import com.mojang.serialization.Codec;
import net.minecraft.core.Registry;
import net.minecraft.core.component.DataComponentType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.network.codec.ByteBufCodecs;
// The data component tally_stick_uses: a whole number kept on an item stack, saved and sent to the client.
public final class TallyStickComponents {
public static final DataComponentType<Integer> USES = Registry.register(BuiltInRegistries.DATA_COMPONENT_TYPE, ExampleMod.id("tally_stick_uses"),
DataComponentType.<Integer>builder().persistent(Codec.INT).networkSynchronized(ByteBufCodecs.VAR_INT).build());
private TallyStickComponents() {
}
// Called from the mod's onInitialize; loading this class registers the component above.
public static void register() {
}
}

In your main mod class, inside onInitialize:

TallyStickComponents.register();

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • CompoundTag.putInt
  • CompoundTag.getInt
  • Item.appendHoverText

Before 1.20.5 an item stack keeps its extra data in an NBT tag (stack.getTag()), not in data components. Only change stacks on the server. Stacks with the same tag merge.

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import net.minecraft.network.chat.TextComponent;
import java.util.List;
import javax.annotation.Nullable;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives in the stack's NBT tag, is saved with the item and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
CompoundTag tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable Level level, List<Component> tooltip, TooltipFlag flag) {
int uses = stack.hasTag() ? stack.getTag().getInt(USES) : 0;
tooltip.add(new TextComponent("Used " + uses + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • CompoundTag.putInt
  • CompoundTag.getInt
  • Item.appendHoverText

Before 1.20.5 an item stack keeps its extra data in an NBT tag (stack.getTag()), not in data components. Only change stacks on the server. Stacks with the same tag merge.

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import java.util.List;
import javax.annotation.Nullable;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
// Tally Stick: counts how often it was used. The number lives in the stack's NBT tag, is saved with the item and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
CompoundTag tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable Level level, List<Component> tooltip, TooltipFlag flag) {
int uses = stack.hasTag() ? stack.getTag().getInt(USES) : 0;
tooltip.add(Component.literal("Used " + uses + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • CompoundNBT.putInt
  • CompoundNBT.getInt
  • Item.appendHoverText

In 1.16.5 an item stack keeps its extra data in an NBT tag (stack.getTag()), not in data components. Only change stacks on the server. Stacks with the same tag merge.

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import net.minecraft.util.text.StringTextComponent;
import java.util.List;
import javax.annotation.Nullable;
import net.minecraft.nbt.CompoundNBT;
import net.minecraft.util.text.ITextComponent;
import net.minecraft.util.Hand;
import net.minecraft.util.ActionResult;
import net.minecraft.entity.player.PlayerEntity;
import net.minecraft.item.Item;
import net.minecraft.item.ItemStack;
import net.minecraft.client.util.ITooltipFlag;
import net.minecraft.world.World;
// Tally Stick: counts how often it was used. The number lives in the stack's NBT tag, is saved with the item and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public ActionResult<ItemStack> use(World world, PlayerEntity player, Hand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!world.isClientSide()) {
CompoundNBT tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return ActionResult.sidedSuccess(stack, world.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable World world, List<ITextComponent> tooltip, ITooltipFlag flag) {
int uses = stack.hasTag() ? stack.getTag().getInt(USES) : 0;
tooltip.add(new StringTextComponent("Used " + uses + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • ItemStack.getTag
  • CompoundTag.putInt
  • Item.appendHoverText

Before 1.20.5 an item stack keeps extra data in an NBT tag: getOrCreateTag to write on the server, getTag to read (it can be null).

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import net.minecraft.network.chat.TextComponent;
import java.util.List;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.TooltipFlag;
import net.minecraft.world.level.Level;
import org.jetbrains.annotations.Nullable;
// Tally Stick: counts how often it was used. The number lives on the stack as an NBT tag and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
public TallyStickItem(Item.Properties properties) {
super(properties);
}
@Override
public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
ItemStack stack = player.getItemInHand(hand);
if (!level.isClientSide()) {
CompoundTag tag = stack.getOrCreateTag();
tag.putInt(USES, tag.getInt(USES) + 1);
}
return InteractionResultHolder.sidedSuccess(stack, level.isClientSide());
}
@Override
public void appendHoverText(ItemStack stack, @Nullable Level level, List<Component> tooltip, TooltipFlag flag) {
CompoundTag tag = stack.getTag();
tooltip.add(new TextComponent("Used " + (tag == null ? 0 : tag.getInt(USES)) + " times"));
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Uses:

  • ItemStack.getOrCreateTag
  • NBTTagCompound.putInt
  • NBTTagCompound.getInt
  • Item.appendHoverText

In 1.12.2 the tag is stack.getTagCompound(), which can be null: create it and store it with setTagCompound, and the tooltip method is addInformation.

src/main/java/com/example/examplemod/item/TallyStickItem.java

package com.example.examplemod.item;
import java.util.List;
import javax.annotation.Nullable;
import net.minecraft.client.util.ITooltipFlag;
import net.minecraft.entity.player.EntityPlayer;
import net.minecraft.item.Item;
import net.minecraft.item.ItemStack;
import net.minecraft.nbt.NBTTagCompound;
import net.minecraft.util.ActionResult;
import net.minecraft.util.EnumActionResult;
import net.minecraft.util.EnumHand;
import net.minecraft.world.World;
import net.minecraftforge.fml.relauncher.Side;
import net.minecraftforge.fml.relauncher.SideOnly;
// Tally Stick: counts how often it was used. The number lives in the stack's NBT tag, is saved with the item and shows in the tooltip.
public class TallyStickItem extends Item {
private static final String USES = "tally_stick_uses";
@Override
public ActionResult<ItemStack> onItemRightClick(World world, EntityPlayer player, EnumHand hand) {
ItemStack stack = player.getHeldItem(hand);
if (!world.isRemote) {
NBTTagCompound tag = stack.getTagCompound();
if (tag == null) {
tag = new NBTTagCompound();
stack.setTagCompound(tag);
}
tag.setInteger(USES, tag.getInteger(USES) + 1);
}
return new ActionResult<>(EnumActionResult.SUCCESS, stack);
}
@Override
@SideOnly(Side.CLIENT)
public void addInformation(ItemStack stack, @Nullable World world, List<String> tooltip, ITooltipFlag flag) {
int uses = stack.hasTagCompound() ? stack.getTagCompound().getInteger(USES) : 0;
tooltip.add("Used " + uses + " times");
}
}

It’s registered like any other item, as TallyStickItem: see a new item.

Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.