Developer API

The plugin exposes a small API for other plugins: you can add your own objective triggers, reward types, register quests from code, listen to leveling events and modify per-player limits. This page assumes you're comfortable writing a Bukkit plugin.

Setup

Maven

<repository>
  <id>MonGens-Cave</id>
  <url>https://repo.mongenscave.com/releases<repository></url>
</repository>

<dependency>
  <groupId>com.mongenscave</groupId>
  <artifactId>mc-QuestAPI</artifactId>
  <version>[VERSION]</version>
</dependency>

Gradle

maven { url "https://repo.mongenscave.com/releases" }

implementation "com.mongenscave:mc-QuestAPI:[VERSION]"

And depend on the plugin in your plugin.yml so it loads first:

depend: [mc-Quests]

The entry point is a static accessor, available from onLoad() onward:

QuestAPI api = McQuests.getApi();

The API at a glance

public interface IQuestAPI {
    void registerObjective(ObjectiveHandler handler);
    void registerCondition(ConditionHandler handler);
    void registerReward(RewardHandler handler);
    void registerQuest(QuestDefinition quest);
    void giveQuest(Player player, String questId);
    void trigger(Player player, ObjectiveTrigger trigger, Object context);
}

Custom objective triggers

This is the most useful extension point: it lets quest creators use your plugin's actions in quests.yml, just like the built-in triggers.

A trigger has two halves — an ObjectiveHandler that knows how to match and count an action, and a call to api.trigger(...) that fires when the action happens.

1. Implement the handler

public final class VoteObjective implements ObjectiveHandler {

    public static final ObjectiveTrigger VOTE = new ObjectiveTrigger("vote");

    @Override
    public ObjectiveTrigger trigger() {
        return VOTE;
    }

    @Override
    public boolean matches(String target, Object context) {
        if (!(context instanceof VoteContext vote)) return false;
        if (target == null || target.equalsIgnoreCase("any")) return true;

        return vote.serviceName().equalsIgnoreCase(target);
    }

    @Override
    public int progress(Object context) {
        return 1;
    }

    public record VoteContext(String serviceName) {}
}

• trigger() — the trigger's ID. It's what quest creators write in the trigger: field (IDs are lowercased automatically).

• matches(target, context) — decides whether this event counts for an objective with the given target. The context is whatever object you pass to api.trigger(...); a small record is the usual pattern.

• progress(context) — how much progress the event is worth. Return 1 for count-based objectives, or an amount (damage, money, items) for total-based ones.

2. Register it and fire it

@Override
public void onEnable() {
    McQuests.getApi().registerObjective(new VoteObjective());
}

@EventHandler
public void onVote(VotifierEvent event) {
    Player player = Bukkit.getPlayerExact(event.getVote().getUsername());
    if (player == null) return;

    McQuests.getApi().trigger(player, VoteObjective.VOTE,
            new VoteObjective.VoteContext(event.getVote().getServiceName()));
}

3. Use it in quests.yml

objectives:
  voter:
    name: "&#B8FFF2&lSupporter"
    trigger: vote
    target: any
    required: 3

How a trigger call flows

api.trigger(player, trigger, context) only affects the given player, and only their active quests. For each active quest, every objective whose trigger: matches the trigger ID is tested with matches(...); on a match, progress(...) is added (capped at required). Progress messages, objective/quest completion and rewards are all handled for you.

Custom rewards

A RewardHandler adds a new type: for the rewards: section:

public final class LootboxReward implements RewardHandler {

    @Override
    public String type() {
        return "lootbox";
    }

    @Override
    public void give(Player player, String value) {
        MyLootboxPlugin.give(player, value);
    }
}

McQuests.getApi().registerReward(new LootboxReward());

rewards:
  - type: lootbox
    display-name: "&#FFD86E1x Rare Lootbox"
    value: rare

The value arrives as the raw string from the config — parsing (amounts, : separators) is up to you.

Custom conditions

The ConditionHandler interface mirrors rewards — type() plus a check(player, value) that returns whether the player may accept the quest:

