# API

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.

{% code title="pom.xml" %}

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

{% endcode %}

{% code title="pom.xml" %}

```markup
<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>
```

{% endcode %}

### Gradle (Groovy)

{% code title="build.gradle" %}

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

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

{% endcode %}

### Gradle (Kotlin)

{% code title="build.gradle.kts" %}

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

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

{% endcode %}

## Get the API instance

```java
Leveler leveler = AuroraLevelsProvider.getLeveler()
```

### Add XP to a player

```java
Player player = ...;
double xp = ...;

leveler.addXpToPlayer(player, xp);

// Or set the player level to something
long newLevel = 10;

leveler.setPlayerLevel(player, newLevel);
```

### Add custom reward types

Example command reward. (This is already implemented.) &#x20;

<pre class="language-java"><code class="lang-java">import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.entity.Player;
<strong>import gg.auroramc.aurora.api.command.CommandDispatcher;
</strong>import gg.auroramc.aurora.api.message.Placeholder;
import gg.auroramc.aurora.api.reward.AbstractReward;

import java.util.List;
<strong>
</strong><strong>public class CommandReward extends AbstractReward {
</strong>    private String command;

    @Override
    public void execute(Player player, long level, List&#x3C;Placeholder&#x3C;?>> 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);
    }
}
</code></pre>

Example money reward. (This is already implemented.)

```java
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)

```java
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);
```

Register a reward corrector (This has to happen on your plugins `onEnable` lifecycle method)

```java
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
    }
}
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.auroramc.gg/auroralevels/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.