Feat(API): Mutable Location in PlayerTeleportToPlotEvent (#4196)

* feat: ability to overwrite spawn location for plot teleports

* chore/feat: migrate to LocationTransformer to resolve unnecessary chunk loads

* chore: simplify transform type

Core/src/main/java/com/plotsquared/core/events/PlayerTeleportToPlotEvent.java

@@ -21,21 +21,26 @@
 import com.plotsquared.core.location.Location;
 import com.plotsquared.core.player.PlotPlayer;
 import com.plotsquared.core.plot.Plot;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.function.UnaryOperator;
 
 /**
  * Called when a player teleports to a plot
  */
 public class PlayerTeleportToPlotEvent extends PlotPlayerEvent implements CancellablePlotEvent {
 
-    private final Location from;
     private final TeleportCause cause;
     private Result eventResult;
+    private final Location from;
+    private UnaryOperator<Location> locationTransformer;
+
 
     /**
      * PlayerTeleportToPlotEvent: Called when a player teleports to a plot
      *
      * @param player That was teleported
-     * @param from   Start location
+     * @param from   The origin location, from where the teleport was triggered (players location most likely)
      * @param plot   Plot to which the player was teleported
      * @param cause  Why the teleport is being completed
      * @since 6.1.0
@@ -57,14 +62,36 @@ public TeleportCause getCause() {
     }
 
     /**
-     * Get the from location
+     * Get the location, from where the teleport was triggered
+     * (the players current location when executing the home command for example)
      *
      * @return Location
      */
     public Location getFrom() {
         return this.from;
     }
 
+    /**
+     * Gets the currently applied {@link UnaryOperator<Location> transformer} or null, if none was set
+     *
+     * @return LocationTransformer
+     * @since TODO
+     */
+    public @Nullable UnaryOperator<Location> getLocationTransformer() {
+        return this.locationTransformer;
+    }
+
+    /**
+     * Sets the {@link UnaryOperator<Location> transformer} to mutate the location where the player will be teleported to.
+     * May be {@code null}, if any previous set transformations should be discarded.
+     *
+     * @param locationTransformer The new transformer
+     * @since TODO
+     */
+    public void setLocationTransformer(@Nullable UnaryOperator<Location> locationTransformer) {
+        this.locationTransformer = locationTransformer;
+    }
+
     @Override
     public Result getEventResult() {
         return eventResult;

Core/src/main/java/com/plotsquared/core/plot/Plot.java

@@ -29,6 +29,7 @@
 import com.plotsquared.core.configuration.caption.StaticCaption;
 import com.plotsquared.core.configuration.caption.TranslatableCaption;
 import com.plotsquared.core.database.DBFunc;
+import com.plotsquared.core.events.PlayerTeleportToPlotEvent;
 import com.plotsquared.core.events.Result;
 import com.plotsquared.core.events.TeleportCause;
 import com.plotsquared.core.generator.ClassicPlotWorld;
@@ -2573,16 +2574,20 @@ public void teleportPlayer(final PlotPlayer<?> player, Consumer<Boolean> result)
      */
     public void teleportPlayer(final PlotPlayer<?> player, TeleportCause cause, Consumer<Boolean> resultConsumer) {
         Plot plot = this.getBasePlot(false);
-        Result result = this.eventDispatcher.callTeleport(player, player.getLocation(), plot, cause).getEventResult();
-        if (result == Result.DENY) {
+
+        PlayerTeleportToPlotEvent event = this.eventDispatcher.callTeleport(player, player.getLocation(), plot, cause);
+        if (event.getEventResult() == Result.DENY) {
             player.sendMessage(
                     TranslatableCaption.of("events.event_denied"),
                     TagResolver.resolver("value", Tag.inserting(Component.text("Teleport")))
             );
             resultConsumer.accept(false);
             return;
         }
-        final Consumer<Location> locationConsumer = location -> {
+
+        final Consumer<Location> locationConsumer = calculatedLocation -> {
+            Location location = event.getLocationTransformer() == null ? calculatedLocation :
+                    Objects.requireNonNullElse(event.getLocationTransformer().apply(calculatedLocation), calculatedLocation);
             if (Settings.Teleport.DELAY == 0 || player.hasPermission("plots.teleport.delay.bypass")) {
                 player.sendMessage(TranslatableCaption.of("teleport.teleported_to_plot"));
                 player.teleport(location, cause);