feat: introduce player reset events for inventory, health, hunger, experience, money, and tamed entities

Author: tastybento

build.gradle.kts

@@ -46,7 +46,7 @@ paperweight.reobfArtifactConfiguration = io.papermc.paperweight.userdev.ReobfArt
 group = "world.bentobox" // From <groupId>
 
 // Base properties from <properties>
-val buildVersion = "3.16.2"
+val buildVersion = "3.17.0"
 val buildNumberDefault = "-LOCAL" // Local build identifier
 val snapshotSuffix = "-SNAPSHOT"  // Indicates development/snapshot version
 

src/main/java/world/bentobox/bentobox/api/events/player/PlayerBaseEvent.java

@@ -0,0 +1,60 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import org.bukkit.event.Cancellable;
+import world.bentobox.bentobox.api.events.BentoBoxEvent;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * @author tastybento
+ */
+public abstract class PlayerBaseEvent extends BentoBoxEvent implements Cancellable {
+    private boolean cancelled;
+
+    protected final Island island;
+    protected final UUID playerUUID;
+    protected final World world;
+
+    public PlayerBaseEvent(UUID playerUUID, Island island, World world) {
+        super();
+        this.playerUUID = playerUUID;
+        this.world = world;
+        this.island = island;
+    }
+
+    /**
+     * @return the island involved in this event. This may be null if the event is not related to an island
+     * or if the island has been deleted.
+     */
+    public Island getIsland() {
+        return island;
+    }
+
+    /**
+     * Get the world involved in this event.
+     * @return world
+     */
+    public World getWorld() {
+        return world;
+    }
+
+    /**
+     * @return the playerUUID
+     */
+    public UUID getPlayerUUID() {
+        return playerUUID;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(boolean cancel) {
+        cancelled = cancel;
+    }
+
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerEvent.java

@@ -0,0 +1,89 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.Bukkit;
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player event happens.
+ *
+ * @author tastybento
+ */
+public class PlayerEvent {
+
+    public enum Reason {
+        INVENTORY_RESET,
+        TAMED_REMOVAL,
+        ENDERCHEST_RESET,
+        MONEY_RESET,
+        HEALTH_RESET,
+        HUNGER_RESET,
+        EXP_RESET,
+        UNKNOWN
+    }
+
+    public static PlayerEventBuilder builder() {
+        return new PlayerEventBuilder();
+    }
+
+    public static class PlayerEventBuilder {
+        private World world;
+        private UUID player;
+        private Island island;
+        private Reason reason = Reason.UNKNOWN;
+
+        public PlayerEventBuilder world(World world) {
+            this.world = world;
+            return this;
+        }
+
+        public PlayerEventBuilder island(Island island) {
+            this.island = island;
+            return this;
+        }
+
+        /**
+         * @param reason for the event
+         * @return TeamEventBuilder
+         */
+        public PlayerEventBuilder reason(Reason reason) {
+            this.reason = reason;
+            return this;
+        }
+
+        /**
+         * @param player - the player involved in the event
+         * @return TeamEventBuilder
+         */
+        public PlayerEventBuilder involvedPlayer(UUID player) {
+            this.player = player;
+            return this;
+        }
+
+        private PlayerBaseEvent getEvent() {
+            return switch (reason) {
+            case INVENTORY_RESET -> new PlayerResetInventoryEvent(world, island, player);
+            case TAMED_REMOVAL -> new PlayerTamedRemovalEvent(world, island, player);
+            case ENDERCHEST_RESET -> new PlayerResetEnderChestEvent(world, island, player);
+            case MONEY_RESET -> new PlayerResetMoneyEvent(world, island, player);
+            case HEALTH_RESET -> new PlayerResetHealthEvent(world, island, player);
+            case HUNGER_RESET -> new PlayerResetHungerEvent(world, island, player);
+            case EXP_RESET -> new PlayerResetExpEvent(world, island, player);
+            case UNKNOWN -> new PlayerUnknownEvent(world, island, player);
+            };
+        }
+
+        /**
+         * Build the event and call it
+         * @return event
+         */
+        public PlayerBaseEvent build() {
+            // Generate new event
+            PlayerBaseEvent newEvent = getEvent();
+            Bukkit.getPluginManager().callEvent(newEvent);
+            return newEvent;
+        }
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetEnderChestEvent.java

@@ -0,0 +1,29 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's ender chest is cleared as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the ender chest contents will not be cleared.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetEnderChestEvent extends PlayerBaseEvent {
+
+    /**
+     * Constructs a new PlayerResetEnderChestEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose ender chest is being cleared
+     */
+    public PlayerResetEnderChestEvent(World world, Island island, UUID player) {
+        super(player, island, world);
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetExpEvent.java

@@ -0,0 +1,29 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's experience (XP) is reset as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the player's experience will not be cleared.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetExpEvent extends PlayerBaseEvent {
+
+    /**
+     * Constructs a new PlayerResetExpEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose experience is being reset
+     */
+    public PlayerResetExpEvent(World world, Island island, UUID player) {
+        super(player, island, world);
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetHealthEvent.java

@@ -0,0 +1,29 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's health is reset to the maximum value as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the player's health will not be reset.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetHealthEvent extends PlayerBaseEvent {
+
+    /**
+     * Constructs a new PlayerResetHealthEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose health is being reset
+     */
+    public PlayerResetHealthEvent(World world, Island island, UUID player) {
+        super(player, island, world);
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetHungerEvent.java

@@ -0,0 +1,29 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's hunger (food level) is reset to the maximum value as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the player's hunger will not be reset.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetHungerEvent extends PlayerBaseEvent {
+
+    /**
+     * Constructs a new PlayerResetHungerEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose hunger is being reset
+     */
+    public PlayerResetHungerEvent(World world, Island island, UUID player) {
+        super(player, island, world);
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetInventoryEvent.java

@@ -0,0 +1,56 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import org.bukkit.event.HandlerList;
+import org.eclipse.jdt.annotation.NonNull;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's inventory is cleared as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the player's inventory will not be cleared.
+ * This is the only reset event that exposes a {@link HandlerList}, making it the canonical
+ * example for the reset-event family.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetInventoryEvent extends PlayerBaseEvent {
+
+    private static final HandlerList handlers = new HandlerList();
+
+    /**
+     * Returns the list of handlers registered for this event type.
+     *
+     * @return the handler list
+     */
+    @Override
+    public @NonNull HandlerList getHandlers() {
+        return getHandlerList();
+    }
+
+    /**
+     * Returns the static handler list for this event type.
+     * Required by Bukkit's event system so that handlers can be looked up by class.
+     *
+     * @return the static handler list
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    /**
+     * Constructs a new PlayerResetInventoryEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose inventory is being cleared
+     */
+    public PlayerResetInventoryEvent(World world, Island island, UUID player) {
+        // Final variables have to be declared in the constructor
+        super(player, island, world);
+    }
+}

src/main/java/world/bentobox/bentobox/api/events/player/PlayerResetMoneyEvent.java

@@ -0,0 +1,31 @@
+package world.bentobox.bentobox.api.events.player;
+
+import org.bukkit.World;
+import world.bentobox.bentobox.database.objects.Island;
+
+import java.util.UUID;
+
+/**
+ * Fired when a player's in-game money balance is reset to zero (or to the configured starting
+ * amount) as part of an island reset.
+ * <p>
+ * This event is cancellable. If cancelled, the player's balance will not be reset.
+ * Requires an economy plugin (e.g. Vault) to be present for the underlying action to take effect.
+ * </p>
+ *
+ * @author tastybento
+ * @see PlayerBaseEvent
+ */
+public class PlayerResetMoneyEvent extends PlayerBaseEvent {
+
+    /**
+     * Constructs a new PlayerResetMoneyEvent.
+     *
+     * @param world  the world in which the reset is occurring
+     * @param island the island being reset, or {@code null} if not applicable
+     * @param player the UUID of the player whose balance is being reset
+     */
+    public PlayerResetMoneyEvent(World world, Island island, UUID player) {
+        super(player, island, world);
+    }
+}