> ## 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 入门

<span id="api-入门" />

本指南详细介绍如何在您的插件中集成 ArcPass API。

<h2 id="添加依赖">
  添加依赖
</h2>

<h3 id="maven">
  Maven
</h3>

在 `pom.xml` 中添加仓库和依赖：

```xml theme={null}
<repositories>
    <!-- GitHub Packages -->
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/KiteMC/ArcPass</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.kitemc</groupId>
        <artifactId>arcpass-api</artifactId>
        <version>1.9.4</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

<h3 id="gradle-kotlin-dsl">
  Gradle (Kotlin DSL)
</h3>

```kotlin theme={null}
repositories {
    maven("https://maven.pkg.github.com/KiteMC/ArcPass")
}

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

<h3 id="gradle-groovy">
  Gradle (Groovy)
</h3>

```groovy theme={null}
repositories {
    maven { url = "https://maven.pkg.github.com/KiteMC/ArcPass" }
}

dependencies {
    compileOnly 'com.kitemc:arcpass-api:1.9.4'
}
```

<h2 id="配置-plugin-yml">
  配置 plugin.yml
</h2>

添加 ArcPass 为软依赖：

```yaml theme={null}
name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
softdepend:
  - ArcPass
```

<h2 id="获取-api-实例">
  获取 API 实例
</h2>

<h3 id="检查-arcpass-是否可用">
  检查 ArcPass 是否可用
</h3>

```java theme={null}
import com.kitemc.arcpass.api.ArcPassAPI;
import com.kitemc.arcpass.api.ArcPassProvider;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    private ArcPassAPI arcPassAPI;

    @Override
    public void onEnable() {
        // 检查 ArcPass 是否已加载
        if (getServer().getPluginManager().getPlugin("ArcPass") != null) {
            arcPassAPI = ArcPassProvider.get();
            getLogger().info("ArcPass API 已加载！");
        } else {
            getLogger().warning("ArcPass 未安装，相关功能将不可用");
        }
    }

    public boolean isArcPassAvailable() {
        return arcPassAPI != null;
    }

    public ArcPassAPI getArcPassAPI() {
        return arcPassAPI;
    }
}
```

<h3 id="延迟获取-推荐">
  延迟获取（推荐）
</h3>

ArcPass 使用延迟初始化，建议在服务器完全启动后获取 API：

```java theme={null}
@Override
public void onEnable() {
    // 延迟获取 API
    getServer().getScheduler().runTaskLater(this, () -> {
        if (getServer().getPluginManager().getPlugin("ArcPass") != null) {
            arcPassAPI = ArcPassProvider.get();
            initializeArcPassFeatures();
        }
    }, 1L); // 1 tick 延迟
}

private void initializeArcPassFeatures() {
    // 初始化与 ArcPass 相关的功能
    getLogger().info("ArcPass 版本: " + arcPassAPI.getVersion());
}
```

<h2 id="基本操作">
  基本操作
</h2>

<h3 id="获取玩家数据">
  获取玩家数据
</h3>

```java theme={null}
public void showPlayerInfo(Player player) {
    if (!isArcPassAvailable()) return;

    // 异步获取玩家数据
    arcPassAPI.getPlayerData(player.getUniqueId())
        .thenAccept(optionalData -> {
            if (optionalData.isEmpty()) {
                player.sendMessage("§c无法获取通行证数据");
                return;
            }

            PlayerData data = optionalData.get();

            // 回到主线程发送消息
            Bukkit.getScheduler().runTask(plugin, () -> {
                player.sendMessage("§6=== 通行证信息 ===");
                player.sendMessage("§7等级: §e" + data.getLevel());
                player.sendMessage("§7经验: §e" + data.getTotalExperience());
                player.sendMessage("§7档位: §e" + String.join(", ", data.getUnlockedTiers()));
            });
        })
        .exceptionally(ex -> {
            getLogger().warning("获取玩家数据失败: " + ex.getMessage());
            return null;
        });
}
```

<h3 id="使用缓存数据">
  使用缓存数据
</h3>

如果需要同步访问数据，可以使用缓存：

```java theme={null}
public int getPlayerLevel(Player player) {
    if (!isArcPassAvailable()) return 0;

    PlayerData data = arcPassAPI.getPlayerDataIfCached(player.getUniqueId());
    return data != null ? data.getLevel() : 0;
}
```

