> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 开发者 API
**需要专业版许可证**
开发者 API 仅在**专业版**许可证下可用。标准版用户调用 `ArcPassProvider.isLoaded()` 将返回 `false`。您可以随时在 [许可证中心](https://license.kitemc.com/products/arcpass) 升级。
ArcPass 提供完整的 API 供第三方插件集成和扩展。
API 概述
ArcPass API 模块 (`arcpass-api`) 采用 MIT 许可证开源，可自由使用。
功能
* 获取和修改玩家数据
* 查询通行证、任务、奖励信息
* 管理赛季系统
* 监听各种事件
* 触发自定义任务进度
文档目录
添加依赖和基本使用
监听 ArcPass 事件
常见场景代码示例
快速开始
添加依赖
**Maven**
```xml theme={null}
github
https://maven.pkg.github.com/KiteMC/ArcPass
com.kitemc
arcpass-api
1.9.4
provided
```
**Gradle (Kotlin DSL)**
```kotlin theme={null}
repositories {
maven {
url = uri("https://maven.pkg.github.com/KiteMC/ArcPass")
}
}
dependencies {
compileOnly("com.kitemc:arcpass-api:1.9.4")
}
```
获取 API 实例
```java theme={null}
import com.kitemc.arcpass.api.ArcPassAPI;
import com.kitemc.arcpass.api.ArcPassProvider;
// 获取 API 实例
ArcPassAPI api = ArcPassProvider.get();
```
基本示例
```java theme={null}
// 获取玩家等级
api.getPlayerData(player.getUniqueId())
.thenAccept(optionalData -> {
optionalData.ifPresent(data -> {
int level = data.getLevel();
long exp = data.getTotalExperience();
player.sendMessage("你的等级: " + level);
});
});
// 给予经验
api.addExperience(player.getUniqueId(), 100)
.thenAccept(newTotal -> {
player.sendMessage("获得 100 经验！总经验: " + newTotal);
});
```
API 接口
ArcPassAPI
主要 API 接口，提供以下功能：
```java theme={null}
public interface ArcPassAPI {
// 玩家数据
CompletableFuture> getPlayerData(UUID playerId);
PlayerData getPlayerDataIfCached(UUID playerId);
CompletableFuture addExperience(UUID playerId, long amount);
CompletableFuture claimReward(UUID playerId, int level, String tierId);
// 通行证系统
Collection getPasses();
Optional getPass(String passId);
Pass getDefaultPass();
// 任务系统
Collection getActiveQuests(UUID playerId);
CompletableFuture completeQuest(UUID playerId, String questId);
void triggerCustomEvent(UUID playerId, String eventId, Object data);
// 赛季系统
Optional getCurrentSeason();
CompletableFuture startNewSeason(String seasonId);
CompletableFuture endSeason();
// 工具
void reload();
String getVersion();
}
```
数据模型
PlayerData
玩家数据接口：
```java theme={null}
public interface PlayerData {
UUID getPlayerId();
int getLevel();
long getTotalExperience();
long getCurrentLevelExperience();
long getExperienceToNextLevel();
Set getUnlockedTiers();
boolean hasTier(String tierId);
Set getCompletedQuests();
boolean hasCompletedQuest(String questId);
Set getClaimedRewards();
boolean hasClaimedReward(int level, String tierId);
}
```
Pass
通行证接口：
```java theme={null}
public interface Pass {
String getId();
String getDisplayName();
List getDescription();
int getMaxLevel();
long getExperienceForLevel(int level);
Collection getTiers();
Optional getTier(String tierId);
Optional getLevel(int level);
}
```
Quest
任务接口：
```java theme={null}
public interface Quest {
String getId();
String getDisplayName();
String getDescription();
QuestType getType();
int getExperienceReward();
List getObjectives();
List getConditions();
}
```
Season
赛季接口：
```java theme={null}
public interface Season {
String getId();
String getDisplayName();
int getSeasonNumber();
SeasonStatus getStatus();
long getStartTime();
long getEndTime();
long getTimeRemainingSeconds();
boolean isActive();
}
```
异步操作
ArcPass API 大量使用 `CompletableFuture` 处理异步操作：
```java theme={null}
// 正确的异步处理方式
api.getPlayerData(playerId)
.thenAccept(data -> {
// 在异步线程处理数据
})
.exceptionally(ex -> {
// 处理异常
plugin.getLogger().warning("获取数据失败: " + ex.getMessage());
return null;
});
// 如果需要在主线程更新
api.getPlayerData(playerId)
.thenAccept(data -> {
Bukkit.getScheduler().runTask(plugin, () -> {
// 在主线程更新 UI 或发送消息
});
});
```
线程安全
* API 方法可以从任何线程调用
* 返回的数据对象是不可变的或线程安全的
* `CompletableFuture` 的回调可能在任意线程执行
下一步
完整的入门教程
事件监听和处理
实用代码示例
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.