Custom Potion Effects (MultiLoader 1.21+)

Mob effects (status effects) are the timed buffs and debuffs applied by potions, beacons, and enchantments. In 1.21.1 the effect system is split into two separate registries: the MobEffect registry holds the effect type and its logic, while the Potion registry holds named combinations of effects and durations that can be applied by potion items. This tutorial creates a custom healing effect, a potion that applies it, and registers brewing recipes on both loaders.

The Effect Class

Create an ExampleEffect class in an effect package inside your common project. Extend MobEffect and override the two tick methods:

java

public class ExampleEffect extends MobEffect {
    public ExampleEffect() {
        super(
            MobEffectCategory.BENEFICIAL,  // BENEFICIAL (blue), HARMFUL (red), NEUTRAL (grey)
            0x5C8CFF                        // particle and icon border colour as an RGB integer
        );
    }
    @Override
    public boolean applyEffectTick(LivingEntity entity, int amplifier) {
        if (!entity.level().isClientSide()) {
            // amplifier is 0-based: level I = 0, level II = 1, level III = 2
            float healAmount = 1.0f + amplifier;
            if (entity.getHealth() < entity.getMaxHealth()) {
                entity.heal(healAmount);
            }
        }
        return true; // returning false removes the effect immediately
    }
    @Override
    public boolean shouldApplyEffectTickThisTick(int duration, int amplifier) {
        // Apply every (40 >> amplifier) ticks: level I every 40 ticks, level II every 20, etc.
        int interval = Math.max(1, 40 >> amplifier);
        return duration % interval == 0;
    }
}

MobEffectCategory controls the colour of the effect icon border and the potion colour:

BENEFICIAL: Blue icon border. Used for Speed, Regeneration, Strength.
HARMFUL: Red icon border. Used for Poison, Weakness, Blindness.
NEUTRAL: Grey icon border. Used for Night Vision, Water Breathing.

shouldApplyEffectTickThisTick is called every game tick while the effect is active. Returning false skips the applyEffectTick call for that tick. This is important for performance: an effect that heals every tick would apply 20 times per second on every living entity carrying it. Spacing applications out with the bit-shift trick ( 40 >> amplifier) halves the interval for each amplifier level, matching the vanilla Regeneration pattern.

TIP

Returning false from applyEffectTick removes the effect from the entity immediately. This is useful for one-shot effects that should self-remove after applying (for example, an instant-heal effect). For ongoing effects that simply tick less often, always return true.

Effect Registry

Create an EffectRegistry class in your common registry package:

java

public class EffectRegistry {
    public static final RegistrationProvider<MobEffect> MOB_EFFECTS =
            RegistrationProvider.get(Registries.MOB_EFFECT, Constants.MOD_ID);
    public static final RegistryObject<MobEffect, ExampleEffect> EXAMPLE_EFFECT =
            MOB_EFFECTS.register("example_effect", ExampleEffect::new);
    public static void init() {}
}

Call EffectRegistry.init() from CommonClass.init():

java

public class CommonClass {
    public static void init() {
        EffectRegistry.init();
        // ... other registries
    }
}

Effects must be registered before potions because the MobEffectInstance constructor in 1.21.1 takes a Holder<MobEffect>, which is resolved from the registry at registration time.

NOTE

Remember to add your effect icon texture in common/src/main/resources/assets/examplemod/textures/mob_effect, with the PNG file of the texture having a size of 18x18. Since we called our effect in the registry example_effect, that is the name of our PNG file.

Attribute Modifiers

Some effects permanently modify an entity's attributes while active (Speed increases movement speed, Strength increases attack damage). Add attribute modifiers in the ExampleEffect constructor by calling addAttributeModifier. Each modifier needs a stable ResourceLocation ID so it can be correctly removed when the effect expires:

java

