ScriptIrc

AkariLevel API 文档

2026年1月11日 ·

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 服务器

相关链接