Add EntityEquipmentChangedEvent (#12011)

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerArmorChangeEvent.java

@@ -5,6 +5,7 @@ import org.bukkit.Material;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
+import org.bukkit.inventory.EquipmentSlot;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
@@ -16,8 +17,10 @@ import static org.bukkit.Material.*;
  * Called when the player themselves change their armor items
  * <p>
  * Not currently called for environmental factors though it <strong>MAY BE IN THE FUTURE</strong>
+ * @apiNote Use {@link io.papermc.paper.event.entity.EntityEquipmentChangedEvent} for all entity equipment changes
  */
 @NullMarked
+@ApiStatus.Obsolete(since = "1.21.4")
 public class PlayerArmorChangeEvent extends PlayerEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -38,11 +41,27 @@ public class PlayerArmorChangeEvent extends PlayerEvent {
      * Gets the type of slot being altered.
      *
      * @return type of slot being altered
+     * @deprecated {@link SlotType} does not accurately represent what item types are valid in each slot. Use {@link #getSlot()} instead.
      */
+    @Deprecated(since = "1.21.4")
     public SlotType getSlotType() {
         return this.slotType;
     }
 
+    /**
+     * Gets the slot being altered.
+     *
+     * @return slot being altered
+     */
+    public EquipmentSlot getSlot() {
+        return switch (this.slotType) {
+            case HEAD -> EquipmentSlot.HEAD;
+            case CHEST -> EquipmentSlot.CHEST;
+            case LEGS -> EquipmentSlot.LEGS;
+            case FEET -> EquipmentSlot.FEET;
+        };
+    }
+
     /**
      * Gets the existing item that's being replaced
      *
@@ -70,6 +89,10 @@ public class PlayerArmorChangeEvent extends PlayerEvent {
         return HANDLER_LIST;
     }
 
+    /**
+     * @deprecated {@link SlotType} does not accurately represent what item types are valid in each slot.
+     */
+    @Deprecated(since = "1.21.4")
     public enum SlotType {
         HEAD(NETHERITE_HELMET, DIAMOND_HELMET, GOLDEN_HELMET, IRON_HELMET, CHAINMAIL_HELMET, LEATHER_HELMET, CARVED_PUMPKIN, PLAYER_HEAD, SKELETON_SKULL, ZOMBIE_HEAD, CREEPER_HEAD, WITHER_SKELETON_SKULL, TURTLE_HELMET, DRAGON_HEAD, PIGLIN_HEAD),
         CHEST(NETHERITE_CHESTPLATE, DIAMOND_CHESTPLATE, GOLDEN_CHESTPLATE, IRON_CHESTPLATE, CHAINMAIL_CHESTPLATE, LEATHER_CHESTPLATE, ELYTRA),

paper-api/src/main/java/io/papermc/paper/event/entity/EntityEquipmentChangedEvent.java

@@ -0,0 +1,89 @@
+package io.papermc.paper.event.entity;
+
+import java.util.Collections;
+import java.util.Map;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.inventory.EquipmentSlot;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called whenever a change to an entity's equipment has been detected. This event is called after effects from
+ * attribute modifiers and enchantments have been updated.
+ * <p>
+ * Examples of actions that can trigger this event:
+ * <ul>
+ *     <li>An entity being added to a world.</li>
+ *     <li>A player logging in.</li>
+ *     <li>The durability of an equipment item changing.</li>
+ *     <li>A dispenser equipping an item onto an entity.</li>
+ *     <li>An entity picking up an armor or weapon item from the ground.</li>
+ *     <li>A player changing their equipped armor.</li>
+ *     <li>A player changes their currently held item.</li>
+ * </ul>
+ */
+@NullMarked
+public class EntityEquipmentChangedEvent extends EntityEvent {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Map<EquipmentSlot, EquipmentChange> equipmentChanges;
+
+    @ApiStatus.Internal
+    public EntityEquipmentChangedEvent(final LivingEntity entity, final Map<EquipmentSlot, EquipmentChange> equipmentChanges) {
+        super(entity);
+
+        this.equipmentChanges = equipmentChanges;
+    }
+
+    @Override
+    public LivingEntity getEntity() {
+        return (LivingEntity) this.entity;
+    }
+
+    /**
+     * Gets a map of changed slots to their respective equipment changes.
+     *
+     * @return the equipment changes map
+     */
+    public @Unmodifiable Map<EquipmentSlot, EquipmentChange> getEquipmentChanges() {
+        return Collections.unmodifiableMap(this.equipmentChanges);
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+
+    /**
+     * Represents a change in equipment for a single equipment slot.
+     */
+    @ApiStatus.NonExtendable
+    public interface EquipmentChange {
+
+        /**
+         * Gets the existing item that is being replaced.
+         *
+         * @return the existing item
+         */
+        @Contract(pure = true, value = "-> new")
+        ItemStack oldItem();
+
+        /**
+         * Gets the new item that is replacing the existing item.
+         *
+         * @return the new item
+         */
+        @Contract(pure = true, value = "-> new")
+        ItemStack newItem();
+    }
+}