PaperMC · Doc94 · Jun 29, 2026 · Jul 2, 2026 · Jul 3, 2026 · Jul 3, 2026
@@ -147,17 +147,17 @@ public static HandlerList getHandlerList() {
     public enum Action {
 
         /**
-         * When the potion effect is added because the entity didn't have its
+         * When the potion effect is added because an entity didn't have its
          * type.
          */
         ADDED,
         /**
-         * When the entity already had the potion effect type, but the effect is
+         * When an entity already had the potion effect type, but the effect is
          * changed.
          */
         CHANGED,
         /**
-         * When the effect is removed due to all effects being removed.
+         * When the potion effect is removed as part of the removal of all effects.
          */
         CLEARED,
         /**
@@ -172,46 +172,76 @@ public enum Action {
     public enum Cause {
 
         /**
-         * When the entity stands inside an area effect cloud.
+         * When an entity stands inside an effect cloud.
          */
-        AREA_EFFECT_CLOUD,
+        EFFECT_CLOUD,
         /**
-         * When the entity is hit by a spectral or tipped arrow.
+         * When an entity is hit by a spectral or tipped arrow.
          */
         ARROW,
         /**
-         * When the entity is inflicted with a potion effect due to an entity
+         * When an entity is inflicted with a potion effect due to an entity
          * attack (e.g. a cave spider or a shulker bullet).
          */
         ATTACK,
+        /**
+         * When an entity gets a positive effect or a negative effect is removed as a gift made by another entity (like a dolphin or an axolotl).
+         */
+        ENTITY_GIFT,
         /**
          * When an entity gets the effect from an axolotl.
+         *
+         * @deprecated no longer used, use {@link #ENTITY_GIFT} and check the source with {@link #getSource()}
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         AXOLOTL,
         /**
-         * When beacon effects get applied due to the entity being nearby.
+         * When an entity plays dead (currently only for the axolotl).
+         */
+        FAKE_DEATH,
+        /**
+         * When an entity self consume an item.
+         */
+        SELF_CONSUME,
+        /**
+         * When an entity consume an item from another entity.
+         */
+        CONSUME_OTHER,
+        /**
+         * When beacon effects get applied due to an entity being nearby.
          */
         BEACON,
         /**
-         * When a potion effect is changed due to the /effect command.
+         * When an entity gets revealed because of a bell.
          */
-        COMMAND,
+        BELL,
+        /**
+         * When an entity comes in contact with a wither rose.
+         */
+        WITHER_ROSE,
+        /**
+         * When an entity comes in contact with an eye blossom.
+         */
+        EYE_BLOSSOM,
         /**
-         * When the entity gets the effect from a conduit.
+         * When an entity gets the effect from a conduit.
          */
         CONDUIT,
         /**
-         * When a conversion from a villager zombie to a villager is started or
-         * finished.
+         * When a conversion started or finished (e.g. a villager zombie to a villager) or a cube mob
+         * is split.
          */
         CONVERSION,
         /**
          * When all effects are removed due to death.
          */
         DEATH,
         /**
-         * When the entity gets the effect from a dolphin.
+         * When an entity gets the effect from a dolphin.
+         *
+         * @deprecated no longer used, use {@link #ENTITY_GIFT} and check the source with {@link #getSource()}
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         DOLPHIN,
         /**
          * When the effect was removed due to expiration.
@@ -220,20 +250,26 @@ public enum Cause {
         /**
          * When an effect is inflicted due to food (e.g. when a player eats or a
          * cookie is given to a parrot).
+         *
+         * @deprecated no longer used, use {@link #SELF_CONSUME} and check the item in hand if needed or {@link #CONSUME_OTHER}
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         FOOD,
         /**
          * When an illusion illager makes himself disappear.
          */
         ILLUSION,
         /**
          * When all effects are removed due to a bucket of milk.
+         *
+         * @deprecated no longer used, use {@link #SELF_CONSUME} and check the item in hand if needed
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         MILK,
         /**
-         * When the entity gets the effect from a nautilus.
+         * When an entity gets the effect from a nautilus.
          */
-        NAUTILUS,
+        NAUTILUS, // TODO: should be ENTITY_GIFT but for now the source is not set (see MC-309103)
         /**
          * When a player gets bad omen after killing a patrol captain.
          *
@@ -242,33 +278,41 @@ public enum Cause {
         @Deprecated(since = "1.21", forRemoval = true)
         PATROL_CAPTAIN,
         /**
-         * When a potion effect is modified through the plugin methods.
-         */
-        PLUGIN,
-        /**
-         * When the entity drinks a potion.
+         * When an entity drinks a potion.
+         *
+         * @deprecated no longer used,use {@link #SELF_CONSUME} and check the item in hand if needed
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         POTION_DRINK,
         /**
-         * When the entity is inflicted with an effect due to a splash potion.
+         * When an entity is inflicted with an effect due to a splash potion.
          */
         POTION_SPLASH,
+        /**
+         * When the effect is caused by a raid.
+         * For example when a player gets close to a village with {@link PotionEffectType#BAD_OMEN} and gets {@link PotionEffectType#RAID_OMEN}
+         * or the raid start or finish with a hero.
+         */
+        RAID,
+        /**
+         * When a player gets close to a trial spawner with {@link PotionEffectType#BAD_OMEN} and gets {@link PotionEffectType#TRIAL_OMEN}.
+         */
+        TRIAL_STARTED,
         /**
          * When a spider gets effects when spawning on hard difficulty.
          */
-        SPIDER_SPAWN,
+        SPIDER_SPAWN, // possibly move to a more generic ENTITY_SPAWN later
         /**
-         * When the entity gets effects from a totem item saving its life.
+         * When an entity gets effects from a totem item saving its life.
+         *
+         * @deprecated no longer used, use {@link #SELF_CONSUME} and check the used item in {@link EntityResurrectEvent}
          */
+        @Deprecated(since = "26.2", forRemoval = true)
         TOTEM,
         /**
-         * When the entity gets water breathing by wearing a turtle helmet.
+         * When an entity gets water breathing by wearing a turtle helmet.
          */
         TURTLE_HELMET,
-        /**
-         * When the Cause is missing.
-         */
-        UNKNOWN,
         /**
          * When a villager gets regeneration after a trade.
          */
@@ -278,8 +322,24 @@ public enum Cause {
          */
         WARDEN,
         /**
-         * When an entity comes in contact with a wither rose.
+         * When a potion effect is changed due to the /effect or /raid command.
+         */
+        COMMAND,
+        /**
+         * When a potion effect is modified through the plugin methods.
+         */
+        PLUGIN,
+        /**
+         * When the Cause is missing.
+         */
+        UNKNOWN;
+
+        /**
+         * When an entity stands inside an area effect cloud.
+         *
+         * @deprecated use {@link #EFFECT_CLOUD} and check the source with {@link #getSource()}
          */
-        WITHER_ROSE
+        @Deprecated(since = "26.2")
+        public static final Cause AREA_EFFECT_CLOUD = EFFECT_CLOUD;
     }
 }
@@ -0,0 +1,11 @@
+--- a/net/minecraft/server/commands/RaidCommand.java
++++ b/net/minecraft/server/commands/RaidCommand.java
+@@ -63,7 +_,7 @@
+         Raid raid = getRaid(source.getPlayerOrException());
+         if (raid != null) {
+             for (Raider raider : raid.getAllRaiders()) {
+-                raider.addEffect(new MobEffectInstance(MobEffects.GLOWING, 1000, 1));
++                raider.addEffect(new MobEffectInstance(MobEffects.GLOWING, 1000, 1), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.COMMAND); // Paper - Add effect cause
+             }
+         }
+
@@ -0,0 +1,11 @@
+--- a/net/minecraft/world/effect/BadOmenMobEffect.java
++++ b/net/minecraft/world/effect/BadOmenMobEffect.java
+@@ -24,7 +_,7 @@
+             && level.isVillage(player.blockPosition())) {
+             Raid raid = level.getRaidAt(player.blockPosition());
+             if (raid == null || raid.getRaidOmenLevel() < raid.getMaxRaidOmenLevel()) {
+-                player.addEffect(new MobEffectInstance(MobEffects.RAID_OMEN, 600, amplification));
++                player.addEffect(new MobEffectInstance(MobEffects.RAID_OMEN, 600, amplification), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.RAID); // Paper - Add effect cause
+                 player.setRaidOmenPosition(player.blockPosition());
+                 return false;
+             }
@@ -48,7 +48,7 @@
                                                      .applyInstantaneousEffect(serverLevel, this, this.getOwner(), entity, effect.getAmplifier(), 0.5);
                                              } else {
 -                                                entity.addEffect(new MobEffectInstance(effect), this);
-+                                                entity.addEffect(new MobEffectInstance(effect), this, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.AREA_EFFECT_CLOUD); // CraftBukkit
++                                                entity.addEffect(new MobEffectInstance(effect), this, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.EFFECT_CLOUD); // CraftBukkit
                                              }
                                          }
 

