How to make a new enchantment in a Minecraft mod
Since 1.21 an enchantment is a data file in data/<your mod>/enchantment. It lists which items accept it (supported_items, a tag), the highest level, the cost range for the enchanting table, the slots where it works, and its effects as components. This one uses the damage component to add damage per level. Its name needs a language entry. Effects such as healing the attacker use other components or code. Before 1.21 an enchantment is a Java object instead.
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.
- Add the enchantment file in data/<your mod>/enchantment (before 1.21, write an Enchantment class instead).
- Choose supported_items (an item tag), max_level, the costs and the slots.
- Put its effect under effects, here minecraft:damage.
- Give it an English name with the key enchantment.<mod id>.<name>.
- Run /enchant @s <mod id>:<name> in a world to test it.
What you can change
Section titled “What you can change”The example uses these values. Change them in the code.
| Setting | In the example | What it does |
|---|---|---|
| max | 3 |
The highest level. |
For each loader and version
Section titled “For each loader and version”The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.
Fabric and NeoForge 1.21 to 1.21.1, Fabric and NeoForge 1.21.2 to 26.3
Section titled “Fabric and NeoForge 1.21 to 1.21.1, Fabric and NeoForge 1.21.2 to 26.3”Uses:
Registries.ENCHANTMENTminecraft:damageminecraft:addminecraft:linear
src/main/resources/data/examplemod/enchantment/razor_edge.json
{ "description": { "translate": "enchantment.examplemod.razor_edge" }, "supported_items": "#minecraft:enchantable/sword", "primary_items": "#minecraft:enchantable/sword", "weight": 5, "max_level": 3, "min_cost": { "base": 10, "per_level_above_first": 10 }, "max_cost": { "base": 40, "per_level_above_first": 10 }, "anvil_cost": 4, "slots": [ "mainhand" ], "effects": { "minecraft:damage": [ { "effect": { "type": "minecraft:add", "value": { "type": "minecraft:linear", "base": 1.0, "per_level_above_first": 1.0 } } } ] }}In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}NeoForge 1.20.1, Forge 1.18.2 to 1.20.1
Section titled “NeoForge 1.20.1, Forge 1.18.2 to 1.20.1”Uses:
Enchantment.getDamageBonusEnchantment.getMaxLevelForgeRegistries.ENCHANTMENTSEnchantmentCategory.WEAPON
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.world.entity.MobType;import net.minecraft.world.item.enchantment.Enchantment;import net.minecraft.world.item.enchantment.EnchantmentCategory;import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;import net.minecraftforge.registries.DeferredRegister;import net.minecraftforge.registries.ForgeRegistries;import net.minecraftforge.registries.RegistryObject;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final DeferredRegister<Enchantment> ENCHANTMENTS = DeferredRegister.create(ForgeRegistries.ENCHANTMENTS, ExampleMod.MOD_ID);
public static final RegistryObject<Enchantment> RAZOR_EDGE = ENCHANTMENTS.register("razor_edge", Sharp::new);
private RazorEdgeEnchantment() { }
// Called from the mod's constructor. public static void register() { ENCHANTMENTS.register(FMLJavaModLoadingContext.get().getModEventBus()); }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnchantmentCategory.WEAPON, new EquipmentSlot[] {EquipmentSlot.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, MobType type) { return level; } }}In your main mod class, inside <init>:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}NeoForge 1.20.2 to 1.20.4
Section titled “NeoForge 1.20.2 to 1.20.4”Uses:
Registries.ENCHANTMENTDeferredRegister.createEnchantment.getDamageBonusEnchantment.getMaxLevelEnchantmentCategory.WEAPON
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.core.registries.Registries;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.world.entity.MobType;import net.minecraft.world.item.enchantment.Enchantment;import net.minecraft.world.item.enchantment.EnchantmentCategory;import net.neoforged.bus.api.IEventBus;import net.neoforged.neoforge.registries.DeferredHolder;import net.neoforged.neoforge.registries.DeferredRegister;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final DeferredRegister<Enchantment> ENCHANTMENTS = DeferredRegister.create(Registries.ENCHANTMENT, ExampleMod.MOD_ID);
public static final DeferredHolder<Enchantment, Enchantment> RAZOR_EDGE = ENCHANTMENTS.register("razor_edge", Sharp::new);
private RazorEdgeEnchantment() { }
// Called from the mod's constructor with the mod event bus. public static void register(IEventBus modBus) { ENCHANTMENTS.register(modBus); }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnchantmentCategory.WEAPON, new EquipmentSlot[] {EquipmentSlot.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, MobType type) { return level; } }}In your main mod class, inside <init>:
RazorEdgeEnchantment.register(modEventBus);In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}NeoForge 1.20.5 to 1.20.6
Section titled “NeoForge 1.20.5 to 1.20.6”Uses:
Registries.ENCHANTMENTEnchantment.definitionEnchantment.dynamicCostItemTags.SWORD_ENCHANTABLEEnchantment.getDamageBonus
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>. On 1.20.5 and 1.20.6 an enchantment is made from Enchantment.definition(…): the items it goes on (an item tag), weight, max level, costs and slots.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.core.registries.Registries;import net.minecraft.world.entity.EquipmentSlot;import javax.annotation.Nullable;import net.minecraft.tags.ItemTags;import net.minecraft.world.entity.EntityType;import net.minecraft.world.item.enchantment.Enchantment;import net.neoforged.bus.api.IEventBus;import net.neoforged.neoforge.registries.DeferredHolder;import net.neoforged.neoforge.registries.DeferredRegister;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final DeferredRegister<Enchantment> ENCHANTMENTS = DeferredRegister.create(Registries.ENCHANTMENT, ExampleMod.MOD_ID);
public static final DeferredHolder<Enchantment, Enchantment> RAZOR_EDGE = ENCHANTMENTS.register("razor_edge", Sharp::new);
private RazorEdgeEnchantment() { }
// Called from the mod's constructor with the mod event bus. public static void register(IEventBus modBus) { ENCHANTMENTS.register(modBus); }
private static final class Sharp extends Enchantment { Sharp() { // swords, weight 10, levels 1 to 3, table cost 10 + 10 per level up to 30 more, anvil cost 1 super(Enchantment.definition(ItemTags.SWORD_ENCHANTABLE, 10, 3, Enchantment.dynamicCost(10, 10), Enchantment.dynamicCost(40, 10), 1, EquipmentSlot.MAINHAND)); }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, @Nullable EntityType<?> type) { return level; } }}In your main mod class, inside <init>:
RazorEdgeEnchantment.register(modEventBus);In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Fabric 1.16.5 to 1.19.2
Section titled “Fabric 1.16.5 to 1.19.2”Uses:
Registry.ENCHANTMENTEnchantment.getDamageBonusEnchantment.getMaxLevelEnchantmentCategory.WEAPON
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.core.Registry;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.world.entity.MobType;import net.minecraft.world.item.enchantment.Enchantment;import net.minecraft.world.item.enchantment.EnchantmentCategory;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final Enchantment RAZOR_EDGE = Registry.register(Registry.ENCHANTMENT, ExampleMod.id("razor_edge"), new Sharp());
private RazorEdgeEnchantment() { }
// Called from ExampleMod#onInitialize; loading this class registers the enchantment above. public static void register() { }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnchantmentCategory.WEAPON, new EquipmentSlot[] {EquipmentSlot.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, MobType type) { return level; } }}In your main mod class, inside onInitialize:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Fabric 1.19.3 to 1.20.4
Section titled “Fabric 1.19.3 to 1.20.4”Uses:
BuiltInRegistries.ENCHANTMENTEnchantment.getDamageBonusEnchantment.getMaxLevelEnchantmentCategory.WEAPON
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.core.Registry;import net.minecraft.core.registries.BuiltInRegistries;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.world.entity.MobType;import net.minecraft.world.item.enchantment.Enchantment;import net.minecraft.world.item.enchantment.EnchantmentCategory;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final Enchantment RAZOR_EDGE = Registry.register(BuiltInRegistries.ENCHANTMENT, ExampleMod.id("razor_edge"), new Sharp());
private RazorEdgeEnchantment() { }
// Called from ExampleMod#onInitialize; loading this class registers the enchantment above. public static void register() { }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnchantmentCategory.WEAPON, new EquipmentSlot[] {EquipmentSlot.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, MobType type) { return level; } }}In your main mod class, inside onInitialize:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Fabric 1.20.5 to 1.20.6
Section titled “Fabric 1.20.5 to 1.20.6”Uses:
BuiltInRegistries.ENCHANTMENTEnchantment.definitionEnchantment.dynamicCostItemTags.SWORD_ENCHANTABLEEnchantment.getDamageBonus
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>. On 1.20.5 and 1.20.6 an enchantment is made from Enchantment.definition(…): the items it goes on (an item tag), weight, max level, costs and slots.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.core.Registry;import net.minecraft.core.registries.BuiltInRegistries;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.tags.ItemTags;import net.minecraft.world.entity.EntityType;import net.minecraft.world.item.enchantment.Enchantment;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final Enchantment RAZOR_EDGE = Registry.register(BuiltInRegistries.ENCHANTMENT, ExampleMod.id("razor_edge"), new Sharp());
private RazorEdgeEnchantment() { }
// Called from ExampleMod#onInitialize; loading this class registers the enchantment above. public static void register() { }
private static final class Sharp extends Enchantment { Sharp() { // swords, weight 10, levels 1 to 3, table cost 10 + 10 per level up to 30 more, anvil cost 1 super(Enchantment.definition(ItemTags.SWORD_ENCHANTABLE, 10, 3, Enchantment.dynamicCost(10, 10), Enchantment.dynamicCost(40, 10), 1, EquipmentSlot.MAINHAND)); }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, EntityType<?> type) { return level; } }}In your main mod class, inside onInitialize:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Forge 1.17.1
Section titled “Forge 1.17.1”Uses:
Enchantment.getDamageBonusEnchantment.getMaxLevelForgeRegistries.ENCHANTMENTSEnchantmentCategory.WEAPON
Before 1.21 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.world.entity.EquipmentSlot;import net.minecraft.world.entity.MobType;import net.minecraft.world.item.enchantment.Enchantment;import net.minecraft.world.item.enchantment.EnchantmentCategory;import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;import net.minecraftforge.registries.DeferredRegister;import net.minecraftforge.registries.ForgeRegistries;import net.minecraftforge.fmllegacy.RegistryObject;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final DeferredRegister<Enchantment> ENCHANTMENTS = DeferredRegister.create(ForgeRegistries.ENCHANTMENTS, ExampleMod.MOD_ID);
public static final RegistryObject<Enchantment> RAZOR_EDGE = ENCHANTMENTS.register("razor_edge", Sharp::new);
private RazorEdgeEnchantment() { }
// Called from the mod's constructor. public static void register() { ENCHANTMENTS.register(FMLJavaModLoadingContext.get().getModEventBus()); }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnchantmentCategory.WEAPON, new EquipmentSlot[] {EquipmentSlot.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, MobType type) { return level; } }}In your main mod class, inside <init>:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Forge 1.16.5
Section titled “Forge 1.16.5”Uses:
Enchantment.getDamageBonusEnchantment.getMaxLevelForgeRegistries.ENCHANTMENTSEnchantmentType.WEAPON
In 1.16.5 an enchantment is a Java object registered in the enchantment registry, not a data file, so there is no JSON here. Test it with /enchant @s <mod id>:<name>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.inventory.EquipmentSlotType;import net.minecraft.entity.CreatureAttribute;import net.minecraft.enchantment.Enchantment;import net.minecraft.enchantment.EnchantmentType;import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;import net.minecraftforge.registries.DeferredRegister;import net.minecraftforge.registries.ForgeRegistries;import net.minecraftforge.fml.RegistryObject;
// Before 1.21 an enchantment is a registered object, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.public final class RazorEdgeEnchantment { public static final DeferredRegister<Enchantment> ENCHANTMENTS = DeferredRegister.create(ForgeRegistries.ENCHANTMENTS, ExampleMod.MOD_ID);
public static final RegistryObject<Enchantment> RAZOR_EDGE = ENCHANTMENTS.register("razor_edge", Sharp::new);
private RazorEdgeEnchantment() { }
// Called from the mod's constructor. public static void register() { ENCHANTMENTS.register(FMLJavaModLoadingContext.get().getModEventBus()); }
private static final class Sharp extends Enchantment { Sharp() { super(Enchantment.Rarity.COMMON, EnchantmentType.WEAPON, new EquipmentSlotType[] {EquipmentSlotType.MAINHAND}); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinCost(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxCost(int level) { return getMinCost(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float getDamageBonus(int level, CreatureAttribute type) { return level; } }}In your main mod class, inside <init>:
RazorEdgeEnchantment.register();In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Forge 1.12.2
Section titled “Forge 1.12.2”Uses:
Enchantment.getDamageBonusEnchantment.getMaxLevelForgeRegistries.ENCHANTMENTSEnchantmentType.WEAPON
In 1.12.2 an enchantment is a Java object (an Enchantment with a Rarity, an EnumEnchantmentType and the slots it works in) registered in a registry event, so there is no JSON here. Test it with /enchant <player> <id> <level>.
src/main/java/com/example/examplemod/enchantment/RazorEdgeEnchantment.java
package com.example.examplemod.enchantment;
import com.example.examplemod.ExampleMod;import net.minecraft.enchantment.Enchantment;import net.minecraft.enchantment.EnumEnchantmentType;import net.minecraft.entity.EnumCreatureAttribute;import net.minecraft.inventory.EntityEquipmentSlot;import net.minecraft.util.ResourceLocation;import net.minecraftforge.event.RegistryEvent;import net.minecraftforge.fml.common.Mod;import net.minecraftforge.fml.common.eventhandler.SubscribeEvent;
// In 1.12.2 an enchantment is a Java object registered in the enchantment registry, not a data file. examplemod:razor_edge goes on swords and adds 1 damage per level.@Mod.EventBusSubscriber(modid = ExampleMod.MOD_ID)public final class RazorEdgeEnchantment { public static final Enchantment ENCHANTMENT = new Sharp();
private RazorEdgeEnchantment() { }
@SubscribeEvent public static void register(RegistryEvent.Register<Enchantment> event) { event.getRegistry().register(ENCHANTMENT); }
// Called from the mod's startup code; the event handler above does the work. public static void register() { }
private static final class Sharp extends Enchantment { Sharp() { super(Rarity.COMMON, EnumEnchantmentType.WEAPON, new EntityEquipmentSlot[] {EntityEquipmentSlot.MAINHAND}); setName("examplemod.razor_edge"); setRegistryName(new ResourceLocation(ExampleMod.MOD_ID, "razor_edge")); }
@Override public int getMaxLevel() { return 3; }
// The enchanting table cost range. @Override public int getMinEnchantability(int level) { return 10 + 10 * (level - 1); }
@Override public int getMaxEnchantability(int level) { return getMinEnchantability(level) + 30; }
// Extra damage on every hit, added by vanilla's damage calculation. @Override public float calcDamageByCreature(int level, EnumCreatureAttribute type) { return level; } }}In src/main/resources/assets/examplemod/lang/en_us.json:
{ "enchantment.examplemod.razor_edge": "Razor Edge"}Sources
Section titled “Sources”Related how-tos
Section titled “Related how-tos”- Add an advancement
- A new dimension
- An enchantment that heals you (lifesteal)
- Define a damage type
- A crafting recipe
In Linen
Section titled “In Linen”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.