From 45d716a5bd888b36d4a6c83a09d42aab7ae89425 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Mon, 6 May 2024 18:42:48 +0200 Subject: [PATCH 1/4] fix: remove teleport API from experimental APIs --- docs/paper/dev/api/roadmap.mdx | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/docs/paper/dev/api/roadmap.mdx b/docs/paper/dev/api/roadmap.mdx index 40e307e48..d6d0003fb 100644 --- a/docs/paper/dev/api/roadmap.mdx +++ b/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 `RETAIN_PASSENGERS` flag, -allowing its passengers to be transferred with the entity. -```java -entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS); -``` - ## Deprecation policy :::warning From 8d5dc022fd0a9798f325ceaa5c7e6c7bef9849ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Mon, 6 May 2024 20:16:28 +0200 Subject: [PATCH 2/4] feat: teleportation API page --- docs/paper/dev/api/entity-teleport.mdx | 70 ++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/paper/dev/api/entity-teleport.mdx diff --git a/docs/paper/dev/api/entity-teleport.mdx b/docs/paper/dev/api/entity-teleport.mdx new file mode 100644 index 000000000..ad5d344ea --- /dev/null +++ b/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 +`teleport` and +`teleportAsync` 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 +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 `TeleportFlag` 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 `RETAIN_PASSENGERS` flag, +allowing its passengers to be transferred with the entity. + +```java +entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS); +``` From e05a3870d3d40acc4e454fb9d203a19d5b80edb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Mon, 6 May 2024 20:18:36 +0200 Subject: [PATCH 3/4] fix: oops --- docs/paper/dev/api/entity-teleport.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/entity-teleport.mdx b/docs/paper/dev/api/entity-teleport.mdx index ad5d344ea..0ba4f2b41 100644 --- a/docs/paper/dev/api/entity-teleport.mdx +++ b/docs/paper/dev/api/entity-teleport.mdx @@ -24,7 +24,7 @@ entity.teleportAsync(location).thenAccept(success -> { // teleports the entity a ## Look at -The +The `lookAt` API allows you to make a player look at a certain position or entity. ```java From ac690b35c9e338efe7dd325097f22a8b3e82c9ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Mon, 6 May 2024 20:21:52 +0200 Subject: [PATCH 4/4] fix: I should read the contributing guide --- config/sidebar.paper.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts index e4ccfb6da..1f77de6c2 100644 --- a/config/sidebar.paper.ts +++ b/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",