Doc ID: SIRC-122

AkariLevel API 文档

AkariLevel 是一个基于 TabooLib 框架开发的 Bukkit 等级插件，提供了丰富的 API 接口用于附属插件开发。

Overview

AkariLevel API 文档

概述

AkariLevel 是一个基于 TabooLib 框架开发的 Bukkit 等级插件，提供了丰富的 API 接口用于附属插件开发。

核心 API 包结构

1. LevelGroup 接口

包名: top.cpjinan.akarilevel.level

功能: 等级组管理、成员管理、等级与经验管理

主要方法:

// 静态方法
getLevelGroups(): Map<String, LevelGroup>  // 获取所有等级组
addLevelGroup(name: String, levelGroup: LevelGroup)  // 新增等级组
removeLevelGroup(name: String)  // 移除等级组

// 实例方法
val name: String  // 编辑名
val display: String  // 展示名
register()  // 注册等级组
unregister()  // 取消注册等级组

// 等级管理
getLevelName(level: Long): String  // 获取等级名称
getLevelName(member: String, level: Long): String  // 获取成员等级名称
getLevelExp(oldLevel: Long, newLevel: Long): Long  // 获取升级所需经验
getMinLevel(): Long  // 获取最低等级
getMaxLevel(): Long  // 获取最高等级

// 成员管理
hasMember(member: String): Boolean  // 检查是否包含成员
addMember(member: String, source: String)  // 增加成员
removeMember(member: String, source: String)  // 移除成员

// 成员等级经验操作
getMemberLevel(member: String): Long  // 获取成员等级
getMemberExp(member: String): Long  // 获取成员经验
setMemberLevel(member: String, amount: Long, source: String)  // 设置成员等级
setMemberExp(member: String, amount: Long, source: String)  // 设置成员经验
addMemberLevel(member: String, amount: Long, source: String)  // 增加成员等级
addMemberExp(member: String, amount: Long, source: String)  // 增加成员经验
removeMemberLevel(member: String, amount: Long, source: String)  // 移除成员等级
removeMemberExp(member: String, amount: Long, source: String)  // 移除成员经验

// 回调方法
onRegister()  // 等级组注册回调
onUnregister()  // 等级组取消注册回调
onMemberChange(member: String, type: MemberChangeType, source: String)  // 成员变更回调
onMemberLevelChange(member: String, oldLevel: Long, newLevel: Long, source: String)  // 成员等级变更回调
onMemberExpChange(member: String, expAmount: Long, source: String)  // 成员经验变更回调

枚举类型:

enum class MemberChangeType {
    JOIN,  // 加入
    QUIT   // 退出
}

使用示例:

// 通过编辑名获取等级组实例
val levelGroup = LevelGroup.getLevelGroups()["等级组编辑名"]

// 注册/取消注册等级组
levelGroup.register()
levelGroup.unregister()

// 设置成员等级/经验
levelGroup.setMemberLevel("成员名称", 10, "等级来源")
levelGroup.setMemberExp("成员名称", 10, "经验来源")

2. ConfigLevelGroup 类

包名: top.cpjinan.akarilevel.level

功能: LevelGroup 接口的默认实现，从配置文件获取等级组

主要方法:

// 静态方法
getConfigLevelGroups(): Map<String, ConfigLevelGroup>  // 获取配置等级组列表
addConfigLevelGroup(name: String, configLevelGroup: ConfigLevelGroup)  // 新增配置等级组
removeConfigLevelGroup(name: String)  // 移除配置等级组
reloadConfigLevelGroups()  // 重载配置等级组

// 实例方法
levelUpMember(member: String)  // 升级成员
checkLevelCondition(member: String, level: Long): Boolean  // 检查等级条件
runLevelAction(member: String, level: Long)  // 执行等级动作
getLevelConfig(level: Long): ConfigurationSection  // 获取等级配置
getKeyLevelConfigs(): Map<Long, ConfigurationSection>  // 获取关键等级配置列表

使用示例:

// 通过配置文件获取并注册等级组实例
val config = Configuration.loadFromFile(file)
val levelGroup = ConfigLevelGroup(config)
levelGroup.register()

3. ConfigLevelAction 接口

包名: top.cpjinan.akarilevel.level

功能: 升级动作处理器接口

主要方法:

// 静态方法
getConfigLevelActions(): Map<String, ConfigLevelAction>  // 获取升级动作列表
registerConfigLevelAction(name: String, configLevelAction: ConfigLevelAction)  // 注册升级动作
unregisterConfigLevelAction(name: String)  // 取消注册升级动作

// 实例方法
run(member: String, levelGroup: String, level: Long, config: ConfigurationSection)  // 执行升级动作

说明: KetherLevelAction 是插件默认的 ConfigLevelAction 接口实现，可以在成员升级时执行 Kether 脚本。

