Skip to main content

Teleportation

Entities can be instantaneously teleported to specific positions, synchronously and asynchronously with the teleport and teleportAsync API.

Performance

If you expect to teleport into unloaded chunks, it is recommended to use the teleportAsync API, as it avoids doing synchronous chunk loads, which put a lot of stress on the server's main thread - hurting overall performance.

entity.teleport(location); // loads chunks synchronously and teleports the entity

entity.teleportAsync(location).thenAccept(success -> { // loads chunks asynchronously and teleports the entity
    // 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!
    }
});
danger

You should NEVER call .get()/.join() on the teleportAsync Future on the main thread, as it WILL deadlock your server, if the chunk you're teleporting into is not loaded.

Look at​

The lookAt API allows you to make a player look at a certain position or entity.

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.

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.

entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS);