EssentialsC API - Core API

APIProvider

class net.godlycow.org.essc.api.APIProvider

The static registry holding the single EssentialsCAPI instance. EssentialsC registers itself here during startup; your plugin reads from it. It's a public final class, so it can't be instantiated.

Method	Returns	Description
static void register(EssentialsCAPI api)	void	Registers the server API instance. Throws `IllegalArgumentException` on null and `IllegalStateException` if already registered. Reserved for EssentialsC.
static void unregister()	void	Clears the registered instance. Reserved for EssentialsC.
static EssentialsCAPI get()	EssentialsCAPI	Returns the registered instance. Throws `IllegalStateException` if EssentialsC has not registered it yet.
static boolean isAvailable()	boolean	True once EssentialsC has registered its API instance. The safe gate before every `get()` call.

Don't call register()/unregister() from your own plugin. They're lifecycle hooks EssentialsC manages in its plugin module. APIProvider also throws UnsupportedOperationException if you try to construct it.

EssentialsCAPI

interface net.godlycow.org.essc.api.EssentialsCAPI

The top-level interface. Grab it once from APIProvider.get() and cache it - it stays valid for the lifetime of the server. It exposes the four feature managers and a status flag for each:

Method	Returns	Description
KitManager getKitManager()	KitManager	Bound kit system: kit definitions, claim profiles, cooldowns, claiming.
RtpManager getRtpManager()	RtpManager	Bound RTP system: requests, world settings, player state, search.
HomeManager getHomeManager()	HomeManager	Bound homes system: create, delete, fetch, and teleport homes.
WarpManager getWarpManager()	WarpManager	Bound warps system: warp definitions, categories, costs, usage.
boolean isKitSystemEnabled()	boolean	Whether the kit system is enabled in the server config.
boolean isRtpSystemEnabled()	boolean	Whether the RTP system is enabled in the server config.
boolean isHomeSystemEnabled()	boolean	Whether the homes system is enabled in the server config.
boolean isWarpSystemEnabled()	boolean	Whether the warps system is enabled in the server config.
String getApiVersion()	String	The EssentialsC plugin version this API is bound to, e.g. `4.2.7.1`.

These managers are bound - the same instances EssentialsC uses internally, so writes you make through the API (say, creating a home) show up in the plugin and its commands right away.

Async methods. The home, kit, and warp managers use CompletableFuture reads and writes because storage is async. Teleport state - cooldowns, warmups, pending requests - is queried synchronously. Never block the main thread waiting on a future; chain with thenAccept() instead.

Versioning

The API version matches the plugin version it ships with. Use getApiVersion() to branch on behaviour that changed between releases - more reliable than parsing the plugin version yourself.

VersionCheck.java

EssentialsCAPI api = APIProvider.get();

// Simple minimum-version check against the bound plugin version.
boolean supportsWarps = api.getApiVersion().compareTo("4.2.0") >= 0;

if (!supportsWarps) {
    plugin.getLogger().warning("Your EssentialsC is too old - warp integration disabled.");
}

Access patterns

A few patterns cover how most plugins integrate. Pick whatever fits your code - all of them cache the singleton once instead of calling APIProvider.get() on every use.

Fail fast

Resolve in onEnable() and disable your plugin if EssentialsC is missing. Use this when EssentialsC is basically required.

Bootstrap.java

public final class Bootstrap {

    private static EssentialsCAPI api;

    public static boolean tryConnect() {
        if (!APIProvider.isAvailable()) {
            return false;
        }
        api = APIProvider.get();
        return true;
    }

    public static EssentialsCAPI api() {
        return api;
    }
}

Lazy singleton

Resolve on first use and cache the result. Handy for libraries loaded before EssentialsC finishes enabling.

EsscAccess.java

public final class EsscAccess {

    private static EssentialsCAPI api;
    private static boolean resolved;

    public static EssentialsCAPI get() {
        if (!resolved) {
            api = APIProvider.isAvailable() ? APIProvider.get() : null;
            resolved = true;
        }
        return api;
    }

    public static boolean isConnected() {
        return get() != null;
    }
}

Feature-flag guard

Systems can be toggled off in the config independently. Always check the matching flag before touching a manager:

GuardExample.java

EssentialsCAPI api = EsscAccess.get();
if (api == null) return;

// Only touch a manager when its system is actually enabled.
if (api.isHomeSystemEnabled()) {
    HomeManager homes = api.getHomeManager();
    // ...
}
if (api.isKitSystemEnabled()) {
    KitManager kits = api.getKitManager();
    // ...
}

Worked example: full bootstrap

Putting it all together - a plugin that connects, registers a listener for every module, and logs a quick status report:

EsscPlugin.java

package com.example.myplugin;

import net.godlycow.org.essc.api.APIProvider;
import net.godlycow.org.essc.api.EssentialsCAPI;
import net.godlycow.org.essc.api.home.event.HomeSetEvent;
import net.godlycow.org.essc.api.kit.event.KitClaimEvent;
import net.godlycow.org.essc.api.rtp.event.RtpRequestEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public final class EsscPlugin extends JavaPlugin implements Listener {

    private EssentialsCAPI essc;

    @Override
    public void onEnable() {
        if (!APIProvider.isAvailable()) {
            getLogger().severe("EssentialsC not found - disabling.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        this.essc = APIProvider.get();
        getServer().getPluginManager().registerEvents(this, this);

        report("home", essc.isHomeSystemEnabled());
        report("kit",  essc.isKitSystemEnabled());
        report("rtp",  essc.isRtpSystemEnabled());
        report("warp", essc.isWarpSystemEnabled());
    }

    private void report(String system, boolean enabled) {
        getLogger().info(system + " module: " + (enabled ? "ready" : "disabled"));
    }

    // Hook into the exact moment a home is created...
    @EventHandler
    public void onHomeSet(HomeSetEvent event) {
        getLogger().info(event.getPlayer().getName() + " set home '" + event.getHomeName() + "'");
    }

    // ...a kit is claimed...
    @EventHandler
    public void onKitClaim(KitClaimEvent event) {
        if (event.isCancelled()) return;
        getLogger().info(event.getPlayer().getName() + " claimed kit " + event.getKit().getName());
    }

    // ...and an RTP request is made.
    @EventHandler
    public void onRtpRequest(RtpRequestEvent event) {
        getLogger().info(event.getPlayer().getName() + " requested RTP in " + event.getWorld().getName());
    }
}

Next Homes API Home, HomeManager, and the 7 home events. Next Kits API Kit, KitClaimProfile, KitManager, and 11 events.