API interface for interacting with EssentialsC's home system. Manages player homes with SQLite persistence, GUI management, teleportation with warmup/cooldown, and admin controls for managing other players' homes.
Most data operations are asynchronous (returning CompletableFuture) to avoid
blocking the main thread during SQLite queries. Teleportation and GUI methods must be
called on the main thread.
Retrieve an instance via EssentialsCAPI.getHomeApi().
HomeApi homes = APIProvider.getAPI().getHomeApi();
// Async query example
homes.getHomes(player.getUniqueId()).thenAccept(list -> {
list.forEach(h -> player.sendMessage(h.name() + " at " + h.formatCoordinates()));
});
// Teleport with warmup/cooldown
homes.getHome(player.getUniqueId(), "base").thenAccept(home -> {
if (home != null) {
Bukkit.getScheduler().runTask(plugin, () -> homes.startTeleport(player, home));
}
});
The HomeEntry record lives in the
net.godlycow.org.essc.api.home sub-package.
Method Summary
| int |
getMaxHomes(Player player) Returns the maximum number of homes the player can have. |
| CompletableFuture<Integer> |
getHomeCount(UUID uuid) Returns the current number of homes for the player (async). |
| CompletableFuture<Boolean> |
homeExists(UUID uuid, String name) Returns whether a home with the given name exists (async). |
| CompletableFuture<Boolean> |
setHome(Player player, String name, Location location) Creates or updates a home for the player (async). |
| CompletableFuture<Boolean> |
setHome(UUID uuid, String name, Location location) Admin method to set a home for offline players (async). |
| CompletableFuture<Boolean> |
deleteHome(UUID uuid, String name) Deletes a home for the player (async). |
| CompletableFuture<HomeEntry> |
getHome(UUID uuid, String name) Returns a specific home for the player (async). |
| CompletableFuture<List<HomeEntry>> |
getHomes(UUID uuid) Returns all homes for the player (async). |
| CompletableFuture<Set<UUID>> |
getAllHomeOwners() Returns all UUIDs that have at least one home set (async). |
| boolean |
isOnCooldown(Player player) Returns whether the player is currently on home teleport cooldown. |
| long |
getRemainingCooldown(Player player) Returns the remaining cooldown in seconds for the player. |
| boolean |
hasPendingTeleport(Player player) Returns whether the player has a pending home teleport warmup. |
| void |
cancelTeleport(Player player) Cancels any pending home teleport for the player. |
| void |
startTeleport(Player player, HomeEntry home) Initiates teleportation to the specified home with warmup/cooldown. |
| void |
openGui(Player player) Opens the home GUI for the player. |
| boolean |
isGuiMode() Returns whether GUI mode is enabled for homes. |
| void |
reload() Reloads the home configuration from disk. |
Returns the maximum number of homes the player can have. Checks permissions
(essentialsc.sethome.<n>) and config default. Returns
Integer.MAX_VALUE for unlimited.
| player | the player to check; must not be null |
| int | the maximum home count, or Integer.MAX_VALUE for unlimited |
Returns the current number of homes for the player.
| uuid | the player's UUID; must not be null |
| CompletableFuture<Integer> | a future resolving to the home count |
Returns whether a home with the given name exists for the player.
| uuid | the player's UUID; must not be null |
| name | the home name; must not be null |
| CompletableFuture<Boolean> | a future resolving to true if exists |
Creates or updates a home for the player at the given location.
| player | the player setting the home; must not be null |
| name | the home name; must not be null |
| location | the location to set; must not be null |
| CompletableFuture<Boolean> | a future resolving to true on success |
Creates or updates a home for the specified UUID at the given location. Admin method for setting homes for offline players.
| uuid | the target player's UUID; must not be null |
| name | the home name; must not be null |
| location | the location to set; must not be null |
| CompletableFuture<Boolean> | a future resolving to true on success |
Deletes a home for the player.
| uuid | the player's UUID; must not be null |
| name | the home name to delete; must not be null |
| CompletableFuture<Boolean> | a future resolving to true if deleted |
Returns a specific home for the player.
| uuid | the player's UUID; must not be null |
| name | the home name; must not be null |
| CompletableFuture<HomeEntry> | a future resolving to the home, or null if not found |
Returns all homes for the player.
| uuid | the player's UUID; must not be null |
| CompletableFuture<List<HomeEntry>> | a future resolving to list of homes; never null |
Returns all UUIDs that have at least one home set.
| CompletableFuture<Set<UUID>> | a future resolving to set of UUIDs; never null |
Returns whether the player is currently on home teleport cooldown.
Parameters:| player | the player to check; must not be null |
| boolean | true if on cooldown |
Returns the remaining cooldown in seconds for the player.
Parameters:| player | the player to check; must not be null |
| long | remaining seconds, or 0 if not on cooldown |
Returns whether the player has a pending home teleport warmup.
Parameters:| player | the player to check; must not be null |
| boolean | true if warmup is in progress |
Cancels any pending home teleport for the player.
Must be called on the main thread.
Parameters:| player | the player whose teleport to cancel; must not be null |
Initiates teleportation to the specified home. Applies warmup, cooldown, and blocked world checks. Sends appropriate messages to the player.
Must be called on the main thread.
Parameters:| player | the player to teleport; must not be null |
| home | the home to teleport to; must not be null |
Opens the home GUI for the player. Only opens if GUI mode is enabled in config.
Must be called on the main thread.
Parameters:| player | the player to open GUI for; must not be null |
Returns whether GUI mode is enabled for homes.
Returns:| boolean | true if homes use GUI interface |
Reloads the home configuration from disk.
Must be called on the main thread.