API Overview

Importing the API

To start using the Polar API, it must be included as a project dependency. Do not shade it. Add https://repo.polar.top/repository/polar/ to the dependency manager:

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

Example

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

            
            <repositories>
                <repository>
                    <id>Polar</id>
                    <url>https://repo.polar.top/repository/polar/</url>
                </repository>
            </repositories>
            
            <dependencies>
                <dependency>
                    <groupId>top.polar</groupId>
                    <artifactId>api</artifactId>
                    <version>2.0.0</version>
                    <scope>provided</scope>
                </dependency>
            </dependencies>
            
        

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

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

Therefore, plugins utilizing the API need to depend on PolarLoader (through plugin.yml).

    @Override
    public void onEnable() {
        top.polar.api.loader.LoaderApi.registerEnableCallback(() -> {
            // Ideally, this logic is implemented in an external class.
            // API access here
            // Listener registration here
            // ... etc
        });
    }

Listening to events

Polar API has a custom-built event system, which is completely independent of Bukkit events.

Events are registered through EventListenerRepository, which is accessible by using the PolarApi reference returned by PolarApiAccessor.

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