MagmaCore 開發者指南

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

MagmaCore 是透過 shade 打包進使用方插件的函式庫。它不是獨立伺服器插件，不應在 depend 中將其當作玩家能安裝的 MagmaCore 插件 JAR。

相依與打包

目前開發座標為 com.magmaguy:MagmaCore:2.2.0-SNAPSHOT，可從 MagmaGuy 快照儲存庫取得。快照內容可能改變而版本字串不變。需要可重現建置時，請記錄實際解析的產物。

Gradle Kotlin DSL

repositories {
    maven("https://repo.magmaguy.com/snapshots")
}

dependencies {
    implementation("com.magmaguy:MagmaCore:2.2.0-SNAPSHOT")
}

Maven sections

<repositories>
    <repository>
        <id>magmaguy-snapshots</id>
        <url>https://repo.magmaguy.com/snapshots</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.magmaguy</groupId>
        <artifactId>MagmaCore</artifactId>
        <version>2.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

這些宣告用於解析相依。還需設定 shading 工作，將其包含在最終插件 JAR 中。遵循整合需求相同的現有使用方的重定位規則，改變套件名稱時檢查以字串進行的反射查找。發行包已將 org.luaj 和 org.reflections 重定位到 com.magmaguy.shaded。

每個插件都可以載入自己的函式庫副本。不同插件類別載入器中的同名 Java 類別是不同型別。請使用明確的跨插件約定，例如 EliteMobs Lua 技能服務與位置登錄表介接器。不要將其他插件私有的 MagmaCore 物件強制轉型為你的副本中的型別。

模組與職責

模組	職責
core	插件生命週期、設定、命令、選單、對局、位置查詢、Lua 腳本、Nightbreak 內容和共用工具
nms:core	NMSManager、NMSAdapter 及不依賴版本的 EasyMinecraftGoals 介面
nms:v*	NMS 約定的伺服器版本實作
dist	包含核心與啟用介接器的 shaded 發行包

共用附魔、物品操作、帳號處理、設定選單、目錄與更新屬於核心服務。為使用方加入行為時，重用負責該功能的元件。

插件生命週期

最小核心生命週期遵循現有使用方的模式：

CoreConsumer.java

package example;

import com.magmaguy.magmacore.MagmaCore;
import org.bukkit.plugin.java.JavaPlugin;

public final class CoreConsumer extends JavaPlugin {
    @Override
    public void onLoad() {
        MagmaCore.createInstance(this);
    }

    @Override
    public void onEnable() {
        MagmaCore.onEnable(this);
    }

    @Override
    public void onDisable() {
        MagmaCore.shutdown(this);
    }
}

這種初始化不只是取得一個工具物件。它會初始化帳號處理、共用命令、監聽器與暫時方塊支援。多載方法 createInstance(plugin, NightbreakPluginSpec) 用於提供插件專屬的共用命令文案。

優先使用明確接收所屬插件的方法。getInstance() 指向目前載入函式庫副本的單例，請求方插件在實例建立時確定。不要用它推斷每個使用方的擁有權。

shutdown(plugin) 清除該插件的下載器、內容更新器、初始化與更新服務註冊，之後也會關閉目前載入副本的共用執行環境。它不只是刪除一筆註冊記錄。請在你的插件關閉時，對自己嵌入的函式庫呼叫；不要為了重設整合而關閉其他插件的函式庫。

在 onLoad 中呼叫 createInstance，使插件的設定封存擁有者能在其他插件為其匯入內容之前註冊。封存透過目標插件自己的 shaded 實作執行；不要使用你的 MagmaCore 副本解釋其他插件的淘汰規則。

分階段啟動可使用 startInitialization，傳入非同步工作、同步工作、成功與失敗回呼。它會在呼叫非同步初始化之前封存符合規則的過時設定。Bukkit 世界和實體操作應放在同步階段。耗時非同步工作應在階段之間檢查 isShutdownRequested(plugin)。getInitializationState 和 isPluginReady 提供初始化管理器狀態。

NMS 與封包實體

僅在插件需要時，透過 com.magmaguy.easyminecraftgoals 中的 NMSManager.initializeAdapter(plugin) 初始化 NMS。使用依賴介接器的功能前，檢查 NMSManager.isEnabled()。初始化可能失敗，也可能發現伺服器版本不受支援。

發行包包含以下介接器系列：

介接器	Minecraft 版本
v1_21_R3	1.21.4
v1_21_R4	1.21.5
v1_21_R5	1.21.6, 1.21.7, 1.21.8
v1_21_R6	1.21.9, 1.21.10
v1_21_R7_spigot, v1_21_R7_paper	1.21.11，Spigot 與 Paper 分別實作
v26	26.1 及目前 26.x 介接器系列

選中介接器並不保證所有未來伺服器版本相容。NMSManager 中的執行時選擇器決定目前伺服器能否載入介接器。早於 1.21.4 的版本不在目前範圍內。

EasyMinecraftGoals 管理僅透過封包存在的實體、可見性與互動路由，以及移動和尋路工具。它們不是普通世界實體。應透過所屬 API 管理，並在介接器仍可用時清理你的使用方建立的物件。

位置與保護查詢

com.magmaguy.magmacore.location.LocationQueryRegistry 提供地牢及區域保護查詢，包括 isInAnyDungeon、isInAnyProtectedRegion 和 canBuild。

透過 registerDungeonLocator 或 registerProtectionProvider 註冊自訂提供方；所屬插件停用時取消註冊同一個提供方。登錄表包含現有插件介接器，並能發現跨插件地牢提供方，而不要求使用方共用一個 MagmaCore 類別載入器。

請選擇符合操作的查詢。位於地牢外不等於擁有該位置的建造權限。涉及 Bukkit 或保護插件的查詢應在伺服器執行緒執行。

函式庫變更後重建使用方

使用 JDK 21，並透過 ./gradlew publishToMavenLocal 將 MagmaCore 發布到 Maven Local；Windows 下使用 .\gradlew.bat publishToMavenLocal。確認使用方解析該儲存庫及所需版本，再重建其 shaded JAR。替換 Maven Local 中的函式庫不會更新已建置的插件。

已安裝插件的 API 見開發者索引。這類整合通常使用 provided 或 compileOnly；MagmaCore 的嵌入式函式庫打包約定不同。