跳至主要內容

Java 插件 API

產生的 Java 參考提供可搜尋的類別、方法與簽章，並記錄各模組的原始碼版本和提交。

編寫與 Nightbreak 插件整合的 Java 插件時，請使用本節。若不編寫 Java 插件而直接製作遊戲行為，請從 Lua 腳本指南開始。

選擇插件​

以下座標均使用群組 com.magmaguy。這些版本在本次更新時已列於公開 Maven 儲存庫；請配合伺服器安裝的插件版本。介紹目前原始碼的 wiki 頁面與產生的參考，可能在 Maven 產物發布之前就涵蓋較新的版本。

插件產物與版本開發者參考
EliteMobsEliteMobs:10.9.1實體、物品、事件與 Lua 技能服務
FreeMinecraftModelsFreeMinecraftModels:2.12.1模型、互動、偽裝、物品與魔法武器
ResourcePackManagerResourcePackManager:2.4.1資源包註冊與重新載入
BetterStructuresBetterStructures:2.7.2建築生成事件
EternalTDEternalTD:1.7.3防禦塔、波次與戰鬥事件
CannonRTPCannonRTP:1.2.2發射、目的地驗證與落地事件
ResurrectionChestResurrectionChest:2.3.1整合範圍
BetterFoodBetterFood:1.5.1整合範圍
MagmaCoreMagmaCore:2.2.0-SNAPSHOT嵌入式函式庫設定與生命週期

加入插件相依​

已發布插件從 MagmaGuy 的 Maven 儲存庫解析。使用 Maven provided 或 Gradle compileOnly，針對已安裝插件編譯。整合 JAR 不應包含目標插件的第二份副本。

例如，EliteMobs 整合使用：

pom.xml sections
<repositories>
    <repository>
        <id>magmaguy-releases</id>
        <url>https://repo.magmaguy.com/releases</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.magmaguy</groupId>
        <artifactId>EliteMobs</artifactId>
        <version>10.9.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

等效的 Gradle Kotlin DSL：

build.gradle.kts sections
repositories {
    maven("https://repo.magmaguy.com/releases")
}

dependencies {
    compileOnly("com.magmaguy:EliteMobs:10.9.1")
}

專案仍需平常的 Bukkit/Paper API 相依。這些範例使用 Java 21 建置；執行伺服器時，請使用該伺服器要求的 Java 版本。

在插件描述檔中宣告執行時相依：

plugin.yml section
depend: [EliteMobs]

其他整合請替換產物、版本與插件名稱。BetterStructures 還要求伺服器安裝 WorldEdit。ResourcePackManager 的 Java 註冊 API 在 Bukkit 後端執行；通用產物也包含代理元件，但這不代表代理插件可以呼叫這個 Bukkit API。

若整合為選用，使用 softdepend，並在確認目標插件已啟用後才載入整合類別。不要在永遠載入的入口中參照選用插件的型別。相依載入順序不代表非同步內容初始化已完成；請遵循目標插件的就緒與重新載入掛鉤。

MagmaCore 的打包約定不同。它是嵌入式函式庫，請遵循其 shading 與生命週期指南，而非這套已安裝插件的做法。

生命週期與相容性​

使用各指南記載的入口。插件 JAR 中的 public Java 類別仍可能只是實作細節。升級前請檢查對應版本的簽章，尤其是使用 api 套件外的管理器或實體類別時。

Bukkit 實體與世界操作應在伺服器執行緒執行。避免用 HTTP、檔案存取或長時間計算阻塞事件處理器。從非同步工作返回時，重新檢查實體與插件就緒狀態。

只保留整合自己擁有的狀態。停用時釋放模型附加、註冊與工作，並在重新載入後重新取得目標插件物件。持有模型或地牢參照不代表其執行個體仍存在。

ResurrectionChest​

ResurrectionChest 2.3.1 沒有專用自訂 Bukkit 事件 API 或整合入口。其 events 套件包含內部 Bukkit 監聽器。不要將這些監聽器建構成擴充入口。

伺服器設定請使用文件記載的設定與命令。公開 Maven 產物允許整合針對該版本編譯，但不代表存在穩定的箱子管理約定。

BetterFood​

BetterFood 1.5.1 沒有專用自訂 Bukkit 事件 API 或整合入口。食物選擇邏輯透過自己的 Bukkit 監聽器執行。

支援的設定見行為指南與設定參考。監聽普通 Bukkit 事件的程式碼應遵守取消狀態與事件優先順序，不應直接呼叫 BetterFood 的內部監聽器。

類別與方法文件​

整合方式請看上述指南；類別、方法與簽章請看產生的 Java 參考。請將參考中記錄的版本與原始碼提交，對照整合使用的版本。