API Overview

Importing the API

To start using the Polar API, you need to include it as your project dependency. Do not shade it. Add https://repo.polar.top/repository/polar/ to your dependency manager:

groupId = "top.polar"
artifactId = "api"
version = "2.0.0"

Gradle example

repositories {
    maven {
        url = uri("https://repo.polar.top/repository/polar/")
    }
}

dependencies {
    compileOnly("top.polar:api:2.0.0")
}

Basic usage

The top.polar.api.PolarApiAccessor class is a convenient way to access the Polar API object. It provides a method to retrieve the PolarApi object supplied as a WeakReference.

try {
    var weakApi = top.polar.api.PolarApiAccessor.access();
} catch (PolarNotLoadedException __) {
    log.error("Api access violation - Polar Anticheat was not loaded");
}

Important nuances regarding events

Polar API provides a flexible and robust event system to handle various server events. Events are represented by the PolarApiEvent class, and the API defines a hierarchy of event classes that extend from it.

Polar class loading strategy

Polar classes are loaded asynchronously to Bukkit main thread. There may be a condition, at which, a plugin dependent on Polar was already loaded, but the PolarApiAccessor class has not been loaded yet.

PolarLoader plugin includes a LoaderApi class, allowing to set up a preliminary listener, which is called the moment Polar is loaded completely.

To do so, make your API-dependant plugin depend on PolarLoader (through plugin.yml).

    @Override
    public void onEnable() {
        top.polar.api.loader.LoaderApi.registerEnableCallback(() -> {
            log.info("Your callback here");
            
            // Api access here
            // Listener registration here
            // ... etc
        });
    }

Listening to events

Polar Api has a custom-built event system, which is completely independent of the Bukkit one.

Events are registered through EventListenerRepository, which is accessible through the Events class, which is accessible through PolarApi.

var listener = api.events().repository().registerListener(...);