Add UserTeleportHomeEvent (#3403)

Adds an event which allows developers to see & cancel when users attempt to teleport home. This event is needed over `PreTeleportEvent` due to the fact that it would be extremely difficult to accurately filter it by the /home command.

Closes #3401

Essentials/src/com/earth2me/essentials/commands/Commandhome.java

@@ -5,6 +5,7 @@ import com.earth2me.essentials.Trade;
 import com.earth2me.essentials.User;
 import com.earth2me.essentials.utils.StringUtil;
 import io.papermc.lib.PaperLib;
+import net.ess3.api.events.UserTeleportHomeEvent;
 import org.bukkit.Location;
 import org.bukkit.Server;
 import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
@@ -48,6 +49,11 @@ public class Commandhome extends EssentialsCommand {
                 PaperLib.getBedSpawnLocationAsync(player.getBase(), true).thenAccept(location -> {
                     CompletableFuture<Boolean> future = getNewExceptionFuture(user.getSource(), commandLabel);
                     if (location != null) {
+                        UserTeleportHomeEvent event = new UserTeleportHomeEvent(user, "bed", location, UserTeleportHomeEvent.HomeType.BED);
+                        server.getPluginManager().callEvent(event);
+                        if (event.isCancelled()) {
+                            return;
+                        }
                         future.thenAccept(success -> {
                             if (success) {
                                 user.sendMessage(tl("teleportHome", "bed"));
@@ -68,7 +74,11 @@ public class Commandhome extends EssentialsCommand {
                 final List<String> homes = finalPlayer.getHomes();
                 if (homes.isEmpty() && finalPlayer.equals(user)) {
                     if (ess.getSettings().isSpawnIfNoHome()) {
-                        user.getAsyncTeleport().respawn(charge, TeleportCause.COMMAND, getNewExceptionFuture(user.getSource(), commandLabel));
+                        UserTeleportHomeEvent event = new UserTeleportHomeEvent(user, null, bed != null ? bed : finalPlayer.getWorld().getSpawnLocation(), bed != null ? UserTeleportHomeEvent.HomeType.BED : UserTeleportHomeEvent.HomeType.SPAWN);
+                        server.getPluginManager().callEvent(event);
+                        if (!event.isCancelled()) {
+                            user.getAsyncTeleport().respawn(charge, TeleportCause.COMMAND, getNewExceptionFuture(user.getSource(), commandLabel));
+                        }
                     } else {
                         showError(user.getBase(), new Exception(tl("noHomeSetPlayer")), commandLabel);
                     }
@@ -121,12 +131,16 @@ public class Commandhome extends EssentialsCommand {
         if (user.getWorld() != loc.getWorld() && ess.getSettings().isWorldHomePermissions() && !user.isAuthorized("essentials.worlds." + loc.getWorld().getName())) {
             throw new Exception(tl("noPerm", "essentials.worlds." + loc.getWorld().getName()));
         }
-        user.getAsyncTeleport().teleport(loc, charge, TeleportCause.COMMAND, future);
-        future.thenAccept(success -> {
-            if (success) {
-                user.sendMessage(tl("teleportHome", home));
-            }
-        });
+        UserTeleportHomeEvent event = new UserTeleportHomeEvent(user, home, loc, UserTeleportHomeEvent.HomeType.HOME);
+        user.getServer().getPluginManager().callEvent(event);
+        if (!event.isCancelled()) {
+            user.getAsyncTeleport().teleport(loc, charge, TeleportCause.COMMAND, future);
+            future.thenAccept(success -> {
+                if (success) {
+                    user.sendMessage(tl("teleportHome", home));
+                }
+            });
+        }
     }
 
     @Override

Essentials/src/net/ess3/api/events/UserTeleportHomeEvent.java

@@ -0,0 +1,99 @@
+package net.ess3.api.events;
+
+import net.ess3.api.IUser;
+import org.bukkit.Location;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called when a user is teleported home via the /home command.
+ *
+ * This is called before {@link net.ess3.api.events.UserTeleportEvent UserTeleportEvent}.
+ */
+public class UserTeleportHomeEvent extends Event implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+
+    private final IUser user;
+    private final String homeName;
+    private final Location target;
+    private final HomeType homeType;
+    private boolean cancelled = false;
+
+    public UserTeleportHomeEvent(IUser user, String homeName, Location target, HomeType homeType) {
+        this.user = user;
+        this.homeName = homeName;
+        this.target = target;
+        this.homeType = homeType;
+    }
+
+    /**
+     * Returns the user who is being teleported
+     *
+     * @return The teleportee.
+     */
+    public IUser getUser() {
+        return user;
+    }
+
+    /**
+     * Returns the name of the home being teleported to.
+     *
+     * The behavior of this method varies based on the {@link HomeType} as follows;
+     * {@link HomeType#HOME}  - Returns name of home being teleported to.
+     * {@link HomeType#BED}   - Returns "bed".
+     * {@link HomeType#SPAWN} - Returns null.
+     *
+     * @return Name of home being teleported to, or null if the user had no homes set.
+     */
+    public String getHomeName() {
+        return homeName;
+    }
+
+    /**
+     * Returns the location the user is teleporting to.
+     *
+     * @return Teleportation destination location.
+     */
+    public Location getHomeLocation() {
+        return target;
+    }
+
+    /**
+     * Returns the home location type.
+     *
+     * {@link HomeType#HOME}  - A user-set home location.
+     * {@link HomeType#BED}   - A user's bed location.
+     * {@link HomeType#SPAWN} - The user's current world spawn.
+     *
+     * @return Home location type.
+     */
+    public HomeType getHomeType() {
+        return homeType;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(boolean cancelled) {
+        this.cancelled = cancelled;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    public enum HomeType {
+        HOME,
+        BED,
+        SPAWN
+    }
+}