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 的嵌入式库打包约定不同。