С чего начать

Разработчик аддонов

Alpha API

AbstractMenus 2.0 находится в alpha. API может измениться до стабильного релиза. Зафиксируй конкретную версию compileOnly в сборке, чтобы свежая выборка не сломала проект.

У AbstractMenus 2.0 есть SPI: через него аддоны в рантайме регистрируют свои действия, правила, свойства предметов, активаторы, каталоги и хендлеры провайдеров (экономика, права, уровни, плейсхолдеры, скины). Встроенные типы тянут тот же SPI.

Аддон можно поставить двумя способами - выбирай:

Путь 1 - аддон, загружаемый AM Jar с addon.conf. Кладётся в plugins/AbstractMenus/addons/, загружается AbstractMenus.

Путь 2 - плагин-как-аддон Обычный Bukkit-плагин. Кладётся в plugins/, загружается Bukkit.

Дальше идут страницы про сам API. Про доставку (какой путь выбрать, формат манифеста, жизненный цикл) смотри страницу аддонов.

Подключи API в свою сборку

API AbstractMenus публикуется на GitHub Packages и собирается под каждый релиз на JitPack.

Заметка

JitPack доступен анонимно. GitHub Packages требует Personal Access Token со скоупом read:packages - даже для публичных пакетов, это ограничение GitHub. Если есть весомая причина использовать GH Packages (например, корпоративный прокси с allowlist на *.github.com) - смотри настройку авторизации внизу страницы. В остальных случаях - JitPack.

Gradle (Kotlin DSL)

build.gradle.kts

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.AbstractMenus:minecraft-plugin:2.0.0-alpha.2")
}

Gradle (Groovy)

build.gradle

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.AbstractMenus:minecraft-plugin:2.0.0-alpha.2'
}

Maven

pom.xml

<repositories>
  <repository>
    <id>jitpack</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.AbstractMenus</groupId>
    <artifactId>minecraft-plugin</artifactId>
    <version>2.0.0-alpha.2</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

artifactId - minecraft-plugin, по имени репозитория. JitPack кладёт мульти-модульные Gradle-проекты под одну корневую координату; внутри jar - модуль api.

Осторожно

API тянет Adventure (net.kyori.adventure.text.*). Paper уже идёт с Adventure внутри, так что там всё работает само. На обычном Spigot Adventure придётся шейдить или подключать руками.

Объяви зависимость в plugin.yml (только Путь 2)

Плагины-как-аддоны (Путь 2) объявляют AbstractMenus жёсткой зависимостью - тогда Bukkit гарантирует, что твой onEnable запустится после того, как AbstractMenus уже поднялся.

plugin.yml

name: MyAddon
version: 1.0.0
depend:
  - AbstractMenus

Если плагин должен подниматься и без AbstractMenus, ставь softdepend: - и тогда обмазывай вызовы API проверкой Bukkit.getPluginManager().getPlugin("AbstractMenus") != null.

У аддонов Пути 1 plugin.yml нет вообще - вместо него addon.conf с полем pluginDependencies. См. страницу аддонов.

Получи экземпляр API

Точка входа - AbstractMenusApi. Берётся через статический get():

import ru.abstractmenus.api.AbstractMenusApi;

AbstractMenusApi api = AbstractMenusApi.get();

Если AbstractMenus ещё не включился - вернёт null. С depend: [AbstractMenus] в манифесте к моменту твоего onEnable он точно поднят.

В аддонах Пути 1 get() дёргать вообще не нужно - API прилетает параметром в методы жизненного цикла:

public final class MyAddon implements MenuExtension {
    @Override
    public void onEnable(AbstractMenusApi api) {
        // api уже инициализирован
    }
}

Что выставляет API

api.actions();         // TypeRegistry<Action>
api.rules();           // TypeRegistry<Rule>
api.activators();      // TypeRegistry<Activator>
api.itemProperties();  // TypeRegistry<ItemProperty>
api.catalogs();        // TypeRegistry<Catalog<?>>

api.providers();       // ProviderRegistry - экономика, права, уровни, плейсхолдеры, скины
api.serializers();     // общие HOCON NodeSerializers
api.variables();       // VariableManager - чтение/запись персональных и глобальных переменных

api.openMenu(activator, ctx, player, menu);
api.getOpenedMenu(player);
api.loadMenus();

api.apiVersion();      // строка версии для диагностики
api.getPlugin();       // сырой хэндл Bukkit Plugin

Под каждый реестр, менеджер и хелпер есть отдельная страница в этом разделе.

Поставка аддона Путь 1 vs Путь 2, жизненный цикл MenuExtension, манифест addon.conf.

Кастомные типы Опиши и зарегистрируй свои действия, правила, свойства предметов, активаторы, каталоги.

Хендлеры провайдеров Подключи свой бэкенд экономики/прав/плейсхолдеров/скинов/уровней.

Сериализаторы HOCON-десериализация для своих типов.

Variables API Чтение и запись персональных и глобальных переменных программно.

Утилиты Хелперы цвета, подстановка плейсхолдеров, планировщик.

Миграция 1.x → 2.0 Соответствие старых вызовов API (Types, Handlers, AbstractMenusProvider) новым.

Опционально: GitHub Packages вместо JitPack

Если по какой-то причине GitHub Packages обязателен (например, политика CI):

1. Сгенерируй Personal Access Token (classic) со скоупом read:packages.

2. Сложи учётку в ~/.gradle/gradle.properties:

   ~/.gradle/gradle.properties

   gpr.user=your-github-username
   gpr.token=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Добавь репозиторий и переключи координату на родную ru.abstractmenus:api:

   build.gradle

   repositories {
       maven {
           url = uri('https://maven.pkg.github.com/AbstractMenus/minecraft-plugin')
           credentials {
               username = providers.gradleProperty('gpr.user')
                       .orElse(providers.environmentVariable('GITHUB_ACTOR')).getOrNull()
               password = providers.gradleProperty('gpr.token')
                       .orElse(providers.environmentVariable('GITHUB_TOKEN')).getOrNull()
           }
       }
       // JitPack всё ещё нужен для транзитивной зависимости api
       // com.github.AbstractMenus:hocon:
       maven { url 'https://jitpack.io' }
   }
   
   dependencies {
       compileOnly 'ru.abstractmenus:api:2.0.0-alpha.2'
   }