RTP API

RtpManager rtp = api.getRtpManager();

// Guard with the same checks EssentialsC uses.
if (!rtp.isRtpSystemEnabled()) return;
if (rtp.isRtpInProgress(player)) {
    player.sendMessage("An RTP is already in progress.");
    return;
}
if (rtp.isOnCooldown(player) && !rtp.hasBypassPermission(player, "cooldown")) {
    player.sendMessage("Cooldown: " + rtp.getRemainingCooldownSeconds(player) + "s");
    return;
}

World target = player.getWorld();
if (!rtp.isWorldEnabled(target.getName())
        || !rtp.hasWorldPermission(player, target.getName())) {
    player.sendMessage("RTP is not available here.");
    return;
}

rtp.requestRtp(player, target).thenAccept(result -> {
    if (result.wasSuccessful()) {
        player.sendMessage("RTP complete at " + result.getDestination().getBlockX() + ", "
            + result.getDestination().getBlockZ());
    } else {
        player.sendMessage("RTP failed: " + result.getFailureReason());
    }
});

RtpWorldSettings settings = rtp.getWorldSettings("world");
if (settings == null) return;

player.sendMessage("RTP range for " + settings.getDisplayName() + ": "
    + settings.getMinRadius() + " - " + settings.getMaxRadius() + " blocks");

if (settings.getBlockedBiomes().contains("minecraft:deep_ocean")) {
    player.sendMessage("Careful - deep oceans are off limits!");
}

RtpPlayerState state = rtp.getPlayerState(player);

String status = state.isRtpInProgress()
    ? "in progress" : "idle";
if (state.isOnCooldown()) {
    status += " (cooldown " + state.getRemainingCooldownSeconds() + "s)";
}
player.sendMessage("RTP status: " + status
    + " | total: " + state.getTotalRtpCount());

rtp.requestRtp(player, world).thenAccept(result -> {
    if (result.wasSuccessful()) {
        // getDestination() is safe to use here.
        long elapsed = result.getCompletionTimestamp() - result.getRequestTimestamp();
        getLogger().info(player.getName() + " RTP'd in " + result.getWorld().getName()
            + " after " + result.getSearchAttempts() + " attempts (" + elapsed + "ms)");
    } else {
        getLogger().info(player.getName() + " RTP failed: " + result.getFailureReason());
    }
});

@EventHandler
public void onRtpRequest(RtpRequestEvent event) {
    // Block RTP during events.
    if (isServerEventRunning()) {
        event.setCancelled(true);
        event.setCancelReason("RTP is disabled during server events.");
    }
}

@EventHandler
public void onRtpWarmupStart(RtpWarmupStartEvent event) {
    // 3x warmup in the nether, instant for donors.
    if (event.getWorld().getEnvironment() == World.Environment.NETHER) {
        event.setWarmupSeconds(event.getWarmupSeconds() * 3);
    } else if (event.getPlayer().hasPermission("vip.instantrtp")) {
        event.setWarmupSeconds(0);
    }
}

@EventHandler
public void onRtpWarmupCancel(RtpWarmupCancelEvent event) {
    switch (event.getReason()) {
        case PLAYER_MOVED -> event.getPlayer().sendMessage("RTP cancelled - you moved!");
        case PLAYER_OFFLINE -> getLogger().info("RTP warmup dropped for offline player.");
        case EVENT_CANCELLED -> { /* vetoed elsewhere */ }
    }
}

@EventHandler
public void onRtpSearchStart(RtpSearchStartEvent event) {
    // Refuse to search worlds with no configured settings.
    if (rtp.getWorldSettings(event.getWorld().getName()) == null) {
        event.setCancelled(true);
        event.setCancelReason("World has no RTP settings.");
    }
}

@EventHandler
public void onRtpSearchComplete(RtpSearchCompleteEvent event) {
    Location loc = event.getLocation();
    if (loc == null) {
        getLogger().info("No safe spot found in " + event.getWorld().getName()
            + " after " + event.getAttempts() + " attempts.");
    }
}

@EventHandler
public void onRtpTeleport(RtpTeleportEvent event) {
    // Snap the destination to a spawn platform if one is configured.
    Location dest = event.getDestination();
    Location platform = findPlatform(dest.getWorld());
    if (platform != null) {
        event.setDestination(platform);
    }

    // Veto teleports into a locked region.
    if (isLocked(dest)) {
        event.setCancelled(true);
        event.setCancelReason("Destination is locked.");
    }
}

@EventHandler
public void onRtpPostTeleport(RtpPostTeleportEvent event) {
    Location dest = event.getDestination();
    event.getPlayer().getWorld().spawnParticle(
        Particle.CLOUD, dest, 40, 0.5, 1, 0.5, 0.01
    );
}

@EventHandler
public void onRtpFail(RtpFailEvent event) {
    switch (event.getReason()) {
        case NO_PERMISSION -> event.getPlayer().sendMessage("You can't use /rtp.");
        case NO_SAFE_LOCATION -> event.getPlayer().sendMessage("No safe spot found - try again.");
        case COOLDOWN_ACTIVE -> event.getPlayer().sendMessage("You're on RTP cooldown.");
        case WARMUP_CANCELLED -> { /* already messaged */ }
        default -> getLogger().info(event.getPlayer().getName() + " RTP failed: "
            + event.getReason() + " " + event.getDetailMessage());
    }
}

@EventHandler
public void onRtpCooldownExpire(RtpCooldownExpireEvent event) {
    event.getPlayer().sendActionBar("You can /rtp again!");
}

List<String> worlds = rtp.getAvailableWorldNamesFor(player);
if (worlds.isEmpty()) {
    player.sendMessage("No worlds available for RTP.");
    return;
}

String chosen = worlds.get(ThreadLocalRandom.current().nextInt(worlds.size()));
World world = Bukkit.getWorld(chosen);
if (world != null) {
    rtp.requestRtp(player, world);
}

// Called from your scoreboard update task (sync or async).
public String rtpLine(Player player) {
    RtpPlayerState state = rtp.getPlayerState(player);
    if (state.isOnCooldown()) {
        return "RTP: " + state.getRemainingCooldownSeconds() + "s";
    }
    return "RTP: ready";
}

if (rtp.isRtpInProgress(player)) {
    rtp.cancelPendingRtp(player);
    player.sendMessage("Your pending RTP was cancelled.");
}