Fabric items

Fabric Items — 1.20.1 Reference

---

Basic Item Registration

public class ModItems {
    public static final Item MY_ITEM = new Item(new FabricItemSettings()
        .maxCount(16)            // stack size (default 64)
        .fireproof()             // not destroyed by fire/lava
        .rarity(Rarity.RARE)    // COMMON / UNCOMMON / RARE / EPIC
    );

    public static void register() {
        Registry.register(Registries.ITEM,
            new Identifier("mymod", "my_item"), MY_ITEM);
    }
}

---

Custom Item with Logic

public class MySpecialItem extends Item {

    public MySpecialItem(Settings settings) {
        super(settings);
    }

    // Right-click in air / on block (no entity target)
    @Override
    public TypedActionResult<ItemStack> use(World world, PlayerEntity player, Hand hand) {
        ItemStack stack = player.getStackInHand(hand);

        if (!world.isClient) {
            player.sendMessage(Text.literal("Used the item!"), false);
            stack.damage(1, player, p -> p.sendToolBreakStatus(hand));
        }

        player.setCurrentHand(hand); // begin use animation
        return TypedActionResult.success(stack, world.isClient);
    }

    // Right-click on a block
    @Override
    public ActionResult useOnBlock(ItemUsageContext ctx) {
        if (!ctx.getWorld().isClient) {
            BlockPos pos = ctx.getBlockPos();
            ctx.getWorld().setBlockState(pos,
                ctx.getWorld().getBlockState(pos)); // example
        }
        return ActionResult.SUCCESS;
    }

    // Right-click on an entity
    @Override
    public ActionResult useOnEntity(ItemStack stack, PlayerEntity player,
            LivingEntity entity, Hand hand) {
        return ActionResult.PASS;
    }

    // Add tooltip lines
    @Override
    public void appendTooltip(ItemStack stack, World world,
            List<Text> tooltip, TooltipContext context) {
        tooltip.add(Text.translatable("item.mymod.my_item.tooltip")
            .formatted(Formatting.GRAY));
        if (Screen.hasShiftDown()) {
            tooltip.add(Text.literal("Shift info here").formatted(Formatting.DARK_GRAY));
        }
    }

    // Custom use time (for food / bows)
    @Override
    public int getMaxUseTime(ItemStack stack) { return 32; }

    @Override
    public UseAction getUseAction(ItemStack stack) { return UseAction.EAT; }
}

---

Food Items

public static final Item MY_FOOD = new Item(new FabricItemSettings()
    .food(new FoodComponent.Builder()
        .hunger(6)              // hunger points restored (×0.5 for half drumsticks)
        .saturationModifier(0.8f)  // saturation multiplier
        .meat()                 // counts as meat (for wolves, etc.)
        .alwaysEdible()         // can eat even when full
        .snack()                // eat faster (16 ticks instead of 32)
        .statusEffect(new StatusEffectInstance(StatusEffects.SPEED, 200, 1), 1.0f)
                                // effect, probability (0.0–1.0)
        .build()
    )
);

---

Custom Tool

ToolMaterial

public enum ModToolMaterial implements ToolMaterial {
    MY_MATERIAL;

    @Override public int getDurability()        { return 800; }
    @Override public float getMiningSpeedMultiplier() { return 7.0f; }
    @Override public float getAttackDamage()    { return 3.0f; }
    @Override public int getMiningLevel()       { return 3; }   // 0=wood,1=stone,2=iron,3=diamond
    @Override public int getEnchantability()    { return 14; }
    @Override public Ingredient getRepairIngredient() {
        return Ingredient.ofItems(ModItems.MY_GEM);
    }
}

Tool items

// Sword, Pickaxe, Axe, Shovel, Hoe
public static final Item MY_SWORD   = new SwordItem(ModToolMaterial.MY_MATERIAL,
    3, -2.4f,   // bonusAttackDamage, attackSpeed
    new FabricItemSettings());

public static final Item MY_PICKAXE = new PickaxeItem(ModToolMaterial.MY_MATERIAL,
    1, -2.8f, new FabricItemSettings());

public static final Item MY_AXE     = new AxeItem(ModToolMaterial.MY_MATERIAL,
    6.0f, -3.0f, new FabricItemSettings());

public static final Item MY_SHOVEL  = new ShovelItem(ModToolMaterial.MY_MATERIAL,
    1.5f, -3.0f, new FabricItemSettings());

public static final Item MY_HOE     = new HoeItem(ModToolMaterial.MY_MATERIAL,
    -3, 0.0f, new FabricItemSettings());

Mining levels in tags

Add your ore block to the correct tag so getMiningLevel() applies:

• minecraft:needs_stone_tool → mining level 1+
• minecraft:needs_iron_tool → mining level 2+
• minecraft:needs_diamond_tool → mining level 3+

---

Custom Armor

ArmorMaterial

