feat: entity teleportation API (#378)

Author: zlataovce

config/sidebar.paper.ts

@@ -138,6 +138,7 @@ const paper: SidebarsConfig = {
             "dev/api/pdc",
             "dev/api/custom-inventory-holder",
             "dev/api/scheduler",
+            "dev/api/entity-teleport",
             "dev/api/plugin-messaging",
             "dev/api/plugin-configs",
             "dev/api/folia-support",

docs/paper/dev/api/entity-teleport.mdx

@@ -0,0 +1,70 @@
+---
+slug: /dev/entity-teleport
+description: The entity teleportation API and how to use it.
+---
+
+# Entity Teleportation
+
+Entities can be instantaneously teleported to specific positions, synchronously and asynchronously with the
+<Javadoc name={"org.bukkit.entity.Entity#teleport(org.bukkit.Location)"}>`teleport`</Javadoc> and
+<Javadoc name={"org.bukkit.entity.Entity#teleportAsync(org.bukkit.Location)"}>`teleportAsync`</Javadoc> API.
+
+```java
+entity.teleport(location); // teleports the entity synchronously
+
+entity.teleportAsync(location).thenAccept(success -> { // teleports the entity asynchronously
+    // this code is ran when the teleport completes
+    // the Future is completed on the main thread, so it is safe to use the API here
+
+    if (success) {
+        // the entity was teleported successfully!
+    }
+});
+```
+
+## Look at
+
+The <Javadoc name={"org.bukkit.entity.Player#lookAt(io.papermc.paper.math.Position,io.papermc.paper.entity.LookAnchor)"}>`lookAt`</Javadoc>
+API allows you to make a player look at a certain position or entity.
+
+```java
+player.lookAt(
+    position,
+    LookAnchor.EYES // the player's eyes will be facing the position
+);
+
+player.lookAt(
+    entity,
+    LookAnchor.EYES // the player's eyes will be facing the entity
+    LookAnchor.FEET // the player will be facing the entity's feet
+);
+```
+
+## Teleport flags
+
+Teleport flags offer a way to teleport entities whilst being able to customize behavior.
+This allows you to do things like teleport players using relative flags and being able to retain passengers.
+
+All available teleport flags can be found in the <Javadoc name={"io.papermc.paper.entity.TeleportFlag"}>`TeleportFlag`</Javadoc> class.
+
+### Relative teleportation
+
+Teleport a player relatively, preventing velocity from being reset in the X, Y and Z axes.
+
+```java
+player.teleport(
+    location,
+    TeleportFlag.Relative.X,
+    TeleportFlag.Relative.Y,
+    TeleportFlag.Relative.Z
+);
+```
+
+### Retaining passengers
+
+Teleport an entity with the <Javadoc name={"io.papermc.paper.entity.TeleportFlag$EntityState#RETAIN_PASSENGERS"}>`RETAIN_PASSENGERS`</Javadoc> flag,
+allowing its passengers to be transferred with the entity.
+
+```java
+entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS);
+```

docs/paper/dev/api/roadmap.mdx

@@ -35,33 +35,6 @@ continue to function and will have their underlying instance replaced automatica
 
 This is done to help reduce possible inconsistencies between world switching between Vanilla and Paper.
 
-## Experimental API
-
-### Teleport flags
-
-Teleport flags offer a way to teleport entities whilst being able to customize behavior.
-This allows you to do things like teleport players using relative flags and being able to retain passengers.
-
-This API is currently finalized and will be marked as stable in a future release.
-
-#### Player teleportation
-Teleport a player relatively, preventing velocity from being reset in the X, Y and Z axes.
-```java
-player.teleport(
-    location,
-    TeleportFlag.Relative.X,
-    TeleportFlag.Relative.Y,
-    TeleportFlag.Relative.Z
-);
-```
-
-#### Vehicle teleportation
-Teleport an entity with the <Javadoc name={"io.papermc.paper.entity.TeleportFlag$EntityState#RETAIN_PASSENGERS"}>`RETAIN_PASSENGERS`</Javadoc> flag,
-allowing its passengers to be transferred with the entity.
-```java
-entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS);
-```
-
 ## Deprecation policy
 
 :::warning