api.godlycow.org / EssentialsC

EssentialsC API

The Java API for EssentialsC - homes, kits, RTP, and warps behind one thread-safe entry point.

Overview

EssentialsC ships a stable, versioned Java API so other plugins can work with its systems without digging into internals. Everything lives in net.godlycow.org.essc.api, split into four areas:

Module Manages Events Reference
home Player homes - create, delete, fetch, and teleport. 7 Homes API
kit Kit definitions, claim profiles, cooldowns, and the claim flow. 11 Kits API
rtp Random teleportation - requests, warmups, search, and results. 9 RTP API
warp Warp definitions, categories, costs, and teleport state. 0 Warps API

Each system fires Bukkit events (27 total across homes, kits, and RTP) so you can hook in right when something happens - and cancel it if you need to. Warps don't fire events for now; they expose a fully async read/write manager instead.

Current version: 4.2.7.1. Every system can be disabled in the plugin config, so check the matching flag before using a manager - isHomeSystemEnabled(), isKitSystemEnabled(), isRtpSystemEnabled(), and isWarpSystemEnabled().

Requirements

Thin layer over the Bukkit API, compiled against Paper. It needs the same runtime as the plugin.

Dependency Version Required
Paper / Folia 1.20 or newer Required
Java 21 or newer Required
EssentialsC plugin 4.2.7.1 or newer (runtime) Required
Paper API (compile) 1.21.1 Required
Vault / PAPI / LuckPerms - Optional
The plugin provides the API at runtime. You compile against the api artifact, but it only registers once EssentialsC has enabled. If EssentialsC is missing, APIProvider.get() throws and APIProvider.isAvailable() returns false. Always check availability first.

Installing the API

The API is published to JitPack. Add the repository and a compileOnly (Maven: provided) dependency - EssentialsC already bundles it at runtime, so you never ship it with your plugin.

Maven

pom.xml 
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.GodlyCow203.EssentialsC</groupId>
        <artifactId>api</artifactId>
        <version>4.2.7.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Groovy)

build.gradle 
repositories {
    maven { url = 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.GodlyCow203.EssentialsC:api:4.2.7.1'
}

Gradle (Kotlin DSL)

build.gradle.kts 
repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.GodlyCow203.EssentialsC:api:4.2.7.1")
}

Plugin setup

Your plugin talks to EssentialsC from onEnable(), so it needs to load after EssentialsC. Declare a soft dependency in plugin.yml and the server orders things for you:

plugin.yml 
name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '1.20'

softdepend:
 - EssentialsC
Prefer softdepend so the game still starts without EssentialsC, but always guard API access with APIProvider.isAvailable(). Or use depend to hard-require EssentialsC and refuse to start without it.

First code

Grab the singleton, check which systems are enabled on your server, then start using the managers. A minimal bootstrap:

MyPlugin.java 
package com.example.myplugin;

import net.godlycow.org.essc.api.APIProvider;
import net.godlycow.org.essc.api.EssentialsCAPI;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    private EssentialsCAPI essc;

    @Override
    public void onEnable() {
        if (!APIProvider.isAvailable()) {
            getLogger().warning("EssentialsC is not installed - features disabled.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        this.essc = APIProvider.get();

        getLogger().info("Connected to EssentialsC API v" + essc.getApiVersion());
        getLogger().info("Homes " + (essc.isHomeSystemEnabled() ? "enabled" : "disabled"));
        getLogger().info("Kits  " + (essc.isKitSystemEnabled() ? "enabled" : "disabled"));
        getLogger().info("RTP   " + (essc.isRtpSystemEnabled() ? "enabled" : "disabled"));
        getLogger().info("Warps " + (essc.isWarpSystemEnabled() ? "enabled" : "disabled"));
    }

    public EssentialsCAPI essc() {
        return essc;
    }
}

Once you have the EssentialsCAPI reference, every manager is one call away:

ManagerQuickstart.java 
EssentialsCAPI api = APIProvider.get();

// Each manager is a singleton bound to the plugin lifecycle.
HomeManager homes  = api.getHomeManager();
KitManager  kits   = api.getKitManager();
RtpManager  rtp    = api.getRtpManager();
WarpManager warps  = api.getWarpManager();

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.

Service locator

Resolve the API in onEnable(), fail fast, and expose it behind your own service:

EsscBridge.java 
public final class EsscBridge {

    private static EssentialsCAPI api;

    private EsscBridge() {}

    /** Returns true if EssentialsC is present and the API is ready. */
    public static boolean init() {
        if (!APIProvider.isAvailable()) {
            return false;
        }
        api = APIProvider.get();
        return true;
    }

    public static EssentialsCAPI api() {
        if (api == null) {
            throw new IllegalStateException("EssentialsC API not initialised");
        }
        return api;
    }

    public static boolean ready() {
        return api != null;
    }
}

Feature-flag guard

Systems can be disabled in the config. Check the matching flag before touching a manager so you never work against a disabled system:

FeatureReport.java 
EssentialsCAPI api = APIProvider.get();

System.out.println("API version : " + api.getApiVersion());
System.out.println("Homes module: " + (api.isHomeSystemEnabled() ? "ready" : "disabled"));
System.out.println("Kits  module: " + (api.isKitSystemEnabled()  ? "ready" : "disabled"));
System.out.println("RTP   module: " + (api.isRtpSystemEnabled()  ? "ready" : "disabled"));
System.out.println("Warps module: " + (api.isWarpSystemEnabled() ? "ready" : "disabled"));
Cache it once. Managers are singletons bound to EssentialsC's lifecycle. Store APIProvider.get() in a final field at enable and pass it around.