需要专业版许可证开发者 API 仅在专业版许可证下可用。标准版用户调用
ArcPassProvider.isLoaded() 将返回 false。您可以随时在 许可证中心 升级。API 概述
ArcPass API 模块 (arcpass-api) 采用 MIT 许可证开源，可自由使用。
功能
- 获取和修改玩家数据
- 查询通行证、任务、奖励信息
- 管理赛季系统
- 监听各种事件
- 触发自定义任务进度
文档目录
API 入门
添加依赖和基本使用
事件系统
监听 ArcPass 事件
代码示例
常见场景代码示例
快速开始
添加依赖
Maven<repository>
<id>github</id>
<url>https://maven.pkg.github.com/KiteMC/ArcPass</url>
</repository>
<dependency>
<groupId>com.kitemc</groupId>
<artifactId>arcpass-api</artifactId>
<version>1.9.4</version>
<scope>provided</scope>
</dependency>
repositories {
maven {
url = uri("https://maven.pkg.github.com/KiteMC/ArcPass")
}
}
dependencies {
compileOnly("com.kitemc:arcpass-api:1.9.4")
}
获取 API 实例
import com.kitemc.arcpass.api.ArcPassAPI;
import com.kitemc.arcpass.api.ArcPassProvider;
// 获取 API 实例
ArcPassAPI api = ArcPassProvider.get();
基本示例
// 获取玩家等级
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 接口，提供以下功能：public interface ArcPassAPI {
// 玩家数据
CompletableFuture<Optional<PlayerData>> getPlayerData(UUID playerId);
PlayerData getPlayerDataIfCached(UUID playerId);
CompletableFuture<Long> addExperience(UUID playerId, long amount);
CompletableFuture<Boolean> claimReward(UUID playerId, int level, String tierId);
// 通行证系统
Collection<Pass> getPasses();
Optional<Pass> getPass(String passId);
Pass getDefaultPass();
// 任务系统
Collection<Quest> getActiveQuests(UUID playerId);
CompletableFuture<Boolean> completeQuest(UUID playerId, String questId);
void triggerCustomEvent(UUID playerId, String eventId, Object data);
// 赛季系统
Optional<Season> getCurrentSeason();
CompletableFuture<Boolean> startNewSeason(String seasonId);
CompletableFuture<Boolean> endSeason();
// 工具
void reload();
String getVersion();
}
数据模型
PlayerData
玩家数据接口：public interface PlayerData {
UUID getPlayerId();
int getLevel();
long getTotalExperience();
long getCurrentLevelExperience();
long getExperienceToNextLevel();
Set<String> getUnlockedTiers();
boolean hasTier(String tierId);
Set<String> getCompletedQuests();
boolean hasCompletedQuest(String questId);
Set<String> getClaimedRewards();
boolean hasClaimedReward(int level, String tierId);
}
Pass
通行证接口：public interface Pass {
String getId();
String getDisplayName();
List<String> getDescription();
int getMaxLevel();
long getExperienceForLevel(int level);
Collection<PassTier> getTiers();
Optional<PassTier> getTier(String tierId);
Optional<PassLevel> getLevel(int level);
}
Quest
任务接口：public interface Quest {
String getId();
String getDisplayName();
String getDescription();
QuestType getType();
int getExperienceReward();
List<QuestObjective> getObjectives();
List<QuestCondition> getConditions();
}
Season
赛季接口：public interface Season {
String getId();
String getDisplayName();
int getSeasonNumber();
SeasonStatus getStatus();
long getStartTime();
long getEndTime();
long getTimeRemainingSeconds();
boolean isActive();
}
异步操作
ArcPass API 大量使用CompletableFuture 处理异步操作：
// 正确的异步处理方式
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的回调可能在任意线程执行
下一步
API 入门详细指南
完整的入门教程
事件系统文档
事件监听和处理
代码示例
实用代码示例