[OLD] KUtils : High level Minecraft plugins - KUtils：高级 Minecraft 插件

KUtils 是一个为 Kotlin 开发者设计的 Minecraft 插件开发库，它通过一系列简洁的语法糖和实用工具，极大地简化了事件监听、任务调度、命令注册等常见开发任务，让开发者能更专注于插件逻辑本身。

💡简化事件监听

使用 listen() 方法可以轻松地监听事件。

使用 KUtils

listen<PlayerJoinEvent> {
    it.player.msg("Hello world!")
}

不使用 KUtils (Kotlin)

server.pluginManager.registerEvent(object : Listener {
    @EventHandler
    fun onPlayerJoin(e: PlayerJoinEvent) {
        e.player.sendMessage("Hello world!")
    }
}, this)

不使用 KUtils (Java)

getServer().getPluginManager().registerEvents(new Listener() {
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent e) {
        e.getPlayer().sendMessage("Hello world!");
    }
}, this);

💡简化任务调度

使用 schedule() 方法可以方便地安排同步或异步任务。

// 延迟 10 秒后执行
schedule(delay = 10) {
    // 这里的代码将在 10 秒后执行
}

// 延迟 10 秒后首次执行，之后每 20 秒重复执行
schedule(delay = 10, period = 20) {
    // 这里的代码将在 10 秒后执行，之后每 20 秒执行一次
}

// 立即异步执行
schedule(async = true) {
    // 这里的代码将立即在异步线程中执行
}

// 异步延迟 20 秒后执行
schedule(true, delay = 20) {
    // 这里的代码将在 20 秒后异步执行
}

// 异步执行，每 3 分钟重复一次
schedule(true, period = 3, unit = TimeUnit.MINUTES) {
    // 这里的代码将每 3 分钟在异步线程中执行一次
}

// 任务可以自行取消
schedule(period = ...) {
    if (...) cancel()
}

💡简化命令注册

使用 command() 方法可以快速注册命令。

使用 KUtils

command("hello") { args ->
    msg("&bHello!")
}

不使用 KUtils (BungeeCord - Kotlin)

proxy.pluginManager.registerCommand(this, object : Command("hello") {
    override fun execute(sender: CommandSender, args: Array<String>) {
        sender.sendMessage("§bHello!")
    }
})

不使用 KUtils (Bukkit - Kotlin)

getCommand("hello").executor = CommandExecutor { sender, command, label, args ->
    sender.sendMessage("§bHello!")
    true
}

💡委托式配置文件管理

您可以使用委托属性来管理复杂的配置文件。

class MyPlugin : BukkitPlugin() {
    object MyConfig : ConfigFile("config") {
        var debug by boolean("debug")
        var alertMessage by string("alert-message")
        var enabledWorlds by stringList("enabled-worlds")
    }

    override fun onEnable() {
        // 使用当前文件初始化对象（会将资源中的 config.yml 复制到数据文件夹）
        init(MyConfig)

        // 可以动态访问属性
        info("debug: " + MyConfig.debug)

        // 可以修改属性（如果使用了 `var` 声明）
        MyConfig.debug = false

        // 保存配置（如果禁用了自动保存）
        MyConfig.save()

        // 从文件重新加载配置
        MyConfig.reload()
    }
}

更多信息请参考相关文档。

💡简化消息发送

向玩家（支持 Player、ProxiedPlayer、CommandSender）发送消息变得非常简单。

使用 KUtils

player.msg("&6Hello world!")

不使用 KUtils (BungeeCord)

player.sendMessage(TextComponent("&6Hello world!".replace("&", "§")))

不使用 KUtils (Bukkit)

player.sendMessage("&6Hello world!".replace("&", "§"))

💡快速日志记录

您可以使用 info()、warning() 和 severe() 方法来记录字符串或异常到控制台。还可以使用 logToFile() 将日志写入插件数据文件夹下的 log.txt 文件。

使用 KUtils

info("Hello world!")

不使用 KUtils (Kotlin)

logger.info("Hello world!")

不使用 KUtils (Java)

getLogger().info("Hello world!");

💡多平台插件的类型别名

如果您想指定任何类型的平台，只需在其名称前加上 Bungee 或 Bukkit。

使用 KUtils

class MyPluginOnBungee : BungeePlugin() {
    override fun onEnable() = info("Hello Bungee!")
}

class MyPluginOnBukkit : BukkitPlugin() {
    override fun onEnable() = info("Hello Bukkit!")
}

不使用 KUtils 则需要为每个平台编写独立的文件。

💡插件更新检查器

您可以使用 Spiget 来检查插件的更新。只需使用 update() 方法并传入您的 Spigot 资源 ID。

// 检查资源 ID 为 15938 的插件更新
update(15938)

// 指定更新提示的颜色
update(15938, LIGHT_PURPLE)

// 指定接收更新通知的权限（默认权限是 "rhaz.update"）
update(15938, LIGHT_PURPLE, "myplugin.updates")

💡高级异常捕获

KUtils 提供了一种优雅的语法来捕获和处理异常。

基础捕获

使用 KUtils

// 这将捕获任何异常并将其作为警告记录
catch<Exception>(::warning) {
    // ex() 是 Exception() 的简写
    throw ex("An error occured")
}

不使用 KUtils

try {
    throw Exception("An error occured")
} catch (ex: Exception) {
    warning(ex)
}

捕获特定异常

// 可以省略回调函数，默认使用 ::printStackTrace
catch<CommandException> {
    throw Exception("This won't be catched")
}

捕获并向命令发送者反馈

val sender: CommandSender = ...
catch<Exception>(sender::msg) {
    if (sender !is Player) throw ex("&cYou're not a player!")
    sender.gamemode = GameMode.CREATIVE
    sender.msg("&bYou're now in creative mode :)")
}

自定义回调

// 将异常告知管理员
val admins = server.onlinePlayers.filter { it.hasPermission("test.admin") }
fun tellToAdmins(ex: Exception) = admins.forEach { it.msg(ex) }

catch<Exception>(::tellToAdmins) {
    throw ex("Alert!")
}

// 使用匿名回调，在警告前添加“An error occured”前缀
catch<Exception>({ warning("An error occured: ${it.message}") }) {
    throw ex(...)
}

自定义异常

class RedException(message: String) : Exception() {
    override val message = "&c$message"
}

fun test() {
    catch<RedException>(::warning) {
        throw RedException("This message will be red")
    }
}

带返回值、回调和默认值的捕获

fun default(ex: Exception) = { warning(ex); "This is the default message" }()

val msg = catch(::default) {
    val line1 = read() ?: throw ex("Could not read first line")
    val line2 = read() ?: throw ex("Could not read second line")
    val line3 = read() ?: throw ex("Could not read third line")
    info("Sucessfully read three lines")
    "$line1, $line2, $line3" // 返回用“,”分隔的三行内容
}

// 如果三行中的任何一行无法读取，将打印“This is the default message”
info("The message is: $msg")

更多功能请参考完整文档。