> 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/ultimatequest-zhong-wen-wen-dang/kai-fa/api.md).

# 开发 API

依赖匹配源码/发行产物，并在 UltimateQuest 启用后访问。父级 revision 当前为 0.1.0-SNAPSHOT，请将匹配模块安装到开发仓库，不应假定有公开 Maven 发行。以下是现有插件方法内的语句，player 为已有在线 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();
});
```

停用时关闭成长订阅。ProgressionView 包含 type、definitionId、season、total、level 和复制的奖励状态映射；ProgressionEvent 包含 action、playerId、type、definitionId、season、total、level、stage。progress 没有对应已加载实例时返回空，不主动加载离线数据。修改经过正常校验/持久化。玩家/世界操作需在对应服务端/区域调度器执行。

## 触发器观察与扩展

TriggerManager.triggerManager 提供 get(String)、values()、register(AbstractTrigger\<?>)、subscribe(Consumer) 和 dispatch。get 接受命名空间键，默认 ultimatequest。当前 subscribe 不返回退订句柄，避免反复注册长期观察者或保留失效插件状态。

QuestContext 包含 trigger、triggerData、player，以及 source()、target()、block()、brokenBlockState()、triggerItem()、location()、event()。TriggerData 可通过 BuiltinContextKeys 获取类型化附加值。目标/物品/方块可能缺失，应检查 null/Optional。QuestContext.level() 固定为 1，不是玩家战令等级。

自定义触发器继承 api.trigger.AbstractTrigger，提供唯一 NamespacedKey、配置键和载荷类型，实现 handle(E, TriggerRuntime)。getEventClasses() 指定精确路由类，不自动匹配子类。注册仅加入管理器，不会为新载荷自动安装 Bukkit 监听器，需要在事件入口显式 dispatch。普通按事件类派发忽略取消事件，定向派发需调用者审慎使用；运行时发出上下文需要关联玩家。

## 条件、匹配与物品

EventConditionsManager.eventConditions.register(AbstractEventCondition) 注册事件条件，实现 protected onMatch(ObjectSingleCondition)，matches 负责 not 和结果提示。onUnload/onEntityUnload 用于清理。

MatchItemManager.matchItemManager.registerNewRule(AbstractMatchItemRule)、MatchEntityManager.matchEntityManager.registerNewRule(AbstractMatchEntityRule) 扩展匹配，仅 configNotContains 为 false 时参与。ChangesManager.changesManager.register(AbstractChangesRule) 扩展物品修改。使用当前 cn.superiormc.ultimatequest 包和既有 TextUtil/ErrorManager 消息入口。

当前运行时不提供能力工厂、Power Modifier、技能、玩家属性或自定义附魔注册 API。见[触发器](/ultimatequest-zhong-wen-wen-dang/pei-zhi/triggers.md)、[条件](/ultimatequest-zhong-wen-wen-dang/pei-zhi/conditions.md)、[物品修改](/ultimatequest-zhong-wen-wen-dang/gong-gong-ge-shi/change-item-rules.md)。