Docs

Getting started with the API

PulsePrison exposes an API so other plugins can read and change data, listen to events and add their own content: actions, currencies, enchants and stat sources. It is how addons are built without touching the core.

Public packagedev.aeros.pulseprison.api
API version3 (getApiVersion())
Java17
ServerPaper 1.20.4+

1. Add the dependency

The API ships inside the plugin jar. Copy PulsePrison-2.0.0.jar into a libs/ folder in your project and compile against it without shading it.

Gradle (Kotlin DSL)

kotlin
repositories {
    mavenCentral()
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.20.4-R0.1-SNAPSHOT")
    compileOnly(files("libs/PulsePrison-2.0.0.jar"))
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(17))
}

Maven

xml
<dependency>
    <groupId>dev.aeros</groupId>
    <artifactId>pulseprison</artifactId>
    <version>2.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/PulsePrison-2.0.0.jar</systemPath>
</dependency>

2. Declare PulsePrison in plugin.yml

yaml
name: MyPrisonAddon
version: 1.0.0
main: com.example.addon.MyPrisonAddon
api-version: '1.20'
depend: [PulsePrison]

depend makes your plugin load after PulsePrison. Use softdepend if your plugin also works without it.

3. Get the API

java
import dev.aeros.pulseprison.api.PulsePrisonAPI;
import dev.aeros.pulseprison.api.PulsePrisonProvider;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPrisonAddon extends JavaPlugin {

    private PulsePrisonAPI prison;

    @Override
    public void onEnable() {
        if (!PulsePrisonProvider.isAvailable()) {
            getLogger().severe("PulsePrison is not available");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        prison = PulsePrisonProvider.get();
        if (prison.getApiVersion() < 3) {
            getLogger().severe("This addon needs PulsePrison API 3 or newer");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        getLogger().info("Hooked into PulsePrison " + prison.getVersion());
    }
}

PulsePrison also registers itself in Bukkit's ServicesManager with the PulsePrisonAPI class.

4. Check modules

Services return neutral values when their module is disabled: empty lists, 0 or a 1.0 multiplier. To decide what to offer:

java
if (prison.isModuleEnabled("private-mines")) {
    getServer().getPluginManager().registerEvents(new MineListener(prison), this);
}

Ids: staff-commands, essentials-commands, clans, seasons, pickaxe-system, rankup-system, multipliers, market, skill-tree, rebirth, pets, robots, private-mines, cells, placeables, autominers, afk-blocks, attributes, boosters, milestones, masteries, pickaxe-skins, crystals, armors, abilities.

5. First use

java
UUID id = player.getUniqueId();

String rank = prison.progression().getRank(id);
int pickaxeLevel = prison.pickaxe().getLevel(id);

if (prison.currencies().take(id, "tokens", 5000)) {
    prison.levels().addExperience(player, "mining", 250);
    player.sendMessage("Paid " + prison.currencies().format("tokens", 5000));
}

Stability

  • Everything in dev.aeros.pulseprison.api is public: it won't change shape without raising getApiVersion().
  • The rest of the plugin (managers, menus, models) is internal and may change between versions. Some internal classes are used to extend the core; they are marked advanced in Extending PulsePrison.
  • Call the API from the main thread unless the method says otherwise.

Next

Getting started with the API | PulsePrison Core Docs