Developer API

For plugin developers hooking into Project One. Server owners do not need anything on this page.

Add the dependency

The plugin jar is already on the server at runtime, so depend on it with compileOnly — shading it in would load a second copy of every class.

Gradle (Kotlin)

build.gradle.kts

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

dependencies {
    compileOnly("com.github.1robie:project-one:1.0")
}

Gradle (Groovy)

build.gradle

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

dependencies {
    compileOnly 'com.github.1robie:project-one:1.0'
}

Maven

pom.xml

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

<dependencies>
    <dependency>
        <groupId>com.github.1robie</groupId>
        <artifactId>project-one</artifactId>
        <version>1.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Declare the dependency in plugin.yml

plugin.yml

depend: [ProjectOne]

Use depend if your plugin is useless without it, softdepend if the integration is optional. Either way this guarantees load order — without it your onEnable may run first and the API lookup returns null.

Get the API instance

import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    private ProjectOneApi api;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().getPlugin("ProjectOne") == null) {
            getLogger().severe("ProjectOne not found; disabling.");
            Bukkit.getPluginManager().disablePlugin(this);
            return;
        }
        this.api = Bukkit.getServicesManager().load(ProjectOneApi.class);
    }
}

Resolve the API in onEnable, never in a static initialiser or constructor — the provider is not registered until the plugin enables.

Folia and threading

This plugin supports Folia, which means there is no single main thread.

// Wrong on Folia: throws, because there is no global main thread.
Bukkit.getScheduler().runTask(plugin, () -> block.setType(Material.STONE));

// Correct: schedule on the thread that owns the region.
Bukkit.getRegionScheduler().run(plugin, block.getLocation(), task ->
        block.setType(Material.STONE));

Read values from the API on any thread; anything that mutates the world must run on the owning region's thread. This is the single most common source of bug reports against Folia-compatible plugins, which is why it sits on the first API page rather than a footnote.

Javadoc

Full generated Javadoc has its own page under this section. It is built by JitPack from the tagged release, so it always matches a published version.

Next

• Events — what you can listen to and cancel