public enum ModArmorMaterial implements ArmorMaterial {
    MY_ARMOR("mymod:my_armor",
        new int[]{3, 6, 8, 3},     // durability multipliers [boots,leggings,chest,helmet]
        new int[]{3, 6, 8, 3},     // protection values
        10,                         // enchantability
        SoundEvents.ITEM_ARMOR_EQUIP_IRON,
        1.0f,                       // toughness
        0.0f,                       // knockback resistance
        () -> Ingredient.ofItems(ModItems.MY_GEM)  // repair ingredient
    );

    // ... boilerplate enum constructor + getters omitted for brevity
    // Implement all ArmorMaterial methods referencing the constructor args
}

Armor items

public static final Item MY_HELMET     = new ArmorItem(ModArmorMaterial.MY_ARMOR,
    ArmorItem.Type.HELMET,     new FabricItemSettings());
public static final Item MY_CHESTPLATE = new ArmorItem(ModArmorMaterial.MY_ARMOR,
    ArmorItem.Type.CHESTPLATE, new FabricItemSettings());
public static final Item MY_LEGGINGS   = new ArmorItem(ModArmorMaterial.MY_ARMOR,
    ArmorItem.Type.LEGGINGS,   new FabricItemSettings());
public static final Item MY_BOOTS      = new ArmorItem(ModArmorMaterial.MY_ARMOR,
    ArmorItem.Type.BOOTS,      new FabricItemSettings());

Armor texture at: assets/minecraft/textures/models/armor/my_armor_layer_1.png (body) and _layer_2.png (leggings).

---

Item Durability

new FabricItemSettings().maxDamage(500) // makes the item damageable with 500 durability

Damage an item in code:

// Damages by 1, breaks and plays break animation if durability hits 0
stack.damage(1, player, p -> p.sendToolBreakStatus(hand));

Check if item is damaged:

stack.isDamaged()      // has any damage
stack.getDamage()      // current damage value
stack.getMaxDamage()   // max damage

---

Custom Enchantment

public class MyEnchantment extends Enchantment {

    public MyEnchantment() {
        super(Enchantment.Rarity.UNCOMMON,
            EnchantmentTarget.WEAPON,    // what slots it can apply to
            new EquipmentSlot[]{EquipmentSlot.MAINHAND}
        );
    }

    @Override public int getMinPower(int level) { return 10 + (level - 1) * 8; }
    @Override public int getMaxPower(int level) { return getMinPower(level) + 15; }
    @Override public int getMaxLevel()           { return 3; }

    // Prevent combining with another enchantment
    @Override
    public boolean canCombine(Enchantment other) {
        return super.canCombine(other) && !(other instanceof SharpnessEnchantment);
    }
}

// Register in onInitialize():
public class ModEnchantments {
    public static final Enchantment MY_ENCHANT = new MyEnchantment();

    public static void register() {
        Registry.register(Registries.ENCHANTMENT,
            new Identifier("mymod", "my_enchant"), MY_ENCHANT);
    }
}

Apply enchantment effect in an event or mixin — enchantments don't auto-apply; you hook into damage events or ticks and read EnchantmentHelper.getLevel(ModEnchantments.MY_ENCHANT, stack).

---

Item Creative Tab

// Add to existing tab:
ItemGroupEvents.modifyEntriesEvent(ItemGroups.TOOLS).register(content -> {
    content.add(ModItems.MY_TOOL);
});

// Create a custom tab:
public static final ItemGroup MY_GROUP = FabricItemGroup.builder()
    .icon(() -> new ItemStack(ModItems.MY_ITEM))
    .displayName(Text.translatable("itemGroup.mymod.main"))
    .entries((ctx, entries) -> {
        entries.add(ModItems.MY_ITEM);
        entries.add(ModItems.MY_SWORD);
    })
    .build();

// Register it:
Registry.register(Registries.ITEM_GROUP,
    new Identifier("mymod", "main"), MY_GROUP);

---

Item Models

assets/mymod/models/item/my_item.json (flat sprite):

{
  "parent": "item/generated",
  "textures": { "layer0": "mymod:item/my_item" }
}

assets/mymod/models/item/my_sword.json (handheld):

{
  "parent": "item/handheld",
  "textures": { "layer0": "mymod:item/my_sword" }
}

Texture PNG at: assets/mymod/textures/item/my_item.png (16×16)

---

Common Mistakes

• maxDamage and maxCount both set — damageable items must have maxCount(1).
• Armor texture path wrong — armor layers go under assets/minecraft/textures/models/armor/, not mymod.
• Enchantment not appearing on table — check getMinPower / getMaxPower aren't returning impossible values, and the item is in the right EnchantmentTarget.
• Food not restoring hunger — ensure FoodComponent is set in FabricItemSettings not on the item class.
• Tooltip not showing — @Override appendTooltip signature must match exactly (5 params in 1.20.1).

---

Related Skills

• fabric-mc-modding — project setup, general registration
• fabric-datagen — generating item models, lang entries, recipes
• minecraft-json-assets — item model JSON format reference
• fabric-rendering — custom item renderers (FABULOUS items)