@@ -17,3 +17,12 @@
 
              ConversionType.convertCommon(from, to, params);
          }
+@@ -95,7 +_,7 @@
+         to.setAbsorptionAmount(from.getAbsorptionAmount());
+
+         for (MobEffectInstance effect : from.getActiveEffects()) {
+-            to.addEffect(new MobEffectInstance(effect));
++            to.addEffect(new MobEffectInstance(effect), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.CONVERSION); // Paper - Add effect cause
+         }
+
+         if (from.isBaby()) {
@@ -14,11 +14,11 @@
              int previousDuration = regenEffect != null ? regenEffect.getDuration() : 0;
              int regenDuration = Math.min(2400, 100 + previousDuration);
 -            player.addEffect(new MobEffectInstance(MobEffects.REGENERATION, regenDuration, 0), this);
-+            player.addEffect(new MobEffectInstance(MobEffects.REGENERATION, regenDuration, 0), this, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.AXOLOTL); // CraftBukkit
++            player.addEffect(new MobEffectInstance(MobEffects.REGENERATION, regenDuration, 0), this, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.ENTITY_GIFT); // CraftBukkit
          }
 
 -        player.removeEffect(MobEffects.MINING_FATIGUE);
-+        player.removeEffect(MobEffects.MINING_FATIGUE, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.AXOLOTL); // Paper - Add missing effect cause
++        player.removeEffect(MobEffects.MINING_FATIGUE, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.ENTITY_GIFT); // Paper - Add missing effect cause - TODO might pass the source later
      }
 
      @Override

