> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/for-ultimatequest/development/api.md).

# Developer API

Use a matching source/release artifact and load after UltimateQuest has enabled. The parent revision currently is 0.1.0-SNAPSHOT; install the matching modules into your development repository instead of assuming a public Maven release. The following are statements inside your existing plugin methods; player is an existing online Player:

```yaml
depend: [UltimateQuest]
```

```xml
<dependency>
    <groupId>cn.superiormc.ultimatequest</groupId>
    <artifactId>core</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

```java
import cn.superiormc.ultimatequest.api.progression.ProgressionService;
import cn.superiormc.ultimatequest.managers.QuestManager;

ProgressionService service = QuestManager.questManager.progression();
service.progress(player.getUniqueId(), "battlepass", "example").ifPresent(view -> {
    long total = view.total();
    int level = view.level();
});
service.addExperience(player, "example", 25L);
service.claimAll(player, "battlepass", "example");
AutoCloseable subscription = service.subscribe(event -> {
    String action = event.action();
    String stage = event.stage();
});
```

Close the progression subscription when your plugin disables. ProgressionView contains type, definitionId, season, total, level, and a copied reward-state map. ProgressionEvent contains action, playerId, type, definitionId, season, total, level, stage. progress returns empty if no corresponding loaded instance exists; it does not load offline data. Mutations use the normal validation/persistence path. Run player/world work on the appropriate server/region scheduler.

## Trigger observation and extension

TriggerManager.triggerManager exposes get(String), values(), register(AbstractTrigger\<?>), subscribe(Consumer), and dispatch methods. get accepts namespaced keys, defaulting to ultimatequest. subscribe has no unsubscribe handle in the current API; avoid repeatedly registering long-lived observers and do not retain invalid plugin state.

QuestContext exposes trigger, triggerData, player, source(), target(), block(), brokenBlockState(), triggerItem(), location(), and event(). TriggerData stores typed extras accessed with BuiltinContextKeys. Context may lack a target/item/block; check null/Optional values before use. QuestContext.level() is fixed at 1, not a player's pass level.

A custom trigger implementation extends api.trigger.AbstractTrigger, supplies a unique NamespacedKey/config key/payload type, and implements handle(E, TriggerRuntime). getEventClasses() controls exact routing classes; routing does not automatically match subclasses. Registering a trigger adds it to the manager, but does not automatically install a new Bukkit event listener for your payload: dispatch your event explicitly where needed. A regular event-class dispatch ignores cancelled events; a targeted dispatch must be used deliberately. Runtime emissions require an associated player.

## Conditions, matching, and items

EventConditionsManager.eventConditions.register(AbstractEventCondition) adds an event condition. Implement protected onMatch(ObjectSingleCondition); matches applies not and optional result messages. onUnload/onEntityUnload provide cleanup hooks.

MatchItemManager.matchItemManager.registerNewRule(AbstractMatchItemRule) and MatchEntityManager.matchEntityManager.registerNewRule(AbstractMatchEntityRule) extend matching. Registered rules participate only when configNotContains returns false. ChangesManager.changesManager.register(AbstractChangesRule) extends item changes. Use the current cn.superiormc.ultimatequest packages and existing TextUtil/ErrorManager message paths.

There are no ability factories, Power Modifiers, skill APIs, player-attribute APIs, or custom-enchantment registration APIs in this runtime. See [triggers](/for-ultimatequest/configuration/triggers.md), [conditions](/for-ultimatequest/configuration/conditions.md), and [item changes](/for-ultimatequest/shared-formats/change-item-rules.md).