> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.asia/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发者 API

> [!WARNING]
>
> **需要专业版许可证**
>
> 开发者 API 仅在**专业版**许可证下可用。标准版用户调用 `ArcPassProvider.isLoaded()` 将返回 `false`。您可以随时在 [许可证中心](https://license.kitemc.com/products/arcpass) 升级。

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

## API 概述

ArcPass API 模块 (`arcpass-api`) 采用 MIT 许可证开源，可自由使用。

### 功能

* 获取和修改玩家数据
* 查询通行证、任务、奖励信息
* 管理赛季系统
* 监听各种事件
* 触发自定义任务进度

### 文档目录

> **[API 入门](https://www.kitemc.asia/arcpass/developer/getting-started.md)**
>
> 添加依赖和基本使用

> **[事件系统](https://www.kitemc.asia/arcpass/developer/events.md)**
>
> 监听 ArcPass 事件

> **[代码示例](https://www.kitemc.asia/arcpass/developer/examples.md)**
>
> 常见场景代码示例

## 快速开始

### 添加依赖

**Maven**

```xml theme={null}
<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>
```

**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<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

玩家数据接口：

```java theme={null}
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

通行证接口：

```java theme={null}
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

任务接口：

```java theme={null}
public interface Quest {
    String getId();
    String getDisplayName();
    String getDescription();
    QuestType getType();
    int getExperienceReward();
    List<QuestObjective> getObjectives();
    List<QuestCondition> 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` 的回调可能在任意线程执行

## 下一步

> **[API 入门详细指南](https://www.kitemc.asia/arcpass/developer/getting-started.md)**
>
> 完整的入门教程

> **[事件系统文档](https://www.kitemc.asia/arcpass/developer/events.md)**
>
> 事件监听和处理

> **[代码示例](https://www.kitemc.asia/arcpass/developer/examples.md)**
>
> 实用代码示例


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.