public ExampleEffect() {
    super(MobEffectCategory.BENEFICIAL, 0x5C8CFF);
    // Increase max health by 2 per amplifier level while the effect is active
    addAttributeModifier(
        Attributes.MAX_HEALTH,
        ResourceLocation.fromNamespaceAndPath(Constants.MOD_ID, "example_effect.max_health"),
        2.0,
        AttributeModifier.Operation.ADD_VALUE
    );
}

Operation.ADD_VALUE adds a flat amount per amplifier level. Operation.ADD_MULTIPLIED_BASE multiplies the base attribute value before other modifiers, and Operation.ADD_MULTIPLIED_TOTAL multiplies the final value after all other modifiers. The vanilla Speed effect uses ADD_MULTIPLIED_BASE so higher levels multiply more aggressively. Use a unique ResourceLocation ID for each modifier to avoid clashes with vanilla or other mods.

Custom Potion

A Potion is a named collection of MobEffectInstance objects. Create one that applies your effect for 45 seconds (900 ticks) at level I. In 1.21.1, MobEffectInstance takes a Holder<MobEffect> rather than the raw effect, which is obtained from the RegistryObject via asHolder():

java

// This code goes in PotionRegistry, not here directly
// See the next section for the full registry class
new Potion(
    new MobEffectInstance(
        EffectRegistry.EXAMPLE_EFFECT.asHolder(),  // Holder<MobEffect>
        900,   // duration in ticks (900 = 45 seconds)
        0      // amplifier: 0 = level I, 1 = level II, etc.
    )
)

Potion duration is always specified in ticks (20 ticks per second). The amplifier is zero-indexed: amplifier 0 displays as "Level I", amplifier 1 displays as "Level II", and so on. You can pass multiple MobEffectInstance arguments to a single Potion to create a potion that applies several effects simultaneously, like vanilla's "Turtle Master" potion.

Potion Registry

Create a PotionRegistry class in your common registry package. Register both a normal-strength and a strong variant:

java

public class PotionRegistry {
    public static final RegistrationProvider<Potion> POTIONS =
            RegistrationProvider.get(Registries.POTION, Constants.MOD_ID);
    public static final RegistryObject<Potion, Potion> EXAMPLE_POTION =
            POTIONS.register("example",
                () -> new Potion(
                    new MobEffectInstance(EffectRegistry.EXAMPLE_EFFECT.asHolder(), 900, 0)));
    public static final RegistryObject<Potion, Potion> EXAMPLE_POTION_STRONG =
            POTIONS.register("strong_example",
                () -> new Potion(
                    new MobEffectInstance(EffectRegistry.EXAMPLE_EFFECT.asHolder(), 450, 1)));
    public static void init() {}
}

Call PotionRegistry.init() from CommonClass.init() after EffectRegistry.init(), since the potion suppliers reference the effect holder.

NOTE

The registry name is used as the translation key suffix. A potion registered as "example" generates the translation key item.minecraft.potion.effect.example for the normal potion item and item.minecraft.splash_potion.effect.example for the splash variant. Add entries for all four item types (potion, splash_potion, lingering_potion, tipped_arrow) in your lang file.

Brewing Recipes

Brewing recipes associate an input potion, a brewing ingredient, and an output potion. In 1.21.1 the brewing recipe registry is loader-specific, so the registration must be split between the two subprojects.

On NeoForge, register using RegisterBrewingRecipesEventon the game bus. The event provides a PotionBrewing.Builder that accepts ingredient-to-potion and potion-to-potion recipes. Let's do this in our existing ExampleEvents class:

java