public final class TownyCondition implements ConditionHandler {

    @Override
    public String type() {
        return "town";
    }

    @Override
    public boolean check(Player player, String value) {
        return TownyAPI.getInstance().getTown(value).hasResident(player.getName());
    }
}

Condition registration is currently a stub: quest-accept checks only evaluate the built-in permission and world conditions, so handlers registered through registerCondition(...) are not consulted yet. Register them for forward compatibility, but don't rely on them gating quests today.

Registering quests from code

registerQuest(...) adds a quest built with QuestDefinition.builder() — the same model the YAML loader produces:

QuestDefinition quest = QuestDefinition.builder()
        .id("event_boss_hunt")
        .level(10)
        .daily(false)
        .objectives(List.of(
                ObjectiveDefinition.builder()
                        .id("kill_boss")
                        .trigger("kill_mythic_mob")
                        .target("EventBoss")
                        .requiredAmount(1)
                        .name("&#FF6B6BSlay the Event Boss")
                        .description(List.of("&7Defeat the boss before it escapes."))
                        .build()))
        .conditions(List.of())
        .rewards(List.of(
                RewardDefinition.builder()
                        .type("quest_xp")
                        .value("500")
                        .build()))
        .acceptExpire(-1)
        .activeExpire(30 * 60 * 1000L)
        .build();

McQuests.getApi().registerQuest(quest);

Note that acceptExpire/activeExpire are milliseconds here (-1 = no limit), unlike the seconds used in quests.yml.

/quests reload rebuilds the quest list from quests.yml, which wipes code-registered quests. If your quests must survive reloads, re-register them — or ship them as YAML and only use the API for the trigger/reward logic.

To hand a quest to a player programmatically:

McQuests.getApi().giveQuest(player, "event_boss_hunt");

This goes through the same pipeline as clicking the quest board — limits and conditions are checked, so it can fail silently. For unconditional grants, mirror the /quests force give admin command instead.

Events

Two Bukkit events cover the leveling system:

PlayerXpGainEvent

Fires before quest XP is applied. Cancellable, and the amount is mutable — this is the hook for custom XP boosters:

@EventHandler
public void onXpGain(PlayerXpGainEvent event) {
    if (event.getPlayer().hasPermission("myserver.booster")) {
        event.setAmount(event.getAmount() * 2);
    }
}

Getters: getPlayer(), getAmount() / setAmount(double), getOriginalAmount(), getLevel(), getCurrentXp().

PlayerLevelUpEvent

Fires once per level gained (a big XP grant can fire it several times in a row). Not cancellable — it's a notification:

@EventHandler
public void onLevelUp(PlayerLevelUpEvent event) {
    broadcastMilestone(event.getPlayer(), event.getNewLevel());
}

Getters: getPlayer(), getOldLevel(), getNewLevel().

Per-player stat modifiers

A QuestUserModifier lets you adjust a player's computed limits and multipliers — the same numbers the level bonuses and premium pass feed into:

McQuests.getInstance().getModifiers().add((player, user) -> {
    if (player.hasPermission("myserver.mvp")) {
        user.setDailyBoardSize(user.getDailyBoardSize() + 1);
        user.setXpMultiplier(user.getXpMultiplier() * 1.1);
    }
});

The MutableQuestUser exposes maxAccepted, maxActive, dailyBoardSize, xpMultiplier and rewardMultiplier. Modifiers run after the base + per-level values are computed; premium bonuses are applied on top of the result.

The computed user object is cached. If your modifier's inputs change at runtime (a rank purchase, a toggled booster), call McQuests.getInstance().getQuestUserService().invalidate(player) to force a rebuild.

Built-in trigger constants

All built-in trigger IDs are available as constants in com.mongenscave.mcquests.api.trigger.Triggers (Triggers.BLOCK_BREAK, Triggers.KILL_MYTHIC_MOB, ...). Use them instead of constructing ObjectiveTrigger by hand when firing or comparing built-in triggers — see How to Create a Quest for the full list and their semantics.