API Examples

HuskHomes banner

API Examples (WIP)

HuskHomes provides API for getting Homes and Warps, getting UserData and information about Users, teleporting OnlineUsers and letting you provide custom RandomTeleportEngines for extending the /rtp commandโ€™s functionality.

This is a work-in-progress. If youโ€™d like to help edit this page, give me a ping on Discord (William).

1. Creating a class to interface with the API

  • Unless your plugin completely relies on HuskHomes, you shouldnโ€™t put HuskHomes API calls into your main class, otherwise if HuskHomes is not installed youโ€™ll encounter ClassNotFoundExceptions
public class HuskHomesAPIHook {

    public HuskHomesAPIHook() {
        // Ready to do stuff with the API
    }

}

2. Checking if HuskHomes is present and creating the hook

  • Check to make sure the HuskHomes plugin is present before instantiating the API hook class
public class MyPlugin extends JavaPlugin {

    public HuskHomesAPIHook huskHomesAPIHook;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().getPlugin("HuskHomes") != null) {
            this.huskHomesAPIHook = new HuskHomesAPIHook();
        }
    }
}

3. Getting an instance of the API

  • You can now get the API instance by calling HuskHomesAPI#getInstance()
import net.william278.huskhomes.api.HuskHomesAPI;

public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    public HuskHomesAPIHook() {
        this.huskHomesAPI = HuskHomesAPI.getInstance();
    }

}

4. Getting a userโ€™s homes

The API provides a number of methods for getting data, including #getUserHomes(user) for a user, as well as getWarps() and getPublicHomes() for public teleport points. Most methods return asynchronously-executing CompletableFutures to ensure the database queries they rely on do not block the main server thread.

public class HuskSyncAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This method prints out a player's homes into console using stdout
    public void printPlayerHomes(UUID uuid) {
        // Use this to adapt an online player to an OnlineUser, which extends User (accepted by getUserHomes).
        // To get the homes of an offline user, use: new User(uuid, username);
        OnlineUser user = huskHomesAPI.adaptUser(Bukkit.getPlayer(uuid));
        // A lot of HuskHomes' API methods return as futures which execute asynchronously.
        huskHomesAPI.getUserHomes(user).thenAccept(homeList -> { // Use #thenAccept(data) to run after the future has executed with data
            for (Home home : homeList) {
                // The home and warp object both extend SavedPosition, which maps a position object to a name and description
                System.out.println(home.meta.name); // It's best to use your plugin logger, but this is just an example.
            }
        });
    }

}