@@ -0,0 +1,10 @@
+--- a/net/minecraft/world/entity/animal/axolotl/PlayDead.java
++++ b/net/minecraft/world/entity/animal/axolotl/PlayDead.java
+@@ -29,6 +_,6 @@
+         Brain<Axolotl> brain = body.getBrain();
+         brain.eraseMemory(MemoryModuleType.WALK_TARGET);
+         brain.eraseMemory(MemoryModuleType.LOOK_TARGET);
+-        body.addEffect(new MobEffectInstance(MobEffects.REGENERATION, 200, 0));
++        body.addEffect(new MobEffectInstance(MobEffects.REGENERATION, 200, 0), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.FAKE_DEATH); // Paper - Add effect cause
+     }
+ }
@@ -84,7 +84,7 @@
                  this.usePlayerItem(player, hand, heldItem);
                  if (!this.level().isClientSide()) {
 -                    this.addEffect(effect);
-+                    this.addEffect(effect, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.FOOD); // Paper - Add missing effect cause
++                    this.addEffect(effect, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.CONSUME_OTHER); // Paper - Add missing effect cause
                  }
 
                  return InteractionResult.SUCCESS;

@@ -45,7 +45,7 @@
          @Override
          public void start() {
 -            this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin);
-+            this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.DOLPHIN); // CraftBukkit
++            this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.ENTITY_GIFT); // CraftBukkit
          }
 
          @Override
@@ -54,7 +54,7 @@
 
              if (this.player.isSwimming() && this.player.level().getRandom().nextInt(6) == 0) {
 -                this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin);
-+                this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.DOLPHIN); // CraftBukkit
++                this.player.addEffect(new MobEffectInstance(MobEffects.DOLPHINS_GRACE, 100), this.dolphin, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.ENTITY_GIFT); // CraftBukkit
              }
          }
      }

