开发者 API

ArcPass 提供完整的 API 供第三方插件集成和扩展。

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.0.0</version>
    <scope>provided</scope>
</dependency>

Gradle (Kotlin DSL)

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/KiteMC/ArcPass")
    }
}

dependencies {
    compileOnly("com.kitemc:arcpass-api:1.0.0")
}

获取 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 入门详细指南

完整的入门教程

事件系统文档

事件监听和处理

代码示例

实用代码示例