Руководство разработчика MagmaCore

Сгенерированный справочник Java содержит классы, методы и сигнатуры с поиском, а также версию исходников и коммит каждого модуля.

MagmaCore встраивается в использующие её плагины посредством shading. Это не отдельный серверный плагин; не указывайте её в depend, как будто игроки могут установить самостоятельный JAR MagmaCore.

Зависимость и упаковка

Текущая координата разработки 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-классы из разных загрузчиков плагинов являются разными типами. Используйте явные межплагинные контракты, например сервис Lua-способностей EliteMobs и адаптеры реестра местоположений. Не приводите внутренний объект MagmaCore другого плагина к типу из своей копии.

Модули и ответственность

Модуль	Ответственность
`core`	Жизненный цикл плагина, конфигурация, команды, меню, матчи, запросы местоположения, Lua, контент Nightbreak и общие утилиты
`nms:core`	`NMSManager`, `NMSAdapter` и независимые от версии интерфейсы EasyMinecraftGoals
`nms:v*`	Реализации контракта NMS для версий сервера
`dist`	Встроенный дистрибутив с ядром и активными адаптерами

Общие зачарования, действия предметов, учётные записи, меню настройки, каталоги и обновления принадлежат сервисам ядра. При добавлении поведения потребителю используйте компонент, уже отвечающий за него.

Жизненный цикл плагина

Минимальный жизненный цикл ядра повторяет существующий шаблон потребителей:

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) очищает регистрации загрузчика, обновления контента, инициализации и обновления плагина, затем также останавливает общую среду загруженной копии библиотеки. Действие не ограничивается удалением одной записи реестра. Вызывайте его для собственной встроенной библиотеки при отключении своего плагина; не останавливайте библиотеку другого плагина ради сброса интеграции.

Вызывайте createInstance в onLoad, чтобы владелец архива конфигураций зарегистрировался до импорта контента другим плагином. Архивирование выполняется собственной встроенной реализацией целевого плагина; не интерпретируйте чужие правила устаревания своей копией MagmaCore.

Для поэтапного запуска startInitialization принимает асинхронную и синхронную работу, а также обработчики успеха и ошибки. Перед асинхронной инициализацией он архивирует подходящие устаревшие конфигурации. Операции Bukkit с мирами и сущностями выполняйте в синхронной фазе. Длительная асинхронная работа должна проверять isShutdownRequested(plugin) между этапами. getInitializationState и isPluginReady показывают состояние менеджера инициализации.

NMS и пакетные сущности

Инициализируйте NMS только при необходимости через NMSManager.initializeAdapter(plugin) из com.magmaguy.easyminecraftgoals. Проверяйте 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 и публикуйте MagmaCore в Maven Local командой ./gradlew publishToMavenLocal, а в Windows .\gradlew.bat publishToMavenLocal. Убедитесь, что потребитель получает нужную версию из этого репозитория, затем пересоберите его JAR со встроенной библиотекой. Замена библиотеки в Maven Local не обновляет уже собранный плагин.

API установленных плагинов перечислены в указателе разработчика. Такие интеграции обычно используют provided или compileOnly; для встроенной MagmaCore действует другой контракт упаковки.

Зависимость и упаковка​

Модули и ответственность​

Жизненный цикл плагина​

NMS и пакетные сущности​

Запросы местоположения и защиты​

Пересборка потребителя после изменения библиотеки​