@@ -14,7 +14,7 @@
          } else {
              this.usePlayerItem(player, hand, itemStack);
 -            this.addEffect(new MobEffectInstance(MobEffects.POISON, 900));
-+            this.addEffect(new MobEffectInstance(MobEffects.POISON, 900), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.FOOD); // CraftBukkit
++            this.addEffect(new MobEffectInstance(MobEffects.POISON, 900), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.CONSUME_OTHER); // CraftBukkit
              if (player.isCreative() || !this.isInvulnerable()) {
                  this.hurt(this.damageSources().playerAttack(player), Float.MAX_VALUE);
              }

@@ -7,7 +7,7 @@
 -        this.convertTo(
 -            EntityTypes.ZOGLIN, ConversionParams.single(this, true, false), zoglin -> zoglin.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0))
 +        final Entity converted = this.convertTo( // Paper - Fix issues with mob conversion; reset to prevent event spam
-+            EntityTypes.ZOGLIN, ConversionParams.single(this, true, false), zoglin -> {zoglin.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0));}, org.bukkit.event.entity.EntityTransformEvent.TransformReason.PIGLIN_ZOMBIFIED, org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason.PIGLIN_ZOMBIFIED // CraftBukkit - add spawn and transform reasons
++            EntityTypes.ZOGLIN, ConversionParams.single(this, true, false), zoglin -> {zoglin.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.CONVERSION);}, org.bukkit.event.entity.EntityTransformEvent.TransformReason.PIGLIN_ZOMBIFIED, org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason.PIGLIN_ZOMBIFIED // CraftBukkit - add spawn and transform reasons // Paper - Add effect cause
          );
 +        // Paper start - Fix issues with mob conversion; reset to prevent event spam
 +        if (converted == null) {

@@ -9,7 +9,7 @@
              EntityTypes.ZOMBIFIED_PIGLIN,
              ConversionParams.single(this, true, true),
 -            zombified -> zombified.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0))
-+            zombified -> {zombified.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0));}, org.bukkit.event.entity.EntityTransformEvent.TransformReason.PIGLIN_ZOMBIFIED, org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason.PIGLIN_ZOMBIFIED // CraftBukkit - add spawn and transform reasons
++            zombified -> {zombified.addEffect(new MobEffectInstance(MobEffects.NAUSEA, 200, 0), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.CONVERSION);}, org.bukkit.event.entity.EntityTransformEvent.TransformReason.PIGLIN_ZOMBIFIED, org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason.PIGLIN_ZOMBIFIED // CraftBukkit - add spawn and transform reasons // Paper - Add effect cause
          );
 +        // Paper start - Fix issues with mob conversion; reset to prevent event spam
 +        if (converted == null) {

@@ -92,15 +92,16 @@
                          this.stop();
                          break;
                      }
-@@ -397,6 +_,7 @@
+@@ -397,16 +_,19 @@
                      } else {
                          this.status = Raid.RaidStatus.VICTORY;
 
 +                        List<org.bukkit.entity.Player> winners = new java.util.ArrayList<>(); // CraftBukkit
                          for (UUID heroUUID : this.heroesOfTheVillage) {
                              Entity entity = level.getEntity(heroUUID);
                              if (entity instanceof LivingEntity hero && !entity.isSpectator()) {
-@@ -404,9 +_,11 @@
+-                                hero.addEffect(new MobEffectInstance(MobEffects.HERO_OF_THE_VILLAGE, 48000, this.raidOmenLevel - 1, false, false, true));
++                                hero.addEffect(new MobEffectInstance(MobEffects.HERO_OF_THE_VILLAGE, 48000, this.raidOmenLevel - 1, false, false, true), org.bukkit.event.entity.EntityPotionEffectEvent.Cause.RAID); // Paper - Add effect cause
                                  if (hero instanceof ServerPlayer playerHero) {
                                      playerHero.awardStat(Stats.RAID_WIN);
                                      CriteriaTriggers.RAID_WIN.trigger(playerHero);

@@ -25,7 +25,7 @@
 +        if (!raid.isStarted() || (raid.isInProgress() && raid.getRaidOmenLevel() < raid.getMaxRaidOmenLevel())) { // CraftBukkit - fixed a bug with raid: players could add up Bad Omen level even when the raid had finished
 +            // CraftBukkit start
 +            if (!org.bukkit.craftbukkit.event.CraftEventFactory.callRaidTriggerEvent(level, raid, player)) {
-+                player.removeEffect(net.minecraft.world.effect.MobEffects.RAID_OMEN);
++                player.removeEffect(net.minecraft.world.effect.MobEffects.RAID_OMEN, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.RAID); // Paper - Add effect cause
 +                return null;
 +            }
 +

@@ -5,7 +5,7 @@
                      effect.getEffect().value().applyInstantaneousEffect(serverLevel, player, player, entity, effect.getAmplifier(), 1.0);
                  } else {
 -                    entity.addEffect(effect);
-+                    entity.addEffect(effect, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.POTION_DRINK); // CraftBukkit
++                    entity.addEffect(effect, org.bukkit.event.entity.EntityPotionEffectEvent.Cause.SELF_CONSUME); // CraftBukkit
                  }
              }, durationScale);
          }