Only expose velocity relative tp flags to API (#11532)

Since 1.21.2, vanilla split relative teleportation flags into position
and delta/velocity flags into separate enum entries.
This highlighted a design flaw in the paper api addition for teleport
flags, which just simply mirrored internals while also only being able
to apply the delta/velocity part of a flag, given the teleport target is
always absolute in the API.

This patch proposes to simply no longer expose the non-velocity related
flags to the API, instead marking the entire Relative enum as being
purely velocity related, as non-velocity related flags are not useful to
callers. This was done over simply exposing all internal flags, as
another vanilla change to the internal enum would result in the same
breakage.

The newly proposed API *only* promises that the passed flags prevent the
loss of velocity in the specific axis/context, which should be
independent enough of vanillas specific implementation of this feature.

patches/api/0353-More-Teleport-API.patch

@@ -36,10 +36,10 @@ index 0000000000000000000000000000000000000000..544eec787ea837f7d29df6519255840d
 +}
 diff --git a/src/main/java/io/papermc/paper/entity/TeleportFlag.java b/src/main/java/io/papermc/paper/entity/TeleportFlag.java
 new file mode 100644
-index 0000000000000000000000000000000000000000..c8b5b570d44da9524bfc59c7e11b2ae59d4b79b9
+index 0000000000000000000000000000000000000000..bbc006152ac7885e1ffd05e84073ac1af45cc1a3
 --- /dev/null
 +++ b/src/main/java/io/papermc/paper/entity/TeleportFlag.java
-@@ -0,0 +1,79 @@
+@@ -0,0 +1,113 @@
 +package io.papermc.paper.entity;
 +
 +import org.bukkit.Location;
@@ -57,35 +57,69 @@ index 0000000000000000000000000000000000000000..c8b5b570d44da9524bfc59c7e11b2ae5
 +    /**
 +     * Note: These flags only work on {@link org.bukkit.entity.Player} entities.
 +     * <p>
-+     * Represents coordinates in a teleportation that should be handled relatively.
-+     * <p>
-+     * Coordinates of the location that the client should handle as relative teleportation
-+     * Relative teleportation flags are only used client side, and cause the player to not lose velocity in that
-+     * specific coordinate. The location of the teleportation will not change.
++     * Relative flags enable a player to not loose 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 {
 +        /**
-+         * Represents the player's X coordinate
++         * Configures the player to not loose velocity in their x axis during the teleport.
 +         */
-+        X,
++        VELOCITY_X,
 +        /**
-+         * Represents the player's Y coordinate
++         * Configures the player to not loose velocity in their y axis during the teleport.
 +         */
-+        Y,
++        VELOCITY_Y,
 +        /**
-+         * Represents the player's Z coordinate
++         * Configures the player to not loose velocity in their z axis during the teleport.
 +         */
-+        Z,
++        VELOCITY_Z,
++        /**
++         * Configures the player to not loose 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.
 +         */
-+        YAW,
++        @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.
 +         */
-+        PITCH;
++        @Deprecated(since = "1.21.3", forRemoval = true)
++        public static final Relative PITCH = VELOCITY_ROTATION;
 +    }
 +
 +    /**