如何用 Kotlin 制作 Minecraft 插件

分步说明

1. 1.创建使用 Kotlin DSL 的 Gradle 项目

   一个 build.gradle.kts，包含 kotlin("jvm") 插件、与你的 Minecraft 版本匹配的 Java 工具链（17、21 或 25）以及 PaperMC 仓库。

2. 2.添加服务端 API

   compileOnly("io.papermc.paper:paper-api:<version>")。和 Java 一样，运行时由服务器提供，所以绝不会被打包进去。

3. 3.编写主类

   class MyPlugin : JavaPlugin()，带 override fun onEnable()。注册命令和监听器的方式和 Java 完全一样。

4. 4.带上 Kotlin 标准库

   用 Shadow 插件把它打包进 .jar，或者通过 plugin.yml 中的 libraries 列表让服务器在启动时下载它。两者都没有的话，插件会报 NoClassDefFoundError: kotlin/... 并失败。

5. 5.编写 plugin.yml

   和 Java 插件是同一个文件：name、version、main（Kotlin 类）、api-version、commands 和 permissions。

6. 6.构建和测试

   ./gradlew shadowJar（或 build），把 build/libs/ 中的 .jar 复制到测试服务器，并查看启动时的控制台。

把 Kotlin 带到服务器上

• 打包进去（shade）：Shadow Gradle 插件会把 Kotlin 标准库和其他运行时库复制进你的 .jar。它适用于所有版本，也是最常见的选择。
• plugin.yml 中的 libraries：从 Spigot 1.16.5 起，插件可以列出 Maven Central 上的库，由服务器为它下载并加载。.jar 保持小巧，但服务器首次启动时需要联网。
• 你额外添加的库：kotlinx-coroutines 是一个单独的库，不属于标准库，同样必须打包进去。把它重定位到你自己的包下，可以避免和打包了其他版本的插件发生冲突。

协程与主线程

协程是一种干净的方式，可以从数据库加载数据而不卡住服务器，但 Bukkit API（世界、实体、物品栏）仍然必须在主线程上使用。把耗时的工作放在后台调度器上，然后在操作游戏之前用调度器切回服务器线程。把协程作用域绑定到插件上，这样它会在 onDisable() 中被取消。

Java 还是 Kotlin？

用 Codexe

选择 Bukkit/Spigot/Paper (Kotlin)。Codexe 会生成一个 Gradle 项目，包含 build.gradle.kts、Paper API、用来打包服务器不提供的内容的 Shadow 插件，代码用到协程时还会把它打包并重定位。插件在标记为就绪之前会被编译，Kotlin 插件和 Java 插件一样，可以在测试服务器上试用，并由测试玩家检查。参见 Kotlin 插件生成器。

“一个名为 Bounties 的 Kotlin 版 Paper 1.21.4 插件：/bounty set <player> <amount> 通过 Vault 设置悬赏，击杀者获得奖励，/bounty top 显示最高的 10 个，数据存储在 SQLite 中，用协程访问数据库。使用 data class 和扩展函数，Bukkit API 调用保持在主线程上。”

常见问题