API interface for interacting with EssentialsC's Back teleport system.
Retrieve an instance via EssentialsCAPI.getBackApi().
BackApi back = APIProvider.getAPI().getBackApi();
// check and retrieve a player's stored back location
if (back.hasBackLocation(player.getUniqueId())) {
back.getBackLocation(player.getUniqueId())
.ifPresent(loc -> player.sendMessage("Back: " + loc.getBlockX() + ", " + loc.getBlockY()));
}
// programmatically teleport a player back
back.teleportBack(player);
Back locations are stored in memory only. They are populated automatically on player death and on teleport events, and cleared when the player disconnects.
Method Summary
| boolean |
hasBackLocation(UUID uuid) Returns whether the given player has a stored back location. |
| Optional<Location> |
getBackLocation(UUID uuid) Returns the stored back location for the given player, if present. |
| boolean |
hasPendingTeleport(UUID uuid) Returns whether the player has a pending back teleport in its warmup phase. |
| boolean |
isOnCooldown(UUID uuid) Returns whether the given player is currently on the back-teleport cooldown. |
| long |
getRemainingCooldown(UUID uuid) Returns the seconds remaining on the player's back-teleport cooldown. |
| long |
getWarmupSeconds() Returns the configured warmup duration in seconds. |
| long |
getCooldownSeconds() Returns the configured cooldown duration in seconds. |
| boolean |
isParticlesEnabled() Returns whether the particle effect is played on teleport completion. |
| boolean |
isSoundsEnabled() Returns whether the teleport sound is played on teleport completion. |
| boolean |
isCancelOnMovementEnabled() Returns whether movement cancels a pending back teleport. |
| void |
setBackLocation(Player player, Location location) Sets or overwrites the stored back location for the given player. |
| void |
removeBackLocation(Player player) Removes the stored back location for the given player. |
| void |
teleportBack(Player player) Initiates a back teleport for the given player. |
| void |
cancelTeleport(Player player, String reason) Cancels a pending warmup back teleport for the given player. |
Returns whether the given player has a stored back location.
A back location is saved automatically on player death and on any teleport event. It is cleared when the player disconnects.
Parameters:| uuid | the UUID of the player; must not be null |
| boolean | true if a back location exists for this player; false otherwise |
Returns the stored back location for the given player, if present.
The returned Location is a defensive copy — modifying it has no effect on the stored location. The optional is empty if no back location has been saved yet or if the player is offline.
| uuid | the UUID of the player; must not be null |
| Optional<Location> | an Optional containing the back Location, or Optional.empty() if none is stored |
Returns whether the given player currently has a pending back teleport in its warmup phase.
A teleport enters the warmup phase when teleportBack(Player) is called and the configured warmup time is greater than zero. The pending state ends when the teleport completes or is cancelled.
| uuid | the UUID of the player; must not be null |
| boolean | true if a warmup teleport is in progress for this player; false otherwise |
Returns whether the given player is currently on the back-teleport cooldown.
Players with the essentialsc.back.admin permission are never considered on cooldown. Returns false if the configured cooldown duration is zero or negative.
| uuid | the UUID of the player; must not be null |
| boolean | true if the player must wait before using /back again; false otherwise |
Returns the number of seconds remaining on the given player's back-teleport cooldown.
Returns 0 if the player is not on cooldown, if the cooldown is disabled, or if the player holds the essentialsc.back.admin permission.
| uuid | the UUID of the player; must not be null |
| long | seconds remaining on the cooldown, 0 or greater |
Returns the configured warmup duration in seconds before a back teleport is executed.
A value of 0 or less means teleports are instant. Players with the essentialsc.back.admin permission always teleport instantly regardless of this value.
| long | warmup duration in seconds; 0 or greater |
Returns the configured cooldown duration in seconds between back teleports.
A value of 0 or less means there is no cooldown.
| long | cooldown duration in seconds; 0 or greater |
Returns whether the particle effect is played at the destination when a back teleport completes.
Returns:| boolean | true if particles are enabled; false otherwise |
Returns whether the teleport sound is played when a back teleport completes.
Returns:| boolean | true if sounds are enabled; false otherwise |
Returns whether a pending back teleport is cancelled if the player moves during the warmup phase.
Returns:| boolean | true if movement cancels the warmup; false otherwise |
Sets (or overwrites) the stored back location for the given player.
Passing a Location with a null world or a null location itself is a no-op. The location is cloned internally — you may safely modify or discard the original after this call.
| player | the player whose back location to set; must not be null |
| location | the location to store; ignored if null or worldless |
Removes the stored back location for the given player.
Has no effect if no location is currently stored.
Parameters:| player | the player whose back location to clear; must not be null |
Initiates a back teleport for the given player.
Internally this method handles the full teleport flow:
- No-op (with player message) if a teleport is already pending.
- No-op (with player message) if no back location is stored.
- No-op (with player message) if the player is on cooldown.
- Instant teleport if warmup is zero or the player has
essentialsc.back.admin. - Otherwise starts the warmup timer; the teleport executes after the configured warmup period unless cancelled.
This method is synchronous and safe to call on the main thread.
Parameters:| player | the player to teleport; must not be null |
Cancels a pending warmup back teleport for the given player.
Has no effect if no warmup teleport is currently in progress. The player will receive a cancellation message whose text may vary based on the reason string.
Known reason values recognised by the plugin:
"move"— player moved during warmup (uses the movement-cancel message key)- Any other value — uses the generic cancellation message key
| player | the player whose pending teleport to cancel; must not be null |
| reason | a short reason string; use "move" for movement cancels, any other value for generic cancellation |