+ * Relative flags enable a player 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...) + */ + enum Relative implements TeleportFlag { + /** + * Configures the player to not lose velocity in their x axis during the teleport. + */ + VELOCITY_X, + /** + * Configures the player to not lose velocity in their y axis during the teleport. + */ + VELOCITY_Y, + /** + * Configures the player to not lose velocity in their z axis during the teleport. + */ + VELOCITY_Z, + /** + * Configures the player to not lose velocity in their current rotation during the teleport. + */ + VELOCITY_ROTATION; + /** + * Configures the player to not loose 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. + */ + @Deprecated(since = "1.21.3", forRemoval = true) + public static final Relative X = VELOCITY_X; + /** + * Configures the player to not loose 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. + */ + @Deprecated(since = "1.21.3", forRemoval = true) + public static final Relative Y = VELOCITY_Y; + /** + * Configures the player to not loose 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. + */ + @Deprecated(since = "1.21.3", forRemoval = true) + public static final Relative Z = VELOCITY_Z; + /** + * Represents the player's yaw + * + * @deprecated relative velocity flags now allow for the whole rotation to be relative, instead of the yaw and + * pitch having individual options. Use {@link #VELOCITY_ROTATION} instead. + */ + @Deprecated(since = "1.21.3", forRemoval = true) + public static final Relative YAW = VELOCITY_ROTATION; + /** + * Represents the player's pitch + * + * @deprecated relative velocity flags now allow for the whole rotation to be relative, instead of the yaw and + * pitch having individual options. Use {@link #VELOCITY_ROTATION} instead. + */ + @Deprecated(since = "1.21.3", forRemoval = true) + public static final Relative PITCH = VELOCITY_ROTATION; + } + + /** + * Represents flags that effect the entity's state on + * teleportation. + */ + enum EntityState implements TeleportFlag { + /** + * If all passengers should not be required to be removed prior to teleportation. + *
+ * 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. + */ + RETAIN_PASSENGERS, + /** + * If the entity should not be dismounted if they are riding another entity. + *
+ * 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. + */ + RETAIN_VEHICLE, + /** + * Indicates that a player should not have their current open inventory closed when teleporting. + *
+ * Note:
+ * This option will be ignored when teleported to a different world.
+ */
+ RETAIN_OPEN_INVENTORY;
+ }
+
+}
diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index f51f3f04ba9efe15f68620c5531b502710078b6e..8bada7f7f0200103edc415ad003132d96ae09607 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/src/main/java/org/bukkit/entity/Entity.java
@@ -126,10 +126,32 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
*
* @param yaw the yaw
* @param pitch the pitch
- * @throws UnsupportedOperationException if used for players
*/
public void setRotation(float yaw, float pitch);
+ // Paper start - Teleport API
+ /**
+ * Teleports this entity to the given location.
+ *
+ * @param location New location to teleport this entity to
+ * @param teleportFlags Flags to be used in this teleportation
+ * @return true if the teleport was successful
+ */
+ default boolean teleport(@NotNull Location location, @NotNull io.papermc.paper.entity.TeleportFlag @NotNull... teleportFlags) {
+ return this.teleport(location, TeleportCause.PLUGIN, teleportFlags);
+ }
+
+ /**
+ * Teleports this entity to the given location.
+ *
+ * @param location New location to teleport this entity to
+ * @param cause The cause of this teleportation
+ * @param teleportFlags Flags to be used in this teleportation
+ * @return true if the teleport was successful
+ */
+ boolean teleport(@NotNull Location location, @NotNull TeleportCause cause, @NotNull io.papermc.paper.entity.TeleportFlag @NotNull... teleportFlags);
+ // 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.
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index 99bad852128f499f8f71552399c49f373d51cf9c..4371ac4683604919782f6268756dff4f05695a40 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -3561,6 +3561,45 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
String getClientBrandName();
// Paper end
+ // Paper start - Teleport API
+ /**
+ * Sets the player's rotation.
+ *
+ * @param yaw the yaw
+ * @param pitch the pitch
+ */
+ void setRotation(float yaw, float pitch);
+
+ /**
+ * Causes the player to look towards the given position.
+ *
+ * @param x x coordinate
+ * @param y y coordinate
+ * @param z z coordinate
+ * @param playerAnchor What part of the player should face the given position
+ */
+ void lookAt(double x, double y, double z, @NotNull io.papermc.paper.entity.LookAnchor playerAnchor);
+
+ /**
+ * Causes the player to look towards the given position.
+ *
+ * @param position Position to look at in the player's current world
+ * @param playerAnchor What part of the player should face the given position
+ */
+ default void lookAt(@NotNull io.papermc.paper.math.Position position, @NotNull io.papermc.paper.entity.LookAnchor playerAnchor) {
+ this.lookAt(position.x(), position.y(), position.z(), playerAnchor);
+ }
+
+ /**
+ * Causes the player to look towards the given entity.
+ *
+ * @param entity Entity to look at
+ * @param playerAnchor What part of the player should face the entity
+ * @param entityAnchor What part of the entity the player should face
+ */
+ void lookAt(@NotNull org.bukkit.entity.Entity entity, @NotNull io.papermc.paper.entity.LookAnchor playerAnchor, @NotNull io.papermc.paper.entity.LookAnchor entityAnchor);
+ // Paper end - Teleport API
+
@NotNull
@Override
Spigot spigot();
diff --git a/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java b/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java
index 2deae344c88920ab95eefd2f65df5c858e04750b..ccfb08af8c57ddac3062c2cec28d7ff428082709 100644
--- a/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java
@@ -13,8 +13,14 @@ public class PlayerTeleportEvent extends PlayerMoveEvent {
private static final HandlerList handlers = new HandlerList();
private TeleportCause cause = TeleportCause.UNKNOWN;
+ // Paper start - Teleport API
+ private boolean dismounted = true;
+ private final java.util.Set