Status effects, also known as effects, are a condition that can affect an entity. They can be positive, negative or neutral in nature. The base game applies these effects in various ways such as food, potions etc.

The /effect command can be used to apply effects on an entity.

Custom Status Effects

In this tutorial we'll add a new custom effect called Tater which gives you one experience point every game tick.

Extend StatusEffect

Let's create a custom effect class by extending StatusEffect, which is the base class for all effects.

public class TaterEffect extends StatusEffect {
	protected TaterEffect() {
		// category: StatusEffectCategory - describes if the effect is helpful (BENEFICIAL), harmful (HARMFUL) or useless (NEUTRAL)
		// color: int - Color is the color assigned to the effect (in RGB)
		super(StatusEffectCategory.BENEFICIAL, 0xe9b8b3);
	}

	// Called every tick to check if the effect can be applied or not
	@Override
	public boolean canApplyUpdateEffect(int duration, int amplifier) {
		// In our case, we just make it return true so that it applies the effect every tick
		return true;
	}

	// Called when the effect is applied.
	@Override
	public boolean applyUpdateEffect(LivingEntity entity, int amplifier) {
		if (entity instanceof PlayerEntity) {
			((PlayerEntity) entity).addExperience(1 << amplifier); // Higher amplifier gives you experience faster
		}

		return super.applyUpdateEffect(entity, amplifier);
	}
}

Registering Your Custom Effect

Similar to block and item registration, we use Registry.register to register our custom effect into the STATUS_EFFECT registry. This can be done in our initializer.

public class ExampleModEffects implements ModInitializer {
	public static final RegistryEntry<StatusEffect> TATER;

	static {
		TATER = Registry.registerReference(Registries.STATUS_EFFECT, Identifier.of("example-mod", "tater"), new TaterEffect());
	}

	@Override
	public void onInitialize() {
		// ...
	}
}

Texture

The status effect icon is a 18x18 PNG which will appear in the player's inventory screen. Place your custom icon in:

resources/assets/example-mod/textures/mob_effect/tater.png

Download Example Texture

Translations

Like any other translation, you can add an entry with ID format "effect.example-mod.<effect-identifier>": "Value" to the language file.

{
  "effect.example-mod.tater": "Tater"
}

Applying The Effect

It's worth taking a look at how you'd typically apply an effect to an entity.

TIP

For a quick test, it might be a better idea to use the previously mentioned /effect command:

effect give @p example-mod:tater

To apply an effect internally, you'd want to use the LivingEntity#addStatusEffect method, which takes in a StatusEffectInstance, and returns a boolean, specifying whether the effect was successfully applied.

var instance = new StatusEffectInstance(ExampleModEffects.TATER, 5 * 20, 0, false, true, true);
entity.addStatusEffect(instance);

Argument	Type	Description
effect	RegistryEntry<StatusEffect>	A registry entry that represents the effect.
duration	int	The duration of the effect in ticks; not seconds
amplifier	int	The amplifier to the level of the effect. It doesn't correspond to the level of the effect, but is rather added on top. Hence, amplifier of 4 => level of 5
ambient	boolean	This is a tricky one. It basically specifies that the effect was added by the environment (e.g. a Beacon) and doesn't have a direct cause. If true, the icon of the effect in the HUD will appear with an aqua overlay.
particles	boolean	Whether to show particles.
icon	boolean	Whether to display an icon of the effect in the HUD. The effect will be displayed in the inventory regardless of this flag.

INFO

To create a potion that uses this effect, please see the Potions guide.