@EventBusSubscriber(modid = Constants.MOD_ID, bus = EventBusSubscriber.Bus.GAME)
public class ExampleEvents {
    // Our previous event methods
    @SubscribeEvent
    public static void register(RegisterBrewingRecipesEvent event) {
        PotionBrewing.Builder builder = event.getBuilder();
        // Awkward Potion + Glistering Melon Slice = Example Potion
        builder.addMix(
            Potions.AWKWARD,
            Items.GLISTERING_MELON_SLICE,
            PotionRegistry.EXAMPLE_POTION.asHolder()
        );
        // Example Potion + Glowstone Dust = Strong Example Potion
        builder.addMix(
            PotionRegistry.EXAMPLE_POTION.asHolder(),
            Items.GLOWSTONE_DUST,
            PotionRegistry.EXAMPLE_POTION_STRONG.asHolder()
        );
    }
}

On Fabric, use FabricBrewingRecipeRegistryBuilder from the Fabric API module fabric-brewing-recipe-registry-api-v1:

java

public class ExampleMod implements ModInitializer {
    @Override
    public void onInitialize() {
        ExampleConfig.setInstance(FabricExampleConfig.load());
        CommonClass.init();
        // Our other things
        registerBrewingRecipes(); // This is new!
    }
    // Our other methods are here...
    private static void registerBrewingRecipes() {
        FabricBrewingRecipeRegistryBuilder.BUILD.register(builder -> {
            builder.addMix(
                Potions.AWKWARD,
                Items.GLISTERING_MELON_SLICE,
                PotionRegistry.EXAMPLE_POTION.asHolder()
            );
            builder.addMix(
                PotionRegistry.EXAMPLE_POTION.asHolder(),
                Items.GLOWSTONE_DUST,
                PotionRegistry.EXAMPLE_POTION_STRONG.asHolder()
            );
        });
    }
}

TIP

The ingredient in addMix is compared by item identity, not by tag. If you want to accept any item in a tag (for example, any type of melon), create a custom Ingredient and use the overload of addMix that accepts an Ingredient instead of an Item.

Lang Entries

Add translation entries for the effect name and all four potion item types into the lang generator. All four item keys (potion, splash, lingering, tipped arrow) share the same suffix but differ in prefix:

json

add("effect.examplemod.example_effect", "Vitality");
        
add("item.minecraft.potion.effect.example", "Potion of Vitality");
add("item.minecraft.splash_potion.effect.example", "Splash Potion of Vitality");
add("item.minecraft.lingering_potion.effect.example", "Lingering Potion of Vitality");
add("item.minecraft.tipped_arrow.effect.example", "Arrow of Vitality");
add("item.minecraft.potion.effect.strong_example", "Potion of Vitality II");
add("item.minecraft.splash_potion.effect.strong_example", "Splash Potion of Vitality II");
add("item.minecraft.lingering_potion.effect.strong_example", "Lingering Potion of Vitality II");
add("item.minecraft.tipped_arrow.effect.strong_example", "Arrow of Vitality II");

The effect translation key uses your mod ID as the namespace: effect.examplemod.example_effect. The potion item keys use minecraft as the namespace because those are vanilla items; only the suffix after effect. is your registry name.

Testing

Run /effect give @s examplemod:example_effect 60 0 to apply the effect for 60 seconds at level I. Open the inventory and confirm the effect icon appears with a blue border and the name "Vitality". Monitor your health bar to confirm the healing tick fires approximately every two seconds.

To test brewing, switch to survival mode, place a brewing stand, add Blaze Powder as fuel, put Awkward Potions in the three bottom slots, and add a Glistering Melon Slice to the top slot. After brewing completes, the potions should change to "Potion of Vitality". Brew a second time with Glowstone Dust to confirm the strong variant is produced.

Use /give @s potion[minecraft:potion_contents="examplemod:example"] in a creative world to skip the brewing step during testing.

You can find the source for this tutorial here:

View Source on GitHub

NEXT IN SERIES

Custom Enchantments (MultiLoader 1.21+)

Understand the 1.21 data-driven enchantment overhaul, write an enchantment JSON using built-in post_attack and apply_mob_effect components, generate it with DatapackBuiltinEntriesProvider, and optionally implement a custom EnchantmentEntityEffect codec for novel behaviour.

Continue →