API Examples

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).

Project setup

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
    }

}

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();
        }
    }
}

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();
    }

}

Doing stuff with the API

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.

Getting a player's homes

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.
            }
        });
    }

}

Teleporting a player

HuskHomes' teleport API is particularly useful if you want to teleport people cross server.

public class HuskSyncAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This teleports a player to 128, 64, 128 on the server "server"
    public void teleportPlayer(Player player) {
        // Use this to adapt an online player to an OnlineUser, which extends User (accepted by getUserHomes).
        OnlineUser user = huskHomesAPI.adaptUser(player);

        // The TeleportBuilder accepts a class that (extends/is a) Position. This can be a Home, Warp or constructed Position.
        // --> Note that the World object needs the name and UID of the world.
        // --> The UID will be used if the world can't be found by name. You can just pass it a random UUID if you don't have it.
        Position position = new Position(128, 64, 128, -90, 0,
                        new World("world", UUID.randomUUID()),
                        new Server("server"));

        // To construct a teleport, get a TeleportBuilder with #teleportBuilder
        huskHomesAPI.teleportBuilder(user)
                .setTarget(position)
                .toTimedTeleport() // This exposes a future returning the built Timed Teleport object (there's also a method for an instant teleport)
                .thenAccept(TimedTeleport::execute); // When the teleport has been resolved, use #execute to have it run
    }

}