4. ConfigLevelCondition 接口

包名: top.cpjinan.akarilevel.level

功能: 升级条件处理器接口

主要方法:

// 静态方法
getConfigLevelConditions(): Map<String, ConfigLevelCondition>  // 获取升级条件列表
registerConfigLevelCondition(name: String, configLevelCondition: ConfigLevelCondition)  // 注册升级条件
unregisterConfigLevelCondition(name: String)  // 取消注册升级条件

// 实例方法
check(member: String, levelGroup: String, level: Long, config: ConfigurationSection): Boolean  // 检查升级条件

说明: KetherLevelCondition 是插件默认的 ConfigLevelCondition 接口实现，可以在成员升级时检查 Kether 条件。

5. Booster 数据类

包名: top.cpjinan.akarilevel.booster

功能: 经验加成器管理

属性:

var id: String  // 加成器ID
var name: String  // 加成器名称
var type: String = ""  // 类型
var multiplier: Double = 1.0  // 倍率
var start: Long = -1  // 开始时间
var duration: Long = -1  // 持续时间
var levelGroup: List<String> = emptyList()  // 适用的等级组列表
var source: List<String> = listOf("COMMAND_ADD_EXP", "MYTHICMOBS_DROP_EXP", "VANILLA_EXP_CHANGE")  // 来源列表

静态方法:

getMemberBoosters(member: String): Map<String, Booster>  // 获取成员经验加成器列表
addMemberBooster(member: String, booster: Booster)  // 新增成员经验加成器
removeMemberBooster(member: String, id: String)  // 移除成员经验加成器
isMemberBoosterEnabled(member: String, id: String): Boolean  // 检查加成器是否启用
enableMemberBooster(member: String, id: String)  // 启用成员经验加成器
disableMemberBooster(member: String, id: String)  // 禁用成员经验加成器
refreshMemberBoosters(member: String)  // 刷新成员经验加成器

使用示例:

// 获取成员经验加成器列表
val boosters = Booster.getMemberBoosters("成员名称")

// 新增成员经验加成器
val booster = Booster(
    id = UUID.randomUUID().toString().take(8),
    name = "经验加成器名称",
    type = "",
    multiplier = 1.0,
    start = System.currentTimeMillis(),
    duration = -1,
    levelGroup = "",
    source = "COMMAND_ADD_EXP"
)
Booster.addMemberBooster("成员名称", booster)

配置相关类

ConfigurationSection

包名: top.cpjinan.akarilevel.taboolib.module.configuration.Configuration

说明: 用于读取配置文件，需要插件的 API 版本作为依赖。

开发注意事项

  1. 回调机制: LevelGroup 接口提供了完整的回调方法，可以重写这些方法实现自定义业务逻辑
  2. 配置驱动: ConfigLevelGroup 是主要的配置驱动实现，支持从配置文件加载等级组
  3. 扩展性: 通过实现 ConfigLevelAction 和 ConfigLevelCondition 接口，可以自定义升级动作和条件
  4. 经验加成: Booster 类提供了灵活的经验加成器管理，支持多种来源和条件
  5. 数据持久化: 插件支持 SQLite/MySQL 数据库，基于 caffeine 的数据缓存机制

典型使用场景

1. 创建自定义等级组

class CustomLevelGroup : LevelGroup {
    override val name: String = "custom-group"
    override val display: String = "自定义等级组"
    
    override fun register() {
        // 自定义注册逻辑
    }
    
    override fun onMemberLevelChange(member: String, oldLevel: Long, newLevel: Long, source: String) {
        // 自定义等级变更处理
    }
}

// 注册自定义等级组
LevelGroup.addLevelGroup("custom", CustomLevelGroup())

2. 添加经验加成器

// 创建双倍经验加成器
val doubleExpBooster = Booster(
    id = "double-exp",
    name = "双倍经验",
    multiplier = 2.0,
    duration = 3600000, // 1小时
    levelGroup = listOf("main", "pvp") // 适用于主等级组和PVP等级组
)

// 为玩家添加加成器
Booster.addMemberBooster("playerName", doubleExpBooster)

3. 监听等级变化

// 通过实现 LevelGroup 接口的回调方法
override fun onMemberLevelChange(member: String, oldLevel: Long, newLevel: Long, source: String) {
    // 发送升级通知
    Bukkit.getPlayer(member)?.sendMessage("恭喜你从 $oldLevel 级升到 $newLevel 级！")
    
    // 执行升级奖励
    if (newLevel % 10 == 0L) {
        // 每10级给予特殊奖励
        runLevelAction(member, newLevel)
    }
}

版本信息

  • 文档最后更新: 2026年1月7日
  • 插件基于 TabooLib 框架开发
  • 支持 Bukkit/Spigot/Paper 服务器

相关链接