ExcellentCrates API 文档

概述

ExcellentCrates 是一个功能丰富的 Minecraft 宝箱插件，提供完整的 API 供开发者集成使用。

包结构

主包: su.nightexpress.excellentcrates
API 包: su.nightexpress.excellentcrates.api
- su.nightexpress.excellentcrates.api.addon – 插件扩展
- su.nightexpress.excellentcrates.api.cost – 开箱成本
- su.nightexpress.excellentcrates.api.crate – 宝箱相关
- su.nightexpress.excellentcrates.api.event – 事件
- su.nightexpress.excellentcrates.api.opening – 开箱相关

核心 API 类

CratesAPI

主要 API 入口类，提供所有核心功能访问。

// 获取插件实例
CratesPlugin plugin = CratesAPI.getPlugin();
// 或使用新方法
CratesPlugin plugin = CratesAPI.plugin();

// 检查 API 是否已加载
boolean isLoaded = CratesAPI.isLoaded();

// 注册扩展插件
CratesAPI.registerAddon(CratesAddon addon);

管理器类

// 用户管理器
UserManager userManager = CratesAPI.getUserManager();

// 宝箱管理器
CrateManager crateManager = CratesAPI.getCrateManager();

// 钥匙管理器
KeyManager keyManager = CratesAPI.getKeyManager();

用户数据操作

// 获取玩家数据
CrateUser user = CratesAPI.getUserData(Player player);
CrateUser user = userManager.getUserData(Player player);
CrateUser user = userManager.getUserData(UUID playerId);
CrateUser user = userManager.getUserData(String playerName);

事件系统

CrateEvent

所有宝箱事件的基类。

CrateOpenEvent

玩家即将打开宝箱时触发，可取消。

@EventHandler
public void onCrateOpen(CrateOpenEvent event) {
    Player player = event.getPlayer();
    Crate crate = event.getCrate();
    
    // 检查是否可取消
    if (event.isCancelled()) {
        return;
    }
    
    // 取消事件
    event.setCancelled(true);
}

CrateObtainRewardEvent

玩家从宝箱中获取奖励时触发。

@EventHandler
public void onRewardObtain(CrateObtainRewardEvent event) {
    Player player = event.getPlayer();
    Crate crate = event.getCrate();
    Reward reward = event.getReward();
    
    // 处理奖励获取逻辑
}

PlaceholderAPI 变量

宝箱相关变量

%crate_id% - 宝箱 ID（文件名称）
%crate_name% - 宝箱显示名称
%crate_description% - 宝箱描述
%crate_permission% - 宝箱的权限节点
%crate_open_cooldown% - 格式化的宝箱开启冷却时间
%crate_open_cost% - 格式化的宝箱开箱收费价格
%crate_last_opener% - 显示最后一个开启该宝箱的玩家
%crate_last_reward% - 显示最后一个获取的宝箱奖励

钥匙相关变量

%key_id% - 钥匙 ID（文件名称）
%key_name% - 钥匙显示名称
%key_virtual% - 是否为虚拟钥匙

奖励相关变量

%reward_id% - 奖励 ID
%reward_name% - 奖励显示名称
%reward_description% - 奖励描述
%reward_weight% - 奖励的权重
%reward_roll_chance% - 奖励的随机几率
%reward_rarity_name% - 奖励的稀有度名称
%reward_rarity_weight% - 奖励的稀有度权重
%reward_rarity_roll_chance% - 奖励的稀有度抽取几率

PlaceholderAPI 全局变量

%excellentcrates_keys_[宝箱 ID]% - 显示玩家拥有指定宝箱的剩余钥匙数量
%excellentcrates_openings_[宝箱 ID]% - 显示玩家开启宝箱的次数
%excellentcrates_openings_raw_[宝箱 ID]% - 不带格式显示玩家开启宝箱的次数
%excellentcrates_cooldown_[宝箱 ID]% - 显示玩家距下次开启宝箱的冷却时间
%excellentcrates_next_milestone_openings_[宝箱 ID]% - 显示玩家距下次累抽奖励所需的抽奖次数
%excellentcrates_next_milestone_reward_[宝箱 ID]% - 显示玩家下次累抽奖励的名称
%excellentcrates_latest_opener_[宝箱 ID]% - 显示上一位开启了该宝箱的玩家
%excellentcrates_latest_rolled_reward_[宝箱 ID]% - 显示上一个抽取出的奖励

使用示例

基本集成

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // 检查 ExcellentCrates 是否已加载
        if (CratesAPI.isLoaded()) {
            getLogger().info("ExcellentCrates API 已加载");
            
            // 获取管理器
            CrateManager crateManager = CratesAPI.getCrateManager();
            KeyManager keyManager = CratesAPI.getKeyManager();
            
            // 注册事件监听器
            getServer().getPluginManager().registerEvents(new MyCrateListener(), this);
        } else {
            getLogger().warning("ExcellentCrates 未找到，相关功能将不可用");
        }
    }
}

public class MyCrateListener implements Listener {
    
    @EventHandler
    public void onCrateOpen(CrateOpenEvent event) {
        Player player = event.getPlayer();
        Crate crate = event.getCrate();
        
        // 自定义开箱逻辑
        if (player.hasPermission("myplugin.special")) {
            // 给予特殊处理
        }
    }
}

获取玩家宝箱数据

public void checkPlayerCrateData(Player player) {
    CrateUser user = CratesAPI.getUserData(player);
    
    // 获取玩家拥有的钥匙数量
    Map<String, Integer> keys = user.getKeys();
    
    // 获取玩家开箱次数
    Map<String, Integer> openings = user.getOpenings();
    
    // 获取玩家冷却时间
    Map<String, Long> cooldowns = user.getCooldowns();
}

注意事项

API 加载时机: 确保在插件完全加载后再调用 API 方法
事件处理: 注意事件的取消状态，避免重复处理
线程安全: 部分操作可能需要在主线程执行
版本兼容: 注意不同版本间的 API 变化

错误处理

try {
    CratesPlugin plugin = CratesAPI.plugin();
    // 正常操作
} catch (IllegalStateException e) {
    // API 未加载时的处理
    getLogger().warning("ExcellentCrates API 未加载: " + e.getMessage());
}

扩展开发

创建扩展插件

public class MyCratesAddon implements CratesAddon {
    
    @Override
    public void onEnable() {
        // 扩展启用逻辑
    }
    
    @Override
    public void onDisable() {
        // 扩展禁用逻辑
    }
    
    @Override
    public String getName() {
        return "MyCratesAddon";
    }
}

注册扩展

CratesAPI.registerAddon(new MyCratesAddon());

文档最后更新: 基于 ExcellentCrates v6.6.1 API
GitHub 仓库: https://github.com/nulli0n/ExcellentCrates-spigot

Overview