<Warning>
  缓存数据可能为 null（玩家刚加入或数据未加载），使用前务必检查。
</Warning>

<h3 id="给予经验">
  给予经验
</h3>

```java theme={null}
public void giveExperience(Player player, long amount) {
    if (!isArcPassAvailable()) return;

    arcPassAPI.addExperience(player.getUniqueId(), amount)
        .thenAccept(newTotal -> {
            Bukkit.getScheduler().runTask(plugin, () -> {
                player.sendMessage("§a获得 " + amount + " 通行证经验！");
                player.sendMessage("§7当前总经验: §e" + newTotal);
            });
        });
}
```

<h3 id="触发自定义任务事件">
  触发自定义任务事件
</h3>

```java theme={null}
// 触发自定义事件
public void onCustomAction(Player player, String actionType) {
    if (!isArcPassAvailable()) return;

    // 这会触发配置中 type: custom, event: my_action 的任务进度
    arcPassAPI.triggerCustomEvent(
        player.getUniqueId(),
        "my_action",  // 事件 ID
        actionType    // 附加数据（可选）
    );
}
```

对应的任务配置：

```yaml theme={null}
custom_task:
  type: daily
  display-name: "&e自定义任务"
  objectives:
    - type: custom
      event: my_action
      amount: 10
```

<h3 id="查询通行证信息">
  查询通行证信息
</h3>

```java theme={null}
public void showPassInfo(Player player) {
    if (!isArcPassAvailable()) return;

    Pass defaultPass = arcPassAPI.getDefaultPass();
    player.sendMessage("§6当前通行证: §e" + defaultPass.getDisplayName());
    player.sendMessage("§7最大等级: §e" + defaultPass.getMaxLevel());

    // 列出所有档位
    player.sendMessage("§7可用档位:");
    for (PassTier tier : defaultPass.getTiers()) {
        String status = tier.isFree() ? "§a免费" : "§e¥" + tier.getPrice();
        player.sendMessage("  §7- " + tier.getDisplayName() + " " + status);
    }
}
```

<h3 id="查询赛季信息">
  查询赛季信息
</h3>

```java theme={null}
public void showSeasonInfo(Player player) {
    if (!isArcPassAvailable()) return;

    Optional<Season> seasonOpt = arcPassAPI.getCurrentSeason();

    if (seasonOpt.isEmpty()) {
        player.sendMessage("§c当前没有活动的赛季");
        return;
    }

    Season season = seasonOpt.get();
    player.sendMessage("§6当前赛季: §e" + season.getDisplayName());
    player.sendMessage("§7状态: §e" + season.getStatus());

    long remaining = season.getTimeRemainingSeconds();
    if (remaining > 0) {
        long days = remaining / 86400;
        long hours = (remaining % 86400) / 3600;
        player.sendMessage("§7剩余时间: §e" + days + "天 " + hours + "小时");
    }
}
```

<h2 id="错误处理">
  错误处理
</h2>

<h3 id="处理-completablefuture-异常">
  处理 CompletableFuture 异常
</h3>

```java theme={null}
arcPassAPI.getPlayerData(playerId)
    .thenAccept(data -> {
        // 正常处理
    })
    .exceptionally(ex -> {
        // 记录异常
        getLogger().severe("ArcPass API 调用失败: " + ex.getMessage());
        ex.printStackTrace();

        // 通知玩家
        Player player = Bukkit.getPlayer(playerId);
        if (player != null) {
            player.sendMessage("§c操作失败，请稍后重试");
        }

        return null; // 必须返回 null
    });
```

<h3 id="超时处理">
  超时处理
</h3>

```java theme={null}
import java.util.concurrent.TimeUnit;

arcPassAPI.getPlayerData(playerId)
    .orTimeout(5, TimeUnit.SECONDS)
    .thenAccept(data -> {
        // 处理数据
    })
    .exceptionally(ex -> {
        if (ex.getCause() instanceof java.util.concurrent.TimeoutException) {
            getLogger().warning("获取数据超时");
        }
        return null;
    });
```

<h2 id="下一步">
  下一步
</h2>

<Columns cols={2}>
  <Card title="事件系统" icon="zap" href="/arcpass/developer/events">
    监听 ArcPass 事件
  </Card>

  <Card title="代码示例" icon="code" href="/arcpass/developer/examples">
    更多实用代码示例
  </Card>
</Columns>


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