API

Developer API Guide

The API allows developers to access registered quests and to progress quests/quest pools for players. You can also create your own custom objectives and register Custom reward types, reward auto-correctors.

This guide assumes you are using 2.0+

Add the API to your project

Maven

You might also need to include Aikars ACF repo if you are using maven.

pom.xml

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

pom.xml

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

Gradle (Kotlin)

build.gradle.kts

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

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

Get the API instance

The instance is only available after onLoad was called on AuroraQuests by your server software's plugin loader.

import gg.auroramc.quests.api.AuroraQuestsPlugin;
import gg.auroramc.quests.api.profile.ProfileManager;
import gg.auroramc.quests.api.questpool.QuestPool;
import gg.auroramc.quests.api.quest.Quest;
import gg.auroramc.quests.api.objective.Objective;

AuroraQuestsPlugin quests = AuroraQuestsPlugin.inst();

// Get the profile manager
ProfileManager manager = quests.getProfileManager(); 

// Get an online player's profile
Profile profile = manager.getProfile(player);

// From here you can get a specific quest pool or all of them from the online profile
QuestPool questPool = profile.getQuestPool(stringId);
Collection<QuestPool> pools = profile.getQuestPools();

// Get all the unlocked global quests or the rolled timed quests from the pool
List<Quest> activeQuests = questPool.getActiveQuests();
// Get all quests in the pool
Collection<Quest> quests = questPool.getQuest();
// Get quest by id
Quest quest = questPool.getQuest(stringId);

// Get the objective list from a quest
List<Objective> objectives = quest.getObjectives();

You can view how to add Custom rewards and correctors for them here. However, you will need to register them through the PoolManager. PoolManager is only initialized after onEnable was called. So you should properly declare you dependency on AuroraQuests and register rewards in your plugin onEnable .

Creating a custom objective

For now, you can look at the source code by clicking here to see how an objective looks like. The onEvent should be used when you interact with bukkit events. This runs through an optimized internal event bus since objectives are per player based. If an Event is a PlayerEvent it will be automatically filtered for your callback handler, meaning it will be only invoked when the player matches the player the objective is atteched to.

TypedObjective and StringTypedObjective are a bit nicer to use than just extending the Objective class.

Make sure to register your Objective in your plugin's onLoad method using:

ObjectiveFactory.registerObjective("objective-id", MyObjective.class);

Progressing built-in objectives

Calling API events

By calling our provided API events you can progress all objectives in every quest pool for a player automatically. A bunch of built-in objectives support this.

• BLOCK_BREAK, BUILD - PlayerBreakCustomBlockEvent

• BLOCK_PLACE, BUILD - PlayerPlaceCustomBlockEvent

• FISH - PlayerCaughtFishEvent

• COMPLETE_DUNGEON - PlayerCompleteDungeonEvent

• CRAFT - PlayerCraftedItemEvent

• SELL_WORTH - PlayerEarnFromSellEvent

• SELL - PlayerSellItemEvent

• BUY - PlayerPurchaseItemEvent

• BUY_WORTH - PlayerSpendOnPurchaseEvent

• ENTER_REGION - PlayerEnterRegionEvent

• INTERACT_NPC - PlayerInteractNPC

• MOB_KILL - PlayerKillMobEvent

• BLOCK_LOOT, FARM, ENTITY_LOOT - PlayerLootEvent

• TAKE_ITEM - PlayerTakeItemEvent

• UPGRADE_ISLAND - PlayerUpgradeIslandEvent

• JOIN_ISLAND - PlayerJoinIslandEvent

• REACH_ISLAND_LEVEL - PlayerIslandLevelChangeEvent

• REACH_ISLAND_WORTH - PlayerIslandWorthChangeEvent

You should always use the event based approach when you can.

Manual objective progress

I assume you read the previous sections, so you can get the list of objectives you want to progress.

Let's say, you want to progress all CONSUME objectives.

// Get the objective list from a quest
List<Objective> objectives = quest.getObjectives();

for (Objective objective : objectives) {
  if (objective instanceof ConsumeObjective consumeObjective) {
    int amount = 10;
    // Since ConsumeObjective extends TypedObjective (like most of the objectives)
    // we can call the helper method to create a meta object. Objective filters will
    // check this meta. Meta is required.
    ObjectiveMeta meta = consumeObjective.meta(new TypeId("minecraft", "chicken"))
    consumeObjective.progress(10, meta)
  }
}