API

Developer API Guide

The API allows developers to access registered collections and to progress collections for players. You can also register Custom reward types and reward auto-correctors.

Add the API to your project

Maven

pom.xml

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

pom.xml

<dependency>
    <groupId>gg.auroramc</groupId>
    <artifactId>AuroraCollections</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:AuroraCollections:{VERSION}'
}

Gradle (Kotlin)

build.gradle.kts

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

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

Get the API instance

import gg.auroramc.collections.api.AuroraCollectionsProvider;
import gg.auroramc.collections.collection.CollectionManager;

CollectionManager manager = AuroraCollectionsProvider.getCollectionManager();

The collection manager is only available after AuroraCollections is enabled, so declare a dependency on AuroraCollections and use it in (or after) your plugin's onEnable.

You can view how to add Custom rewards and correctors for them API. Though you will need to register them through the CollectionManager:

manager.getRewardFactory().registerRewardType(NamespacedId.fromDefault("my_reward"), MyReward.class);
manager.getRewardAutoCorrector().registerCorrector(NamespacedId.fromDefault("my_reward"), new MyRewardCorrector());

Reading collections

// Every category and collection
java.util.Collection<Category> categories = manager.getCategories();
List<Collection> all = manager.getAllCollections();
List<Collection> farming = manager.getCollectionsByCategory("farming");

// A single collection by category id and collection id (file name)
Collection wheat = manager.getCollection("farming", "wheat");

int level = wheat.getPlayerLevel(player);
Long collected = wheat.getCount(player);
int maxLevel = wheat.getMaxLevel();

// Category level/completion (sum of the collection levels inside the category)
int categoryLevel = manager.getCategoryLevel("farming", player);
double completion = manager.getCategoryCompletionPercent("farming", player); // 0.0 - 1.0

Progressing collections

This will progress all collections with the block_loot trigger with the given item. The available trigger names are constants in the gg.auroramc.collections.collection.Trigger class. You can pass multiple triggers, the first one a collection uses will be applied.

ItemStack myItem = ...;
TypeId typeId = AuroraAPI.getItemManager().resolveId(myItem);
int amount = myItem.getAmount();

manager.progressCollections(player, typeId, amount, Trigger.BLOCK_LOOT);

You can also progress a single collection directly. This ignores the collection's triggers and types:

Collection collection = manager.getCollection("mining", "diamond");
collection.progress(player, null, 10, null);

Events

CollectionLevelUpEvent is called for every level a player reaches in a collection. It can be called asynchronously, so check event.isAsynchronous() before touching things that require the main thread.

import gg.auroramc.collections.api.event.CollectionLevelUpEvent;

@EventHandler
public void onLevelUp(CollectionLevelUpEvent event) {
    Player player = event.getPlayer();
    Collection collection = event.getCollection();
    long level = event.getLevel();
}