API 入门

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

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

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

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

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

name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
softdepend:
  - ArcPass

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;
    }
}

@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());
}

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;
        });
}

public int getPlayerLevel(Player player) {
    if (!isArcPassAvailable()) return 0;

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

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);
            });
        });
}

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

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

custom_task:
  type: daily
  display-name: "&e自定义任务"
  objectives:
    - type: custom
      event: my_action
      amount: 10

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);
    }
}

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 + "小时");
    }
}

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
    });

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;
    });