Homes API

// Option 1: one-call conversion.
Location loc = home.toLocation(server);

// Option 2: manual, e.g. to tweak coordinates first.
Location loc2 = new Location(
    server.getWorld(home.getWorldName()),
    home.getX(), home.getY(), home.getZ(),
    home.getYaw(), home.getPitch()
);

HomeManager homes = api.getHomeManager();

homes.fetchHome(player.getUniqueId(), "base").thenAccept(home -> {
    if (home == null) {
        player.sendMessage("You don't have a home called 'base'.");
        return;
    }
    player.teleportAsync(home.toLocation(server));
});

// Start the full teleport flow (warmup + teleport + events).
if (homes.isOnCooldown(player)) {
    player.sendMessage("Wait " + homes.getRemainingCooldownSeconds(player) + "s");
    return;
}
if (homes.hasPendingTeleport(player)) {
    player.sendMessage("A home teleport is already in progress.");
    return;
}

homes.fetchHome(player.getUniqueId(), "base").thenAccept(home -> {
    if (home != null) {
        homes.startTeleport(player, home); // fires warmup/teleport events
    }
});

@EventHandler
public void onHomeSet(HomeSetEvent event) {
    Player p = event.getPlayer();

    // Veto homes inside a protected region, with a custom reason.
    if (isProtected(event.getLocation())) {
        event.setCancelled(true);
        event.setCancelReason("Location is protected.");
        p.sendMessage("You can't set a home there!");
    }

    String homeName = event.getHomeName();
    Location loc = event.getLocation();
}

@EventHandler
public void onHomeDelete(HomeDeleteEvent event) {
    // Log every home deletion to a file.
    getLogger().info(event.getPlayer().getName()
        + " deleted home '" + event.getHomeName() + "'");
}

@EventHandler
public void onHomeTeleport(HomeTeleportEvent event) {
    Home home = event.getHome();

    // Block teleports into unloaded/vanished worlds.
    if (server.getWorld(home.getWorldName()) == null) {
        event.setCancelled(true);
        event.setCancelReason("Home world is missing.");
    }
}

@EventHandler
public void onHomeWarmupStart(HomeWarmupStartEvent event) {
    // Double the warmup for players in combat.
    if (isInCombat(event.getPlayer())) {
        event.setWarmupSeconds(event.getWarmupSeconds() * 2);
    }

    // Give donors instant teleports.
    if (event.getPlayer().hasPermission("vip.instant")) {
        event.setWarmupSeconds(0);
    }
}

@EventHandler
public void onHomeWarmupCancel(HomeWarmupCancelEvent event) {
    switch (event.getReason()) {
        case PLAYER_MOVED -> event.getPlayer().sendMessage("Teleport cancelled - you moved!");
        case PLAYER_OFFLINE -> getLogger().info("Home warmup dropped for offline player.");
        case EVENT_CANCELLED -> { /* another plugin vetoed it */ }
    }
}

@EventHandler
public void onHomePostTeleport(HomePostTeleportEvent event) {
    Player p = event.getPlayer();
    Location dest = event.getDestination();

    p.playSound(dest, Sound.BLOCK_PORTAL_TRAVEL, 0.5f, 1.2f);
    p.sendActionBar("Welcome home, " + p.getName() + "!");
}

@EventHandler
public void onHomeCooldownExpire(HomeCooldownExpireEvent event) {
    // previousTeleportTime is the millis timestamp of the last teleport.
    long last = event.getPreviousTeleportTime();
    getLogger().info(event.getPlayer().getName() + " home cooldown expired");
}

@EventHandler
public void onJoin(PlayerJoinEvent event) {
    Player p = event.getPlayer();
    HomeManager homes = api.getHomeManager();

    homes.homeExists(p.getUniqueId(), "spawn")
        .thenAccept(exists -> {
            if (!exists) {
                Location spawn = p.getWorld().getSpawnLocation();
                homes.setHome(p, "spawn", spawn);
            }
        });
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
    if (!(sender instanceof Player p)) return true;

    api.getHomeManager().fetchHomes(p.getUniqueId()).thenAccept(homes -> {
        if (homes.isEmpty()) {
            p.sendMessage("You have no homes. Use /sethome.");
            return;
        }
        StringBuilder sb = new StringBuilder("Homes (").append(homes.size()).append("): ");
        for (int i = 0; i < homes.size(); i++) {
            if (i > 0) sb.append(", ");
            sb.append(homes.get(i).getName());
        }
        p.sendMessage(sb.toString());
    });
    return true;
}

@EventHandler
public void onBan(BanListEvent event) { /* not a real event - illustrative */ }

// Using a UUID lookup:
public void purgePlayer(UUID uuid) {
    HomeManager homes = api.getHomeManager();
    homes.fetchHomes(uuid).thenAccept(list -> {
        for (Home home : list) {
            homes.deleteHome(uuid, home.getName());
        }
        homes.clearCache(uuid);
    });
}