Teleport rework

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