如何用 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 的呼叫維持在主執行緒上。」

常見問題