API

Developer API Guide

The API allows developers to access the global Player leveler and assign players XP or a specific level. You can also register Custom reward types and reward auto-correctors.

Add the API to your project

Maven (not recommended)

I won't help you if you use Maven. Use gradle. You might also need to include Aikars ACF repo when you use maven.

pom.xml

<repository>
    <id>auroramc</id>
    <url>https://repo.auroramc.gg/releases/</url>
</repository>

pom.xml

<dependency>
    <groupId>gg.auroramc</groupId>
    <artifactId>AuroraLevels</artifactId>
    <version>{VERSION}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>gg.auroramc</groupId>
    <artifactId>Aurora</artifactId>
    <version>{VERSION}</version>
    <scope>provided</scope>
</dependency>

Gradle (Groovy)

build.gradle

repositories {
    maven {
        url "https://repo.auroramc.gg/releases/"
    }
}

dependencies {
    compileOnly 'gg.auroramc:Aurora:{VERSION}'
    compileOnly 'gg.auroramc:AuroraLevels:{VERSION}'
}

Gradle (Kotlin)

build.gradle.kts

repositories { 
    maven("https://repo.auroramc.gg/releases/")
}

dependencies { 
    compileOnly("gg.auroramc:Aurora:{VERSION}")
    compileOnly("gg.auroramc:AuroraLevels:{VERSION}")
}

Get the API instance

Add AuroraLevels to the depend (or softdepend) list of your plugin.yml. The leveler is available once AuroraLevels is enabled, so get it in your onEnable or later.

import gg.auroramc.levels.api.AuroraLevelsProvider;
import gg.auroramc.levels.api.leveler.Leveler;

Leveler leveler = AuroraLevelsProvider.getLeveler();

Read player data

import gg.auroramc.levels.api.data.LevelData;

LevelData data = leveler.getUserData(player);

int level = data.getLevel();
// XP collected in the current level (can be a decimal number)
double currentXp = data.getCurrentXP();

// XP needed to reach the next level from the current level (full amount)
double required = leveler.getRequiredXpForLevelUp(player);
// XP the xp-formula gives for a given level
double xpForLevel25 = leveler.getXpForLevel(25);

The player's data is loaded asynchronously by AuroraLib, so check AuroraAPI.getUser(player.getUniqueId()).isLoaded() before reading or changing it.

Add XP to a player

Player player = ...;
double xp = ...;

// Returns the XP that was actually added (after PlayerXpGainEvent listeners changed it)
// Returns 0 if the player has no aurora.levels.use permission, is at max level,
// or the event was cancelled
double added = leveler.addXpToPlayer(player, xp);

// Or set the player level to something (rewards for the new levels are given)
int newLevel = 10;

leveler.setPlayerLevel(player, newLevel);

// Set the level without rewards, notifications and events (for testing only)
leveler.setPlayerLevelRaw(player, newLevel);

Only call addXpToPlayer from the main thread or from the global region scheduler (on Folia).

Add custom reward types

Example command reward. (This is already implemented.)

import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.entity.Player;
import gg.auroramc.aurora.api.command.CommandDispatcher;
import gg.auroramc.aurora.api.message.Placeholder;
import gg.auroramc.aurora.api.reward.AbstractReward;

import java.util.List;

public class CommandReward extends AbstractReward {
    private String command;

    @Override
    public void execute(Player player, long level, List<Placeholder<?>> placeholders) {
        if (command == null) return;
        CommandDispatcher.dispatch(player, command, placeholders);
    }

    @Override
    public void init(ConfigurationSection args) {
        // Always call super.init here!
        super.init(args);
        command = args.getString("command", null);
    }
}

Example money reward. (This is already implemented.)

import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.entity.Player;
import gg.auroramc.aurora.api.command.CommandDispatcher;
import gg.auroramc.aurora.api.message.Placeholder;
import gg.auroramc.aurora.api.AuroraAPI;
import gg.auroramc.aurora.api.reward.NumberReward;

import java.util.List;

public class MoneyReward extends NumberReward {
    private String economy;

    @Override
    public void execute(Player player, long level, List<Placeholder<?>> placeholders) {
        var econ = AuroraAPI.getEconomy(economy);
        if(econ == null) econ = AuroraAPI.getDefaultEconomy();

        econ.deposit(player, getValue(placeholders));
    }

    @Override
    public void init(ConfigurationSection args) {
        super.init(args);
        economy = args.getString("economy", "Vault");
    }
}

Register your rewards (This has to happen on your plugins onEnable lifecycle method)

import gg.auroramc.aurora.api.reward.RewardFactory;
import gg.auroramc.aurora.api.util.NamespacedId;

RewardFactory factory = leveler.getRewardFactory();
// This will be an available reward type in config
// Just use plugin-name/reward-name to reference it.
factory.registerRewardType(NamespacedId.of("plugin-name", "reward-name"), YourRewardClass.class);

import gg.auroramc.aurora.api.reward.RewardCorrector;
import org.bukkit.entity.Player;

public class MyCorrector implements RewardCorrector {
    @Override
    public void correctRewards(Player player) {
      // do your thing
    }
}

Correctors run when a player's data is loaded (on join) and for every online player after /level reload.

leveler.getRewardAutoCorrector()
    .registerCorrector(NamespacedId.of("plugin-name", "corrector-name"), new MyCorrector());

Events

Both events can be fired asynchronously, depending on which thread the XP or level change happened.

PlayerXpGainEvent

Called before a player gains XP. You can cancel it, or change the amount of XP with setXp, for example to make XP boosters.

import gg.auroramc.levels.api.event.PlayerXpGainEvent;

@EventHandler
public void onXpGain(PlayerXpGainEvent event) {
    if (event.getPlayer().hasPermission("myplugin.xpboost")) {
        event.setXp(event.getXp() * 2);
    }
}

PlayerLevelUpEvent

Called after a player reached a new level. getLevel() returns the new level. If the player gains several levels at once, it is called once for every level, in order. It is also called when the level is changed with setPlayerLevel or /level set; if the level was lowered, it is called once with the new level.

import gg.auroramc.levels.api.event.PlayerLevelUpEvent;

@EventHandler
public void onLevelUp(PlayerLevelUpEvent event) {
    Player player = event.getPlayer();
    long level = event.getLevel();
}