Rework API teleportation to better align with Vanilla (#13181)

Co-authored-by: Lulu13022002 <41980282+Lulu13022002@users.noreply.github.com>


This patch includes extensive changes to teleport logic in the API to better represent vanilla behavior. In particular, teleporting with passengers is now supported by default. This also allows for entities to be teleported across dimensions with passengers, except for players, which is still not supported. Entity state related teleportation flags have been deprecated, as that behavior occurs by default now. Additionally, relative teleportation flags are now supported on entities. 

Most importantly, we no longer hack onto the respawn logic when teleporting players between dimensions in the API. This is a good step towards working on no longer reusing player entities on dimension swap, which is something we are trying to no longer do as it causes a large amount of desync issues on the client/server.

Entity teleportation via /tp now aligns with vanilla too, which now maintains velocity when teleporting.

This is a breaking change.

Author: Owen1212055

paper-api/src/main/java/io/papermc/paper/entity/TeleportFlag.java

@@ -1,25 +1,25 @@
 package io.papermc.paper.entity;
 
 import org.bukkit.Location;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.Player;
 import org.bukkit.event.player.PlayerTeleportEvent;
 
 /**
  * Represents a flag that can be set on teleportation that may
  * slightly modify the behavior.
  *
- * @see EntityState
  * @see Relative
  */
 public sealed interface TeleportFlag permits TeleportFlag.EntityState, TeleportFlag.Relative {
 
     /**
-     * Note: These flags only work on {@link org.bukkit.entity.Player} entities.
-     * <p>
-     * Relative flags enable a player to not lose their velocity in the flag-specific axis/context when teleporting.
+     * Relative flags enable an entity to not lose their velocity in the flag-specific axis/context when teleporting.
      *
      * @apiNote The relative flags exposed in the API do *not* mirror all flags known to vanilla, as relative flags concerning
      * the position are non-applicable given teleports always expect an absolute location.
-     * @see org.bukkit.entity.Player#teleport(Location, PlayerTeleportEvent.TeleportCause, TeleportFlag...)
+     * @see Player#teleport(Location, PlayerTeleportEvent.TeleportCause, TeleportFlag...)
+     * @see Entity#teleport(Location, PlayerTeleportEvent.TeleportCause, TeleportFlag...)
      */
     enum Relative implements TeleportFlag {
         /**
@@ -40,6 +40,7 @@ enum Relative implements TeleportFlag {
         VELOCITY_ROTATION;
         /**
          * Configures the player to not lose velocity in their x axis during the teleport.
+         *
          * @deprecated Since 1.21.3, vanilla split up the relative teleport flags into velocity and position related
          * ones. As the API does not deal with position relative flags, this name is no longer applicable.
          * Use {@link #VELOCITY_X} instead.
@@ -48,6 +49,7 @@ enum Relative implements TeleportFlag {
         public static final Relative X = VELOCITY_X;
         /**
          * Configures the player to not lose velocity in their y axis during the teleport.
+         *
          * @deprecated Since 1.21.3, vanilla split up the relative teleport flags into velocity and position related
          * ones. As the API does not deal with position relative flags, this name is no longer applicable.
          * Use {@link #VELOCITY_Y} instead.
@@ -56,6 +58,7 @@ enum Relative implements TeleportFlag {
         public static final Relative Y = VELOCITY_Y;
         /**
          * Configures the player to not lose velocity in their z axis during the teleport.
+         *
          * @deprecated Since 1.21.3, vanilla split up the relative teleport flags into velocity and position related
          * ones. As the API does not deal with position relative flags, this name is no longer applicable.
          * Use {@link #VELOCITY_Z} instead.
@@ -83,30 +86,45 @@ enum Relative implements TeleportFlag {
     /**
      * Represents flags that effect the entity's state on
      * teleportation.
+     *
+     * @deprecated As of 1.21.10, the default behavior for teleportation is now aligned with vanilla
+     * behavior. This means all of these flags are functionally done by default.
      */
+    @Deprecated(since = "1.21.10", forRemoval = true)
     enum EntityState implements TeleportFlag {
         /**
          * If all passengers should not be required to be removed prior to teleportation.
          * <p>
          * Note:
          * Teleporting to a different world with this flag present while the entity has entities riding it
          * will cause this teleportation to return false and not occur.
+         *
+         * @deprecated This is now default behavior in teleportation. If you want to dismount all passengers,
+         * remove them with {@link Entity#removePassenger(Entity)}.
          */
+        @Deprecated(since = "1.21.10", forRemoval = true)
         RETAIN_PASSENGERS,
         /**
          * If the entity should not be dismounted if they are riding another entity.
          * <p>
          * Note:
          * Teleporting to a different world with this flag present while this entity is riding another entity will
          * cause this teleportation to return false and not occur.
+         *
+         * @deprecated This behavior was highly technical and is not replicatable due to client limitations,
+         * and has not functioned for many updates.
          */
+        @Deprecated(since = "1.21.10", forRemoval = true)
         RETAIN_VEHICLE,
         /**
          * Indicates that a player should not have their current open inventory closed when teleporting.
          * <p>
          * Note:
          * This option will be ignored when teleported to a different world.
+         *
+         * @deprecated No longer done on teleportation, use {@link Player#closeInventory()} to do this yourself.
          */
+        @Deprecated(since = "1.21.10", forRemoval = true)
         RETAIN_OPEN_INVENTORY;
     }
 

paper-api/src/main/java/org/bukkit/entity/Entity.java

@@ -138,6 +138,11 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     // Paper start - Teleport API
     /**
      * Teleports this entity to the given location.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param location New location to teleport this entity to
      * @param teleportFlags Flags to be used in this teleportation
@@ -149,6 +154,11 @@ default boolean teleport(@NotNull Location location, @NotNull io.papermc.paper.e
 
     /**
      * Teleports this entity to the given location.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param location New location to teleport this entity to
      * @param cause The cause of this teleportation
@@ -179,17 +189,25 @@ default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull L
     // Paper end - Teleport API
 
     /**
-     * Teleports this entity to the given location. If this entity is riding a
-     * vehicle, it will be dismounted prior to teleportation.
+     * Teleports this entity to the given location.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param location New location to teleport this entity to
      * @return <code>true</code> if the teleport was successful
      */
     public boolean teleport(@NotNull Location location);
 
     /**
-     * Teleports this entity to the given location. If this entity is riding a
-     * vehicle, it will be dismounted prior to teleportation.
+     * Teleports this entity to the given location.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param location New location to teleport this entity to
      * @param cause The cause of this teleportation
@@ -198,17 +216,25 @@ default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull L
     public boolean teleport(@NotNull Location location, @NotNull TeleportCause cause);
 
     /**
-     * Teleports this entity to the target Entity. If this entity is riding a
-     * vehicle, it will be dismounted prior to teleportation.
+     * Teleports this entity to the target Entity.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param destination Entity to teleport this entity to
      * @return <code>true</code> if the teleport was successful
      */
     public boolean teleport(@NotNull Entity destination);
 
     /**
-     * Teleports this entity to the target Entity. If this entity is riding a
-     * vehicle, it will be dismounted prior to teleportation.
+     * Teleports this entity to the target Entity.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause this to return false. This behavior may
+     * change in future versions.
      *
      * @param destination Entity to teleport this entity to
      * @param cause The cause of this teleportation
@@ -219,6 +245,12 @@ default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull L
     // Paper start
     /**
      * Loads/Generates(in 1.13+) the Chunk asynchronously, and then teleports the entity when the chunk is ready.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause the future to return false. This behavior may
+     * change in future versions.
+     *
      * @param loc Location to teleport to
      * @return A future that will be completed with the result of the teleport
      */
@@ -228,6 +260,12 @@ default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull L
 
     /**
      * Loads/Generates(in 1.13+) the Chunk asynchronously, and then teleports the entity when the chunk is ready.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause the future to return false. This behavior may
+     * change in future versions.
+     *
      * @param loc Location to teleport to
      * @param cause Reason for teleport
      * @return A future that will be completed with the result of the teleport
@@ -241,9 +279,16 @@ final class Holder {
 
     /**
      * Loads/Generates(in 1.13+) the Chunk asynchronously, and then teleports the entity when the chunk is ready.
+     * <p>
+     * Note: This uses default in game behavior for teleportation, especially in regard to handling
+     * passengers and vehicles across dimensions. It should be noted at this moment, teleporting a {@link Player}
+     * with passengers across dimensions is not supported and will cause the future to return false. This behavior may
+     * change in future versions.
+     *
      * @param loc Location to teleport to
      * @param cause Reason for teleport
      * @param teleportFlags Flags to be used in this teleportation
+     *
      * @return A future that will be completed with the result of the teleport
      */
     java.util.concurrent.@NotNull CompletableFuture<Boolean> teleportAsync(@NotNull Location loc, @NotNull TeleportCause cause, @NotNull io.papermc.paper.entity.TeleportFlag @NotNull... teleportFlags);

paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java

@@ -77,7 +77,10 @@ public enum Reason {
         UNKNOWN,
         /**
          * Player is teleporting
+         *
+         * @deprecated As of 1.21.10, this is not called anymore as inventories are not closed on teleportation.
          */
+        @Deprecated(since = "1.21.10")
         TELEPORT,
         /**
          * Player is no longer permitted to use this inventory