M | Utility: TeleportUtils

M | Utility: TeleportUtils

---

Table of Contents

• 1. Overview
• 2. What is TeleportUtils?
• 3. Basic Usage
• 4. API Reference
• 5. Advanced Patterns
• 6. Troubleshooting & Notes
• 7. See Also

---

1. Overview

TeleportUtils is a utility class in FXItems for teleporting players safely, with optional particle and sound effects.
It provides a centralized way to handle player teleportation with distance checks and effect options.

---

2. What is TeleportUtils?

• Teleports a player to a target location.
• Optionally limits teleport distance.
• Can preserve the player's yaw/pitch direction.
• Optionally plays a sound and/or spawns particles on teleport.

---

3. Basic Usage

Example: Teleport player with effects and distance check

boolean success = TeleportUtils.teleportPlayer(
    player,
    targetLocation,
    40,     // maxDistance in blocks
    true,   // preserveDirection
    true,   // playSound
    true    // spawnParticles
);

if (!success) {
    player.sendMessage("Teleport failed!");
}

---

4. API Reference

/**
 * Teleports a player to a target location with optional distance limit, direction preservation, sound, and particles.
 *
 * @param player            The player to teleport.
 * @param targetLocation    The location to teleport to.
 * @param maxDistance       The maximum allowed distance for teleportation.
 * @param preserveDirection Whether to preserve the player's original yaw and pitch.
 * @param playSound         Whether to play a sound effect during teleportation.
 * @param spawnParticles    Whether to spawn particles at the teleportation location.
 * @return True if the teleportation was successful, false otherwise.
 */
public static boolean teleportPlayer(Player player, Location targetLocation, int maxDistance, boolean preserveDirection, boolean playSound, boolean spawnParticles)

---

5. Advanced Patterns

• Restricting ability range:
  Use maxDistance to limit how far a player can teleport, e.g., for wands or teleport items.
• Visual feedback:
  Use playSound and spawnParticles for better player experience.
• Preserving orientation:
  preserveDirection is useful for blink/warp effects where facing matters.

---

6. Troubleshooting & Notes

• If the target location is too far, teleport will fail and send a message to the player.
• playSound uses the Enderman teleport sound at the origin location.
• spawnParticles spawns Particle.PORTAL at the destination.

---

7. See Also

• L | Utility: CooldownUtils
• N | Utility: ProjectileUtils
• API: Utils

---